512 lines
14 KiB
Markdown
512 lines
14 KiB
Markdown
# 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
|