Neo-ZQYY/_DEL/wechat-miniprogram/steering/tdesign.md

TDesign 小程序组件库

官方文档：https://tdesign.tencent.com/miniprogram/overview GitHub：https://github.com/Tencent/tdesign-miniprogram

TDesign 是腾讯出品的企业级设计体系，提供微信小程序组件库，包含 60+ 高质量组件。

安装

npm i tdesign-miniprogram -S --production

安装后在微信开发者工具中构建 npm：工具 → 构建 npm。

构建时若出现 NPM packages not found，在 project.config.json 补充：

{
  "setting": {
    "packNpmManually": true,
    "packNpmRelationList": [
      {
        "packageJsonPath": "./package.json",
        "miniprogramNpmDistDir": "./miniprogram/"
      }
    ]
  }
}

构建成功后勾选 将 JS 编译成 ES5。

必要配置

移除 style: v2

将 app.json 中的 "style": "v2" 移除，否则会导致 TDesign 组件样式错乱。

TypeScript 配置

如果使用 TypeScript 开发，修改 tsconfig.json：

{
  "compilerOptions": {
    "paths": {
      "tdesign-miniprogram/*": ["./miniprogram/miniprogram_npm/tdesign-miniprogram/*"]
    }
  }
}

最低基础库版本

^2.12.0

使用组件

引入

在页面或组件的 .json 中注册：

{
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button"
  }
}

全局引入则在 app.json 中配置 usingComponents。

使用

<t-button theme="primary">按钮</t-button>

引入路径规则

所有组件路径格式：tdesign-miniprogram/{组件名}/{组件名}

{
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button",
    "t-input": "tdesign-miniprogram/input/input",
    "t-cell": "tdesign-miniprogram/cell/cell",
    "t-cell-group": "tdesign-miniprogram/cell-group/cell-group",
    "t-icon": "tdesign-miniprogram/icon/icon",
    "t-image": "tdesign-miniprogram/image/image",
    "t-dialog": "tdesign-miniprogram/dialog/dialog",
    "t-toast": "tdesign-miniprogram/toast/toast",
    "t-navbar": "tdesign-miniprogram/navbar/navbar",
    "t-tabs": "tdesign-miniprogram/tabs/tabs",
    "t-tab-panel": "tdesign-miniprogram/tab-panel/tab-panel",
    "t-popup": "tdesign-miniprogram/popup/popup",
    "t-picker": "tdesign-miniprogram/picker/picker",
    "t-picker-item": "tdesign-miniprogram/picker-item/picker-item",
    "t-tag": "tdesign-miniprogram/tag/tag",
    "t-avatar": "tdesign-miniprogram/avatar/avatar",
    "t-badge": "tdesign-miniprogram/badge/badge",
    "t-search": "tdesign-miniprogram/search/search",
    "t-empty": "tdesign-miniprogram/empty/empty",
    "t-loading": "tdesign-miniprogram/loading/loading",
    "t-skeleton": "tdesign-miniprogram/skeleton/skeleton",
    "t-swipe-cell": "tdesign-miniprogram/swipe-cell/swipe-cell",
    "t-tab-bar": "tdesign-miniprogram/tab-bar/tab-bar",
    "t-tab-bar-item": "tdesign-miniprogram/tab-bar-item/tab-bar-item"
  }
}

完整组件列表

基础（6）

组件	标签	说明
Button 按钮	t-button	主按钮、次按钮、文字按钮、图标按钮
Divider 分割线	t-divider	内容分隔
Fab 悬浮按钮	t-fab	浮动操作按钮
Icon 图标	t-icon	内置图标库
Layout 布局	t-row / t-col	栅格布局
Link 链接	t-link	文字链接

导航（8）

组件	标签	说明
BackTop 返回顶部	t-back-top	长页面返回顶部
Drawer 抽屉	t-drawer	侧边滑出面板
Indexes 索引	t-indexes	字母索引列表
Navbar 导航条	t-navbar	自定义顶部导航栏
SideBar 侧边导航栏	t-side-bar / t-side-bar-item	侧边分类导航
Steps 步骤条	t-steps / t-step-item	流程步骤展示
TabBar 底部标签栏	t-tab-bar / t-tab-bar-item	底部导航
Tabs 选项卡	t-tabs / t-tab-panel	顶部选项卡切换

输入（16）

组件	标签	说明
Calendar 日历	t-calendar	日期选择
Cascader 级联选择器	t-cascader	多级联动选择
CheckBox 多选框	t-checkbox / t-checkbox-group	多选
ColorPicker 颜色选择器	t-color-picker	颜色选取
DateTimePicker 日期选择器	t-date-time-picker	日期时间选择
Input 输入框	t-input	文本输入
Picker 选择器	t-picker / t-picker-item	滚动选择
Radio 单选框	t-radio / t-radio-group	单选
Rate 评分	t-rate	星级评分
Search 搜索框	t-search	搜索输入
Slider 滑动选择器	t-slider	滑块选择
Stepper 步进器	t-stepper	数量加减
Switch 开关	t-switch	开关切换
Textarea 多行文本框	t-textarea	多行输入
TreeSelect 树形选择器	t-tree-select	树形多级选择
Upload 上传	t-upload	文件/图片上传

数据展示（18）

组件	标签	说明
Avatar 头像	t-avatar / t-avatar-group	用户头像
Badge 徽章	t-badge	消息提示红点/数字
Cell 单元格	t-cell / t-cell-group	列表项
Collapse 折叠面板	t-collapse / t-collapse-panel	可展开/收起内容
CountDown 倒计时	t-count-down	倒计时显示
Empty 空状态	t-empty	无数据提示
Footer 页脚	t-footer	页面底部信息
Grid 宫格	t-grid / t-grid-item	宫格布局
Image 图片	t-image	增强图片（懒加载、加载状态）
ImageViewer 图片预览	t-image-viewer	图片放大预览
Progress 进度条	t-progress	进度展示
QRCode 二维码	t-qrcode	二维码生成
Result 结果	t-result	操作结果反馈
Skeleton 骨架屏	t-skeleton	加载占位
Sticky 吸顶容器	t-sticky	滚动吸顶
Swiper 轮播图	t-swiper / t-swiper-nav	轮播展示
Tag 标签	t-tag / t-check-tag	标签展示/可选标签
Watermark 水印	t-watermark	页面水印

反馈（13）

组件	标签	说明
ActionSheet 动作面板	t-action-sheet	底部弹出操作列表
Dialog 对话框	t-dialog	模态对话框
DropdownMenu 下拉菜单	t-dropdown-menu / t-dropdown-item	下拉筛选
Guide 引导	t-guide	新手引导
Loading 加载	t-loading	加载中状态
Message 全局提示	t-message	顶部消息提示
NoticeBar 消息提醒	t-notice-bar	通知栏
Overlay 遮罩层	t-overlay	背景遮罩
Popover 弹出气泡	t-popover	气泡提示/菜单
Popup 弹出层	t-popup	通用弹出层
PullDownRefresh 下拉刷新	t-pull-down-refresh	下拉刷新
SwipeCell 滑动操作	t-swipe-cell	左右滑动操作
Toast 轻提示	t-toast	轻量提示

常用组件用法示例

Button 按钮

<!-- 主题 -->
<t-button theme="primary">主按钮</t-button>
<t-button theme="default">次按钮</t-button>
<t-button theme="danger">危险按钮</t-button>
<t-button theme="light">浅色按钮</t-button>

<!-- 变体 -->
<t-button variant="base">填充</t-button>
<t-button variant="outline">描边</t-button>
<t-button variant="dashed">虚框</t-button>
<t-button variant="text">文字</t-button>

<!-- 尺寸 -->
<t-button size="large">大按钮</t-button>
<t-button size="medium">中按钮</t-button>
<t-button size="small">小按钮</t-button>
<t-button size="extra-small">超小按钮</t-button>

<!-- 块级 -->
<t-button block theme="primary">块级按钮</t-button>

<!-- 图标按钮 -->
<t-button theme="primary" icon="app">带图标</t-button>

<!-- 加载状态 -->
<t-button theme="primary" loading>加载中</t-button>

<!-- 禁用 -->
<t-button theme="primary" disabled>禁用</t-button>

Input 输入框

<t-input
  label="标签"
  placeholder="请输入"
  value="{{value}}"
  bind:change="onChange"
  maxlength="20"
  type="text"
  clearable
/>

<!-- 带前缀图标 -->
<t-input
  prefixIcon="search"
  placeholder="搜索"
  bind:change="onSearch"
/>

<!-- 密码输入 -->
<t-input
  label="密码"
  type="password"
  placeholder="请输入密码"
  clearable
/>

Cell 单元格

<t-cell-group>
  <t-cell title="单行标题" arrow />
  <t-cell title="单行标题" note="辅助信息" arrow />
  <t-cell title="单行标题" description="描述信息" arrow />
  <t-cell title="单行标题" left-icon="user" arrow />
</t-cell-group>

Dialog 对话框

<t-dialog
  visible="{{showDialog}}"
  title="对话框标题"
  content="对话框内容"
  confirm-btn="确认"
  cancel-btn="取消"
  bind:confirm="onConfirm"
  bind:cancel="onCancel"
/>

// 命令式调用
const dialog = this.selectComponent('#t-dialog')
dialog.open()
// 或
dialog.close()

Toast 轻提示

<t-toast id="t-toast" />

import Toast from 'tdesign-miniprogram/toast/index'

Toast({
  context: this,
  selector: '#t-toast',
  message: '提示信息',
  theme: 'success',  // success / warning / error / loading
  duration: 2000
})

Popup 弹出层

<t-popup visible="{{visible}}" placement="bottom" bind:visible-change="onVisibleChange">
  <view class="popup-content">弹出内容</view>
</t-popup>

Tabs 选项卡

<t-tabs defaultValue="{{0}}" bind:change="onTabChange">
  <t-tab-panel label="标签1" value="0">内容1</t-tab-panel>
  <t-tab-panel label="标签2" value="1">内容2</t-tab-panel>
  <t-tab-panel label="标签3" value="2">内容3</t-tab-panel>
</t-tabs>

Navbar 导航条

<t-navbar
  title="页面标题"
  left-arrow
  bind:go-back="onGoBack"
/>

<!-- 自定义导航栏（需在 page.json 设置 navigationStyle: custom） -->
<t-navbar title="自定义" left-arrow fixed>
  <view slot="capsule">胶囊区域</view>
</t-navbar>

TabBar 底部标签栏

<t-tab-bar value="{{activeTab}}" bind:change="onTabBarChange">
  <t-tab-bar-item value="home" icon="home">首页</t-tab-bar-item>
  <t-tab-bar-item value="user" icon="user">我的</t-tab-bar-item>
</t-tab-bar>

Search 搜索框

<t-search
  placeholder="搜索"
  value="{{searchValue}}"
  bind:change="onSearchChange"
  bind:submit="onSearchSubmit"
  bind:clear="onSearchClear"
/>

Empty 空状态

<t-empty icon="folder-open" description="暂无数据" />

Loading 加载

<t-loading theme="circular" size="40rpx" text="加载中..." />

Skeleton 骨架屏

<t-skeleton loading="{{loading}}" row-col="{{rowCol}}">
  <view>实际内容</view>
</t-skeleton>

data: {
  loading: true,
  rowCol: [
    { width: '100%', height: '340rpx' },
    [{ width: '45%' }, { width: '45%' }],
    { width: '100%' },
    { width: '60%' }
  ]
}

样式覆盖（4 种方式）

1. style / custom-style 属性

<t-button style="color: red">按钮</t-button>
<t-button custom-style="color: red">按钮</t-button>

开启 virtualHost 时两者效果一致；未开启时只能用 custom-style。

2. 解除样式隔离

TDesign 全体组件开启了 addGlobalClass，页面样式可直接覆盖：

/* 页面 wxss */
.t-button--primary {
  background-color: navy;
}

在自定义组件中使用需开启 styleIsolation: 'shared'。

3. 外部样式类

<t-button t-class="my-btn-class">按钮</t-button>

.my-btn-class {
  color: red !important;
}

每个组件支持的外部样式类见组件文档（如 t-class、t-class-icon、t-class-content 等）。

4. CSS 变量

page {
  --td-brand-color: navy;           /* 主题色 */
  --td-success-color: #00a870;      /* 成功色 */
  --td-warning-color: #ed7b2f;      /* 警告色 */
  --td-error-color: #e34d59;        /* 错误色 */
}

每个组件都有独立的 CSS 变量，见组件文档的 CSS Variables 部分。

自定义主题

全局 Design Token 变量定义：_variables.less

/* app.wxss — 全局主题定制 */
page {
  --td-brand-color: #0052d9;
  --td-brand-color-light: #d9e1ff;
  --td-success-color: #00a870;
  --td-warning-color: #ed7b2f;
  --td-error-color: #e34d59;

  /* 文字颜色 */
  --td-text-color-primary: rgba(0, 0, 0, 0.9);
  --td-text-color-secondary: rgba(0, 0, 0, 0.6);
  --td-text-color-placeholder: rgba(0, 0, 0, 0.26);
  --td-text-color-disabled: rgba(0, 0, 0, 0.26);

  /* 背景颜色 */
  --td-bg-color-container: #fff;
  --td-bg-color-page: #f3f3f3;

  /* 圆角 */
  --td-radius-default: 12rpx;
  --td-radius-large: 18rpx;
  --td-radius-round: 999px;

  /* 字体 */
  --td-font-size-s: 24rpx;
  --td-font-size-base: 28rpx;
  --td-font-size-m: 32rpx;
  --td-font-size-l: 36rpx;
}

深色模式

TDesign 1.3.0+ 支持深色模式。

开启步骤

1. app.json 添加 "darkmode": true
2. app.wxss 引入主题变量：

@import 'miniprogram_npm/tdesign-miniprogram/common/style/theme/_index.wxss';

3. 页面样式使用 CSS Variable：

.text {
  color: var(--td-text-color-secondary);
}

特殊组件适配

自定义 TabBar 和 root-portal 内的组件需手动添加 .page 类名：

<view class="page">
  <t-tab-bar />
</view>

在线查询

如需查看某个具体组件的完整 API（Props / Events / Slots / CSS Variables），可抓取：

• 组件总览：https://tdesign.tencent.com/miniprogram/overview
• 具体组件：https://tdesign.tencent.com/miniprogram/components/{组件名} 例如：https://tdesign.tencent.com/miniprogram/components/button
• 快速开始：https://tdesign.tencent.com/miniprogram/getting-started
• 样式覆盖：https://tdesign.tencent.com/miniprogram/custom-style
• 自定义主题：https://tdesign.tencent.com/miniprogram/custom-theme
• 深色模式：https://tdesign.tencent.com/miniprogram/dark-mode
• CSS 变量定义：https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/style/_variables.less