新手系列 I 如何使用 TDesign 轻松开发项目，秘诀都在这里

TDesign 简介

TDesign 是一个包含多框架的组件库体系，目前 TDesign 相对成熟的 Web 组件库有：Vue/Vue Next/React/WeChat MiniProgram，还有正在建设中的 Mobile Vue Next(Vue3)/Mobile React/QQ MiniProgram/Flutter 等移动端组件库。本文主讲已基本完善的几个组件库。

TDesign 中的 Vue Next 表示 Vue3，同 Vue 官方命名一致。

快速开始

使用 TDesign 大概有两类场景：一个是全新的项目使用 TDesign ；二个是在已有项目环境中引入 TDesign。

如果是全新的业务项目使用 TDesign，可以使用官网提供的 tdesign-starter 快速创建完整的项目，包含完整的登录、请求、路由、页面布局、暗黑模式等内容，以及列表页、表单页、图表页、订单页、详情页、结果页等页面信息。在这个初始项目的基础上开发业务项目，可以减少大量项目搭建和初始化工作。

React 实践项目体验地址

Vue2 实践项目体验地址

Vue3 实践项目体验地址

tdesign-starter documents for React

tdesign-starter docuements for Vue2

tdesign-starter docuements for Vue3

其中，微信小程序使用 小程序开发者工具中的「TDesign - 零售电商模板」快速创建项目。

如果在已有项目中引入 TDesign，可以参考官网提供的「快速开始」，文档描述包含 npm 包引入和 CDN 引入两种方式，还有 Vite 和 Webpack 两种构建工具配置方式说明。如果在操作过程中遇到了奇怪的问题时，请仔细阅读文档下方的 FAQ，大概率可以找到问题的解决方案。

如：Vue2 的使用过程中，大家反馈很多的一个问题是使用某些组件时遇到 vue.runtime.esm.js:4605 [Vue warn]: inject() can only be used inside setup() or functional components，这类报错表示实际安装了不兼容版本 Vue2.7.x，此时将项目依赖配置由 ^2.6.14 更为 ~2.6.14，而后重新安装依赖包即可。FAQ 中有这类典型问题的描述。

React 快速开始

Vue2 快速开发

Vue3 快速开始

主题生成

不同的业务可能会有不同的主题要求，TDesign 默认的主题配置无法满足所有业务场景。针对不同的业务场景，TDesign 支持根据业务实际情况扩展设计独特的行业组件风格，包含：颜色、字体、圆角、阴影、尺寸等主题设计内容，有着非常详细的 Design Token。

各框架的官网正下方有一个用于调整组件风格样式的主题生成器的插件。

点开后，开发和设计都可以直接在官网实时调整主题内容并预览实际效果，确认主题效果后，点击 “下载按钮”，会导出一个主题 CSS 变量文件，将这个文件引入到项目中即可。

微信小程序需要在项目中修改 CSS 变量。

TDesign Design Token

React 自定义主题

Vue2 自定义主题

Vue3 自定义主题

微信小程序自定义主题

如果希望修改类名前缀，请同步参考下方的「组件类名前缀」。

全局配置

全局配置旨在解决重复而繁琐的问题，如果你遇到了下面这些问题，则表示应该考虑使用全局配置这项功能了：

1. 希望项目中的部分组件特性统一设置，而非每次使用时都重复设置，如：Dialog 取消按钮都保持一个样式
2. 项目的用户面向多个国家，需要实现不同的国际语言配置
3. 类名前缀和现有项目冲突，希望替换前缀 t 为其他
4. 希望禁用或选择 TDesign 的部分动画效果
5. 希望替换项目中的所有排序图标、关闭图标、展开/收起图标等各类图标

全局配置包含 组件特性功能、国际语言配置、组件类名前缀、动画效果、图标替换等功能，由全局组件 ConfigProvider 统一控制，通过属性 globalConfig 配置各类特性，Vue2/Vue3/React 三个框架的组件库均同步支持，都有着详细的 API 配置文档。TDesign 微信小程序组件库暂不支持全局配置，期待更新。

<ConfigProvider :globalConfig="{ classPrefix, animation, icon, datePicker, upload, ... }">
  <App>
    <DatePicker>Click</DatePicker>
  </App>
</ConfigProvider>

React 全局配置

Vue2 全局配置

Vue3 全局配置

组件特性配置

项目开发过程中，你会每一次重复地设置组件的某个属性吗？如：

1. 对话框 Dialog 组件支持统一配置 点击蒙层是否触发探矿关闭
2. 表单 Form 组件支持统一配置 是否显示必填符号(*) 和 常用校验未通过的校验文本。点击查看校验文本配置 FormErrorMessage
3. 表格 Table 组件支持统一配置 排序图标、过滤图标 等（注意：组件内部的图标配置作用范围仅为当前组件，而全局的图标配置是全量组件）

这些都可以通过全局配置一次性统一设置。除了这些，还支持很多其他组件的特性配置，不再赘述，详细内容请参考官网全局配置 API 文档：

React 全局配置 API

Vue2 全局配置 API

Vue3 全局配置 API 。

<ConfigProvider :globalConfig="{
  dialog: {
    closeOnOverlayClick: true,
    closeOnEscKeydown: true,
  }
}">
    <App>TDesign Dialog Config</App>
</ConfigProvider>

如果在使用过程中，希望某个组件特性支持全局统一配置，可以通过提 issue 和群内沟通等方式告知，届时会进行特性评估和开发。

国际语言配置

支持简体中文(zh_CN)、繁体中文(zh_TW)、英语(en_US)、韩语(ko_KR)、日语(ja_JP)、俄语(ru_RU)、意大利语(it_IT)、阿拉伯语(ar_KW)等多国语言。全局语言配置以组件维度进行拆分，不同的组件有不同的语言配置文本。

// js
import enConfig from 'tdesign-vue-next/es/locale/en_US'; import merge from 'lodash/merge';
const customConfig = {
input: { placeholder: 'input text' },
  dialog: { confirm: 'OK' },
};

<!-- html ->
<t-config-provider :global-config="merge(enConfig, customConfig)">
 <App><Button>Click</Button></App>
</t-config-provider>

React 语言配置 API

Vue2 语言配置 API

Vue3 语言配置 API

支持语言配置和前面「组件特性配置」同时使用，都是根据组件的维度进行配置。

组件类名前缀

为避免类名前缀冲突，支持通过全局配置的方式修改组件的类名前缀。假如要修改类名前缀为 **tc**，这样设置：

<t-config-provider :globalConfig="{ classPrefix: 'tc'}">     <t-button>TDesign to any design</t-button>
</t-config-provider>

同时，还需同步修改 CSS 样式文件中的类名前缀：

如果是全量引入组件样式 (style/index.css）的情况，直接全局搜索 .t- 替换为目标前缀，同时建议更为通过 CDN 的方式引入样式包。

如果是按需引入，且业务刚好也是基于 less 开发，可进行以下配置，注意需要引入 esm 包含 .less 文件的这个包。

lessOptions: {
  modifyVars: {
    '@prefix': 'tc',
  },
  javascriptEnabled: true,
},

动画效果

组件本身自带了一些动画效果，ripple 波纹动画， expand 展开动画，fade 渐变动画。如果业务希望去除或保留部分动画效果可以通过设置 globalConfig.animation 实现。

lessOptions: {
  modifyVars: {
    '@prefix': 'tc',
  },
  javascriptEnabled: true,
},

代码为 React 示例，Vue3/Vue2 同理。

全局图标替换

图标替换有两种方式：一种是替换某一个组件的某一个图标；另一种是全局统一替换某一个图标。

替换某一个组件的某一个图标

这个在前面的「组件特性配置」中已经提及，Table 的排序图标和过滤图标替换。主要适用于仅需替换某一个组件图标的场景，作用范围是当前组件，不会作用到全局影响其他组件。除 Table 之外，目前已经支持单组件图标配置的组件还有：

Tree 组件的目录图标、Tag 组件的关闭图标、Steps 组件的错误图标等。点击查看示例代码

Select 组件的清除图标，当你在使用这个功能的时候，请慎重，如果不是十分明确，建议更为使用全局统一替换清除图标。

更多配置，查看官网「全局配置」页面中的 API 文档，搜索关键词 “icon” 可以快速查看。

<ConfigProvider :globalConfig="{tree: { folderIcon: <FilterIcon /> }}">
    <App>TDesign Tree Folder Icon</App>
</ConfigProvider> 

全局统一替换某一个图标

不同的业务有不同的图标规范，有的甚至需要全部替换现有组件图标，再加上不同的组件可能会使用相同的图标，如：展开图标、错误图标、清除图标等。为减少全量组件图标配置时间，提供了统一的图标映射关系配置。

<ConfigProvider :globalConfig="{
  icon: {
    CloseIcon: CloseIconCustom,
    ErrorCircleFilledIcon: ErrorCircleFilledIconCustom,
    HelpCircleFilledIcon: HelpCircleFilledIconCustom,
  }
}">
    <App>TDesign Tree Folder Icon</App>
</ConfigProvider> 

官网暂时没有给出示例代码，静待补充。功能可以正常使用。

组件开发

文档阅读

每个组件都有独立的文档，由示例代码、API 文档、设计指南等三部分组成。

示例 部分会呈现每个组件的核心功能，一个示例代码，可能会有由多个 API 共同作用。如果开发过程中发现直接复制官网的代码也会有问题，说明你正在使用的版本号大概率不是最新版本号，建议尝试升级。

API 部分则是分别描述每一个 API 的功能和注意事项，所有的 API 都有详细的 TypeScript 类型描述。简单类型会直接呈现 TS 类型定义，如：Button.type 可选项为：submit/reset/button。可复用的通用类型或复杂类型则是通过跳转链接引导查看，如：SizeEnum 和 TNode，这样可以一定程度避免大篇幅的类型描述，也可以避免很多重复的类型描述。 点击文档中蓝色字“通用类型定义”可以查看所有的通用类型定义，点击蓝色字“详细类型定义” 则可以查看当前组件的所有类型定义。文档中如果看到 xxxProps 一类的 API，则表示透传子组件的全部属性，如：buttonProps/popupProps/selectInputProps/tagProps 等。点击“API Documents”可以跳转查看对应组件的 Props API 文档。

指南 部分则是交互使用建议，不同的场景会有不同的交互约束。

代码提示

完整正确的代码提示，可以减少开发过程中查询文档的时间，提高代码书写效率。React 基于 TS 开发，常用的编辑器 VSCode 和 Webstorm 都有代码提示，无需额外关心。基于 Vue2/Vue3 开发的项目，且使用的编辑器是 VSCode 需要重点关注下。

代码提示有：组件代码高亮、组件名提示、组件属性提示等。

编辑器是 Webstorm

如果使用 Webstorm 中开发 Vue 项目，直接下载安装最新版本的组件库即可，保证安装的文件包含 helper/web-types.json 和 global.d.ts 。老版本的组件库可能不包含这两个文件，也就没有组件属性提示。

编辑器是 VSCode

如果项目是 TS，请先安装 Vue 官方推荐插件 Volar ，然后在 tsconfig.json 的 includes 配置项中添加路径配置 node_modules/tdesign-vue-next/global.d.ts。如果没有效果，可尝试重启编辑器或 Volar 服务。如果依然没有效果，请升级 TDesign 组件库版本号为正式版，由于组件库使用了 Vue 高版本的类型和特性，需同时升级 Vue 版本号 v3.2.47+。

如果项目是 JS，安装 Vue 官方推荐插件 Vetur 即可，安装 TDesign 组件库后，插件 Vetur 会自动引入代码提示相关文件。注意：这个插件不支持在同时打开多个项目时显示代码提示，一个编辑器窗口，一个项目。如果是项目中使用的 TDesign 老版本，可能会因为不存在 helper/attributes.json 和 helper/tags.json 两个文件而没有代码提示，这两个文件是 Vetur 插件所需。

如果发现有缺失的组件或属性提示，可以联系我们添加。

如何提缺陷

很多同学在提问时有一个习惯，直接贴几张图和几段文本描述，就开始沟通。而 TDesign 是一个组件库体系，包含 Vue2/Vue3/React/Miniprogram 等多个框架组件库，必要信息的缺失导致我们需要花时间继续沟通询问，每个人每一次的询问重复累计下来，都是很大一段时间的浪费。忙的时候，极有可能会因为没有理解问题而选择忽略不回复。

当你在使用组件的过程中遇到问题时，怀疑是组件本身的缺陷，可以先在官网的每一个示例代码下方点击 CodeSandbox 或者 Stackblitz ，进去复现一下你的问题，然后保存代码，复制新链接发给我们。在纯净地环境中复现出来的问题，可以证明大概率是组件的问题，需要我们进行处理。一般情况，我们也会优先处理提供了可复现问题链接的问题。

如果提供链接麻烦了些，需要至少提供自己正在使用框架和版本号。最简单的方式，直接复制 package.json 里面的包信息，示例："tdesign-vue-next": "^1.2.2" 。

准备好框架版本号和可复现问题链接后，就可以开始在群里或者 issue 中提问和咨询了。下图为提 issue 的位置，每个组件页面都有对应的按钮组，点击进入即可。

总结，当你遇到缺陷时，排查问题的正确步骤如下：

1. 点击官网示例代码提供的 CodeSandbox 或者 Stackblitz 入口，进去复现一下你的问题
2. 如果在第 1 步中复现了问题，保存代码，复制新链接发送给我们，或者提 issue
3. 如果在第 1 步中没有复现问题，继续下方第 4 步
4. 关注一下自己正在使用的组件库版本号，可在 package.json 中查看依赖包信息
5. 在官网“更新日志”中，查看官网最新的版本号，观察最新版本和你正在使用的版本号之间，有什么变更点，也许刚好就已经修复了你现在遇到的问题（Features 表示新支持的特性；Bug Fixes 表示已经修复的缺陷；BreakingChanges 表示不兼容变更）

版本号升级

如果业务的版本号还是 0.x.x，无论新老业务，都建议尽快安排时间升级到最新版本，否则后面积累的问题会越来越多，也无法使用正式版中的新特性和已修复的缺陷。

如果你们的业务已经成功升级，在升级过程中也遇到些特别的问题，欢迎分享经验，以供大家参考，相信会有很多同学向你们表达感激。

每周都会发布新版本，凡事重要的变更都会同步到的更新日志中，也会在各个用户群里面通知大家。如果你现在还没有添加任何 TDesign 相关的群，可以联系我们邀请你加入群聊，以便沟通你在开发过程中遇到的各种问题。对于低版本业务升级，重点关注 变更日志中的 “Breaking Changes” 就好，根据日志中的变更描述调整用法，数量不多。对于已经是正式版的用户，新版本一般不会有不兼容更新，只需定期关注每周发布的新特性和缺陷修复，直接升级即可。

React 更新日志

Vue2 更新日志

Vue3 更新日志

升级过程中遇到的所有问题，都可以联系我们进行沟通和处理。

协同共建

TDesign 是一个外部开源项目，使用 Github 账号开发，可以积累贡献度。

欢迎有兴趣的你，技术的你，有特别想法的你加入我们！

具体贡献指南参考各个仓库的 CONTRIBUTING.md 文件，在贡献的过程中有任何疑惑，可以加入 TDesign 用户群咨询