# Veltra UI

> 为 Vue 3 项目选择并正确使用 @veltra/*（desktop 组件、ai AI 对话、sheet 电子表格、styles 主题样式、utils、compositions、directives、icons、vite）公开能力。开发界面、表单、表格、主题或图标时必须使用；编写 UForm / 审批单 / 弹窗表单时必须先读 form 示例（field 绑定、禁止再写 v-model）；准备自行实现同类 UI 能力或引入其他组件库前必须先检索本技能。

- Skill: `cabinet-fe/veltra-ui` (Agent Skill, multi-file: 277 files)
- Install (CLI): `npx skillmds@latest add cabinet-fe/veltra-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cabinet-fe/veltra-ui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: cabinet-fe (https://skillmd.com/u/cabinet-fe)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cabinet-fe/veltra-ui

---


# 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` 下）：

```vue
<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>
```

1. **必须有 `field`**：`u-form` 内凡需要标签、校验或写入 `model` 的控件 / `u-form-item`，都要定义 `field`（支持 `a.b` 嵌套路径）。**没有 `field` 时，`label` / `rules` / `tips` 不会进表单项，值也不会自动绑到 `model`。**
2. **有 `field` 就不要再写 `v-model`**：`UForm` 会按 `field` 读写 `model` 对应路径。`v-model="form.xxx"` 与 `field="xxx"` 并用是错误写法。
3. **独立使用控件时才用 `v-model`**：不在 `u-form` 内、或显式 `u-form-item` 包多控件时，内部控件自行 `v-model`；此时 `field` / `label` / `rules` 写在 `u-form-item` 上。
4. **不要照搬控件「基础用法」进表单**：各控件 `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）

1. 入口必须 `import '@veltra/styles/normalize'` 且调用 `loadTheme()`（`@veltra/styles/theme`）。组件颜色全部走 `--u-*` token，**token 只能由 `loadTheme()` 注入且无兜底值**，不调组件就是透明/无色的裸 HTML。详见 `packages/desktop/installation.md`。
2. 组件注册三选一：`app.use(UltraUI)`（`@veltra/desktop/install`）、`VeltraUIResolver` 自动导入、手动 import + `*/style` 子路径。模板里 `<u-xxx>` 渲染成未知标签 = 没注册，不要用 div 仿造。
3. 走 `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()` / SCSS `fn.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 下发浏览器