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

@r-utils/common

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

特性

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

安装

pnpm add @r-utils/common

导入方式

推荐：根入口导入

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

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

兼容：子路径按需导入

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

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 打印相关工具

使用示例

权限字符串校验

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

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

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

等待指定时间

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

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

倒计时

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

const countdown = new Countdown(10 * 1000);

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

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

countdown.start();

简单数值倒计时

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();

输入值规则处理

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"

禁止正负号并转成数字

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

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

console.log(value); // 0

连续敲击触发回调

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();
});

缓动滚动计算

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

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

注意事项

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