160 lines
3.2 KiB
Markdown
160 lines
3.2 KiB
Markdown
# r-utils
|
||
|
||
前端工具库 monorepo，使用 pnpm workspace 管理，Vite 构建。
|
||
|
||
## 包列表
|
||
|
||
| 包名 | 路径 | 描述 |
|
||
| ---- | ---- | ---- |
|
||
| `@r-utils/common` | `packages/common` | 通用 JS/TS 工具（权限、倒计时、打印、时间等） |
|
||
| `@r-utils/vue3` | `packages/vue3` | Vue3 工具（class 处理、dispatch 等） |
|
||
| `@r-utils/uni-app` | `packages/uni-app` | uni-app 工具（请求封装、蓝牙、NFC、打印等） |
|
||
| `@r-utils/vue2` | `packages/vue2` | Vue2 工具（visibility 插件） |
|
||
|
||
## 环境要求
|
||
|
||
- Node.js >= 18.12.0
|
||
- pnpm >= 8.15.6
|
||
|
||
## 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
## 构建
|
||
|
||
### 构建所有包
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
### 构建单个包
|
||
|
||
```bash
|
||
cd packages/common
|
||
pnpm build
|
||
```
|
||
|
||
每个包使用 **Vite lib 模式**构建，输出到 `dist/` 目录：
|
||
|
||
```text
|
||
dist/
|
||
├── index.mjs # ESM 格式
|
||
├── index.cjs # CJS 格式
|
||
├── index.d.ts # TypeScript 类型声明
|
||
├── index.mjs.map # Source Map
|
||
└── index.cjs.map
|
||
```
|
||
|
||
### 监听模式
|
||
|
||
```bash
|
||
cd packages/common
|
||
pnpm watch
|
||
```
|
||
|
||
## 使用方式
|
||
|
||
### ESM 引入（推荐）
|
||
|
||
支持 tree-shaking，打包工具会自动按需引入用到的部分。
|
||
|
||
```ts
|
||
// 完整引入
|
||
import { Permission, Countdown, KnockTest } from '@r-utils/common';
|
||
|
||
// 按需引入（bundler 自动 tree-shaking，只打包 Permission）
|
||
import { Permission } from '@r-utils/common';
|
||
|
||
// Vue3 工具
|
||
import { mergeClass, dispatch } from '@r-utils/vue3';
|
||
|
||
// uni-app 工具
|
||
import { Request } from '@r-utils/uni-app';
|
||
|
||
// Vue2 插件
|
||
import { VisibilityPlugin } from '@r-utils/vue2';
|
||
Vue.use(VisibilityPlugin);
|
||
```
|
||
|
||
### CJS 引入
|
||
|
||
```js
|
||
const { Permission } = require('@r-utils/common');
|
||
```
|
||
|
||
### package.json exports
|
||
|
||
每个包均配置了标准的 `exports` 字段，打包工具会自动选择正确的格式：
|
||
|
||
```json
|
||
{
|
||
"exports": {
|
||
".": {
|
||
"types": "./dist/index.d.ts",
|
||
"import": "./dist/index.mjs",
|
||
"require": "./dist/index.cjs"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 开发
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pnpm test
|
||
|
||
# 运行单个测试文件
|
||
npx jest packages/common/test/permission.test.ts
|
||
```
|
||
|
||
### 代码检查与格式化
|
||
|
||
```bash
|
||
pnpm lint
|
||
pnpm format
|
||
```
|
||
|
||
### Git 提交
|
||
|
||
```bash
|
||
# 使用 commitizen（遵循 conventional commits）
|
||
pnpm commit
|
||
```
|
||
|
||
提交时 husky 会自动运行 lint-staged 和 jest 测试。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
r-util-js/
|
||
├── packages/
|
||
│ ├── common/ # @r-utils/common
|
||
│ │ ├── src/
|
||
│ │ │ ├── permission/ # Permission 权限校验
|
||
│ │ │ ├── timer/ # Countdown、TimeoutTimer
|
||
│ │ │ ├── printer/ # ESC/TSC 打印指令
|
||
│ │ │ ├── knock-test/ # KnockTest 敲击触发
|
||
│ │ │ └── time/ # 时间工具
|
||
│ │ ├── vite.config.ts
|
||
│ │ └── tsconfig.json
|
||
│ ├── vue3/ # @r-utils/vue3
|
||
│ ├── uni-app/ # @r-utils/uni-app
|
||
│ └── vue2/ # @r-utils/vue2
|
||
├── eslint.config.js # ESLint v9 flat config
|
||
├── prettier.config.js
|
||
└── pnpm-workspace.yaml
|
||
```
|
||
|
||
## 参与贡献
|
||
|
||
1. Fork 本仓库
|
||
2. 新建 `feat/xxx` 分支
|
||
3. 提交代码
|
||
4. 新建 Pull Request
|