1

2026-03-15 10:15:02 +08:00
parent 2dd217522c
commit 72bb11b34f
916 changed files with 65306 additions and 16102803 deletions
--- a/_DEL/wechat-miniprogram/steering/tdesign.md
+++ b/_DEL/wechat-miniprogram/steering/tdesign.md
@@ -0,0 +1,511 @@
+# 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