TDesign Miniprogram 组件库实践

项目地址：https://github.com/Tencent/tdesign-miniprogram
文档：https://tdesign.tencent.com/miniprogram
关联清单：https://github.com/justjavac/awesome-wechat-weapp

TDesign Miniprogram 是腾讯出品的企业级小程序组件库，设计统一、规范完善、覆盖广泛，适合中大型业务。

🎯 文章目标

• 安装与按需接入 TDesign Miniprogram
• 完成基础组件使用与交互
• 进行主题定制与工程化治理
• 了解常见问题与调试思路

⚙️ 安装与引入

npm i tdesign-miniprogram -S
# 微信开发者工具：工具 -> 构建 npm

按需在页面 JSON 中声明 usingComponents（以 Button、Dialog 为例）：

// pages/index/index.json
{
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button",
    "t-dialog": "tdesign-miniprogram/dialog/dialog"
  }
}

页面示例：

<!-- pages/index/index.wxml -->
<view class="container">
  <t-button theme="primary" bindtap="onOpen">打开对话框</t-button>
  <t-dialog id="dialog" title="提示" content="确认继续？" />
</view>

// pages/index/index.js
Page({
  onOpen() {
    const dialog = this.selectComponent('#dialog')
    dialog?.show?.()
  }
})

🎨 主题与样式定制

• 推荐按官方主题方案进行变量覆盖（参考文档「定制主题」）
• 可通过定制样式文件在 app.wxss 最后引入，逐步覆盖色板与间距体系
• 优先使用组件 props 控制尺寸/状态，再用样式覆盖细节

🏗️ 工程实践

• 按需与分包：仅在使用页面声明组件，分包内页面使用的组件放在分包 JSON 中声明，降低主包体积
• 统一二次封装：把业务常用的按钮、表单项等二次封装为 app- 前缀组件，统一文案与交互
• 表单治理：结合统一校验库或自研校验模块，输出一致的错误提示样式与规则
• 可访问性：对重要交互组件补充无障碍属性，确保读屏友好

🧪 常见问题

• 构建 npm 报错：清理 miniprogram_npm 并重建；检查基础库与工具版本
• 样式覆盖无效：确认引入顺序、作用域与选择器权重；必要时使用更具体的选择器
• 包体增大：避免一次性注册大量组件，按页面拆分并结合分包

✅ 适用场景

• 规范统一、体量较大的企业级小程序
• 对设计一致性、可维护性要求高的项目
• 需要完善组件覆盖与文档支持的团队

🔗 参考

• GitHub：https://github.com/Tencent/tdesign-miniprogram
• 文档：https://tdesign.tencent.com/miniprogram
• 自定义组件：https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/

📊 总结

TDesign Miniprogram 在规范、覆盖与质量上表现稳定，适合中大型团队。通过按需引入、主题层与二次封装，可在保证一致性的前提下快速交付。