# TDesign 小程序组件库

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

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

## 安装

```bash
npm i tdesign-miniprogram -S --production
```

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

构建时若出现 `NPM packages not found`，在 `project.config.json` 补充：
```json
{
  "setting": {
    "packNpmManually": true,
    "packNpmRelationList": [
      {
        "packageJsonPath": "./package.json",
        "miniprogramNpmDistDir": "./miniprogram/"
      }
    ]
  }
}
```

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

## 必要配置

### 移除 style: v2

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

### TypeScript 配置

如果使用 TypeScript 开发，修改 `tsconfig.json`：
```json
{
  "compilerOptions": {
    "paths": {
      "tdesign-miniprogram/*": ["./miniprogram/miniprogram_npm/tdesign-miniprogram/*"]
    }
  }
}
```

### 最低基础库版本

`^2.12.0`

## 使用组件

### 引入

在页面或组件的 `.json` 中注册：
```json
{
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button"
  }
}
```

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

### 使用

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

### 引入路径规则

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

```json
{
  "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 按钮

```xml
<!-- 主题 -->
<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 输入框

```xml
<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 单元格

```xml
<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 对话框

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

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

### Toast 轻提示

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

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

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

### Popup 弹出层

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

### Tabs 选项卡

```xml
<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 导航条

```xml
<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 底部标签栏

```xml
<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 搜索框

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

### Empty 空状态

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

### Loading 加载

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

### Skeleton 骨架屏

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

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

## 样式覆盖（4 种方式）

### 1. style / custom-style 属性
```xml
<t-button style="color: red">按钮</t-button>
<t-button custom-style="color: red">按钮</t-button>
```
开启 virtualHost 时两者效果一致；未开启时只能用 `custom-style`。

### 2. 解除样式隔离
TDesign 全体组件开启了 `addGlobalClass`，页面样式可直接覆盖：
```css
/* 页面 wxss */
.t-button--primary {
  background-color: navy;
}
```
在自定义组件中使用需开启 `styleIsolation: 'shared'`。

### 3. 外部样式类
```xml
<t-button t-class="my-btn-class">按钮</t-button>
```
```css
.my-btn-class {
  color: red !important;
}
```
每个组件支持的外部样式类见组件文档（如 `t-class`、`t-class-icon`、`t-class-content` 等）。

### 4. CSS 变量
```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](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/style/_variables.less)

```css
/* 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` 引入主题变量：
```css
@import 'miniprogram_npm/tdesign-miniprogram/common/style/theme/_index.wxss';
```
3. 页面样式使用 CSS Variable：
```css
.text {
  color: var(--td-text-color-secondary);
}
```

### 特殊组件适配

自定义 TabBar 和 root-portal 内的组件需手动添加 `.page` 类名：
```xml
<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