227 lines
5.1 KiB
Markdown
227 lines
5.1 KiB
Markdown
# r-utils
|
||
|
||
前端工具库 monorepo，使用 pnpm workspace + Turbo 管理任务，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、打印、Vue3 Hooks 等） |
|
||
| `@r-utils/uview-plus` | `packages/uview-plus` | uview-plus 组合式 API Hooks（Picker、Calendar 等） |
|
||
| `@r-utils/vue2` | `packages/vue2` | Vue2 工具（visibility 插件） |
|
||
|
||
## 环境要求
|
||
|
||
- Node.js >= 18.12.0
|
||
- pnpm >= 10.0.0
|
||
|
||
## 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
## 构建
|
||
|
||
### 构建所有包
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
Turbo 会自动按依赖拓扑排序构建（例如 `@r-utils/common` 会先于依赖它的包构建），并复用缓存加速重复任务。
|
||
|
||
### 构建单个包（Turbo 过滤）
|
||
|
||
```bash
|
||
pnpm build -- --filter=@r-utils/common
|
||
```
|
||
|
||
### 构建单个包
|
||
|
||
```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
|
||
# 监听所有包
|
||
pnpm build:watch
|
||
|
||
# 仅监听单个包
|
||
pnpm build:watch -- --filter=@r-utils/common
|
||
```
|
||
|
||
## 使用方式
|
||
|
||
### 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';
|
||
|
||
// uni-app Vue3 Hooks
|
||
import { useShare } from '@r-utils/uni-app/vue3';
|
||
|
||
// uview-plus Hooks
|
||
import { usePickerSingle, usePicker, useCalendar } from '@r-utils/uview-plus';
|
||
|
||
// 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
|
||
|
||
# 运行单个测试文件
|
||
pnpm vitest run packages/common/test/permission.test.ts
|
||
```
|
||
|
||
### 代码检查与格式化
|
||
|
||
```bash
|
||
pnpm lint
|
||
pnpm format
|
||
```
|
||
|
||
### Git 提交
|
||
|
||
项目使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范,通过 `commitizen` + `cz-git` 提供交互式提交体验。
|
||
|
||
```bash
|
||
# 使用交互式提交(推荐)
|
||
pnpm commit
|
||
```
|
||
|
||
提交时 husky 会自动运行:
|
||
|
||
- `lint-staged` - 代码检查和格式化
|
||
- `pnpm test`（Vitest） - 单元测试
|
||
- `commitlint` - 提交信息格式校验
|
||
|
||
详细说明请参考 [提交规范指南](./docs/COMMIT_GUIDE.md)。
|
||
|
||
## 发布
|
||
|
||
发布流程已提取到独立文档：[发布流程](./docs/RELEASE.md)。
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
pnpm changeset # 记录变更
|
||
pnpm release:check # 测试 + 构建
|
||
pnpm release # 更新版本号与 CHANGELOG
|
||
pnpm release:publish # 发布到 npm 仓库
|
||
pnpm release:all # 一键执行检查 + 版本更新 + 发布
|
||
```
|
||
|
||
项目已配置发布到私有 npm 仓库 `http://npm.nps.yunvip123.cn`。
|
||
|
||
### 安装已发布的包
|
||
|
||
```bash
|
||
# 配置 npm registry
|
||
npm config set registry http://npm.nps.yunvip123.cn
|
||
|
||
# 或在项目中使用 .npmrc 文件
|
||
echo "registry=http://npm.nps.yunvip123.cn" > .npmrc
|
||
|
||
# 安装包
|
||
pnpm add @r-utils/common
|
||
pnpm add @r-utils/vue3
|
||
pnpm add @r-utils/uni-app
|
||
pnpm add @r-utils/uview-plus
|
||
pnpm add @r-utils/vue2
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```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
|
||
│ ├── uview-plus/ # @r-utils/uview-plus
|
||
│ └── vue2/ # @r-utils/vue2
|
||
├── eslint.config.js # ESLint v9 flat config
|
||
├── prettier.config.js
|
||
└── pnpm-workspace.yaml
|
||
```
|
||
|
||
## 参与贡献
|
||
|
||
欢迎贡献代码!请先阅读:
|
||
|
||
- [贡献指南](./docs/CONTRIBUTING.md) - 了解开发流程和规范
|
||
- [提交规范指南](./docs/COMMIT_GUIDE.md) - 了解 Git 提交规范
|
||
|
||
基本流程:
|
||
|
||
1. Fork 本仓库
|
||
2. 新建分支 `feat/xxx` 或 `fix/xxx`
|
||
3. 提交代码(使用 `pnpm commit`)
|
||
4. 新建 Pull Request
|