236 lines
5.2 KiB
Markdown
236 lines
5.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/uview-plus` | `packages/uview-plus` | uview-plus 组合式 API Hooks（Picker、Calendar 等） |
|
||
| `@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';
|
||
|
||
// 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
|
||
|
||
# 运行单个测试文件
|
||
npx jest 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` - 代码检查和格式化
|
||
- `jest` - 单元测试
|
||
- `commitlint` - 提交信息格式校验
|
||
|
||
详细说明请参考 [提交规范指南](./docs/COMMIT_GUIDE.md)。
|
||
|
||
## 发布
|
||
|
||
### 1. 版本管理（standard-version）
|
||
|
||
使用 `standard-version` 更新版本号、生成 CHANGELOG、创建 Git commit 和 tag。版本配置见 `.versionrc.json`，会同步更新根包和所有子包的版本号。
|
||
|
||
```bash
|
||
# 默认 patch 版本
|
||
pnpm release
|
||
|
||
# 指定版本类型
|
||
npx standard-version --release-as minor # 1.0.0 -> 1.1.0
|
||
npx standard-version --release-as major # 1.0.0 -> 2.0.0
|
||
```
|
||
|
||
### 2. 构建并发布到私有 npm 仓库
|
||
|
||
项目已配置发布到私有 npm 仓库 `http://npm.nps.yunvip123.cn`。
|
||
|
||
#### Windows (PowerShell)
|
||
|
||
```powershell
|
||
powershell scripts/publish.ps1
|
||
```
|
||
|
||
#### Linux/macOS (Bash)
|
||
|
||
```bash
|
||
bash scripts/publish.sh
|
||
```
|
||
|
||
发布脚本会自动执行以下步骤：
|
||
|
||
1. 检查 Git 工作区状态
|
||
2. 运行测试（确保代码质量）
|
||
3. 构建所有子包
|
||
4. 依次发布 `@r-utils/common`、`@r-utils/vue3`、`@r-utils/uni-app`、`@r-utils/vue2`
|
||
5. 询问是否推送到远程仓库
|
||
|
||
### 安装已发布的包
|
||
|
||
```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
|