workdesktop-ai

文档版本：V_1.5 ｜ 创建时间：2026-09-16 22:03:47 ｜ 最后修改时间：2026-10-14 适用对象：使用本库的开发者（人类阅读；AI 助手每次开发前请先阅读 ai-router.md） 核心目标：帮助开发者快速了解、安装并上手 WorkDesktop AI 文档简述：项目门面说明，覆盖特性、安装、三种引入方式、全局配置、组件总览、请求核心、Hooks 与本地开发指引。当前库版本：v1.2.6

本项目的初衷是想让AI在做前端设计的时候拥有更加可控，更加稳定的输出结果。

如果你是使用AI来构建前端，你只需要在开始构建时加上提示词“使用workdesktop-ai组件库进行构建”即可。

WorkDesktop AI 是一套面向企业后台管理场景的 Vue 3 组件库，在 ElementPlus 之上做「场景化复合封装」：

• 列表一体化：DataGrid 一个组件完成「查询 + 分页 + 工具栏 + 表格 + 列设置 + 卡片/表格切换」；
• 请求一体化：内置 axios 封装，自动完成 { code, message, data } 解封包、Loading、错误提示；
• AI 编码友好：HTML 模板渲染优先，组件用标签即所得，TypeScript 类型完整；仓库根目录附带面向 AI 的 ai-router.md 场景路由与 ai-api/ 路由化 API 参考（主路由 README.md + 每组件一个子文件，自动生成、随包发布，AI 按组件名定位只读一个文件，无需翻源码）；
• 双入口：既支持 npm 工程化使用，也支持浏览器 <script> 直引（UMD），无需构建。

特性

安装

npm install workdesktop-ai element-plus @element-plus/icons-vue

vue（^3.3）与 element-plus（^2.5）为 peer 依赖，由宿主项目安装；axios 已打进产物。

快速开始

npm 全量引入

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import zhCn from 'element-plus/es/locale/lang/zh-cn'

import WorkDesktop from 'workdesktop-ai' // Vue 插件：全量注册 29 个组件
import 'workdesktop-ai/style.css'

const app = createApp(App)
app.use(ElementPlus, { locale: zhCn })
app.use(WorkDesktop, {
  request: { urlPrefix: '/api' } // 可选的全局配置，见下文「全局配置」
})
app.mount('#app')

模板中直接写组件：

<wd-search-panel head-refresh-datagrid filter="main" collapsible>
  <template #default="{ model }">
    <el-form-item label="姓名">
      <el-input v-model="model.name" placeholder="模糊搜索姓名" clearable />
    </el-form-item>
  </template>
</wd-search-panel>

<wd-data-grid api="/user/list" :active="true" filter="main">
  <el-table-column prop="id" label="ID" width="80" />
  <el-table-column prop="name" label="姓名" min-width="120" />
  <el-table-column prop="dept" label="部门" width="110" />
  <el-table-column prop="createTime" label="创建时间" min-width="120" />
</wd-data-grid>

搜索面板与表格配置相同 filter，点击「查询」即自动刷新表格并重置到第一页 —— 无需写任何联动代码。

按需引入

方式一：主入口命名导出（tree-shaking 由构建工具完成）：

import { createApp } from 'vue'
import { WdDataGrid, WdDataForm } from 'workdesktop-ai'
import 'workdesktop-ai/style.css'

const app = createApp(App)
app.component(WdDataGrid.name, WdDataGrid)
app.component(WdDataForm.name, WdDataForm)

方式二：子路径按需入口（27 个子路径，产物与样式都可按组件粒度引入）：

import WdDataGrid from 'workdesktop-ai/data-grid'
import 'workdesktop-ai/base.css'            // 基础样式（必引）
import 'workdesktop-ai/data-grid/style.css' // 该组件的样式

• 子路径命名规则为组件名的 kebab-case：data-grid / data-form / drawer-button / search-panel / station 等；
• 其中 14 个组件带独立 style.css（data-grid、data-form、editable-grid、drawer、iframe、panel、viewer、station、search-panel、search-item、form-item、auto-complete、image-upload、tips），其余组件无额外样式；
• 注意：WdPopconfirmButton 没有子路径入口，只从主入口 import { WdPopconfirmButton } from 'workdesktop-ai' 引入。

纯 script 直引（UMD，无需构建）

在 HTML 中依次引入 Vue3、ElementPlus、图标库与本库产物：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <link rel="stylesheet" href="https://unpkg.com/element-plus/dist/index.css" />
  <link rel="stylesheet" href="./dist/style.css" />
</head>
<body>
  <div id="app">
    <wd-data-grid :data-source="rows" :active="false" with-index>
      <el-table-column prop="name" label="姓名" />
      <el-table-column prop="age" label="年龄" width="90" />
    </wd-data-grid>
  </div>

  <script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
  <script src="https://unpkg.com/element-plus/dist/index.full.min.js"></script>
  <script src="https://unpkg.com/@element-plus/icons-vue/dist/index.iife.min.js"></script>
  <!-- UMD 产物：挂载到 window.WorkDesktop -->
  <script src="./dist/index.umd.js"></script>
  <script>
    // 全局配置（可选，在 install 之前声明即可）
    window.workDesktopConfig = {
      request: { urlPrefix: '/api' },
      theme: { colors: { primary: '#2f6bff' } }
    }
    const { WorkDesktop } = window.WorkDesktop
    const app = Vue.createApp({
      setup() { return { rows: [{ name: '张三', age: 28 }] } }
    })
    app.use(ElementPlus)
    app.use(WorkDesktop)
    app.mount('#app')
  </script>
</body>
</html>

全局配置

配置按 默认层 → 全局层 → 组件 props 三级覆盖（deep merge）。全局层可通过插件的第二个参数，或在纯 script 场景下通过 window.workDesktopConfig 声明：

app.use(WorkDesktop, {
  // HTTP
  request: {
    urlPrefix: '/api',
    axiosConfig: { timeout: 15000 }, // 透传给 axios
    loading: { enable: true },
    dedup: true, // 并发相同请求合并去重（method+url+params 一致只发一次）
    transform: {
      requestInterceptor: (config) => config, // 发请求前改写 axios 配置
      responseInterceptor: (res) => res // 拿到响应后改写
    }
  },
  // 响应约定：{ code, message, data }，code >= successCode 视为成功
  response: { successCode: 0 },
  // 每个组件的默认 props
  page: {
    componentDefault: {
      WdDatagrid: { withPager: true, pageSize: 20 },
      WdDataForm: { submitApi: '/save' }
    }
  },
  // 主题：skin 一键套用预设皮肤（11 套可选），colors / cssVars 在其上继续覆盖
  // 覆盖优先级：cssVars > colors > skin；colors 改动会自动推导 El 浅/深色阶
  theme: { skin: 'default', colors: { primary: '#2f6bff' }, cssVars: { '--wd-radius': '8px' } }
})

组件级 props 优先级最高，三者按需覆盖。运行期也提供 API：setGlobalConfig / mergeConfig / getGlobalConfig / resetConfig。

注意：配置在组件挂载时读取一次并缓存，运行中修改全局配置只影响之后新挂载的组件；已挂载组件可通过变更 :key 强制重建。

与 ElementPlus 的边界

• 基础控件（按钮、输入框、下拉、表格单元格等）继续使用 ElementPlus，不重复造轮子；
• 本库只做场景化复合与业务约定的封装，宿主对 ElementPlus 的使用方式完全不受影响。

组件总览（29 个）

手动调用请求（RequestAPI）

本库所有请求类组件（DataGrid / DataForm / 按钮组 / 输入选择 / 上传等）都基于同一个请求核心开发，该核心对外公开，开发者可以在组件外手动调用 API 请求代码：

import { RequestAPI, request, type ApiResult } from 'workdesktop-ai'

// 方式一：全局单例（与组件共用同一套 urlPrefix / loading / 提示 / 解封逻辑）
const result: ApiResult = await request.get('/user/list', { currentPage: 1, pageSize: 20 })
if (result.success) {
  console.log(result.data) // 已解封的业务 data
}

// 方式二：new RequestAPI() 自建独立实例（可传 axios 配置：baseURL / timeout / headers 等）
const customApi = new RequestAPI({ baseURL: '/other-api', timeout: 20000 })
await customApi.post('/user/save', { name: '张三' })

// 方法一致：get / post / put / delete / request；业务失败 resolve(success=false)，仅网络异常 reject

reqOptions 可覆盖项：{ showLoading?, showTips?, tipsConfig?, axiosConfig?, signal?, dedup? }；可用 request.on(handler) 订阅 apiBefore / apiSuccess / apiFail / apiException / apiAfter 请求事件。

Hooks

import { useRequest, useDataGrid, useEventBus } from 'workdesktop-ai'

// 请求：自动 loading / 错误处理
const { data, loading, run, refresh } = useRequest('/user/detail', { immediate: true })

// 表格数据流
const grid = useDataGrid({ api: '/user/list', immediate: true })
await grid.search({ name: '张' })

AI 编码助手

使用 Copilot / Cursor / Trae 等 AI 助手开发时，让它每次开发前先阅读 ai-router.md——编码场景指导的路由索引，按任务命中场景（分页列表 / 表单 / 详情 / 树 / 批量 / 弹窗选择器 / 导入导出）定位到 scenarios/ 目录下对应子文件阅读，避免通读全篇。需要组件的精确 API（props/emits/slots/方法签名/自定义类型）时查 ai-api/ 路由——主路由 README.md 按组件名在索引中定位，只打开对应子文件（如 wd-select.md），不要通读整个目录。它由文档站元数据 docs/src/api-meta/ 经 npm run gen:ai-api 自动生成（prepack 钩子保证发版前自动重生成），覆盖全部 30 个组件与全局配置 / HTTP 请求核心 / 皮肤主题 3 个基础设施 API，无需逐个翻组件源码。

本地开发

npm install        # 安装依赖
npm run dev        # 本地 Playground（vite）
npm run docs:dev   # 文档站本地预览
npm test           # 单元 / 集成测试
npm run test:coverage  # 覆盖率（阈值：lines/funcs ≥ 80%，branches ≥ 70%）
npm run typecheck  # 类型检查（vue-tsc）
npm run build      # 产出 ESM + UMD + .d.ts 到 dist/

项目示例与文档站启动

文档站

项目内置独立文档站（Vue Vite 应用），包含组件完整文档、API 表格、可运行代码示例：

cd code
npm install      # 如果已安装过依赖可跳过
npm run docs:dev # 启动文档站，默认 http://localhost:5003

打开浏览器访问即可查看每个组件的 API 与在线可运行示例。所有示例均可「查看代码」复制粘贴直接使用。

纯 HTML UMD 示例

项目内置 code/examples/index.html，可直接打开浏览器查看纯 script 标签引入用法（UMD 全局版本）。也可以启动一个简单 HTTP 服务器预览：

# PowerShell 自带 Python，无需额外安装
cd code
python -m http.server 8000
# 打开浏览器访问 http://localhost:8000/examples/index.html

::  cmd 下也一样
cd code
python -m http.server 8000

Playground

npm run dev 可启动组件调试游乐场，用于开发测试新组件或修改现有组件。

参与贡献

欢迎提交 Issue 与 PR，详见 CONTRIBUTING.md。版本变更记录见 CHANGELOG.md。

License

MIT

版本变化

• V_1.6（2026-10-14）：相对 V_1.5 的变化：
  1. ai-api 从单文件改为路由目录 ai-api/：主路由 README.md（阅读约定 + Element Plus 透传规则 + 按 8 分组列出的组件索引）+ 30 个组件与 3 个基础设施页各一个子文件（如 wd-select.md / use-config.md），AI 按组件名定位只读一个子文件，不再通读 227.5kB 的单文件；
  2. package.json 的 files 由 ai-api.md 改为 ai-api（目录随包发布），prepack 钩子逻辑不变；
  3. 删除单文件 ai-api.md；特性列表、「AI 编码助手」章节改指 ai-api/ 路由。
• V_1.5（2026-10-14）：相对 V_1.4 的变化：
  1. 新增 ai-api.md 聚合 API 参考：由 docs/src/api-meta/ 元数据经 scripts/gen-ai-api.mjs（npm run gen:ai-api）自动生成，覆盖 30 个组件的 Props/Events/Slots/暴露方法/数据类型与 3 个基础设施 API，AI 查精确 API 不再需要读组件源码；
  2. package.json 的 files 新增 ai-api.md，scripts 新增 gen:ai-api 与 prepack 钩子（npm pack/publish 前自动重生成，保证与源码同步）；
  3. 特性列表、「AI 编码助手」章节改指 ai-api.md；顺手修正特性表组件数 29 → 30、头部库版本号对齐当前 package.json v1.2.6。
• V_1.4（2026-10-14）：相对 V_1.3 的变化：
  1. 删除 llms.txt，AI 阅读完全由 ai-router.md + scenarios/ 场景子路由承担（原 llms.txt 承载的"精确 API 查阅"改道组件源码 src/components/**/*.vue 与随包类型声明 dist/types/）；
  2. 特性列表与「AI 编码助手」章节移除 llms.txt 链接；
  3. package.json 的 files 移除 llms.txt。
• V_1.3（2026-10-14）：相对 V_1.2 的变化：
  1. AI 路由文件由 scenarios/README.md 调整为包根目录独立文件 ai-router.md（主路由不再写在 README 里，README 仅告知 AI 每次开发前先阅读该文件）；
  2. 头部适用对象与「AI 编码助手」章节链接同步指向 ai-router.md；
  3. package.json 的 files 新增 ai-router.md。
• V_1.2（2026-10-14）：相对 V_1.1 的变化：
  1. 「AI 编码助手」章节重写：AI 第一阅读入口由 llms.txt 改为 scenarios/README.md 路由文件（编码场景指导按场景拆分为 9 个子路由，AI 按任务命中场景定位阅读）；llms.txt 保留为组件 API 全量事实参考；
  2. 头部适用对象同步更新；
  3. package.json 的 files 新增 scenarios 目录，npm 发布时随包分发。
• V_1.1（2026-09-24 13:44:41）：对齐库版本 v1.1.1。相对 V_1.0 的变化：
  1. 头部库版本 v1.0.2 → v1.1.1；
  2. 特性表「开箱主题」补充 1.1.1 新增的 11 套预设皮肤（theme.skin）与 El 派生色阶自动推导；
  3. 全局配置示例 theme 补充 skin 用法与覆盖优先级说明；
  4. 特性表「测试保障」用例数按当前真实运行结果更新（106 → 237）。
• V_1.0（2026-09-16 22:03:47）：首次建立带版本标注的 README。相对旧版的变化：
  1. 组件总数 25 → 28（按 src/components/index.ts 实际导出核对）；
  2. 「组件总览」按源码分组重排：WdViewer 归入数据组、WdSearchPanel/WdFormItem/WdSearchItem 归入表单组，补齐旧版遗漏的 WdRequester、WdFormItem、WdSearchItem、WdDialogButton、WdPopconfirmButton、WdStation；
  3. 「按需引入」新增子路径入口方式（27 个子路径 + 14 个独立样式说明，标注 WdPopconfirmButton 仅主入口）；
  4. 特性表补充「并发去重」「27 个组件子路径入口」，Hooks 列表补齐 useGlobalConfig / useGlobalState；
  5. 新增「AI 编码助手」章节，指引阅读仓库根目录的 llms.txt；
  6. reqOptions 补充 dedup 项；全局配置示例补充 dedup，并新增「配置挂载时缓存」注意提示；
  7. 头部新增文档版本信息块（版本 / 时间 / 适用对象 / 目标 / 简述），文尾新增本「版本变化」章节。