tdesign-miniprogram-plus

本项目是基于 TDesign 官方 tdesign-miniprogram（develop 主干，当前对齐上游 v1.15.0）的派生增强版。

关于本项目

tdesign-miniprogram-plus 在保持与官方 tdesign-miniprogram 完全兼容的前提下，提供一些官方暂未支持的增量功能：

• 完全兼容原版：组件 API、引用路径、用法与官方一致，可平滑替换 —— 把依赖与引用里的 tdesign-miniprogram 换成 tdesign-miniprogram-plus 即可。
• 持续同步上游：版本号采用 x.y.z-plus.N 格式，其中 x.y.z 即对应的官方版本（例如 1.15.0-plus.1 表示基于官方 1.15.0）。

如需官方原版，请前往 Tencent/tdesign-miniprogram。

基于官方的改造

下面列出本项目相比官方 tdesign-miniprogram 的增量改造，均为新增能力，不改变官方既有属性的默认行为。

Cascader 级联选择器：新增搜索能力（filterable）

官方 Cascader 仅支持逐级点选，本项目为其新增关键词搜索：开启 filterable 后顶部出现搜索框，输入关键字时层级面板切换为扁平的匹配路径列表，直接定位目标项；清空关键字则恢复正常层级选择。

新增属性：

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | filterable | Boolean | false | 是否可搜索。开启后顶部展示搜索框，输入关键字将层级面板切换为扁平的匹配路径列表 | | filter | Function | - | 自定义过滤函数，返回 true 表示匹配。签名 (keyword, option, path) => boolean；缺省时使用大小写不敏感的内置匹配（命中路径中任一 label 或叶子节点文本） | | filter-placeholder | String | - | 搜索框占位文案，缺省回退到全局语言包 |

用法示例：

<t-cascader
  visible="{{visible}}"
  value="{{value}}"
  options="{{options}}"
  filterable
  filter-placeholder="搜索地区"
  bind:change="onChange"
/>

配套新增了 --td-cascader-filter-* 系列 CSS 变量用于定制搜索结果列表样式，详见组件文档。

组件依赖闭包裁剪脚本（物理 tree-shaking）

官方未提供按需裁剪能力：即便开启 lazyCodeLoading: "requiredComponents" 也只优化启动注入，并不减小 miniprogram_npm 包体积。本项目新增 script/tree-shake.mjs，按下游小程序实际引用到的组件对全量 dist 做物理裁剪 —— 计算依赖闭包后删除未引用的组件目录与开发期冗余文件，显著减小打包体积。

特性：

• 依赖闭包分析：从 app 各 .json 的 usingComponents 求根集，BFS 解析组件间相对引用至不动点；并扫描 @import(wxss)、<wxs src>(wxml)、require/import(js) 的内嵌依赖，保守保留（宁可多留不错删）。
• 安全护栏：始终保留 common/mixins/locale/config-provider 共享目录；根集为空时默认中止以防误删整库，--dry-run 仅预览、--force 强制执行。
• 零依赖：仅用 Node 内置模块，node 直接可跑。

用法：

node script/tree-shake.mjs --app <小程序源码根目录> --dist <tdesign dist 目录> [--lib tdesign-miniprogram-plus] [--dry-run] [--force]

TDesign 适配微信小程序的组件库。

预览

小程序组件示例小程序，请使用微信扫码预览 ↓

安装

使用 NPM

小程序已经支持使用 NPM 安装第三方包。

具体使用方式，可以参考小程序官网文档： 《NPM 支持》

npm i tdesign-miniprogram-plus -S --production

建议使用 NPM，不再推荐“源码拷贝的方式”

使用组件

以按钮组件为例，只需要在 JSON 文件中引入按钮对应的自定义组件即可

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

在开发者工具中预览

# 安装项目依赖
pnpm install

# 执行组件编译
npm run dev

打开微信开发者工具，把 _example 目录添加进去就可以预览示例了。

基础库版本

最低基础库版本^2.6.5

贡献成员

反馈

有任何问题，建议通过 Github issues 反馈或扫码加入用户微信群。

开源协议

TDesign 遵循 MIT 协议。