tdesign-miniprogram 贡献指南：从编码规范、组件开发到测试与发布的完整工作流-平芜编程栈

前端
UI组件
小程序
设计系统
移动开发

【免费下载链接】tdesign-miniprogram

Wechat MiniProgram and Uniapp UI components lib for TDesign

项目地址：https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram

本文围绕仓库根目录的 CONTRIBUTING.md 展开，系统讲解 tdesign-miniprogram（TDesign 微信小程序与 uni-app 组件库）的官方贡献规范：t-前缀约定、Airbnb JS 规范、LESS 样式规范、Git Flow 分支策略与 Conventional Commits 提交规范、pnpm + gulp驱动的开发服务、组件目录与示例页的路由约定，以及基于miniprogram-simulate/miniprogram-automator的两层测试体系和版本发布流程。读完后，你可以按照仓库现有结构规范地完成一个新组件的开发、测试与提交。

一、开发规范：前缀、JavaScript 与 CSS

`t-`前缀：JS 与 CSS 统一由变量控制

组件和 CSS 前缀统一以t-开头。官方文档强调"无论 JS 还是 CSS 都使用变量定义前缀，方便后续替换"。在仓库中可以印证这一约定：

全局样式变量：packages/components/common/style/_variables.less 第一行即@prefix: t;，所有组件 LESS 类名基于该变量拼接；
运行时配置：packages/components/common/config.ts 导出prefix: CONFIG_PREFIX，JS 侧生成的类名、唯一 ID（如 packages/components/common/utils.ts 中的${prefix}_${compName}_${number}）均取用同一前缀；
测试环境同样显式注入前缀：packages/tdesign-miniprogram/test/jest.config.js 中globals: { CONFIG_PREFIX: 't' }，保证单测运行时与真机一致。

从源码结构看，前缀在三处（LESS 变量、JS 配置、测试全局量）保持单一事实来源，这也是"方便后续替换"这一设计意图的具体落地方式。

JavaScript：Airbnb 规范与自动修复

JS 遵循 Airbnb JavaScript 编码规范，仓库通过 ESLint 落地：根 package.json 的devDependencies包含eslint、eslint-config-airbnb-base、@typescript-eslint/parser等，并提供了两条脚本：

npm run lint：对packages/components、packages/pro-components、packages/tdesign-miniprogram/example下的js/ts做检查；
npm run lintfix：在lint基础上追加--fix自动修复。

此外还有npm run format（Prettier 批量格式化）以及lint:uniapp/lintfix:uniapp针对 uni-app 侧vue/ts/js文件的独立检查入口，可见仓库对小程序端与 uni-app 端分别维护 lint 规则。

CSS：LESS + TDesign CSS 命名规范

组件样式使用 LESS 开发，并遵循 TDesign 的 CSS 命名规范（BEM 风格）。构建链中由gulp-less（见 pnpm-workspace.yaml 的 catalog 依赖声明less、gulp-less）完成编译。命名上可以观察 packages/components/common/style/_variables.less 中以@prefix: t;为根的变量组织方式，与t-radio、t-cell等组件实际类名保持一致。

二、Git 规范：分支策略与提交说明

分支：Git Flow，从`develop`拉特性分支

主仓库遵循 Git Flow 规范：新组件分支一律从developcheckout，例如贡献 button 组件时使用feature/button分支。这一约定配合后面的 tag 发布流程（见第五节），使develop成为日常集成分支。

提交：Conventional Commits + 本地自动校验

仓库使用的提交规范是@commitlint/config-conventional，可以直接看到根目录 commitlint.config.js 的全部内容：

module.exports = { extends: ['@commitlint/config-conventional'] };

配套机制在根 package.json 中均有落点：

提交信息辅助生成：config.commitizen.path指向cz-conventional-changelog，即通过 commitizen 交互式生成符合规范的 commit 信息；
钩子挂载："prepare": "husky"表明使用 husky 挂载 Git hooks；
pre-commit 自动修复：lint-staged配置对暂存的js/ts/wxss/less/wxml/html/json/md/wxs文件执行prettier --write，对小程序侧js/ts执行eslint --fix，对 uni-app 侧ts/js/vue执行eslint --fix。对应贡献文档中"提交会触发 git pre-commit 检查，修复提示的 ESLint 错误"的说明；
changelog 生成：fix与feat类型的提交会被用来生成 changelog，仓库另提供npm run changelog（对应 script/generate-changelog.js）辅助生成。

这意味着每次git commit时，提交信息校验与文件级 lint 修复都会自动执行，无需人工把关。

三、环境准备与开发服务

安装依赖

pnpm install

这是一个 pnpm monorepo：根 package.json 声明packageManager: pnpm@11.20.0，pnpm-workspace.yaml 将packages/**全部纳入工作区（排除packages/common与uni_modules），并通过catalog机制统一各子包的依赖版本。依赖安装后prepare脚本会自动完成 husky 钩子初始化。

启动开发服务

npm start

start实际执行cross-env NODE_ENV=development gulp dev --gulpfile script/gulpfile.js。查看 script/gulpfile.js 可知任务编排：

const build = gulp.series(dist.build, example.build('all')); const watch = gulp.parallel(dist.watch, example.watch); const dev = gulp.series(build, watch);

即先构建再并行监听 dist 与 example 两条流水线。贡献文档中给出的两条构建路径与 script/gulpfile.example.js 的实现一一对应：

组件源码packages/components编译产物输出到packages/tdesign-miniprogram/miniprogram_dist（dist 流水线）；
示例工程packages/tdesign-miniprogram/example输出到仓库根下_example目录。gulp 任务syncDist会把miniprogram_dist同步进_example/miniprogram_npm/tdesign-miniprogram，使示例工程以 npm 包方式引用刚构建的组件。

构建完成后，使用微信开发者工具导入_example文件夹即可在真机/模拟器中调试示例。

示例页如何从源码同步到示例工程

script/gulpfile.example.js 中的copySrcExample任务负责示例页同步，其输入模式为packages/components/**/_example/**/*.*，输出目录为packages/tdesign-miniprogram/example/pages。这与贡献文档中"路由路径规范为packages/components/${组件名}/_example/${组件名}，代码最终会拷贝到example/${组件名}/${组件名}"完全一致——gulp 通过重命名管线把_example前缀剥离，使每个示例页在示例工程中拥有独立的路由目录。

四、组件开发：目录结构与文件约定

贡献文档给出新组件的开发步骤：在组件源码路径下创建组件文件夹及对应的wxml、ts、json、md文件，并在文件夹内创建_example存放示例页；新组件示例页二维码需要联系 PMC 生成。

以仓库中真实的 radio 组件为例，一个完整组件目录的实际形态比文档列举的文件更多，参考 packages/components/radio：

packages/components/radio/ ├── radio.ts # 组件逻辑 ├── radio.wxml # 模板 ├── radio.json # 组件配置 ├── radio.less # 样式 ├── props.ts # 属性定义 ├── type.ts # 类型定义 ├── README.md # 组件文档（中文） ├── README.en-US.md # 组件文档（英文） ├── __test__/ # 单元测试（见下节） └── _example/ # 示例页，每个子目录一个 demo（base/card/horizontal/...）

其中_example下的每个子目录（如_example/base、_example/card）都会成为示例工程中的一个独立路由页面，并被测试系统扫描生成快照测试（见下节），因此新增 demo 后记得重新生成测试文件。

官方文档开发

官方文档（组件站点）的代码位于site子目录中，当前仓库即 packages/tdesign-miniprogram/site。根 package.json 提供了site:dev（本地开发）、site:prerender（预渲染）等脚本，均通过pnpm -C委托到 site 子包执行。文档的本地编译运行细节以 site 子目录内的 README 为准。

五、测试体系：单元测试与端到端测试

单元测试与集成测试：miniprogram-simulate + jest

用例放置在packages/components下对应组件目录的__test__目录中，例如 packages/components/radio/test/index.test.js。其典型写法是通过miniprogram-simulate加载并渲染组件，然后断言 data 与交互事件：

import simulate from 'miniprogram-simulate'; const id = load(path.resolve(__dirname, './index')); it(':base', async () => { const comp = simulate.render(id); comp.attach(document.createElement('parent-wrapper')); const radio = comp.querySelector('.single'); expect(radio.data.checked).not.toBeTruthy(); radio.querySelector('.t-radio__icon').dispatchEvent('tap'); await simulate.sleep(10); expect(radio.data.checked).toBeTruthy(); });

执行命令：

npm run test

从根 package.json 看，test会委托到 packages/tdesign-miniprogram/test/package.json，其中"test": "jest && jest -c jest.e2e.config.js"，即一次命令依次跑完单测与 E2E；也可以分开执行npm run test:unit与npm run test:e2e。

结合 packages/tdesign-miniprogram/test/jest.config.js 可以确认几个关键细节：

单测匹配规则：packages/(components|pro-components|uniapp-components)/**/__test__/**/*.test.{js,ts}，因此__test__目录名是硬性约定；
moduleNameMapper将tdesign-miniprogram/*映射到packages/components/*，测试无需关心包发布形态；
snapshotSerializers使用miniprogram-simulate/jest-snapshot-plugin，使快照输出为可读的小程序结构而非原始 JSON；
报告输出到test/unit/report/test-report.html（jest-html-reporter），覆盖率由 v8 provider 收集，type.ts/props.ts等纯类型文件被排除在覆盖率统计之外。

另外仓库还有一个"demo 快照测试"的自动化脚本：packages/tdesign-miniprogram/test/scripts/gen-demo-test.js（即npm run test:demo）会扫描每个组件_example下的全部 demo 目录，自动生成__test__/demo.test.js，对每个示例页执行"渲染即快照"的回归测试——文件头部明确注释"由脚本自动生成，请勿手写直接修改，否则会被覆盖"。

端到端测试：miniprogram-automator + jest

E2E 用例放置在示例工程的example/pages对应组件目录的__test__目录中，例如example/pages/radio/__test__/index.test.js。执行命令：

npm run test:e2e

对应 packages/tdesign-miniprogram/test/jest.e2e.config.js，其testMatch匹配示例工程下的__test__用例，覆盖率与 HTML 报告分别输出到test/e2e/coverage与test/e2e/report。E2E 依赖miniprogram-automator连接开发者工具自动化实例，因此运行前提是示例工程已构建且开发者工具可用，这一点在实际执行时需注意。

六、版本发布流程

发布版本前需先确认要升级到的目标版本，遵循语义化版本（semver）规则。贡献文档给出的发布步骤如下，其中第 3 步"打包可直接使用的代码（npm run build:assets）"已于 0.7.0 移除，不再执行：

更新 packages/tdesign-miniprogram/package.json 的版本；
更新CHANGELOG，添加本次发布的变更信息（可借助npm run changelog与standard-changelog生成）；
~~打包可直接使用的代码：npm run build:assets~~（0.7.0 起移除）；
在develop分支打上 tag，使用纯数字版本号，如0.1.0；
提交 commit 并推送到 origin。

推送 tag 后即触发 CI/CD 流程，自动完成三件事：

发布 npm 包；
上传小程序包；
更新 TDesign 官网。

CI/CD 之后还需要人工完成小程序侧的收尾：

在 TDesign 小程序体验版中测试对应变更是否正常；
测试通过后到微信公众平台将刚上传的版本提交审核；
审核通过后点击发布，本次发布流程才真正结束。

可以推断，"develop 分支打 tag + 推送触发 CI/CD"与第二节的 Git Flow 分支策略是一体的：develop负责集成，tag 作为发布信号，npm、小程序包、官网三条发布线由同一信号驱动，保证三端版本一致。

七、贡献流程速查

环节	命令 / 操作	说明
安装依赖	`pnpm install`	pnpm monorepo，catalog 统一版本
开发服务	`npm start`	构建 + 监听`miniprogram_dist`与`_example`
导入调试	微信开发者工具导入`_example`	含`miniprogram_npm`组件包
代码检查	`npm run lint`/`npm run lintfix`	Airbnb 规范 + Prettier
单元测试	`npm run test:unit`（或`npm run test`）	miniprogram-simulate + jest
demo 快照	`npm run test:demo`	扫描`_example`自动生成快照用例
端到端测试	`npm run test:e2e`	miniprogram-automator + jest
提交规范	Conventional Commits	commitizen 辅助，husky 钩子自动校验与修复
发布	改版本 → CHANGELOG → develop 打 tag → 推送	CI/CD 发布 npm/小程序包/官网，再到公众平台提审发布

以上流程均可在仓库中逐一验证：规范配置见 commitlint.config.js 与根 package.json，构建脚本见 script/gulpfile.js、script/gulpfile.example.js，测试配置见 packages/tdesign-miniprogram/test/jest.config.js 与 packages/tdesign-miniprogram/test/jest.e2e.config.js。按照这套约定贡献代码，能确保变更在规范校验、自动化测试和 CI/CD 发布链路上平滑流转。

前端
UI组件
小程序
设计系统
移动开发

【免费下载链接】tdesign-miniprogram

Wechat MiniProgram and Uniapp UI components lib for TDesign

项目地址：https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram

点击查看免费下载

tdesign-miniprogram 贡献指南：从编码规范、组件开发到测试与发布的完整工作流

【免费下载链接】tdesign-miniprogram

一、开发规范：前缀、JavaScript 与 CSS

`t-`前缀：JS 与 CSS 统一由变量控制

JavaScript：Airbnb 规范与自动修复

CSS：LESS + TDesign CSS 命名规范

二、Git 规范：分支策略与提交说明

分支：Git Flow，从`develop`拉特性分支

提交：Conventional Commits + 本地自动校验

三、环境准备与开发服务

安装依赖

启动开发服务

示例页如何从源码同步到示例工程

四、组件开发：目录结构与文件约定

官方文档开发

五、测试体系：单元测试与端到端测试

单元测试与集成测试：miniprogram-simulate + jest

端到端测试：miniprogram-automator + jest

六、版本发布流程

七、贡献流程速查

【免费下载链接】tdesign-miniprogram

相关推荐

UltiSnips 贡献指南：从测试编写、代码规范到 Bug 复现的完整开发工作流

WeChatMsg：免费把微信聊天记录导出成 Word、HTML 和 CSV 的开源工具

Kubeshark 贡献指南详解：从代码规范到测试与发布的完整协作流程

windows_exporter memory collector 深度解析：Windows 内存指标采集原理、完整指标清单与监控告警实践

coreboot 模块定制机制解析：用 __weak 弱符号实现静态钩子

VB.NET WinForms全局异常捕获三层架构与数据保全实战

台风烧录器实战：内存SPD读写与DDR5避坑指南

让 AI 少读一点：谁来决定删掉哪些信息

STC15单片机驱动OLED黑屏排查：IO模式、I²C地址与时序三要素

【免费下载链接】tdesign-miniprogram

一、开发规范：前缀、JavaScript 与 CSS

t-前缀：JS 与 CSS 统一由变量控制

JavaScript：Airbnb 规范与自动修复

CSS：LESS + TDesign CSS 命名规范

二、Git 规范：分支策略与提交说明

分支：Git Flow，从develop拉特性分支

提交：Conventional Commits + 本地自动校验

三、环境准备与开发服务

安装依赖

启动开发服务

示例页如何从源码同步到示例工程

四、组件开发：目录结构与文件约定

官方文档开发

五、测试体系：单元测试与端到端测试

单元测试与集成测试：miniprogram-simulate + jest

端到端测试：miniprogram-automator + jest

六、版本发布流程

七、贡献流程速查

【免费下载链接】tdesign-miniprogram

相关推荐

UltiSnips 贡献指南：从测试编写、代码规范到 Bug 复现的完整开发工作流

WeChatMsg：免费把微信聊天记录导出成 Word、HTML 和 CSV 的开源工具

Kubeshark 贡献指南详解：从代码规范到测试与发布的完整协作流程

windows_exporter memory collector 深度解析：Windows 内存指标采集原理、完整指标清单与监控告警实践

coreboot 模块定制机制解析：用 __weak 弱符号实现静态钩子

VB.NET WinForms全局异常捕获三层架构与数据保全实战

台风烧录器实战：内存SPD读写与DDR5避坑指南

让 AI 少读一点：谁来决定删掉哪些信息

STC15单片机驱动OLED黑屏排查：IO模式、I²C地址与时序三要素

`t-`前缀：JS 与 CSS 统一由变量控制

分支：Git Flow，从`develop`拉特性分支