Base Tools

甘草医生前端团队常用工具库，包含 ts（通用工具）、web（浏览器相关）、uni（小程序/uniapp 相关）。支持从模块根导入，类型完整，且可在 IDE 中快捷查看源码与注释。

特性

• 统一从模块根导入，稳定 API：@gancao/base-tools/ts、@gancao/base-tools/web、@gancao/base-tools/uni
• 子路径导入亦可用，内部映射到模块根，避免目录变动影响用户
• 发布 dist + src，开启 declarationMap，编辑器支持“转到源定义”查看真实源码
• 现代 ESM 输出与摇树优化，sideEffects: false

安装

• pnpm add @gancao/base-tools
• npm i @gancao/base-tools
• yarn add @gancao/base-tools

快速使用

// 通用 TS 模块（推荐从模块根导入）
import { addUnitPx, arrayMove } from '@gancao/base-tools/ts';

console.log(addUnitPx(12)); // "12px"
console.log(arrayMove([1, 2, 3], 0, 2)); // [2,3,1]

// Web 模块
import { getDispositionFileName } from '@gancao/base-tools/web';
console.log(getDispositionFileName('attachment; filename="report.csv"')); // "report.csv"

// Uni 模块
import { addUnitRpx } from '@gancao/base-tools/uni';
console.log(addUnitRpx(10)); // "10rpx"

React / Vue 使用

// React
import { useDebounce } from '@gancao/base-tools/react';
import { withErrorBoundary } from '@gancao/base-tools/react';

// Vue
import { useLatest } from '@gancao/base-tools/vue';
import { vClickOutside } from '@gancao/base-tools/vue';

导入约定与冲突避免

• 推荐按子路径导入以避免跨模块同名符号冲突：
  • @gancao/base-tools/ts
  • @gancao/base-tools/web
  • @gancao/base-tools/uni
  • @gancao/base-tools/react
  • @gancao/base-tools/vue
• 本库通过 exports 与 typesVersions 为这些子路径提供稳定的类型映射，确保跳转源码与注释可用。

TypeScript 配置建议（提升自动补全）

• 若你的项目使用 TypeScript 5.2+，建议：
  • "moduleResolution": "bundler"
  • 或在 TS 4.7+："moduleResolution": "node16" | "nodenext"
• 这些解析策略能更好地识别包的 exports/子路径，并改进自动导入提示。
• 对于 TS 4.6 及以下，库已通过 typesVersions 提供子路径类型映射，能正常类型检查与跳转，但自动导入提示可能较弱。

兼容方案：分包（薄包装）以提升 JS/旧解析的提示

• 若你的项目为 Node 14 + Vue 2，且不便改为 moduleResolution: bundler，可使用薄包装分包：
  • @gancao/base-tools-ts → 转发 @gancao/base-tools/ts
    • 安装：npm i @gancao/base-tools-ts 或 pnpm add @gancao/base-tools-ts
    • 使用：import { addUnitPx } from '@gancao/base-tools-ts'
  • @gancao/base-tools-web → 转发 @gancao/base-tools/web
    • 安装：npm i @gancao/base-tools-web 或 pnpm add @gancao/base-tools-web
    • 使用：import { loadScript } from '@gancao/base-tools-web'
  • @gancao/base-tools-uni → 转发 @gancao/base-tools/uni
    • 安装：npm i @gancao/base-tools-uni 或 pnpm add @gancao/base-tools-uni
    • 使用：import { sleep } from '@gancao/base-tools-uni'
• 如需仅引入框架相关工具，可使用：
  • @gancao/base-tools-react → 转发 @gancao/base-tools/react
    • 安装：npm i @gancao/base-tools-react 或 pnpm add @gancao/base-tools-react
    • 使用：import { useMounted } from '@gancao/base-tools-react'
    • 需在项目中安装 React（建议 React 18+）。
  • @gancao/base-tools-vue → 转发 @gancao/base-tools/vue
    • 安装：npm i @gancao/base-tools-vue 或 pnpm add @gancao/base-tools-vue
    • 使用：import { useMounted } from '@gancao/base-tools-vue'
    • 适配 Vue 3（建议 Vue 3.3+）；Vue 2 项目请勿使用。
• 分包仅做根入口转发到主包子路径（不复制源码），能在旧解析和纯 JS 项目中更容易触发自动导入；现代环境仍推荐直接使用主包的子路径导入。