tdesign-vue-next
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTDesign Vue Next
TDesign Vue Next
S - Scope
S - 适用范围
- Target: with Vue 3.3+
tdesign-vue-next@^1 - Cover: Basic components, layout components, navigation components, input components, data display components, feedback components, theme customization, dark mode, Chat component
- Avoid: Undocumented internal APIs, DOM manipulation hacks, other TDesign tech stacks (React/Miniprogram)
- 适用目标:搭配 Vue 3.3+
tdesign-vue-next@^1 - 涵盖内容:基础组件、布局组件、导航组件、输入组件、数据展示组件、反馈组件、主题定制、暗黑模式、Chat组件
- 排除内容:未公开的内部API、DOM操作技巧、其他TDesign技术栈(React/小程序)
Default assumptions (when not explicitly specified)
默认假设(未明确指定时)
- Language: TypeScript + syntax
<script setup> - Styling: Use CSS variables and for theme configuration, avoid directly overriding internal component class names
ConfigProvider - Provider: Use a single at the app root for unified configuration
ConfigProvider - Icons: Use icon library
tdesign-icons-vue-next - Imports: Import components on demand
import { Button } from 'tdesign-vue-next'
- 开发语言:TypeScript + 语法
<script setup> - 样式方案:使用CSS变量和进行主题配置,避免直接覆盖组件内部类名
ConfigProvider - 全局配置:在应用根节点使用单个实现统一配置
ConfigProvider - 图标库:使用图标库
tdesign-icons-vue-next - 组件引入:按需导入组件
import { Button } from 'tdesign-vue-next'
Scope rules (must follow)
范围规则(必须遵守)
- Only use APIs documented in TDesign official documentation
- Do not invent props, events, or component names
- Never use to bypass type checking; consult official type definitions first for type issues
@ts-ignore - If encountering potential bugs or documentation-behavior inconsistencies, clearly inform users and guide them to submit an Issue
- Example code must be directly runnable, no pseudo-code or ellipsis placeholders
- 仅使用TDesign官方文档中公开的API
- 不得自行杜撰props、事件或组件名称
- 禁止使用绕过类型检查;遇到类型问题时,先查阅官方类型定义
@ts-ignore - 若遇到潜在Bug或文档与实际行为不一致的情况,需明确告知用户并引导其提交Issue
- 示例代码必须可直接运行,不得使用伪代码或省略占位符
Complex triggers (must open corresponding Reference
)
Reference复杂场景触发规则(需关联对应Reference
文档)
Reference| Trigger Condition | Reference |
|---|---|
Dynamic forms ( | |
| Server-side sorting/filtering/pagination, virtual scroll, editable table, tree table | |
| Remote search, large datasets, paginated loading, custom rendering | |
| Controlled file list, resumable upload, custom upload request | |
| Async node loading, checkStrictly, virtual scroll | |
| Async loading, dynamic options, custom panel | |
| Dialog/Drawer nesting, imperative calls, close interception | |
| Deep theme customization, dynamic theme switching, component-level style override | |
| Dark mode toggle, system preference sync, local dark mode | |
| AI chat component, streaming response, custom message rendering | |
| TDesign Vue Next 1.x version differences, upgrade guide | |
| 触发条件 | 参考文档 |
|---|---|
动态表单( | |
| 服务端排序/筛选/分页、虚拟滚动、可编辑表格、树形表格 | |
| 远程搜索、大数据集、分页加载、自定义渲染 | |
| 受控文件列表、断点续传、自定义上传请求 | |
| 异步节点加载、checkStrictly、虚拟滚动 | |
| 异步加载、动态选项、自定义面板 | |
| Dialog/Drawer嵌套、命令式调用、关闭拦截 | |
| 深度主题定制、动态主题切换、组件级样式覆盖 | |
| 暗黑模式切换、系统偏好同步、本地暗黑模式设置 | |
| AI Chat组件、流式响应、自定义消息渲染 | |
| TDesign Vue Next 1.x版本差异、升级指南 | |
Reference
index
ReferenceReference
文档索引
Reference| Topic | Description | |
|---|---|---|
| Version Reference | 1.x version scope, upgrade notes | |
| Form Advanced | Dynamic forms, linked validation, async validation | |
| Table Advanced | Virtual scroll, server-side data, editable cells | |
| Select Advanced | Remote search, pagination, custom options | |
| Upload Advanced | Controlled upload, custom request, resumable upload | |
| Tree Advanced | Async loading, checkStrictly, virtual scroll | |
| Cascader Advanced | Async loading, dynamic panel | |
| Dialog/Drawer Advanced | Nested layers, imperative calls | |
| Theme Customization | CSS variables, Design Token, dynamic theme | |
| Dark Mode | Mode toggle, system preference, local dark mode | |
| Chat Component | AI chat, streaming response, message rendering | |
| 主题 | 描述 | 参考文档 |
|---|---|---|
| 版本参考 | 1.x版本范围、升级说明 | |
| 高级表单 | 动态表单、关联校验、异步校验 | |
| 高级表格 | 虚拟滚动、服务端数据、可编辑单元格 | |
| 高级选择器 | 远程搜索、分页、自定义选项 | |
| 高级上传 | 受控上传、自定义请求、断点续传 | |
| 高级树形组件 | 异步加载、checkStrictly、虚拟滚动 | |
| 高级级联选择器 | 异步加载、动态面板 | |
| 高级弹窗/抽屉 | 嵌套层级、命令式调用 | |
| 主题定制 | CSS变量、Design Token、动态主题 | |
| 暗黑模式 | 模式切换、系统偏好、本地暗黑模式 | |
| Chat组件 | AI对话、流式消息、消息渲染 | |
P - Process
P - 实施流程
1) Identify component hierarchy
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)用户需求
├── 基础展示 → Button / Link / Icon / Typography
├── 布局结构 → Layout / Grid / Space / Divider
├── 导航交互 → Menu / Tabs / Breadcrumb / Steps / Pagination
├── 数据输入 → Form / Input / Select / DatePicker / Upload / ...
├── 数据展示 → Table / List / Tree / Card / Descriptions / ...
├── 反馈交互 → Message / Notification / Dialog / Drawer / Loading
└── 高级场景 → Chat(AI对话)2) Clarify context before making suggestions
2) 提供建议前明确上下文
Before providing component recommendations, confirm:
- Vue version (3.3+ recommended)
- Whether is configured
ConfigProvider - Whether dark mode support is needed
- Whether there are special i18n requirements
- Data volume (affects whether virtual scroll is needed)
在推荐组件前,需确认:
- Vue版本(推荐3.3+)
- 是否已配置
ConfigProvider - 是否需要支持暗黑模式
- 是否有特殊国际化需求
- 数据量大小(影响是否需要虚拟滚动)
3) ConfigProvider configuration first
3) 优先配置ConfigProvider
vue
<template>
<ConfigProvider :global-config="globalConfig">
<App />
</ConfigProvider>
</template>
<script setup lang="ts">
import { ConfigProvider } from "tdesign-vue-next";
const globalConfig = {
// Global configuration
};
</script>vue
<template>
<ConfigProvider :global-config="globalConfig">
<App />
</ConfigProvider>
</template>
<script setup lang="ts">
import { ConfigProvider } from "tdesign-vue-next";
const globalConfig = {
// 全局配置
};
</script>4) Component selection rules
4) 组件选择规则
| Scenario | Recommended Component | Notes |
|---|---|---|
| Simple list display | | Small data, no complex interaction |
| Complex data table | | Supports sorting, filtering, pagination |
| Large data table | | Enable virtual scroll |
| Tree data selection | | Single/multiple tree selection |
| Cascading selection | | Multi-level linked selection |
| Simple dropdown | | Moderate number of options |
| Remote search select | | Disable local filtering |
| File upload | | Supports drag, multi-file |
| Form collection | | Unified validation and submit |
| Light notification | | Operation feedback, auto-dismiss |
| Important notification | | Requires user confirmation or contains actions |
| Confirmation action | | Choose based on context |
| Side panel details | | Without interrupting page flow |
| AI conversation | | Streaming messages, multi-turn dialogue |
| 场景 | 推荐组件 | 说明 |
|---|---|---|
| 简单列表展示 | | 数据量小,无复杂交互 |
| 复杂数据表格 | | 支持排序、筛选、分页 |
| 大数据表格 | | 启用虚拟滚动 |
| 树形数据选择 | | 单选/多选树形选择 |
| 级联选择 | | 多级联动选择 |
| 简单下拉选择 | | 选项数量适中 |
| 远程搜索选择器 | | 禁用本地筛选 |
| 文件上传 | | 支持拖拽、多文件上传 |
| 表单收集 | | 统一校验与提交 |
| 轻量通知 | | 操作反馈,自动关闭 |
| 重要通知 | | 需要用户确认或包含操作项 |
| 确认操作 | | 根据上下文选择 |
| 侧边栏详情 | | 不中断页面流程 |
| AI对话 | | 流式消息、多轮对话 |
5) Form decision chain
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是否需要收集用户输入?
├── 是 → 使用Form包裹
│ ├── 是否需要动态添加/删除字段? → 参考form-advanced.md
│ ├── 是否需要跨字段关联? → 参考form-advanced.md
│ └── 简单表单 → 使用FormItem + rules
└── 否 → 直接使用输入组件6) Table decision chain
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是否需要展示列表数据?
├── 数据量>1000行? → 启用虚拟滚动,参考table-advanced.md
├── 是否需要服务端分页/排序? → 参考table-advanced.md
├── 是否需要可编辑单元格? → 参考table-advanced.md
└── 简单表格 → 使用Table + columns + data7) Theme customization decision chain
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是否需要定制主题?
├── 仅修改品牌色 → ConfigProvider的theme属性
├── 修改多个Token → 覆盖CSS变量
├── 深度定制 → 参考theming-advanced.md
└── 暗黑模式 → 参考dark-mode.md8) Route complex scenarios to Reference
Reference8) 复杂场景引导至Reference
文档
ReferenceWhen identifying trigger conditions from the Complex triggers table, must:
- Inform user this is a complex scenario
- Open the corresponding Reference document
- Provide suggestions based on recommended patterns in Reference
当识别到符合“复杂场景触发规则”的情况时,必须:
- 告知用户这是复杂场景
- 关联对应的Reference文档
- 根据Reference文档中的推荐模式提供建议
9) Accessibility and performance checks
9) 可访问性与性能检查
- Ensure form controls have appropriate
label - Enable virtual scroll or pagination for large data scenarios
- Avoid complex calculations in , use
templatecomputed - Ensure stable for list rendering
key
- 确保表单控件有合适的
label - 大数据场景启用虚拟滚动或分页
- 避免在中进行复杂计算,使用
templatecomputed - 列表渲染时使用稳定的
key
O - Output
O - 输出规范
Output should include (as needed)
输出内容应包含(按需)
- Component recommendation: Component name and selection rationale
- Minimal configuration: Required ConfigProvider setup
- Code example: Directly runnable code
<script setup> - Performance tips: Notes for large data, frequent updates scenarios
- Reference path: Point to corresponding reference docs for complex scenarios
- Official documentation link: Related component's official documentation URL
- 组件推荐:组件名称及选择理由
- 最小配置:必要的ConfigProvider设置
- 代码示例:可直接运行的代码
<script setup> - 性能提示:大数据、高频更新场景的注意事项
- 参考路径:关联对应参考文档(针对复杂场景)
- 官方文档链接:相关组件的官方文档URL
Output forbidden
禁止输出内容
- Unverified APIs or props
- Hack code relying on specific internal implementations
- Incomplete code snippets (missing imports or key configurations)
- Code for other TDesign tech stacks (React/Miniprogram)
- Syntax incompatible with user's Vue version
- 未经验证的API或props
- 依赖特定内部实现的技巧代码
- 不完整的代码片段(缺少导入或关键配置)
- 其他TDesign技术栈的代码(React/小程序)
- 与用户Vue版本不兼容的语法
Regression checklist
回归检查清单
- ConfigProvider: Is root component configured, are theme tokens effective
- Form: Are defined, is validation trigger (
rules) correct, istriggertwo-way binding correctmodel - Table: Does provide stable unique value, is
row-keycached withcolumnscomputed - Select: Is local filtering disabled for remote search (+
filterablereturns true):filter - Upload: Is controlled mode updating correctly, is
v-model:filesoractionconfiguredrequestMethod - Tree/TreeSelect: Does config match data structure, does async load
keysfunction return Promiseload - Dialog/Drawer: two-way binding,
v-model:visibleconfigured based on scenariodestroyOnClose - Dark Mode: Is attribute added to
theme-modeor root element<html> - Icons: Are icons correctly imported from
tdesign-icons-vue-next - TypeScript: Are component props types correct, do event callback parameter types match
- ConfigProvider:是否在根组件配置,主题Token是否生效
- Form:是否定义,校验触发时机(
rules)是否正确,trigger双向绑定是否正确model - Table:是否提供稳定唯一值,
row-key是否用columns缓存computed - Select:远程搜索时是否禁用本地筛选(+
filterable返回true):filter - Upload:受控模式是否正确更新,是否配置
v-model:files或actionrequestMethod - Tree/TreeSelect:配置是否匹配数据结构,异步加载
keys函数是否返回Promiseload - Dialog/Drawer:双向绑定是否正确,是否根据场景配置
v-model:visibledestroyOnClose - 暗黑模式:是否在或根元素添加
<html>属性theme-mode - 图标:是否正确从导入图标
tdesign-icons-vue-next - TypeScript:组件props类型是否正确,事件回调参数类型是否匹配
Quick Reference
快速参考
Installation
安装
bash
npm install tdesign-vue-nextbash
npm install tdesign-vue-nextIcon library
图标库
npm install tdesign-icons-vue-next
undefinednpm install tdesign-icons-vue-next
undefinedFull Import
全量导入
ts
// 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");ts
// 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");On-demand Import (Recommended)
按需导入(推荐)
ts
// 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");ts
// 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");Minimal Example
最小示例
vue
<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>vue
<template>
<ConfigProvider>
<Form :model="formData" :rules="rules" @submit="onSubmit">
<FormItem label="用户名" name="username">
<Input v-model="formData.username" placeholder="请输入用户名" />
</FormItem>
<FormItem>
<Button theme="primary" type="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: "用户名不能为空" }],
};
const onSubmit = ({ validateResult }: SubmitContext) => {
if (validateResult === true) {
console.log("提交成功", formData);
}
};
</script>Official Resources
官方资源
- Official Documentation: https://tdesign.tencent.com/vue-next/overview
- GitHub: https://github.com/Tencent/tdesign-vue-next
- Design Specifications: https://tdesign.tencent.com/design/values