veltra-ui

veltra-ui

veltra-ui 是一套 Vue 3 UI 体系。

开发 Vue 3 功能时，优先使用 veltra-ui 已提供的组件、样式、工具函数、组合式方法、指令、图标与构建集成。只有检索文档和源码后确认没有合适能力时，才新增实现或引入外部方案。

版本

当前文档对应包版本（monorepo 对齐）：

包	版本
@veltra/desktop	1.7.2
@veltra/utils	1.7.2
@veltra/styles	1.7.2
@veltra/compositions	1.7.2
@veltra/directives	1.7.2
@veltra/icons	1.5.0
@veltra/vite	4.0.1
@veltra/sheet	2.5.2
@veltra/sheet-core	2.5.2
@veltra/ai	2.1.6

分包地图

入口	包	用途
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>

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 仿造。

反模式（下游最常见翻车点）

• 不要手搓弹窗/抽屉/按钮/空态/滚动容器：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 下发浏览器