tdesign-vue-next

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TDesign Vue Next

TDesign Vue Next

S - Scope

S - 适用范围

  • Target:
    tdesign-vue-next@^1
    with Vue 3.3+
  • 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)
  • 适用目标
    tdesign-vue-next@^1
    搭配 Vue 3.3+
  • 涵盖内容:基础组件、布局组件、导航组件、输入组件、数据展示组件、反馈组件、主题定制、暗黑模式、Chat组件
  • 排除内容:未公开的内部API、DOM操作技巧、其他TDesign技术栈(React/小程序)

Default assumptions (when not explicitly specified)

默认假设(未明确指定时)

  • Language: TypeScript +
    <script setup>
    syntax
  • Styling: Use CSS variables and
    ConfigProvider
    for theme configuration, avoid directly overriding internal component class names
  • Provider: Use a single
    ConfigProvider
    at the app root for unified configuration
  • Icons: Use
    tdesign-icons-vue-next
    icon library
  • 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)

范围规则(必须遵守)

  1. Only use APIs documented in TDesign official documentation
  2. Do not invent props, events, or component names
  3. Never use
    @ts-ignore
    to bypass type checking; consult official type definitions first for type issues
  4. If encountering potential bugs or documentation-behavior inconsistencies, clearly inform users and guide them to submit an Issue
  5. Example code must be directly runnable, no pseudo-code or ellipsis placeholders
  1. 仅使用TDesign官方文档中公开的API
  2. 不得自行杜撰props、事件或组件名称
  3. 禁止使用
    @ts-ignore
    绕过类型检查;遇到类型问题时,先查阅官方类型定义
  4. 若遇到潜在Bug或文档与实际行为不一致的情况,需明确告知用户并引导其提交Issue
  5. 示例代码必须可直接运行,不得使用伪代码或省略占位符

Complex triggers (must open corresponding
Reference
)

复杂场景触发规则(需关联对应
Reference
文档)

Trigger ConditionReference
Dynamic forms (
FormItem
add/remove), cross-field validation, async validation
references/form-advanced.md
Server-side sorting/filtering/pagination, virtual scroll, editable table, tree table
references/table-advanced.md
Remote search, large datasets, paginated loading, custom rendering
references/select-advanced.md
Controlled file list, resumable upload, custom upload request
references/upload-advanced.md
Async node loading, checkStrictly, virtual scroll
references/tree-advanced.md
Async loading, dynamic options, custom panel
references/cascader-advanced.md
Dialog/Drawer nesting, imperative calls, close interception
references/dialog-drawer-advanced.md
Deep theme customization, dynamic theme switching, component-level style override
references/theming-advanced.md
Dark mode toggle, system preference sync, local dark mode
references/dark-mode.md
AI chat component, streaming response, custom message rendering
references/chat-advanced.md
TDesign Vue Next 1.x version differences, upgrade guide
references/tdesign-v1.md
触发条件参考文档
动态表单(
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 Chat组件、流式响应、自定义消息渲染
references/chat-advanced.md
TDesign Vue Next 1.x版本差异、升级指南
references/tdesign-v1.md

Reference
index

Reference
文档索引

TopicDescription
Reference
Version Reference1.x version scope, upgrade notes
references/tdesign-v1.md
Form AdvancedDynamic forms, linked validation, async validation
references/form-advanced.md
Table AdvancedVirtual scroll, server-side data, editable cells
references/table-advanced.md
Select AdvancedRemote search, pagination, custom options
references/select-advanced.md
Upload AdvancedControlled upload, custom request, resumable upload
references/upload-advanced.md
Tree AdvancedAsync loading, checkStrictly, virtual scroll
references/tree-advanced.md
Cascader AdvancedAsync loading, dynamic panel
references/cascader-advanced.md
Dialog/Drawer AdvancedNested layers, imperative calls
references/dialog-drawer-advanced.md
Theme CustomizationCSS variables, Design Token, dynamic theme
references/theming-advanced.md
Dark ModeMode toggle, system preference, local dark mode
references/dark-mode.md
Chat ComponentAI chat, streaming response, message rendering
references/chat-advanced.md

主题描述参考文档
版本参考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
Chat组件AI对话、流式消息、消息渲染
references/chat-advanced.md

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
    ConfigProvider
    is configured
  • 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) 组件选择规则

ScenarioRecommended ComponentNotes
Simple list display
List
Small data, no complex interaction
Complex data table
Table
Supports sorting, filtering, pagination
Large data table
Table
+
virtual-scroll
Enable virtual scroll
Tree data selection
TreeSelect
Single/multiple tree selection
Cascading selection
Cascader
Multi-level linked selection
Simple dropdown
Select
Moderate number of options
Remote search select
Select
+
filterable
+
remote
Disable local filtering
File upload
Upload
Supports drag, multi-file
Form collection
Form
+
FormItem
Unified validation and submit
Light notification
Message
Operation feedback, auto-dismiss
Important notification
Notification
Requires user confirmation or contains actions
Confirmation action
Dialog
/
Popconfirm
Choose based on context
Side panel details
Drawer
Without interrupting page flow
AI conversation
Chat
Streaming messages, multi-turn dialogue
场景推荐组件说明
简单列表展示
List
数据量小,无复杂交互
复杂数据表格
Table
支持排序、筛选、分页
大数据表格
Table
+
virtual-scroll
启用虚拟滚动
树形数据选择
TreeSelect
单选/多选树形选择
级联选择
Cascader
多级联动选择
简单下拉选择
Select
选项数量适中
远程搜索选择器
Select
+
filterable
+
remote
禁用本地筛选
文件上传
Upload
支持拖拽、多文件上传
表单收集
Form
+
FormItem
统一校验与提交
轻量通知
Message
操作反馈,自动关闭
重要通知
Notification
需要用户确认或包含操作项
确认操作
Dialog
/
Popconfirm
根据上下文选择
侧边栏详情
Drawer
不中断页面流程
AI对话
Chat
流式消息、多轮对话

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 + data

7) 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.md

8) Route complex scenarios to
Reference

8) 复杂场景引导至
Reference
文档

When identifying trigger conditions from the Complex triggers table, must:
  1. Inform user this is a complex scenario
  2. Open the corresponding Reference document
  3. Provide suggestions based on recommended patterns in Reference
当识别到符合“复杂场景触发规则”的情况时,必须:
  1. 告知用户这是复杂场景
  2. 关联对应的Reference文档
  3. 根据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
    template
    , use
    computed
  • Ensure stable
    key
    for list rendering

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

O - Output

O - 输出规范

Output should include (as needed)

输出内容应包含(按需)

  1. Component recommendation: Component name and selection rationale
  2. Minimal configuration: Required ConfigProvider setup
  3. Code example: Directly runnable
    <script setup>
    code
  4. Performance tips: Notes for large data, frequent updates scenarios
  5. Reference path: Point to corresponding reference docs for complex scenarios
  6. Official documentation link: Related component's official documentation URL
  1. 组件推荐:组件名称及选择理由
  2. 最小配置:必要的ConfigProvider设置
  3. 代码示例:可直接运行的
    <script setup>
    代码
  4. 性能提示:大数据、高频更新场景的注意事项
  5. 参考路径:关联对应参考文档(针对复杂场景)
  6. 官方文档链接:相关组件的官方文档URL

Output forbidden

禁止输出内容

  1. Unverified APIs or props
  2. Hack code relying on specific internal implementations
  3. Incomplete code snippets (missing imports or key configurations)
  4. Code for other TDesign tech stacks (React/Miniprogram)
  5. Syntax incompatible with user's Vue version
  1. 未经验证的API或props
  2. 依赖特定内部实现的技巧代码
  3. 不完整的代码片段(缺少导入或关键配置)
  4. 其他TDesign技术栈的代码(React/小程序)
  5. 与用户Vue版本不兼容的语法

Regression checklist

回归检查清单

  • ConfigProvider: Is root component configured, are theme tokens effective
  • Form: Are
    rules
    defined, is validation trigger (
    trigger
    ) correct, is
    model
    two-way binding correct
  • Table: Does
    row-key
    provide stable unique value, is
    columns
    cached with
    computed
  • Select: Is local filtering disabled for remote search (
    filterable
    +
    :filter
    returns true)
  • Upload: Is controlled mode
    v-model:files
    updating correctly, is
    action
    or
    requestMethod
    configured
  • Tree/TreeSelect: Does
    keys
    config match data structure, does async load
    load
    function return Promise
  • Dialog/Drawer:
    v-model:visible
    two-way binding,
    destroyOnClose
    configured based on scenario
  • Dark Mode: Is
    theme-mode
    attribute added to
    <html>
    or root element
  • 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
    +
    :filter
    返回true)
  • Upload:受控模式
    v-model:files
    是否正确更新,是否配置
    action
    requestMethod
  • Tree/TreeSelect
    keys
    配置是否匹配数据结构,异步加载
    load
    函数是否返回Promise
  • Dialog/Drawer
    v-model:visible
    双向绑定是否正确,是否根据场景配置
    destroyOnClose
  • 暗黑模式:是否在
    <html>
    或根元素添加
    theme-mode
    属性
  • 图标:是否正确从
    tdesign-icons-vue-next
    导入图标
  • TypeScript:组件props类型是否正确,事件回调参数类型是否匹配

Quick Reference

快速参考

Installation

安装

bash
npm install tdesign-vue-next
bash
npm install tdesign-vue-next

Icon library

图标库

npm install tdesign-icons-vue-next
undefined
npm install tdesign-icons-vue-next
undefined

Full 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

官方资源