r-util-js/README.md

# 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