r-util-js/packages/common/README.md

# @r-utils/common

与框架无关的通用 JS/TS 工具库，适用于任意前端项目，也可在具备对应运行时 API 的环境中使用。

## 特性

- 不依赖 Vue、uni-app 或 uview-plus。
- 支持 ESM / CJS 双格式产物。
- 支持根入口导入和子路径按需导入。
- 标记 `sideEffects: false`，方便业务打包器进行 tree-shaking。

## 安装

```bash
pnpm add @r-utils/common
```

## 导入方式

### 推荐：根入口导入

大多数场景推荐从根入口导入，使用心智负担更低，现代打包器仍可结合 ESM 和 `sideEffects: false` 做 tree-shaking。

```ts
import {
  Permission,
  wait,
  Countdown,
  TimeoutTimer,
  getValueOfRule,
} from "@r-utils/common";
```

### 兼容：子路径按需导入

如果你希望导入路径更精确，也可以使用子路径导入。两种方式都支持，按团队习惯选择即可。

```ts
import { Permission } from "@r-utils/common/permission";
import { wait } from "@r-utils/common/time";
import { Countdown, TimeoutTimer } from "@r-utils/common/timer";
import { getValueOfRule } from "@r-utils/common/input-rule";
```

## 导出模块

| 子路径 | 说明 |
| --- | --- |
| `@r-utils/common/permission` | 权限字符串格式校验 |
| `@r-utils/common/time` | 时间相关工具 |
| `@r-utils/common/timer` | 倒计时、超时计时器 |
| `@r-utils/common/input-rule` | 输入值规则处理 |
| `@r-utils/common/knock-test` | 连续敲击/点击触发器 |
| `@r-utils/common/ui` | 与框架无关的 UI 计算工具 |
| `@r-utils/common/printer` | ESC/TSC 打印相关工具 |

## 使用示例

### 权限字符串校验

```ts
import { Permission } from "@r-utils/common";

const permission = new Permission([], 3, ":");

permission.isValid("user:create:button"); // true
permission.isValid("user:create"); // false
```

### 等待指定时间

```ts
import { wait } from "@r-utils/common";

async function submit() {
  await wait(300);
  console.log("继续执行");
}
```

### 倒计时

```ts
import { Countdown } from "@r-utils/common";

const countdown = new Countdown(10 * 1000);

countdown.addStepEventListener((time) => {
  console.log("剩余时间：", time);
});

countdown.addCountdownEventListener(() => {
  console.log("倒计时结束");
});

countdown.start();
```

### 简单数值倒计时

```ts
import { TimeoutTimer } from "@r-utils/common";

const timer = new TimeoutTimer(5000, 0, 1000);

timer.addStepEventListener((time) => {
  console.log("剩余毫秒：", time);
});

timer.addCountdownEventListener(() => {
  console.log("完成");
});

timer.start();
```

### 输入值规则处理

```ts
import { getValueOfRule } from "@r-utils/common";

const value = getValueOfRule("12.345", {
  min: 0,
  max: 99999.99,
  required: true,
  digits: 2,
  keepDecimal: true,
});

console.log(value); // "12.35"
```

### 禁止正负号并转成数字

```ts
import { getValueOfRule } from "@r-utils/common";

const value = getValueOfRule("-12", {
  min: 0,
  required: true,
  noSign: true,
  number: true,
});

console.log(value); // 0
```

### 连续敲击触发回调

```ts
import { KnockTest } from "@r-utils/common";

const knockTest = new KnockTest({
  maxWaitTime: 5000,
  operations: [
    { times: 3, duration: 1000, delay: 500 },
    { times: 2, duration: 1000, delay: 500 },
  ],
});

knockTest.addCallback(() => {
  console.log("触发隐藏功能");
});

button.addEventListener("click", () => {
  knockTest.knock();
});
```

### 缓动滚动计算

```ts
import { slowlyScroll } from "@r-utils/common";

await slowlyScroll(0, 300, 500, (value) => {
  window.scrollTo(0, value);
});
```

## 注意事项

- `Countdown`、`TimeoutTimer` 和 `KnockTest` 内部使用 `window.setInterval` / `window.setTimeout`，更适合浏览器或类浏览器环境。
- 推荐优先使用根入口导入；如果需要更精确的模块边界，也可以使用子路径导入。
- 打印相关模块通常依赖具体设备和业务场景，建议在真实设备环境中验证。