读透 Angular Components 的 CHANGELOG从 v20 到 v22 的版本演进、破坏性变更与升级迁移指南【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components本篇指南以本仓库根目录下的 CHANGELOG.md 为核心主线系统讲解 Angular ComponentsAngular Material 与 CDK 的官方组件基础设施的版本发布体系与变更记录组织方式从版本条目结构与代号命名规律到 Breaking Changes 区块的解读方法再到 feat/fix/refactor 提交表的阅读技巧。读者读完后将能够快速定位任意版本的核心变更、评估升级风险、并根据仓库源码src/aria、src/cdk、src/material 与 goldens印证变更背后的实现细节。一、CHANGELOG.md 是什么一份贯穿十年的版本编年史CHANGELOG.md是 Angular Components 仓库中最重要的元文档之一完整记录了从 2021 年 v12 到当前 v22 时代以及更早通过 CHANGELOG_ARCHIVE.md 归档的历史版本每一轮发布的全部公开变更。当前仓库根目录的 package.json 中版本号为22.2.0-next.5与 CHANGELOG 顶部最新的22.2.0-next.5 bismuth-badge (2026-09-09)条目一一对应说明该文档由发布流水线同步生成是最新代码库状态的权威反映。整个文件的组织遵循时间倒序原则最新的版本在最顶部越往下越古老直至 12.0.0 之前的Changes Prior to 12.0.0收尾段落。每个版本条目通过一个!-- CHANGELOG SPLIT MARKER --注释分隔该标记供自动化工具按版本切分内容便于在发布时提取本次新增的变更片段。1.1 版本条目三段式结构以仓库中任意一个版本条目为例一个完整的版本记录包含三个组成部分版本标题行# 22.2.0-next.5 bismuth-badge (2026-09-09)Breaking Changes 区块仅在大版本或关键小版本中出现按aria/cdk/material/multiple等包范围分组列出破坏性 API 变更提交表按包范围scope分组的提交记录表格每行包含 Commit、Type、Description 三列1.2 版本号三段式语义从条目中可以归纳出三类版本流版本类型示例含义预发布next22.2.0-next.5下一 minor/major 的滚动预览随主分支持续迭代补丁patch22.1.6仅含 bug fix无新特性与 next 并行发布正式发布22.1.0/22.0.0minor 为特性发布major 为里程碑版本含破坏性变更从文件头部可以看出维护团队采用next 与 patch 双轨并行的策略例如 2026-09-09 同一天同时发布了22.2.0-next.5与22.1.6前者承载后续功能迭代后者为当前稳定分支的修复。这种节奏保证了使用稳定版的用户能及时获得缺陷修复而尝鲜者可以在 next 上提前验证新特性。1.3 代号Codename命名规律每个版本都配有一个由物质/材料 动物或物品构成的押韵代号bismuth-badge铋徽章、platinum-piano铂金钢琴、nickel-nanobot镍纳米机器人、hydrogen-horse氢马、calcium-carrot钙胡萝卜、aurostibite-ambulance锑金矿救护车、damask-dachshund锦缎腊肠犬。这些代号是 Angular 社区的标志性传统方便在 CI 产物、发布说明和社区讨论中无歧义地指代某个具体版本——例如bismuth-badge 修了什么比22.2.0-next.5更容易记忆和传播。二、Breaking Changes 区块升级前必须阅读的迁移清单CHANGELOG 中最具实战价值的段落是每个 major 版本如 22.0.0、21.0.0、20.0.0开头的## Breaking Changes。它按包范围逐条列出所有不兼容变更本质上就是官方给出的迁移工作清单。下面结合仓库源码解读三类典型的破坏性变更模式。2.1 API 整体替换与重命名以 22.0.0 的 aria 为例22.0.0 版本的aria区块宣布了 Combobox 组件的重大架构调整移除旧的 legacy combobox 与 autocomplete 实现全面切换到独立的 standalone comboboxSimpleCombobox被提升promote为正式的Combobox所有simple-combobox前缀的符号、选择器和 token 统一改名为combobox前缀如SIMPLE_COMBOBOX_POPUP→COMBOBOX_POPUP对应的示例代码被重定位到 src/components-examples/aria/autocomplete 与 src/components-examples/aria/toolbar。这一变更在源码中留有清晰的痕迹src/aria/combobox 目录下的公开 API 文件 public-api.ts 与核心实现 combobox.ts、combobox-widget.ts 即为迁移后的正式入口同时 22.0.0 还同步更新了 goldens/aria 下的 API 黄金文件golden files。对使用者而言升级到 22.0.0 后模板中aria-combobox的取值方式与 import 路径都发生了变化需要对照该区块逐条修改。2.2 删除过时 API以 21.0.0 的工厂函数大扫除为例21.0.0 的 Breaking Changes 是仓库历史上规模最大的一次清理特点是成批删除带_FACTORY/_PROVIDER后缀的工厂函数与动画符号CDK 侧移除了LIVE_ANNOUNCER_ELEMENT_TOKEN_FACTORY、TREE_KEY_MANAGER_FACTORY等工厂Material 侧移除了几乎每个组件的默认选项工厂与滚动策略工厂例如MAT_AUTOCOMPLETE_DEFAULT_OPTIONS_FACTORY、MAT_DATEPICKER_SCROLL_STRATEGY_FACTORY、MAT_TOOLTIP_DEFAULT_OPTIONS_FACTORY同时删除了所有matXxxAnimations动画符号如matDialogAnimations、matSelectAnimations、matTooltipAnimationsPortal 体系完成术语统一TemplatePortalDirective→CdkPortalPortalHostDirective→CdkPortalOutletDomPortalHost→DomPortalOutlet20.0.0 时已先删除旧版 PortalHost 系列。这些删除动作背后的原因在 21.0.0 的提交描述中可见端倪——remove deprecated factory functions与remove deprecated animation definitions即 Angular 组件库在向 signals 优先、独立于 View Engine 的现代架构演进过程中逐步淘汰基于构造器注入与工厂 provider 的旧式 API。对升级者的启示如果你在代码中注入了任何MAT_*_DEFAULT_OPTIONS_FACTORY之类的 token21.0.0 是一个必须修改源码的版本替代方案通常是直接使用MatXxxDefaultOptions这类注入 token 或组件自身的defaultOptions配置如 22.0.0 中 badge 新增的allow badge defaults to be configured。2.3 输入属性重命名与信号表单兼容以 22.0.0 的 values→value 为例22.0.0 的multiple区块包含两条影响面很广的变更将 Combobox、Listbox、Tree、Menu、Toolbar、Select 的values输入/模型统一重命名为value提交记录为refactor(multiple): rename values to value for signal forms compatibilityMatListOption.checkboxPosition被移除改用togglePosition同时MatListOptionCheckboxPosition重命名为MatListOptionTogglePosition一批带 rest 参数的构造器被移除凡是继承 Material/CDK 组件的自定义类都需要同步更新super调用。这条信息对使用 signal-based forms 的团队尤其重要value语义的统一使组件能直接与 Angular 新的信号表单模型signal form对接src/cdk/stepper 中 22.1.0 的提交allow signal form to be assigned as stepControl也印证了这一演进方向。三、提交表解读如何从一行记录挖出完整变更信息除大版本外绝大多数条目只有提交表。表格固定为三列列含义示例Commit提交哈希与 PR/Issue 引用[0bb7b183e] fix **overlay:** expose currently open overlays (#33768)Type变更类型feat/fix/refactor/perfDescription组件范围 一句话描述**overlay:** expose currently open overlays3.1 Type 列区分特性与修复feat新能力。例如 22.2.0-next.4 的feat **icon:** add material symbol classes automatically、22.0.0 的feat **button:** Add support for showing a progress indicator inside the buttonfix缺陷修复。例如 22.2.0-next.3 的fix **sidenav:** prevent drawer from getting stuck when toggled rapidly、22.0.0 的fix **menu:** close menu when cleared from triggerrefactor结构调整。例如 22.0.0 的refactor(multiple): rename values to value另有少量perf类性能优化散布在历史版本中。3.2 Scope 列覆盖的包范围当前仓库的包范围与 CHANGELOG 中的分组完全对应可在 src 目录下逐一确认Scope仓库位置说明ariasrc/aria无障碍组件集accordion、combobox、grid、listbox、menu、tabs、toolbar、treecdksrc/cdk组件开发工具包overlay、portal、a11y、drag-drop、table 等materialsrc/materialAngular Material 组件库本体cdk-experimentalsrc/cdk-experimental实验性功能如 21.0.0 的 signals-based combobox 原型google-mapssrc/google-mapsGoogle Maps 封装youtube-playersrc/youtube-playerYouTube 播放器封装multiple跨包变更涉及多个包范围的提交归入此类例如 22.0.0 的feat **accordion:** introduce accordion harness、feat **grid:** add test harnesses、feat **tree:** add test harnesses等一批提交对应 src/aria 下各组件新增的 test harness它们进一步沉淀在 goldens/aria 的 API golden 文件中表明 aria 包从 22.0.0 起移除了 developer preview 标签提交remove developer preview tag from aria正式进入稳定 API 行列。3.3 修复类提交的高频主题从近几轮版本统计修复提交呈现几个高频主题可以作为选型与升级的参考Overlay 弹层行为combobox 弹层失焦关闭22.2.0-next.4、menu 焦点延迟进入22.2.0-next.4、autocomplete 空弹层遮挡内容21.0.0等Sidenav/Drawer 状态机快速切换卡死22.2.0-next.3、打开时内容标记为 inert22.0.0等表单与无障碍联动aria 指令阻止意外表单提交22.0.0、menu 的 disabledInteractive 焦点落点22.2.0-next.4等。四、重点版本速览从 v20 到 v22 的演进脉络4.1 v22 时代2026aria 成熟化与 Material 能力补强22.0.0 aurostibite-ambulance (2026-06-03)aria 包全面转正combobox 完成 simple-combobox 迁移多个 aria 组件引入测试 harnessmaterial 新增按钮内进度指示器feat **button:** Add support for showing a progress indicator、dialog/bottom-sheet 支持透传 bindings、tabs 支持独立动画时长配置22.1.0 v22-1-0 (2026-07-29)slide-toggle 新增 full-width 支持combobox 支持 readonly22.2.0-next.x2026-08 起icon 自动添加 material symbol 类、menu 新增disabledInteractive输入、cdk overlay 暴露当前打开的 overlays 列表。4.2 v21 时代2025-2026面向 signals 的现代化清理21.0.0 damask-dachshund (2025-11-19) 的核心是全面移除已废弃的工厂函数、动画符号与旧 Portal API详见上文 2.2 节并引入实验性的 signals-based comboboxsrc/cdk-experimental为 22.0.0 的正式落地铺路。21.2.x 系列则以高频 patch 修复维持稳定分支质量。4.3 v20 时代2025Portal 重命名与 SelectionModel 返回值20.0.0 calcium-carrot (2025-05-28) 完成 Portal 命名统一DomPortalHost→DomPortalOutlet等SelectionModel的select/deselect/toggle/setSelection/clear全部改为返回布尔值button harness 的getVariant与getAppearance职责拆分checkbox 与 slide-toggle 移除旧式 required validator。五、源码佐证CHANGELOG 条目如何映射到仓库实现对于每个想深入验证的变更仓库提供了三层证据链API 表面各包的 public-api.ts 与 goldens 下的*.api.md黄金文件记录了公开符号的精确签名任何删除、重命名都会反映在其中例如 22.0.0 提交refactor(multiple): update api goldens实现层对应组件的源码文件如 combobox.ts、menu.ts 可直接查看新增输入如disabledInteractive的实际声明测试层同目录下的*.spec.ts与 testing 子目录中的 harness 文件验证了变更的预期行为。此外仓库的 scripts/breaking-changes.mts 是维护者用于追踪、标注破坏性变更的辅助脚本配合 goldens 的 API 快照机制保证了任何公开 API 变化都必须同步更新 CHANGELOG这一工程约定能够被自动化执行。六、实操基于 CHANGELOG 制定升级路径将 CHANGELOG 当作升级手册使用推荐四步流程确认当前版本查看 package.json 的version字段或 CHANGELOG 顶部条目明确所在版本线扫描 Breaking Changes从当前版本到目标版本之间逐一收集所有 major 版本22.0.0、21.0.0、20.0.0……的 Breaking Changes 区块按aria/cdk/material分组整理成迁移清单分类处置删除类工厂函数、动画符号、旧 Portal 名直接全局替换重命名类checkboxPosition→togglePosition、values→value修改模板与组件代码构造器签名变化类检查是否有继承 Material/CDK 组件的自定义类需要同步super验证利用 src 下各包自带的*.spec.ts测试与 goldens API 黄金文件作为行为基准运行单元测试与 API 比对如approve-api-golden工具链确认迁移无遗漏。对于只想追踪修复的用户只关注fix类型且 scope 为所用包的条目即可对于想要提前适配新特性的用户则应关注22.x.0-next.y预发布条目——但需注意 next 版本的 API 在正式发布前仍可能调整例如 22.2.0-next 系列中 menu 的disabledInteractive焦点行为仍在持续修复中。七、总结CHANGELOG.md 不仅是发布记录更是 Angular Components 仓库工程规范的浓缩体现版本号三段式语义、代号命名传统、Breaking Changes 的包级分组、提交表的 scope/type 体系共同构成了一套可机器解析、可人工阅读、可驱动迁移的变更管理机制。理解它等于拿到了从 v12 到 v22 全部演进决策的索引——无论是评估升级风险、定位回归来源还是研究某个组件 API 的来龙去脉都可以从这里出发再深入 src、goldens 与 scripts 验证每一处细节。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考