# tdesign-miniprogram-plus > 本项目是基于 [TDesign 官方 `tdesign-miniprogram`](https://github.com/Tencent/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](https://github.com/Tencent/tdesign-miniprogram)。 ## 基于官方的改造 下面列出本项目相比官方 `tdesign-miniprogram` 的增量改造，均为**新增能力**，不改变官方既有属性的默认行为。 ### Cascader 级联选择器：新增搜索能力（`filterable`） 官方 `Cascader` 仅支持逐级点选，本项目为其新增关键词搜索：开启 `filterable` 后顶部出现搜索框，输入关键字时层级面板切换为**扁平的匹配路径列表**，直接定位目标项；清空关键字则恢复正常层级选择。 新增属性： | 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `filterable` | `Boolean` | `false` | 是否可搜索。开启后顶部展示搜索框，输入关键字将层级面板切换为扁平的匹配路径列表 | | `filter` | `Function` | - | 自定义过滤函数，返回 `true` 表示匹配。签名 `(keyword, option, path) => boolean`；缺省时使用大小写不敏感的内置匹配（命中路径中任一 label 或叶子节点文本） | | `filter-placeholder` | `String` | - | 搜索框占位文案，缺省回退到全局语言包 | 用法示例： ```html ``` > 配套新增了 `--td-cascader-filter-*` 系列 CSS 变量用于定制搜索结果列表样式，详见组件文档。 ### 组件依赖闭包裁剪脚本（物理 tree-shaking） 官方未提供按需裁剪能力：即便开启 `lazyCodeLoading: "requiredComponents"` 也只优化启动注入，并不减小 `miniprogram_npm` 包体积。本项目新增 `script/tree-shake.mjs`，按下游小程序**实际引用到的组件**对全量 dist 做物理裁剪 —— 计算依赖闭包后删除未引用的组件目录与开发期冗余文件，显著减小打包体积。 特性： - **依赖闭包分析**：从 app 各 `.json` 的 `usingComponents` 求根集，BFS 解析组件间相对引用至不动点；并扫描 `@import`(wxss)、``(wxml)、`require/import`(js) 的内嵌依赖，保守保留（宁可多留不错删）。 - **安全护栏**：始终保留 `common`/`mixins`/`locale`/`config-provider` 共享目录；根集为空时默认中止以防误删整库，`--dry-run` 仅预览、`--force` 强制执行。 - **零依赖**：仅用 Node 内置模块，`node` 直接可跑。 用法： ```bash node script/tree-shake.mjs --app <小程序源码根目录> --dist [--lib tdesign-miniprogram-plus] [--dry-run] [--force] ``` [TDesign](https://github.com/Tencent/tdesign) 适配微信小程序的组件库。 ## 预览 小程序组件示例小程序，请使用微信扫码预览 ↓
## 安装 ### 使用 NPM 小程序已经支持使用 NPM 安装第三方包。 具体使用方式，可以参考小程序官网文档： [《NPM 支持》](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html?search-key=npm) ```bash npm i tdesign-miniprogram-plus -S --production ``` > 建议使用 NPM，不再推荐“源码拷贝的方式” ## 使用组件 以按钮组件为例，只需要在 `JSON` 文件中引入按钮对应的自定义组件即可 ```json { "usingComponents": { "t-button": "tdesign-miniprogram-plus/button/button" } } ``` ## 在开发者工具中预览 ```bash # 安装项目依赖 pnpm install # 执行组件编译 npm run dev ``` 打开[微信开发者工具](https://mp.weixin.qq.com/debug/wxadoc/dev/devtools/download.html)，把 `_example` 目录添加进去就可以预览示例了。 ## 基础库版本 最低基础库版本`^2.6.5` ## 贡献成员 ## 反馈 有任何问题，建议通过 [Github issues](https://github.com/Tencent/tdesign-miniprogram/issues) 反馈或扫码加入用户微信群。 ## 开源协议 TDesign 遵循 [MIT 协议](https://github.com/Tencent/tdesign-miniprogram/LICENSE)。