UI 视觉设计 / 系统课时
为破坏性变更制定版本规则
为破坏性变更制定版本规则
组件库把 Button.kind 改成 Button.variant,即使按钮外观不变,也可能让存量项目在升级后编译失败。这里用一次属性改名建立版本分级、弃用过渡、发布验收和升级通知规则,让维护者与接入方都能依据同一份证据决定何时升级。
学习目标
- 按公开契约的兼容性区分 PATCH、MINOR 和 MAJOR。
- 为属性废弃与移除安排可验证的迁移窗口。
- 编写包含影响范围、验收证据和升级动作的发布说明。
用消费方能否继续工作判定版本
先在组件规范中列出公开契约:属性和类型、事件与插槽、设计令牌与 CSS 变量、默认行为,以及承诺稳定的键盘和无障碍语义。改动是否“破坏”,应以已有合法用法升级后能否正常工作为准,而不是以代码改了多少行判断。
对已发布稳定版,采用 SemVer 2.0.0 的三段版本号。以当前 1.4.2 为例:
| 级别 | 版本示例 | 可以这样改 | 不可以混入 |
|---|---|---|---|
| PATCH(修复) | 1.4.3 |
修复不影响既有正确用法的焦点环缺失 | 移除属性、改变默认值 |
| MINOR(兼容扩展) | 1.5.0 |
新增可选 variant 属性,同时保留 kind;将 kind 标记为弃用 |
让旧 kind 调用失效 |
| MAJOR(破坏性) | 2.0.0 |
正式移除 kind,要求接入方改用 variant |
不写迁移说明就静默发布 |
即使 TypeScript 类型未变化,删除已公开的令牌、改变按钮默认尺寸、修改事件触发时机,也可能破坏消费方。反过来,视觉快照变化不自动等于 MAJOR:先核对是否是经过确认、且仍兼容公开契约的错误修复。
给属性改名留出兼容窗口
假设 Button 在 1.4.2 只接受 kind="danger"。先于 1.5.0 新增 variant 并保留旧属性,文档写明弃用;直到 2.0.0 才移除 kind。下面是可用 Node.js 18+ 运行的属性解析演示:将代码保存为 button-version.mjs,执行 node button-version.mjs。
function resolveV15({ kind, variant } = {}) {
// 兼容期允许旧属性,新属性优先
return variant ?? kind ?? "primary";
}
function resolveV2({ kind, variant } = {}) {
// 主版本移除旧属性,避免旧调用被悄悄忽略
if (kind !== undefined) throw new Error("kind 已移除,请使用 variant");
return variant ?? "primary";
}
console.log(`1.5.0 旧调用: ${resolveV15({ kind: "danger" })}`);
try {
resolveV2({ kind: "danger" });
} catch (error) {
console.log(`2.0.0 旧调用: ${error.message}`);
}
console.log(`2.0.0 新调用: ${resolveV2({ variant: "danger" })}`);预期输出:
1.5.0 旧调用: danger
2.0.0 旧调用: kind 已移除,请使用 variant
2.0.0 新调用: danger示例只演示公开属性的解析规则,不是完整的 UI 渲染实现。实际发布 2.0.0 时,还应从组件的 TypeScript 声明中删除 kind,使未迁移的调用在类型检查阶段暴露,而不是等用户点击后才发现异常。
将变更分级纳入发布审批
团队可以采用下列发布门禁;其中“两款存量产品”是本例的验收范围,实际项目应覆盖全部关键消费者。
- 提交变更单:写明组件、旧用法、新用法、可能受影响的页面或封装层,以及预计版本。
- 判定等级:旧用法失效、默认行为改变或已公开令牌被移除时标记 MAJOR;兼容新增和弃用公告标记 MINOR;仅兼容性修复标记 PATCH。
- 准备证据:在 Storybook 固定
primary、secondary、danger状态;检查键盘焦点、禁用行为和已批准视觉基线。 - 评审放行:组件库单测与类型检查通过;两款存量产品完成构建和冒烟;未获批准的视觉差异为 0;MAJOR 必须附迁移指南及回退策略。
- 发布归档:将代码、文档、变更记录与版本标签一一对应,留存审批人和验收链接。

让升级通知可直接照做
以发布 2.0.0 为例,变更说明至少要写到以下粒度:
- 破坏点:
Button.kind已移除;从1.5.0起就已声明弃用,替代属性为variant。 - 迁移动作:搜索
Button的调用及二次封装,将kind="danger"改为variant="danger";不要批量替换其他对象中同名的kind。 - 验收方法:升级依赖后运行项目类型检查与组件测试,复核删除确认等高风险按钮的视觉、焦点和点击行为。
- 通知计划:示例团队在 MAJOR 发布前 14 天告知接入方,发布当天附上变更记录、迁移指南、负责人和问题反馈渠道;这个提前量是团队策略,不是 SemVer 的强制规定。
如果上线后发现阻断问题,应暂停升级推广,指导消费者回退到已验证的上一主版本,或发布新的修复版本;不要修改已经发布的 2.0.0 包内容。这样版本号、迁移路径和实际验收记录才能相互对应。