企业官网建设流程全解析

读透 Angular Components 的 CHANGELOG：从 v20 到 v22 的版本演进、破坏性变更与升级迁移指南

【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components

本篇指南以本仓库根目录下的 CHANGELOG.md 为核心主线，系统讲解 Angular Components（Angular 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 版本条目三段式结构

以仓库中任意一个版本条目为例，一个完整的版本记录包含三个组成部分：

1. 版本标题行：# 22.2.0-next.5 "bismuth-badge" (2026-09-09)
2. Breaking Changes 区块（仅在大版本或关键小版本中出现）：按aria/cdk/material/multiple等包范围分组，列出破坏性 API 变更
3. 提交表：按包范围（scope）分组的提交记录表格，每行包含 Commit、Type、Description 三列

1.2 版本号三段式语义

从条目中可以归纳出三类版本流：

从文件头部可以看出，维护团队采用"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 combobox；
• SimpleCombobox被提升（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、matTooltipAnimations）；
• Portal 体系完成术语统一：TemplatePortalDirective→CdkPortal，PortalHostDirective→CdkPortalOutlet，DomPortalHost→DomPortalOutlet（20.0.0 时已先删除旧版 PortalHost 系列）。

这些删除动作背后的原因在 21.0.0 的提交描述中可见端倪——"remove deprecated factory functions"与"remove deprecated animation definitions"，即 Angular 组件库在向 signals 优先、独立于 View Engine 的现代架构演进过程中，逐步淘汰基于构造器注入与工厂 provider 的旧式 API。对升级者的启示：如果你在代码中注入了任何MAT_*_DEFAULT_OPTIONS_FACTORY之类的 token，21.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 compatibility）；
• MatListOption.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"也印证了这一演进方向。

三、提交表解读：如何从一行记录挖出完整变更信息

除大版本外，绝大多数条目只有提交表。表格固定为三列：

3.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 button；
• fix：缺陷修复。例如 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 trigger；
• refactor：结构调整。例如 22.0.0 的refactor(multiple): rename values to value；
• 另有少量perf类性能优化散布在历史版本中。

3.2 Scope 列：覆盖的包范围

当前仓库的包范围与 CHANGELOG 中的分组完全对应，可在 src 目录下逐一确认：

例如 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）、打开时内容标记为 inert（22.0.0）等；
• 表单与无障碍联动：aria 指令阻止意外表单提交（22.0.0）、menu 的 disabledInteractive 焦点落点（22.2.0-next.4）等。

四、重点版本速览：从 v20 到 v22 的演进脉络

4.1 v22 时代（2026）：aria 成熟化与 Material 能力补强

• 22.0.0 "aurostibite-ambulance" (2026-06-03)：aria 包全面转正，combobox 完成 simple-combobox 迁移，多个 aria 组件引入测试 harness；material 新增按钮内进度指示器（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 支持 readonly；
• 22.2.0-next.x（2026-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 combobox（src/cdk-experimental），为 22.0.0 的正式落地铺路。21.2.x 系列则以高频 patch 修复维持稳定分支质量。

4.3 v20 时代（2025）：Portal 重命名与 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 条目如何映射到仓库实现

对于每个想深入验证的变更，仓库提供了三层证据链：

1. API 表面：各包的 public-api.ts 与 goldens 下的*.api.md黄金文件记录了公开符号的精确签名，任何删除、重命名都会反映在其中（例如 22.0.0 提交refactor(multiple): update api goldens）；
2. 实现层：对应组件的源码文件，如 combobox.ts、menu.ts 可直接查看新增输入（如disabledInteractive）的实际声明；
3. 测试层：同目录下的*.spec.ts与 testing 子目录中的 harness 文件，验证了变更的预期行为。

此外，仓库的 scripts/breaking-changes.mts 是维护者用于追踪、标注破坏性变更的辅助脚本，配合 goldens 的 API 快照机制，保证了"任何公开 API 变化都必须同步更新 CHANGELOG"这一工程约定能够被自动化执行。

六、实操：基于 CHANGELOG 制定升级路径

将 CHANGELOG 当作升级手册使用，推荐四步流程：

1. 确认当前版本：查看 package.json 的version字段或 CHANGELOG 顶部条目，明确所在版本线；
2. 扫描 Breaking Changes：从当前版本到目标版本之间，逐一收集所有 major 版本（22.0.0、21.0.0、20.0.0……）的 Breaking Changes 区块，按aria/cdk/material分组整理成迁移清单；
3. 分类处置：删除类（工厂函数、动画符号、旧 Portal 名）直接全局替换；重命名类（checkboxPosition→togglePosition、values→value）修改模板与组件代码；构造器签名变化类，检查是否有继承 Material/CDK 组件的自定义类需要同步super；
4. 验证：利用 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