nl-toolbox

v0.1.3

Published

a month ago

Vue3 嵌入式企业工具箱组件包：悬浮球入口 + 搜索气泡卡片 + Win11 风格小窗口，内置办公/开发/财务/人事 27 个常用工具，支持亮暗自适应主题与后端角色按 code 码下发工具。

0High
0Medium
0Low

ngzz

nl-toolbox vue vue3 toolbox tools 工具箱悬浮球 floating-ball floating-window enterprise 企业工具组件库 component

nl-toolbox

Vue3 嵌入式企业工具箱组件包：悬浮球入口 + 搜索气泡卡片 + Win11 风格小窗口 内置 27 个办公/开发/财务/人事常用工具，支持后端按角色下发工具（code 码）、亮暗自适应主题、JS/TS 双版本。

特性

| 能力 | 说明 | |---|---| | 🎈 悬浮球入口 | 可拖拽、松手自动吸附左右边缘并隐藏一半，hover 滑出；也可用自定义按钮经命令式 API 唤出 | | 🗂 气泡卡片 | 点击悬浮球直接展示工具宫格列表（无菜单栏），顶部搜索框实时过滤；历史/收藏收进头部小图标（轻量切换） | | 🪟 三种展示方式 | 小窗口（默认，Win11 文件管理器交互）/ 抽屉 / 模态框，可全局配置或按工具配置 | | 📌 单窗口机制 | 始终只有一个小窗口：切换工具复用同一窗口（不越开越多）；窗口内"返回列表"可直接换工具；拖拽/缩放位置记忆（localStorage 按工具持久化，重开自动恢复） | | 🎨 四种风格预设 | Win11（默认）/ macOS / Win98 复古 / 8-bit 像素，完全不同的设计语言，均可亮暗两态；附主题制作手册与可复制的主题模板文件 | | 🧰 27 个内置工具 | 覆盖办公、开发、财务、人事四大场景，每个工具独立目录，可增删不影响核心 | | 🔑 code 码机制 | 工具按 code 码展示：空数组 = 全部；支持 loadTools 从后端按角色异步拉取 | | 🌓 亮暗自适应主题 | 默认 auto 跟随系统实时切换；light / dark 可强制覆盖；CSS 变量可深度定制 | | 🌐 CDN 纯 HTML 引用 | 提供 UMD 构建（window.NlToolbox），无需构建工具，<script> 标签直接使用 | | 🔤 JS/TS 双版本 | TS 源码 + 编译 ESM/CJS/UMD + 完整 .d.ts，JS 项目直接可用、TS 项目类型完备 | | 📦 零运行时依赖 | 仅 peerDependency vue，全部工具算法纯 JS 实现 |

安装

# npm
npm install nl-toolbox
# pnpm
pnpm add nl-toolbox
# yarn
yarn add nl-toolbox

环境要求：
Vue ≥ 3.3（peerDependency，不打包 vue）
Node.js ≥ 18（vite 6 要求 ^18.0.0 || ^20.0.0 || >=22.0.0）
pnpm ≥ 9.0.0（lockfile v9.0 的读取下限；已用 pnpm 9.15.0 实测安装构建通过）
推荐 pnpm ≥ 10.4 或 11.x：10.0–10.3 会提示"忽略构建脚本"（esbuild 通常仍可运行）；10.4+ 通过 pnpm-workspace.yaml 的 onlyBuiltDependencies/allowBuilds 放行 esbuild，无告警
仓库锁定 packageManager: [email protected]（corepack 用户自动使用该版本）

快速开始

方式一：插件方式（推荐）

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import VueToolbox from 'nl-toolbox'
import 'nl-toolbox/style.css' // 必须引入样式

const app = createApp(App)

app.use(VueToolbox, {
  toolCodes: [],        // 工具 code 列表；空数组 = 展示全部
  defaultMode: 'window', // 默认展示方式：window | drawer | modal
  theme: 'auto',         // 主题：auto（默认自适应）| light | dark（强制）
})
app.mount('#app')

<!-- App.vue -->
<template>
  <ToolboxProvider>
    <!-- 悬浮球入口（放在页面任意位置） -->
    <ToolboxFloatingBall />
  </ToolboxProvider>
</template>

方式二：组件方式（更灵活）

<script setup lang="ts">
import { ref } from 'vue'
import { ToolboxProvider, ToolboxFloatingBall } from 'nl-toolbox'

// 命令式 API 引用
const toolboxRef = ref<InstanceType<typeof ToolboxProvider> | null>(null)

// 静态指定工具（空数组 = 全部）
const toolCodes = ref<string[]>(['calculator', 'json-format', 'timestamp'])
</script>

<template>
  <ToolboxProvider
    ref="toolboxRef"
    :tool-codes="toolCodes"
    :default-mode="'window'"
    :theme="'auto'"
  >
    <ToolboxFloatingBall />

    <!-- 自定义按钮唤出（不使用悬浮球时） -->
    <button @click="toolboxRef?.open()">打开工具箱</button>
    <button @click="toolboxRef?.openTool('calculator', 'modal')">以模态框打开计算器</button>
  </ToolboxProvider>
</template>

CDN 纯 HTML 引用（无需构建工具）

nl-toolbox 提供 UMD 构建（dist/index.umd.js，挂载全局变量 window.NlToolbox），可在纯 HTML 页面中直接使用，无需 npm / vite / webpack。

<!DOCTYPE html>
<html>
  <head>
    <!-- ① Vue 3 全局构建（含模板编译器） -->
    <script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
    <!-- ② nl-toolbox UMD 构建 -->
    <script src="https://unpkg.com/nl-toolbox/dist/index.umd.js"></script>
    <!-- ③ nl-toolbox 样式（含全部风格预设） -->
    <link rel="stylesheet" href="https://unpkg.com/nl-toolbox/dist/style.css" />
  </head>
  <body>
    <div id="app"></div>
    <script>
      // 从全局变量取组件与插件
      const { ToolboxProvider, ToolboxFloatingBall } = NlToolbox

      Vue.createApp({
        template: `
          <ToolboxProvider preset="win11">
            <ToolboxFloatingBall />
          </ToolboxProvider>
        `,
        components: { ToolboxProvider, ToolboxFloatingBall },
      })
        .use(NlToolbox.default, { toolCodes: [] }) // 安装插件（注册内置工具）
        .mount('#app')
    </script>
  </body>
</html>

完整示例见 examples/cdn.html（含四种风格预设切换）。若使用国内 CDN，可将 unpkg.com 换成 cdn.jsdelivr.net。

风格预设：Win11 / macOS / Win98 / 像素

组件外观由 风格预设（preset） 决定，四种内置预设是完全不同的设计语言：

| preset | 设计语言 | 亮点 | |---|---|---| | win11（默认） | 圆角、柔和阴影、扁平现代 | Windows 11 文件管理器交互 + 视觉 | | mac | 大圆角、毛玻璃、SF Pro | 交通灯窗口按钮（红黄绿圆点）、毛玻璃标题栏/卡片/任务栏、标题居中 | | win98 | 经典银灰、3D 立体边框、直角 | 蓝色渐变标题栏、按钮/输入框立体凸起凹陷（bevel）、硬投影 | | pixel | 8-bit 像素、粗黑边框、硬投影 | 像素字体、黑底白字标题栏（暗色反转）、按钮按下像素位移反馈 |

<!-- 组件方式指定预设 -->
<ToolboxProvider preset="mac">...</ToolboxProvider>

<!-- 插件方式（全局默认） -->
app.use(VueToolbox, { preset: 'pixel' })

<!-- 运行时动态切换 -->
<ToolboxProvider :preset="currentPreset">...</ToolboxProvider>

预设与亮暗正交组合（如 mac + dark、win98 + light），theme 仍为 'auto'（默认跟随系统实时切换）/ 'light' / 'dark'（强制覆盖）。

自定义风格 preset

主题制作手册：docs/主题制作手册.md（全部 CSS 变量、结构类名钩子、自建指南）
主题模板文件（可复制示例）：src/styles/presets/_template.css
现成示例：src/styles/presets/{win11,mac,win98,pixel}.css

type MyPreset = ToolboxPreset | 'retro-green' // 扩展类型
<ToolboxProvider preset="retro-green">...</ToolboxProvider>

第一批内置工具 code 码表

code 码 = 后端下发的唯一标识。toolCodes 为空时展示全部；下表为第一批 27 个内置工具。

办公工具 `office`（10）

| code | 名称 | 默认方式 | 功能要点 | |---|---|---|---| | calculator | 计算器 | window | 四则/百分比/键盘输入；保留最近 30 次完整计算过程，复制/导出 TXT、CSV | | rmb-uppercase | 人民币大小写转换 | window | 小写金额 ↔ 中文大写（壹贰叁…元角分整），负数/0/小数，反向解析 | | date-calc | 日期计算器 | window | 日期差值、日期加减 N 天/月/年、星期与当月天数 | | workday-calc | 工作日计算器 | window | 自然日/工作日统计、到期日推算，内置 2025-2026 法定节假日表（可覆盖） | | duration-calc | 时长计算器 | window | 时分秒 ↔ 小时/分钟互转、打卡工时计算（含午休扣除） | | unit-convert | 单位换算 | window | 长度/重量/温度/面积/体积/数据存储单位互转 | | text-stats | 文字统计 | window | 字数/字符/行数/段落/中英文字符/数字/标点/字节数 | | text-batch | 批量文本处理 | window | 去重/排序/去空白/加行号/批量替换/大小写 | | text-diff | 文本对比 | window | 两段文本并排差异高亮（LCS 算法） | | csv-json | CSV/JSON 互转 | window | CSV ↔ JSON，分隔符可选、表头模式、错误定位 |

开发工具 `dev`（11）

| code | 名称 | 默认方式 | 功能要点 | |---|---|---|---| | json-format | JSON 格式化 | window | 格式化/压缩/校验（错误行列定位）/键排序 | | timestamp | 时间戳转换 | window | 时间戳 ↔ 格式化时间，秒/毫秒自动识别，多格式预设 | | base64 | Base64 编解码 | window | 文本 ↔ Base64（UTF-8 安全，支持中文） | | url-codec | URL 编解码 | window | encode/decodeURIComponent，组件/整串两种模式 | | hash | 哈希计算 | window | MD5 / SHA1 / SHA256 实时计算（纯 JS 实现） | | regex | 正则测试 | window | 实时匹配高亮、分组结果、常用正则速查 | | case-convert | 命名转换 | window | camelCase / PascalCase / snake_case / kebab-case / CONSTANT_CASE | | hex-convert | 进制转换 | window | 2/8/10/16 进制互转，支持负数与小数 | | uuid | UUID 生成 | window | UUID v4 批量生成，大写/去横线格式 | | color | 颜色转换 | window | HEX / RGB / HSL 互转、透明度、取色预览 | | validator | 格式校验 | window | 手机号/邮箱/身份证/银行卡/URL/IP 等批量校验 |

财务税务 `finance`（4）

| code | 名称 | 默认方式 | 功能要点 | |---|---|---|---| | tax-calc | 个税计算器 | window | 中国个税（累计预扣法），逐月明细与全年汇总 | | salary-calc | 工资计算器 | window | 税前税后互算，五险一金比例/基数上限可配 | | overtime-calc | 加班费计算 | window | 加班时长 → 加班费（平日 1.5 / 休息日 2 / 节假日 3 倍可配） | | bank-card | 银行卡校验 | window | Luhn 校验、4-4-4-4 格式化、发卡行识别 |

人事行政 `hr`（2）

| code | 名称 | 默认方式 | 功能要点 | |---|---|---|---| | id-card | 身份证解析 | window | 15/18 位解析（地区/生日/性别/校验码）、18↔15 互转 | | password-gen | 密码生成器 | window | 强密码批量生成（长度/字符集/排除易混淆）、强度评估 |

后端角色配置（按 code 下发工具）

规则：toolCodes 为空数组 = 展示全部已注册工具；非空 = 只展示列表中的工具（按顺序）。

方案一：静态配置

// 不同角色配置不同工具
const ROLE_TOOLS: Record<string, string[]> = {
  admin: [], // 空 = 全部
  dev: ['json-format', 'timestamp', 'base64', 'hash', 'regex'],
  finance: ['tax-calc', 'salary-calc', 'overtime-calc', 'bank-card'],
  office: ['calculator', 'rmb-uppercase', 'workday-calc', 'csv-json'],
}

方案二：异步从后端拉取（推荐）

<script setup lang="ts">
import { ToolboxProvider, ToolboxFloatingBall } from 'nl-toolbox'

// 后端按当前用户角色返回 code 列表
async function loadTools(): Promise<string[]> {
  const res = await fetch('/api/my-tools') // 后端根据登录用户角色返回
  const data = await res.json()
  // 例如：{ "tools": ["calculator", "json-format", ...] }
  return data.tools
}
</script>

<template>
  <ToolboxProvider :load-tools="loadTools">
    <ToolboxFloatingBall />
  </ToolboxProvider>
</template>

后端示例：GET /api/my-tools 返回当前登录用户的角色（admin / dev / finance / employee）对应的工具 code 列表。加载失败时自动回退到静态 toolCodes。

主题：自适应亮暗 + 强制覆盖

// 主题三态
theme: 'auto'   // 默认：跟随系统亮暗，并实时监听系统切换（matchMedia）
theme: 'light'  // 强制亮色：忽略系统偏好
theme: 'dark'   // 强制暗色：忽略系统偏好

<!-- 组件方式传值 -->
<ToolboxProvider :theme="'dark'">...</ToolboxProvider>

<!-- 运行时动态切换 -->
<ToolboxProvider :theme="userTheme">...</ToolboxProvider> <!-- userTheme: ref('auto' | 'light' | 'dark') -->

主题定制（CSS 变量）

所有组件使用 CSS 变量取色，宿主可直接覆盖：

/* 覆盖默认主题变量（作用在 .nltb-root 容器） */
.nltb-root {
  --nltb-primary: #ff5722;          /* 主色 */
  --nltb-bg: #f8f8f8;               /* 背景 */
  --nltb-radius: 8px;               /* 圆角 */
  /* 更多变量见 src/styles/index.css */
}

三种展示方式

| 方式 | 说明 | |---|---| | window（默认） | 模拟小窗口，交互对齐 Win11 文件管理器：拖拽标题栏移动、八方向缩放（四边+四角，最小 320×240）、最小化（收到底部任务栏条）/最大化/还原/关闭、双击标题栏最大化、点击窗口置顶（z-index 层级） | | drawer | 右侧抽屉滑入，遮罩/Escape 关闭 | | modal | 居中模态框，遮罩/Escape 关闭 |

小窗口交互细节（始终单窗口）

不关闭导航：从气泡卡片选择工具后，卡片保持打开（导航始终可用），可继续点选其它工具
始终只有一个窗口：连续选择工具复用同一个窗口切换内容，永远不会出现第二个小窗口
返回列表：窗口内容区顶部提供"← 返回列表"导航，可在窗口内直接切换工具（无需关闭窗口/重新打开卡片）
宫格排版：气泡卡片与窗口内列表均以宫格瓦片展示工具（图标 + 名称），非纵向列表
拖拽记忆：窗口拖拽移动/缩放后，位置与尺寸按工具 code 持久化到 localStorage（{prefix}:window-bounds），下次打开该工具自动恢复

// 全局默认（插件选项或 Provider prop）
defaultMode: 'window' | 'drawer' | 'modal'

// 按工具单独配置（注册工具时指定）
{
  code: 'calculator',
  defaultMode: 'modal',
  // ...
}

// 打开时临时指定
toolboxRef.openTool('calculator', 'drawer')

自定义工具

import { registerTool } from 'nl-toolbox'
import MyTool from './MyTool.vue'

// 注册自定义工具（也可在后端下发时配合使用）
registerTool({
  code: 'my-custom-tool',          // 唯一 code（后端按角色下发它即可）
  name: '我的自定义工具',
  description: '一句话描述',
  category: 'office',              // 内置分类或自定义字符串
  keywords: ['别名1', 'alias'],
  icon: { type: 'icon', value: 'settings' }, // 本版本统一 icon；type: 'img' 时 value 为图片 URL
  defaultMode: 'window',
  defaultSize: { width: 500, height: 400 },
  component: MyTool,               // 任意 Vue 组件
})

图标规范：{ type: 'icon', value: '图标名' } 使用内置 SVG 图标（settings/toolbox/search 等，见 src/icons/index.ts）；{ type: 'img', value: 'https://...' } 使用图片（已支持，本版本内置工具全部使用 icon）。

API 文档

ToolboxProvider Props

| Prop | 类型 | 默认 | 说明 | |---|---|---|---| | toolCodes | string[] | [] | 工具 code 列表；空数组 = 全部 | | loadTools | () => Promise<string[]> | — | 异步从后端拉取当前角色可用工具 | | defaultMode | 'window' \| 'drawer' \| 'modal' | 'window' | 全局默认展示方式 | | preset | 'win11' \| 'mac' \| 'win98' \| 'pixel' | 'win11' | 风格预设 | | storagePrefix | string | 'nl-toolbox' | localStorage 前缀（多实例隔离） | | historyLimit | number | 20 | 使用历史上限 | | theme | 'auto' \| 'light' \| 'dark' | 'auto' | 主题（自适应/强制覆盖） | | zIndex | number | 9990 | 浮层基础层级 |

ToolboxProvider Events

| 事件 | 载荷 | 说明 | |---|---|---| | open / close | — | 气泡卡片打开/关闭 | | toolOpen | { code, mode } | 打开某工具 | | toolClose | { code } | 关闭工具容器 | | historyChange | HistoryItem[] | 使用历史变化 | | favoritesChange | string[] | 收藏变化 | | themeChange | 'light' \| 'dark' | 主题变化 |

命令式 API（provider ref）

| 方法 | 说明 | |---|---| | open() / close() / toggle() | 气泡卡片开/关/切换 | | openTool(code, mode?) | 打开指定工具（mode 可临时覆盖展示方式；小窗口模式下复用同一窗口） | | registerTool(meta) / unregisterTool(code) | 动态注册/注销工具 | | closeAll() | 关闭全部浮层 | | getTools() | 当前可用工具列表 | | isCardOpen() | 气泡卡片是否打开 | | getWindows() | 当前打开的窗口实例列表 |

类型导出

import type {
  ToolMeta, ToolIcon, DisplayMode, ThemeMode,
  ToolboxPluginOptions, HistoryItem, ToolWindowState,
} from 'nl-toolbox'

JS / TS 双版本说明

源码：TypeScript 编写，全部带详细中文注释（发布包内包含 src/）
JS 用户：直接 import VueToolbox from 'nl-toolbox' 使用编译产物（ESM .mjs / CJS .cjs / UMD .umd.js）
TS 用户：exports.types 自动指向完整 .d.ts，组件 Props/Events/Exposed 全部有类型提示（兼容新旧 moduleResolution：exports 映射 + 顶层 types 字段）
需要 TS 源码：可 import ... from 'nl-toolbox/src/...' 自行编译
无构建工具：CDN 引用 dist/index.umd.js（见 CDN 章节）

开发与发布

pnpm install        # 安装依赖
pnpm dev            # 启动 playground 演示（http://localhost:5173）
pnpm test           # 运行测试（vitest，94 个用例）
pnpm build          # 构建：dist/index.mjs + index.cjs + style.css + types/*.d.ts
pnpm pack:check     # 预览发布包内容（npm pack --dry-run）
pnpm publish        # 发布到 npm（需先登录 npm login）

目录结构

src/
├── index.ts              # 包入口（插件 + 组件 + 类型 + 注册表 API）
├── types.ts              # 公共类型
├── registry.ts           # 工具注册表（code 码过滤）
├── constants.ts          # 常量（分类/默认值/preset）
├── context.ts            # Provider 上下文（provide/inject）
├── utils/                # 27 个工具的纯函数逻辑（全部单测覆盖）
├── composables/          # 主题/存储/历史/收藏/搜索/窗口管理
├── components/           # Provider / 悬浮球 / 卡片 / 窗口 / 抽屉 / 模态框 / 任务栏
├── icons/                # 内置 SVG 图标集
├── styles/
│   ├── index.css         # 样式入口（组装 base + 各 preset）
│   ├── base.css          # 与风格无关的基础样式
│   └── presets/          # 风格预设（win11/mac/win98/pixel）+ _template.css 主题模板
└── tools/                # 27 个内置工具组件（每工具一个目录）
docs/
├── 主题制作手册.md         # 主题制作手册（变量总表/结构钩子/自建指南）
examples/
└── cdn.html              # CDN 纯 HTML 引用示例

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

nl-toolbox

目录

特性

安装

快速开始

方式一：插件方式（推荐）

方式二：组件方式（更灵活）

CDN 纯 HTML 引用（无需构建工具）

风格预设：Win11 / macOS / Win98 / 像素

自定义风格 preset

第一批内置工具 code 码表

办公工具 office（10）

开发工具 dev（11）

财务税务 finance（4）

人事行政 hr（2）

后端角色配置（按 code 下发工具）

方案一：静态配置

方案二：异步从后端拉取（推荐）

主题：自适应亮暗 + 强制覆盖

主题定制（CSS 变量）

三种展示方式

小窗口交互细节（始终单窗口）

自定义工具

API 文档

ToolboxProvider Props

ToolboxProvider Events

命令式 API（provider ref）

类型导出

JS / TS 双版本说明

开发与发布

目录结构

License

办公工具 `office`（10）

开发工具 `dev`（11）

财务税务 `finance`（4）

人事行政 `hr`（2）