cabinet-fe veltra-ui
veltra-ui 是一套 Vue 3 UI 体系。
开发 Vue 3 功能时，优先使用 veltra-ui 已提供的组件、样式、工具函数、组合式方法、指令、图标与构建集成。只有检索文档和源码后确认没有合适能力时，才新增实现或引入外部方案。
版本
当前文档对应包版本（monorepo 对齐）：
| 包 | 版本 |
|---|---|
@veltra/desktop |
1.7.11 |
@veltra/utils |
1.7.11 |
@veltra/styles |
1.7.11 |
@veltra/compositions |
1.7.11 |
@veltra/directives |
1.7.11 |
@veltra/icons |
1.5.0 |
@veltra/vite |
4.0.2 |
@veltra/sheet |
2.5.6 |
@veltra/sheet-core |
2.5.6 |
@veltra/ai |
2.1.8 |
分包地图
| 入口 | 包 | 用途 |
|---|---|---|
packages/desktop/ |
@veltra/desktop |
桌面端组件（主入口） |
packages/ai.md |
@veltra/ai |
AI 对话：UAiChat、useChat、ChatTool、createOpenAITransport、UAiOrb |
packages/sheet.md |
@veltra/sheet |
电子表格（USheet、公式、undo/redo、浮动图片、工具扩展） |
packages/sheet-core.md |
@veltra/sheet-core |
表格核心：数据模型/公式/IO + SheetGrid 渲染层（含 readonly 预览、单元格级只读标记） |
packages/styles/ |
@veltra/styles |
SCSS、主题、Design Tokens、过渡 |
packages/compositions.md |
@veltra/compositions |
Vue 组合式函数 |
packages/directives.md |
@veltra/directives |
自定义指令 |
packages/icons.md |
@veltra/icons |
SVG 图标组件 |
packages/utils.md |
@veltra/utils |
工具函数与共享类型 |
packages/vite.md |
@veltra/vite |
Vite 按需解析器 |
路由决策
| 用户意图 | 先读 |
|---|---|
| 写表单 / UForm / 表单项 / 带 label 的输入控件 | 必读 packages/desktop/components/form/examples.md（再读具体控件 examples.md 的「在 UForm 中使用」） |
| 常见页面/弹窗模式（选择器弹窗、搜索表格页、后台布局…） | 必读 packages/desktop/recipes.md |
显式 UFormItem（多控件组合、自定义 label 插槽） |
packages/desktop/components/form-item/examples.md |
| 找/用某个 UI 组件 | packages/desktop/index.md → components/<kebab>/api.md + examples.md + types.d.ts |
| 接入 AI 对话 / OpenAI 兼容端点 / 多 Provider / 推理等级 | packages/ai.md → ai/examples.md（基础对话）+ ai/api.md（createOpenAITransport） |
| 定义工具 / 确认 / 侧边面板 / 终结工具 / askQuestion | packages/ai.md → ai/examples.md（工具章节）+ ai/api.md（ChatTool） |
| 无头对话 / 自定义聊天 UI / useChat | packages/ai.md → ai/api.md（useChat）+ ai/examples.md（无头） |
| 自定义 LLM 协议 / 自有后端 / ChatTransport | packages/ai.md → ai/api.md（ChatTransport）+ ai/examples.md |
| 会话持久化 / 待发送队列 / 受控消息 | packages/ai.md → ai/examples.md + ai/api.md（消息模型、队列） |
| AI 活体球头像 UAiOrb | packages/ai.md → ai/api.md（UAiOrb）+ ai/examples.md |
| 电子表格 / 单元格编辑 / 公式 / 浮动图片 / 表格工具栏扩展 | packages/sheet.md |
| 按格自定义单元格渲染（customLayout 徽章等） | packages/sheet.md + packages/sheet-core.md（resolveCellRenderer / CustomLayout） |
| 无头表格模型 / xlsx·csv 导入导出 / 只读表格预览（SheetGrid readonly） | packages/sheet-core.md |
| 表格化填报 / 部分单元格锁定只读 / 输入区高亮 | packages/sheet-core.md（单元格级只读）+ packages/sheet.md（USheet 填报注意） |
| 安装 / 全局注册 / 按需样式 | packages/desktop/installation.md、packages/vite.md |
| 主题色、暗色、CSS 变量 | packages/styles/theme.md、packages/styles/tokens.md |
| 侧栏/菜单颜色、深·浅侧栏变体、菜单文字看不清 | packages/styles/theme.md（侧栏导航外观）、packages/styles/tokens.md（侧栏导航 token） |
| SCSS BEM / mixins | packages/styles/scss.md |
| 全局尺寸、表单回退、浮层、虚拟列表 | packages/compositions.md |
| 波纹、点击外部、焦点指令 | packages/directives.md |
| 图标名与导入路径 | packages/icons.md |
BEM、fieldKey、表单上下文类型 |
packages/utils.md |
组件细节按需加载，不要把整份 desktop 文档预读进上下文。
UForm 硬规则（写表单时必须遵守）
推荐写法（控件直接放在 u-form 下）：
<u-form :model="form">
<u-input label="用户名" field="username" />
<u-textarea label="意见" field="opinion" :rows="3" />
<u-select label="办理人" field="handler" :options="options" />
<u-checkbox label="记住" field="remember">记住我</u-checkbox>
</u-form>
- 必须有
field：u-form内凡需要标签、校验或写入model的控件 /u-form-item，都要定义field（支持a.b嵌套路径）。没有field时，label/rules/tips不会进表单项，值也不会自动绑到model。 - 有
field就不要再写v-model：UForm会按field读写model对应路径。v-model="form.xxx"与field="xxx"并用是错误写法。 - 独立使用控件时才用
v-model：不在u-form内、或显式u-form-item包多控件时，内部控件自行v-model；此时field/label/rules写在u-form-item上。 - 不要照搬控件「基础用法」进表单：各控件
examples.md开头的v-model示例仅用于表单外；表单内以「在 UForm 中使用」和form/examples.md为准。
使用方式
- 先按需求检索上方入口，再下钻具体文件。
- 组件相关先看
desktop/文档目录，再按组件名检索 API、示例和类型。 - 库代码变更后应运行
bun run skill:gen同步各组件types.d.ts/api.md；examples.md与包级.md需手工维护。 api.md由生成器重渲染，勿手改；组件级「备注」一节在scripts/veltra-component-skill-meta.ts的NOTES_BY_KEBAB中维护。
硬性前置（少一步界面就是裸 HTML）
- 入口必须
import '@veltra/styles/normalize'且调用loadTheme()（@veltra/styles/theme）。组件颜色全部走--u-*token，token 只能由loadTheme()注入且无兜底值，不调组件就是透明/无色的裸 HTML。详见packages/desktop/installation.md。 - 组件注册三选一：
app.use(UltraUI)（@veltra/desktop/install）、VeltraUIResolver自动导入、手动 import +*/style子路径。模板里<u-xxx>渲染成未知标签 = 没注册，不要用 div 仿造。 - 走
VeltraUIResolver时，模板组件不要再写import：显式import { UButton } from '@veltra/desktop'会让模板改用该绑定，resolver 既不注入组件也不注入样式副作用，页面结构对但没样式。凡显式 import 的组件（h()/render函数 / JSX / TSX 里用的）必须自己补import '@veltra/desktop/components/<目录>/style'；写<script lang="tsx">还要装并注册@vitejs/plugin-vue-jsx，否则报react/jsx-dev-runtime/react/jsx-runtime解析失败。
反模式（下游最常见翻车点）
- 不要手搓弹窗/抽屉/按钮/空态/滚动容器：
UDialog自带标题栏与关闭按钮、UEmpty自带空态插画、UScroll自带滚动条。界面里出现"仿 macOS 窗口圆点""纯文本标题栏""手绘空态插画"即走偏——回到desktop/index.md找组件。 - 不要用内联样式/手写 CSS 堆颜色、阴影、圆角：一律用主题 token（
cssVar()/ SCSSfn.use-var()，见styles/tokens.md、styles/scss.md）；觉得"组件没颜色"先去补loadTheme()，而不是写补丁样式。 - 不要引入其他组件库或自建同类组件：先查
packages/desktop/index.md组件清单与路由表，确认没有再自建。 - 表单规则见上方「UForm 硬规则」：有
field不写v-model。
检查清单
- 宿主已安装对应
@veltra/*peer，版本与上表一致或兼容 - 入口已
import '@veltra/styles/normalize'并调用loadTheme()（任何组件使用前都必须，不是可选项） - 按需样式走
VeltraUIResolver或显式style导入（见vite.md） - 优先检索本技能文档，确认无合适能力后再自建或引入外部库
- 弹窗/抽屉/空态/按钮等均使用库组件，未手搓窗口外壳与基础控件
- 写表单时已读
form/examples.md：控件有field、无多余v-model，且需要标签时field与label成对出现 - 写 AI 对话时已读
packages/ai.md：transport必填、父级有高度、生产环境不把 API Key 下发浏览器