tdesign-vue-next

TDesign Vue Next

S - 范围

• 目标：tdesign-vue-next@^1，搭配 Vue 3.3+
• 涵盖：基础组件、布局组件、导航组件、输入组件、数据展示组件、反馈组件、主题自定义、暗色模式、Chat 组件
• 避免：未记录的内部 API、DOM 操作技巧、其他 TDesign 技术栈（React/Miniprogram）

默认假设（未明确指定时）

• 语言：TypeScript + <script setup> 语法
• 样式：使用 CSS 变量和 ConfigProvider 配置主题，避免直接覆盖组件内部类名
• Provider：在应用根节点使用单个 ConfigProvider 进行统一配置
• 图标：使用 tdesign-icons-vue-next 图标库
• 导入：按需导入组件 import { Button } from 'tdesign-vue-next'

范围规则（必须遵守）

1. 仅使用 TDesign 官方文档中记录的 API
2. 不要编造属性、事件或组件名称
3. 绝不要使用 @ts-ignore 绕过类型检查；遇到类型问题时，先查阅官方类型定义
4. 如果遇到潜在 Bug 或文档与实际行为不一致的情况，务必告知用户并引导其提交 Issue
5. 示例代码必须可以直接运行，不得使用伪代码或省略号占位符

复杂场景触发条件（必须打开对应的 Reference）

触发条件	Reference
动态表单（添加/移除 FormItem）、跨字段校验、异步校验	references/form-advanced.md
服务端排序/筛选/分页、虚拟滚动、可编辑表格、树形表格	references/table-advanced.md
远程搜索、大型数据集、分页加载、自定义渲染	references/select-advanced.md
受控文件列表、断点续传、自定义上传请求	references/upload-advanced.md
异步加载节点、checkStrictly、虚拟滚动	references/tree-advanced.md
异步加载、动态选项、自定义面板	references/cascader-advanced.md
Dialog/Drawer 嵌套、命令式调用、拦截关闭	references/dialog-drawer-advanced.md
深度自定义主题、动态切换主题、组件级样式覆盖	references/theming-advanced.md
切换暗色模式、同步系统偏好、本地暗色模式	references/dark-mode.md
AI 聊天组件、流式响应、自定义消息渲染	references/chat-advanced.md
TDesign Vue Next 1.x 版本差异、升级指南	references/tdesign-v1.md

Reference 索引

主题	描述	Reference
版本参考	1.x 版本范围、升级说明	references/tdesign-v1.md
表单高级用法	动态表单、关联校验、异步校验	references/form-advanced.md
表格高级用法	虚拟滚动、服务端数据、可编辑单元格	references/table-advanced.md
选择器高级用法	远程搜索、分页、自定义选项	references/select-advanced.md
上传高级用法	受控上传、自定义请求、断点续传	references/upload-advanced.md
树高级用法	异步加载、checkStrictly、虚拟滚动	references/tree-advanced.md
级联选择器高级用法	异步加载、动态面板	references/cascader-advanced.md
对话框/抽屉高级用法	嵌套层级、命令式调用	references/dialog-drawer-advanced.md
主题自定义	CSS 变量、Design Token、动态主题	references/theming-advanced.md
暗色模式	模式切换、系统偏好、本地暗色模式	references/dark-mode.md
聊天组件	AI 聊天、流式响应、消息渲染	references/chat-advanced.md

---

P - 流程

1）识别组件层级

User requirements
  ├── Basic display → Button / Link / Icon / Typography
  ├── Layout structure → Layout / Grid / Space / Divider
  ├── Navigation interaction → Menu / Tabs / Breadcrumb / Steps / Pagination
  ├── Data input → Form / Input / Select / DatePicker / Upload / ...
  ├── Data display → Table / List / Tree / Card / Descriptions / ...
  ├── Feedback → Message / Notification / Dialog / Drawer / Loading
  └── Advanced scenarios → Chat (AI conversation)

2）提出建议前先明确上下文

在提供组件建议前，确认：

• Vue 版本（推荐 3.3+）
• 是否配置了 ConfigProvider
• 是否需要支持暗色模式
• 是否有特殊的 i18n 要求
• 数据量（会影响是否需要虚拟滚动）

3）先配置 ConfigProvider

<template>
  <ConfigProvider :global-config="globalConfig">
    <App />
  </ConfigProvider>
</template>

<script setup lang="ts">
import { ConfigProvider } from "tdesign-vue-next";

const globalConfig = {
  // Global configuration
};
</script>

4）组件选择规则

场景	推荐组件	备注
简单列表展示	List	数据量小，无复杂交互
复杂数据表格	Table	支持排序、筛选、分页
大型数据表格	Table + virtual-scroll	启用虚拟滚动
树形数据选择	TreeSelect	单选/多选树形选择
级联选择	Cascader	多级关联选择
简单下拉选择	Select	选项数量适中
远程搜索选择	Select + filterable + remote	禁用本地筛选
文件上传	Upload	支持拖拽、多文件
表单收集	Form + FormItem	统一校验和提交
轻量通知	Message	操作反馈，自动关闭
重要通知	Notification	需要用户确认或包含操作
确认操作	Dialog / Popconfirm	根据上下文选择
侧边面板详情	Drawer	不打断页面流程
AI 对话	Chat	流式消息、多轮对话

5）表单决策链

Need to collect user input?
  ├── Yes → Use Form wrapper
  │     ├── Need dynamic add/remove fields? → See form-advanced.md
  │     ├── Need cross-field linking? → See form-advanced.md
  │     └── Simple form → Use FormItem + rules
  └── No → Use input component directly

6）表格决策链

Need to display list data?
  ├── Data > 1000 rows? → Enable virtual scroll, see table-advanced.md
  ├── Need server-side pagination/sorting? → See table-advanced.md
  ├── Need editable cells? → See table-advanced.md
  └── Simple table → Use Table + columns + data

7）主题自定义决策链

Need to customize theme?
  ├── Only modify brand color → ConfigProvider theme prop
  ├── Modify multiple tokens → Override CSS variables
  ├── Deep customization → See theming-advanced.md
  └── Dark mode → See dark-mode.md

8）将复杂场景转到 Reference

从复杂触发条件表中识别出触发条件时，必须：

1. 告知用户这是一个复杂场景
2. 打开相应的 Reference 文档
3. 根据 Reference 中推荐的模式提供建议

9）无障碍与性能检查

• 确保表单控件具有适当的 label
• 对于大型数据场景，启用虚拟滚动或分页
• 避免在 template 中进行复杂计算，使用 computed
• 确保列表渲染具有稳定的 key

---

O - 输出

输出应包含（视需要而定）

1. 组件推荐：组件名称及选择理由
2. 最小配置：必需的 ConfigProvider 设置
3. 代码示例：可直接运行的 <script setup> 代码
4. 性能提示：针对大型数据、频繁更新场景的说明
5. Reference 路径：指向复杂场景对应的参考文档
6. 官方文档链接：相关组件的官方文档 URL

禁止输出

1. 未经验证的 API 或属性
2. 依赖特定内部实现的 hack 代码
3. 不完整的代码片段（缺少导入或关键配置）
4. 其他 TDesign 技术栈（React/Miniprogram）的代码
5. 与用户 Vue 版本不兼容的语法

回归检查清单

• ConfigProvider：是否配置了根组件，主题令牌是否生效
• Form：是否定义了 rules，校验触发器（trigger）是否正确，model 双向绑定是否正确
• Table：row-key 是否提供稳定的唯一值，columns 是否使用 computed 缓存
• Select：远程搜索时是否禁用了本地筛选（filterable + :filter 返回 true）
• Upload：受控模式下 v-model:files 是否正确更新，是否配置了 action 或 requestMethod
• Tree/TreeSelect：keys 配置是否匹配数据结构，异步加载的 load 函数是否返回 Promise
• Dialog/Drawer：v-model:visible 双向绑定是否正确，是否根据场景配置了 destroyOnClose
• 暗色模式：是否已将 theme-mode 属性添加到 <html> 或根元素
• 图标：是否已从 tdesign-icons-vue-next 正确导入图标
• TypeScript：组件属性类型是否正确，事件回调参数类型是否匹配

---

快速参考

安装

npm install tdesign-vue-next
# Icon library
npm install tdesign-icons-vue-next

全量导入

// main.ts
import { createApp } from "vue";
import TDesign from "tdesign-vue-next";
import "tdesign-vue-next/es/style/index.css";
import App from "./App.vue";

createApp(App).use(TDesign).mount("#app");

按需导入（推荐）

// main.ts
import { createApp } from "vue";
import { Button, Input, Form, FormItem } from "tdesign-vue-next";
import "tdesign-vue-next/es/style/index.css";
import App from "./App.vue";

const app = createApp(App);
app.use(Button).use(Input).use(Form).use(FormItem);
app.mount("#app");

最小示例

<template>
  <ConfigProvider>
    <Form :model="formData" :rules="rules" @submit="onSubmit">
      <FormItem label="Username" name="username">
        <Input v-model="formData.username" placeholder="Enter username" />
      </FormItem>
      <FormItem>
        <Button theme="primary" type="submit">Submit</Button>
      </FormItem>
    </Form>
  </ConfigProvider>
</template>

<script setup lang="ts">
import { reactive } from "vue";
import {
  ConfigProvider,
  Form,
  FormItem,
  Input,
  Button,
} from "tdesign-vue-next";
import type { FormRules, SubmitContext } from "tdesign-vue-next";

const formData = reactive({
  username: "",
});

const rules: FormRules<typeof formData> = {
  username: [{ required: true, message: "Username is required" }],
};

const onSubmit = ({ validateResult }: SubmitContext) => {
  if (validateResult === true) {
    console.log("Submit successful", formData);
  }
};
</script>

官方资源

• 官方文档：https://tdesign.tencent.com/vue-next/overview
• GitHub：https://github.com/Tencent/tdesign-vue-next
• 设计规范：https://tdesign.tencent.com/design/values