@xiaojinquan/super-kit

使用文档 · @xiaojinquan/super-kit@0.0.20

1. 安装

npm install @xiaojinquan/super-kit
# 或
pnpm add @xiaojinquan/super-kit

• 本库将 vue 声明为可选 peerDependency，不会强制安装。
• 仅使用组件 / 指令时需要项目里存在 vue；纯工具方法（utils / env）无需 vue。
• dayjs 为运行时依赖，消费方安装本包时自动拉取，不会重复打进 dist。

外部依赖说明

本库部分功能引用了外部依赖。这些依赖均不打包进 dist，以 import/require 形式保留、由消费方依赖树解析。使用前请按表确认运行环境已满足：

构建侧保障（防止外部依赖被误打包）：

1. tsup.config.ts 与 scripts/vite-lib.mjs 均从 package.json 的 dependencies + peerDependencies 自动派生 external（含子路径正则），新增运行时包写进 package.json 即自动 external，无需改构建脚本。
2. scripts/check-external.mjs（独立命令 pnpm check:external）扫描 dist 全部产物，若发现外部依赖被内联或存在未声明依赖泄漏则非零退出；已接入 pnpm build 末尾与 pnpm publish:npm 的混淆之后，作为发布闸门。

2. 入口总览

通过 package.json 的 exports 子路径按需引入，构建工具会自动解析 ESM / CJS：

3. 工具方法总览

import { formatNumber, debounce, copyText, formatDate } from "@xiaojinquan/super-kit/utils";
// 或（根入口已再导出 utils）
import { formatNumber, debounce, copyText } from "@xiaojinquan/super-kit";

全部工具方法按模块分组，均为框架无关、可 tree-shaking 的纯函数 / 类，模块之间也可互相引用（如 uniapp 依赖 parse 的 getFileUrlInfo 与 format 的 urlConversion）。

3.1 分类速查（全部导出）

4. 各模块完整 API 参考

4.1 array — 数组处理

import {
  unique,
  flatten,
  group,
  flatToTree,
  treeToFlat,
  deepClone,
  fuzzySearch,
} from "@xiaojinquan/super-kit/utils";
unique([1, 1, 2, 3]); // [1, 2, 3]
flatten([1, [2, [3]]]); // [1, 2, 3]
group([{ t: "A" }, { t: "A" }], "t"); // [{ name: 'A', children: [...] }]
flatToTree(list, ["pid", "id"]); // 树形数组
treeToFlat(tree, ["pid", "id"], "children");
deepClone(obj); // 深拷贝（带循环引用缓存）
fuzzySearch("hello", "h%o"); // true

4.2 base — 进制 / 压缩

import {
  convertRadix,
  toDecimal,
  fromDecimal,
  lzwCompress,
  lzwDecompress,
} from "@xiaojinquan/super-kit/utils";
convertRadix("110", 2, 10); // '6'
convertRadix("AF", 16, 10); // '175'
convertRadix("175", 10, 16); // 'af'
toDecimal("ff", 16); // 255
fromDecimal(255, 16); // 'ff'
lzwCompress("repeat repeat"); // 压缩字符串（可 outputBase64: true）
lzwDecompress(compressed); // 还原

4.3 calendar — 农历 / 日历（全静态方法，无需实例化）

import { Calendar } from "@xiaojinquan/super-kit/utils";

LunarResult 含：lYear lMonth lDay Animal IMonthCn IDayCn cYear cMonth cDay gzYear gzMonth gzDay isToday isLeap nWeek ncWeek isTerm Term astro。

Calendar.solar2lunar(2026, 1, 1); // { lYear: 2025, IMonthCn: '腊月', ... }
Calendar.lunar2solar(2026, 1, 1); // 公历信息对象
Calendar.toGanZhiYear(2026); // '丙午'
Calendar.getAnimal(2026); // '马'

4.4 canvas — 画布绘制（传入 CanvasRenderingContext2D）

import { textPrewrap, fillRoundRect, drawRoundRectPath } from "@xiaojinquan/super-kit/utils";
const ctx = canvas.getContext("2d")!;
fillRoundRect(ctx, 10, 10, 200, 100, 15, "rgba(0,150,255,0.8)");
textPrewrap(ctx, "长文本…", 10, 10, 16, 24, 200, 3, 20);

4.5 chineseConverter — 简繁转换（单例）

import { ChineseConverter } from "@xiaojinquan/super-kit/utils";
const cv = ChineseConverter.getInstance(); // 全局唯一实例

ChineseConverter.getInstance().toSimplifieds("繁體"); // '繁体'
ChineseConverter.getInstance().toTraditionals("简体"); // '簡體'

4.6 color — 颜色处理

import { rgbToHex, rgbaToHex, hexToRgba, randomColor, getGradientStyle, ThemeColor } from "@xiaojinquan/super-kit/utils";
rgbToHex(255, 0, 0); // '#ff0000'
rgbaToHex(255, 0, 0, 0.5); // '#ff8080'
hexToRgba("#ff0000"); // { r:255, g:0, b:0, a:1 }
hexToRgba("#ff0000", 0.5, true); // 'rgba(255,0,0,0.5)'
randomColor({ format: "hex", brightness: "light" });

// 文字渐变：相同字符串恒定同一渐变
const g = getGradientStyle("Hello World");
// <span style={g.style}>Hello World</span>
getGradientStyle("Custom", { angle: 90, type: "radial", radialShape: "circle" });

// 图片主色提取（浏览器 / H5）
const tc = new ThemeColor("https://example.com/cover.jpg");
const { shrinkUrl, themeColor, rgba } = await tc.ready;

4.7 dateTime — 时间处理（基于 dayjs）

⚠️ 依赖 dayjs：本模块全部时间函数基于 dayjs 及其 weekOfYear / dayOfYear 插件实现。dayjs 为运行时依赖（已写入 package.json 的 dependencies），安装本包时自动拉取，无需另行安装。

import {
  formatDate,
  formatRelativeTime,
  getTimeRange,
  isLeapYear,
} from "@xiaojinquan/super-kit/utils";
formatDate(1735689600000); // '2026-01-01 00:00:00'
formatDate("2026-08-20", "YYYY-MM-DD"); // '2026-08-20'
formatRelativeTime("2026-08-19 12:00", "2026-08-20 12:00"); // '昨天'
const [start, end] = getTimeRange("month"); // 本月起止时间戳
isLeapYear(2024); // true

4.8 desensitize — 脱敏

import {
  desensitizePhone,
  desensitizeName,
  desensitizeIdCard,
} from "@xiaojinquan/super-kit/utils";
desensitizePhone("13812345678"); // '138****5678'
desensitizeName("张三"); // '张**'
desensitizeIdCard("110101199001011234"); // '110101********1234'

4.9 dom — DOM 操作

import { copyText, loadScript, loadScripts, loadCSS } from "@xiaojinquan/super-kit/utils";
const ok = await copyText("hello");
if (ok) console.log("已复制");
// 指令 v-copy 内部即调用 copyText

await loadScript("/sdk.js");                 // 推荐：Promise 式
loadScript("/sdk.js", () => console.log("loaded")); // 兼容：回调式

await loadScripts(["/a.js", "/b.js", "/c.js"]); // 依次加载 a → b → c

await loadCSS("/theme.css");
await loadCSS("/print.css", { media: "print" });

4.10 format — 格式化

import {
  formatNumber,
  amountToChinese,
  urlConversion,
  formatPhone,
  numberToChinese,
} from "@xiaojinquan/super-kit/utils";
formatNumber(1234567.89); // '1,234,567.89'
formatNumber(1234567.89, { currency: "¥" }); // '¥1,234,567.89'
amountToChinese(1234.56); // '壹仟贰佰叁拾肆元伍角陆分'
urlConversion("//a.com/b"); // 'https://a.com/b'
formatPhone("13812345678"); // '138-1234-5678'
numberToChinese(1234); // '一千二百三十四'

4.11 function — 函数增强

import { debounce, throttle, throttleTimer } from "@xiaojinquan/super-kit/utils";
const search = debounce((v: string) => console.log(v), 300);
search.cancel(); // 取消待执行任务
const scroll = throttle(() => {}, 200);
const click = throttleTimer(() => {}, 1000);

4.12 location — 经纬度（全静态方法，无需实例化）

import { Location } from "@xiaojinquan/super-kit/utils";

Point = { longitude: number; latitude: number }。

Location.getDistance(116.4, 39.9, 121.47, 31.23); // 两点球面距离（米）
Location.wgs84togcj02(116.4, 39.9); // 坐标转换

4.13 parse — 解析

import {
  getInfoByIdCard,
  getPasswordStrength,
  getFileUrlInfo,
  extractRichText,
} from "@xiaojinquan/super-kit/utils";
getInfoByIdCard("110101199003071234"); // { birthday:'1990-03-07', gender:'男', age:36 }
getPasswordStrength("Abc123_"); // { level:4, description:'极强', score:4, length:7, meetsMinLength:true }
getFileUrlInfo("https://x/y.jpg"); // { fullName:'y.jpg', name:'y', suffix:'jpg', type:'1' }

4.14 random — 随机

import { uuidv4, randomInt, generateCaptcha, shuffle } from "@xiaojinquan/super-kit/utils";
uuidv4(); // '3b1f8c7e-2a9d-4c5b-...'
randomInt(1, 10); // 1~10
generateCaptcha(6, { charSet: "number" }); // '372915'
shuffle([1, 2, 3, 4, 5]);

4.15 string — 字符串

import {
  escapeHtml,
  camelToSeparated,
  queryObject,
  trim,
  convertCase,
  decodeUnicodeEscapes,
} from "@xiaojinquan/super-kit/utils";
escapeHtml("<a>"); // '&lt;a&gt;'
camelToSeparated("fooBar"); // 'foo_bar'
queryObject("?a=1&b=2"); // { a:'1', b:'2' }
trim("  a   b  ", "extra"); // 'a b'
convertCase("hello world", "capitalize"); // 'Hello World'
decodeUnicodeEscapes("\\u4F60\\u597D"); // '你好'

4.16 storage — 浏览器存储（cookie / localStorage / sessionStorage）

仅浏览器 / H5 可用（依赖 DOM document / window.localStorage / window.sessionStorage）；Node / uni-app 小程序原生端不可用。cookie 读写的编解码复用 string 模块的 queryObject（解析 document.cookie），与 queryString 风格一致。提供三个可监听缓存类（API 风格一致，互相对称）：

• LocalStorageWatcher — 监听 localStorage（支持跨标签页同步，原生 storage 事件）
• SessionStorageWatcher — 监听 sessionStorage（仅同标签页，无原生事件）
• CookieWatcher — 监听 cookie（基于轮询 diff，默认 500ms，能捕获任意来源写入）

import {
  setCookie, getCookie, getCookies,
  setLocalStorage, getLocalStorage,
  setSessionStorage, getSessionStorage,
  LocalStorageWatcher, localStorageWatcher,
  SessionStorageWatcher, sessionStorageWatcher,
  CookieWatcher, cookieWatcher,
} from "@xiaojinquan/super-kit/utils";

// cookie
setCookie("token", "abc", { expires: 7, sameSite: "Lax" });
getCookie("token"); // 'abc'
getCookies();       // { token: 'abc', ... }

// localStorage / sessionStorage（自动 JSON 序列化 / 反序列化）
setLocalStorage("user", { id: 1, name: "Tom" });
getLocalStorage("user"); // { id: 1, name: 'Tom' }
setSessionStorage("draft", { text: "hello" });
getSessionStorage("draft"); // { text: 'hello' }

// LocalStorageWatcher：跨标签页同步 + 同标签页桥接
const off = localStorageWatcher.watchStorage("token", (newVal, oldVal) => {
  console.log(newVal, oldVal);
});
localStorageWatcher.setStorageWatch("token", "abc123"); // 触发上面的回调
off(); // 取消监听

// SessionStorageWatcher：仅同标签页同步
sessionStorageWatcher.watchStorage("draft", (newVal) => console.log(newVal));
sessionStorageWatcher.setStorageWatch("draft", { title: "未命名" });

// CookieWatcher：轮询 diff（≤500ms 内触发）
cookieWatcher.watchCookie("token", (newVal, oldVal) => {
  console.log("token 变化：", newVal, oldVal);
});
setCookie("token", "new-value"); // 下一个 tick 内触发回调

// 自定义轮询间隔
const cw = new CookieWatcher({ intervalMs: 1000 });

4.17 uniapp — uni-app / 小程序 API 封装

对 uni.* 回调式 API 做 Promise 化 / 对象传参 / 字段对齐官方命名 封装，不依赖 @dcloudio/uni-app 类型包（内部维护局部 Uni 子集类型 + getUni() 运行时访问，非 uni 环境抛明确错误）。入参均为对象、字段一一对应官方命名；文件类方法支持 [key: string]: unknown 透传索引签名（官方新增字段无需改库）。

import {
  showToast,
  chooseMedia,
  scanCode,
  getLoginCode,
  getSystemInfoSync,
  rpxToPx,
  pxToRpx,
  backRefresh,
  storageWatcher, // 可监听本地缓存事件中心（全局唯一单例，推荐直接使用）
} from "@xiaojinquan/super-kit/utils";

showToast("保存成功");

const media = await chooseMedia({ count: 1, mediaType: ["image"] });
if (media) console.log(media.tempFiles);

const scanned = await scanCode(); // 默认 scanType: ['qrCode','barCode']
if (scanned) console.log(scanned.result, scanned.scanType);

const code = await getLoginCode();
if (code) console.log(code);

const sys = getSystemInfoSync(); // 同步返回

const px = rpxToPx(100);  // 设备屏宽 375 时返回 50
const rpx = pxToRpx(50);  // 返回 100

失败处理约定：多数 choose / 文件类方法（chooseMessageFile chooseMedia scanCode chooseLocation getLocation downloadFile openDocument getScreenBrightness getImageInfo getLoginCode addPhoneContact）失败 resolve(false)、不 reject，调用方 if (res) 判空即可；getDomInfo 对入参错误 reject，需 try/catch；getSystemInfoSync 为同步函数。部分能力为微信小程序 / App 专属（如 saveImageToPhotosAlbum 相册权限、addPhoneContact 通讯录权限、5 个 getter），H5 / 各端支持度不同，宜按平台条件调用（如 #ifdef MP-WEIXIN）。

4.16.1 storageWatcher — 可监听本地缓存事件中心（全局唯一单例）

对 uni 本地缓存（getStorageSync / setStorageSync / setStorage / removeStorageSync / getStorageInfoSync / clearStorageSync）做可监听封装。**已封装为 class StorageWatcher，并导出全局唯