WinUI API 评审流程深度指南从 Experimental 提案到 Stable 契约的完整规范【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml导读本文以仓库中 docs/api-specs/api-review-process.md 为骨架系统梳理 WinUIMicrosoft.UI.Xaml所有公开 API 从提案、编写 Spec、本地评审、官方评审到标记为 Stable 的全流程规范并结合本仓库的 IDL 契约源码、真实 Spec 示例与实现/测试代码进行纵深印证。读完本文你将掌握实验性ExperimentalAPI 与稳定StableAPI 的边界如何界定、一份合格的 API Spec 应如何撰写、官方 API 评审会议如何运作、评审结论如何落到实现并最终固化进公开契约从而能够以符合 WinUI 工程规范的方式参与或理解该项目的 API 演进流程。为什么需要 API 评审稳定性承诺的起点WinUI 有一个硬性规定所有随 WinUI 发布的 API 都必须经过 Windows API reviewWindows API 评审流程见 api-review-process.md。这份文档从 WinUI 的视角完整描述了该流程并给出了所有 API 必须遵循的准则。其背后的逻辑并不难理解公开 API 一旦发布稳定版本就等同于向开发者社区作出长期兼容承诺任何后续改动都可能造成破坏性变更。评审流程存在的意义就是在 API 固化之前用一套结构化的设计审查机制把改不动了之前的修改成本压到最低。核心概念Experimental 与 Stable API 的边界理解整个评审流程首先要分清两种 API 状态Experimental实验性API不需要经过 API review。它们只会出现在 WinAppSDK 的实验性experimental发布版本中不会进入稳定版本。实验性 API 不承诺任何稳定性因此允许在后续版本中随意变更。Stable稳定API一旦随版本发布就不能再修改任何改动都属于破坏性变更。因此形成了明确的演进路线处于开发中的新 API 应首先标记为 Experimental只有在完整走完 API review 之后才允许标记为 Stable。这一机制在仓库的 IDL 源码中有非常直观的落地。查看 controls/idl/Microsoft.UI.Xaml.Controls.idl 第 10–19 行namespace features { #ifdef MUX_PRERELEASE // In prerelease, the feature is disabled by default (giving it the [experimental] tag) feature_name Feature_Experimental { DisabledByDefault, FALSE }; #else // In release, the experimental feature is disabled, removing it from the final WinMD feature_name Feature_Experimental { AlwaysDisabled, FALSE }; #endif }这段代码揭示了一个关键的实现细节在prerelease预发布构建中Feature_Experimental被定义为DisabledByDefault即 API 仍存在于 WinMD 中但默认带上了[experimental]标签在release正式发布构建中该 feature 被置为AlwaysDisabled实验性 API 会直接从最终的 WinMD 元数据中被移除从物理上保证它不可能流入稳定版本。同文件第 140–141 行还定义了配套的宏#define MUX_PREVIEW contract(Microsoft.UI.Xaml.XamlContract, 12), feature(Feature_Experimental) #define MUX_INTERNAL contract(Microsoft.UI.Xaml.XamlContract, 12), feature(Feature_Experimental)也就是说[MUX_PREVIEW]这类 IDL 属性本质上就是把 API 挂到实验性 feature 与指定版本的 XamlContract 上——是否为实验性 API在 WinUI 里不是口头约定而是由构建系统在元数据层面强制保证的。评审流程全景七个关键步骤api-review-process.md 给出的整体流程共七步是贯穿全文的主线与团队中的API RepAPI 代表之一协作在本仓库中创建一份API SpecMarkdown 文档创建 PR 并先在本地完成评审本地评审通过后与 API Rep 协作安排官方 API review参加 API review 会议评审后将反馈落实到 API 设计中将 API 标记为 Stable。后续各节将按这七个步骤逐一展开并穿插仓库中的真实实现证据。API Reps评审过程中的关键角色整个流程中反复出现一个角色——API RepAPI 代表。从第一步开始你就需要与团队中的一位 API Rep 结对工作他既是本地评审的参与者和批准者也是与官方 API Review Board 之间的桥梁负责安排评审日程、主持评审会议、在会议上逐条推进评论并在会后答疑解惑。可以这样理解分工API 作者负责把设计写清楚API Rep 负责把评审流程走通。创建 API Spec第一份交付物存放位置与模板创建 API Spec 的第一步是在本仓库的docs/api-specs目录下新建一份 Markdown 文档原文档写作时使用的路径为docs\api-specs即当前仓库的 docs/api-specs 目录。原文档同时建议参考一份官方提供的 spec 模板文档该模板来自 Windows App SDK 仓库不在本仓库内这里不做外链。仓库中已经沉淀了一批按此流程产出的真实 Spec可以直接作为学习范本例如PipsPager-IsWrapEnabled-spec.mdScrollPresenter-Scroll-Zoom-Starting-spec.mdShouldConstrainPopupsToWorkArea-spec.mdWindow-MinMaxSize-spec.md面向的读者写给谁看撰写 Spec 时受众定位直接决定写作质量。原文档给出了两条明确的受众要求假设读者对 XAML 有大致了解但不是专家。不要以 XAML 开发团队成员为假想读者这份 Spec 文档将构成公开文档的基础同时会被Windows API review board 的成员审阅而他们大多不是 XAML 专家。由此得出两条写作禁忌不要使用内部代号不要涉及过于圈内inside baseball的话题。一份好的 Spec 应当让一个熟悉 XAML 但不懂内部实现的普通开发者以及一群跨领域的评审委员都能看懂这个 API 解决什么问题、语义是什么、边界在哪里。Spec Note内部讨论与公开内容的分离有些信息对内部讨论有价值但不适合进入公开文档。原文档规定这样的内容可以写成Spec Note做法是以 Spec Note 作为前缀并使用斜体与正文区分开来。仓库中的 PipsPager-IsWrapEnabled-spec.md 第 35–37 行就是一个标准的实际案例Spec note: PipsPager documentation should be updated to reflect two changes. First is to update the part which describes what happens when setting different navigation button visibility options (see above for new content). Second is to remove the line that says Wrapping between the first and last items is not supported.这条 Spec Note 记录了正式发布后需要同步更新哪些公开文档的内部待办正文中完全不体现两者互不干扰。仓库中的真实 Spec 结构示范以 PipsPager-IsWrapEnabled-spec.md 为例一份通过评审的 API Spec 通常包含以下典型章节可作为撰写时的结构参考Background背景描述现状痛点。例如 PipsPager 在用户位于第一个 pip 时向前导航按钮会消失要跳到最后一个 pip 必须逐一点击穿过所有 pip本 Spec 新增的WrapMode属性让用户在首尾之间一键跳转。API PagesAPI 说明页逐个描述新增 API 的语义、默认值与行为细节。例如WrapMode属性默认为PipsPagerWrapMode::None并详细说明Wrap模式下导航按钮可见性Collapsed/Visible/VisibleOnPointerOver的完整行为矩阵以及键盘焦点行为的变化。API DetailsAPI 细节以 MIDL3 语法给出精确的接口定义例如namespace Microsoft.UI.Xaml.Controls { enum PipsPagerWrapMode { None, Wrap }; unsealed runtimeclass PipsPager : Microsoft.UI.Xaml.Controls.Control { // ... PipsPagerWrapMode WrapMode; static Microsoft.UI.Xaml.DependencyProperty WrapModeProperty{ get; }; } }这种背景—API 页—API 细节的组织方式正是 Spec 既要说服评审委员、又要能直接指导实现与文档写作的体现。本地评审进入官方评审前的第一道关在把 Spec 提交给官方 API Review Board 之前必须先让本地团队先行评审。原文档规定的本地评审流程是向本仓库 main 分支创建PR带上你的 Spec在评审中包含本地API Rep响应所有反馈一旦 PR 获得 API Rep 批准即可合并到 main。这一步的意义是内部先把关、先收敛把明显的问题挡在本地让官方评审聚焦于更高层的设计问题而不是被琐碎错误消耗。官方 API 评审与 Review Board 的正式会议Spec 完成本地评审后进入官方流程创建新的 PR用于官方评审。原文档给出了两种做法一是对文档做一个微不足道的空白字符改动后创建新 PR二是干脆不合并最初的 PR直接用它作为官方评审载体。通常创建新 PR 更可取因为它能为官方评审提供一个干净整洁的 PR。与 API Rep 协作安排评审日程。评审会议之前API Review Board 成员会先在 PR 上添加评论。评审日程排定之后、评审发生之前不要再对 PR 做任何更新也不要在 PR 评论中应用任何建议的反馈——评审期间保持 PR 冻结是确保会议讨论基于同一版本的硬性要求。评审会议期间API Rep 会逐条过一遍所有活跃评论与会者就如何回应达成共识对文档提出的修改将以前缀RECOMMENDED推荐的评论形式呈现。可见官方评审并非匿名打分而是一个由 API Rep 主持、评审委员与 API 作者共同收敛共识的实时讨论过程产出物是一组带RECOMMENDED标记的明确修改指令。反馈落地同步 Spec 与实现官方评审结束后需要把反馈落实为两件事更新 Spec针对评审反馈修改文档推送变更将 PR 合并到 main如有疑问继续与 API Rep 协作解决。对齐实现Spec 定稿后务必对实现做必要修改确保实现与 Spec 描述完全一致。Spec 描述的设计最终如何在实现中落地可以在 PipsPager 上找到完整闭环。对照 Spec 中的WrapMode属性仓库中controls/dev/PipsPager/PipsPager.idl 第 83–87 行给出了实际 IDL 声明WrapMode属性带有[MUX_PUBLIC_V7]公开契约标记和[MUX_DEFAULT_VALUE(winrt::PipsPagerWrapMode::None)]默认值声明与 Spec 中默认 None的描述完全吻合controls/dev/PipsPager/PipsPager.cpp 第 449 行实现了OnWrapModeChanged()回调第 742–744 行在属性变更时触发它controls/dev/PipsPager/PipsPager.h 第 76 行提供了便捷判断IsWrapEnabled(){ return WrapMode() winrt::PipsPagerWrapMode::Wrap; }。这就是Spec 定稿 → 实现对齐的仓库级证据Spec 里写的每个语义都能在 IDL、头文件与实现中找到对应物。标记为 Stable最后的闸门流程的最后一步是把新 API 标记为 Stable原文档给出了三条刚性约束移除 Experimental 标签并将 API 加入合适的 contract契约在完整走完 API review 流程之前不得将 API 标记为 Stable一旦标记为 Stable不得再做任何改动否则即构成破坏性变更。这与前文提到的 IDL 机制形成了闭环实验性 API 通过Feature_Experimental与[MUX_PREVIEW]挂在可随时变化的预览通道上而稳定 API 则通过[MUX_PUBLIC]/[MUX_PUBLIC_V7]这类版本化属性固化进正式契约。以 PipsPager 的PipsPagerWrapMode枚举为例controls/dev/PipsPager/PipsPager.idl 第 13–19 行中[MUX_PUBLIC_V7]的出现意味着该枚举已进入正式公开契约从此进入不可回退、不可变更的状态。面向社区的公开评审一条并行的反馈通道值得一并了解的是仓库中还有一份配套的姊妹文档 docs/api-specs/public-api-review-process.md它描述了同一 API 工作流中面向外部开发者社区的公开评审版本。核心机制包括Spec 草稿以 PR 形式发布同时创建带spec-review标签的 GitHub issue 跟踪提案并挂入 API Spec Review 看板社区反馈期为固定的 1 个月社区成员可通过 PR 评论或代码建议code suggestion提供反馈反馈被分为四类处理Immediate Action立即处理、Deferred Action延后处理、Not Planned不计划、Discussion讨论每条反馈都会以指定的方式得到确认最终总结帖、行内回复、Resolve comment、直接采纳建议等。这份文档还给出了建设性反馈与无效反馈的对比范例例如这个控件不支持辅助功能无效vs.该控件应如何支持屏幕阅读器以下是状态变更应如何播报的示例有效——对于想参与 WinUI API 公开评审的开发者来说是了解如何提有效意见的直接指南。从 Spec 到测试评审后的验证闭环评审通过、实现对齐之后还有最后一道验证环节测试。Spec 中定义的行为最终都要有自动化测试兜底。以 PipsPager 的 WrapMode 为例controls/dev/PipsPager/InteractionTests/PipsPagerTests.cs 中就包含成组的交互测试PipsPagerWrapModeNavigation第 391 行验证 Wrap 模式下的环绕导航PipsPagerWrapModeNavigationInfinitePages第 418 行验证无限页场景PipsPagerWrapModeNavigationButtonsHiddenInOnePageScenario第 443 行验证单页场景下导航按钮的隐藏行为。配合 PipsPagerTestBase.cs 第 105–107 行的SetWrapMode辅助方法通过TestPipsPagerWrapModeComboBox选择器设置 WrapMode可以看到 Spec 中每个行为分支都被映射为可执行的测试用例——这也再次印证了 API 评审流程的最终产出不只是文档而是文档 实现 测试三者一致的完整闭环。小结回到 api-review-process.md 的主线WinUI 的 API 演进被一条清晰的纪律贯穿——新 API 先以 Experimental 身份进入预览通道自由迭代再通过API Rep 结对 → 编写 Spec → 本地评审 → 官方评审会议 → 反馈落地 → 标记 Stable的七步流程完成固化最后由 IDL 契约机制与自动化测试共同保证一经发布、永不破坏。对于希望参与 WinUI 开发的贡献者这份流程既是行为规范也是理解仓库中每个公开 API 设计来龙去脉的钥匙。【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/16 22:56:30 · 阅读 1.2k WinUI API 评审流程深度指南：从 Experimental 提案到 Stable 契约的完整规范
WinUI API 评审流程深度指南从 Experimental 提案到 Stable 契约的完整规范【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml导读本文以仓库中 docs/api-specs/api-review-process.md 为骨架系统梳理 WinUIMicrosoft.UI.Xaml所有公开 API 从提案、编写 Spec、本地评审、官方评审到标记为 Stable 的全流程规范并结合本仓库的 IDL 契约源码、真实 Spec 示例与实现/测试代码进行纵深印证。读完本文你将掌握实验性ExperimentalAPI 与稳定StableAPI 的边界如何界定、一份合格的 API Spec 应如何撰写、官方 API 评审会议如何运作、评审结论如何落到实现并最终固化进公开契约从而能够以符合 WinUI 工程规范的方式参与或理解该项目的 API 演进流程。为什么需要 API 评审稳定性承诺的起点WinUI 有一个硬性规定所有随 WinUI 发布的 API 都必须经过 Windows API reviewWindows API 评审流程见 api-review-process.md。这份文档从 WinUI 的视角完整描述了该流程并给出了所有 API 必须遵循的准则。其背后的逻辑并不难理解公开 API 一旦发布稳定版本就等同于向开发者社区作出长期兼容承诺任何后续改动都可能造成破坏性变更。评审流程存在的意义就是在 API 固化之前用一套结构化的设计审查机制把改不动了之前的修改成本压到最低。核心概念Experimental 与 Stable API 的边界理解整个评审流程首先要分清两种 API 状态Experimental实验性API不需要经过 API review。它们只会出现在 WinAppSDK 的实验性experimental发布版本中不会进入稳定版本。实验性 API 不承诺任何稳定性因此允许在后续版本中随意变更。Stable稳定API一旦随版本发布就不能再修改任何改动都属于破坏性变更。因此形成了明确的演进路线处于开发中的新 API 应首先标记为 Experimental只有在完整走完 API review 之后才允许标记为 Stable。这一机制在仓库的 IDL 源码中有非常直观的落地。查看 controls/idl/Microsoft.UI.Xaml.Controls.idl 第 10–19 行namespace features { #ifdef MUX_PRERELEASE // In prerelease, the feature is disabled by default (giving it the [experimental] tag) feature_name Feature_Experimental { DisabledByDefault, FALSE }; #else // In release, the experimental feature is disabled, removing it from the final WinMD feature_name Feature_Experimental { AlwaysDisabled, FALSE }; #endif }这段代码揭示了一个关键的实现细节在prerelease预发布构建中Feature_Experimental被定义为DisabledByDefault即 API 仍存在于 WinMD 中但默认带上了[experimental]标签在release正式发布构建中该 feature 被置为AlwaysDisabled实验性 API 会直接从最终的 WinMD 元数据中被移除从物理上保证它不可能流入稳定版本。同文件第 140–141 行还定义了配套的宏#define MUX_PREVIEW contract(Microsoft.UI.Xaml.XamlContract, 12), feature(Feature_Experimental) #define MUX_INTERNAL contract(Microsoft.UI.Xaml.XamlContract, 12), feature(Feature_Experimental)也就是说[MUX_PREVIEW]这类 IDL 属性本质上就是把 API 挂到实验性 feature 与指定版本的 XamlContract 上——是否为实验性 API在 WinUI 里不是口头约定而是由构建系统在元数据层面强制保证的。评审流程全景七个关键步骤api-review-process.md 给出的整体流程共七步是贯穿全文的主线与团队中的API RepAPI 代表之一协作在本仓库中创建一份API SpecMarkdown 文档创建 PR 并先在本地完成评审本地评审通过后与 API Rep 协作安排官方 API review参加 API review 会议评审后将反馈落实到 API 设计中将 API 标记为 Stable。后续各节将按这七个步骤逐一展开并穿插仓库中的真实实现证据。API Reps评审过程中的关键角色整个流程中反复出现一个角色——API RepAPI 代表。从第一步开始你就需要与团队中的一位 API Rep 结对工作他既是本地评审的参与者和批准者也是与官方 API Review Board 之间的桥梁负责安排评审日程、主持评审会议、在会议上逐条推进评论并在会后答疑解惑。可以这样理解分工API 作者负责把设计写清楚API Rep 负责把评审流程走通。创建 API Spec第一份交付物存放位置与模板创建 API Spec 的第一步是在本仓库的docs/api-specs目录下新建一份 Markdown 文档原文档写作时使用的路径为docs\api-specs即当前仓库的 docs/api-specs 目录。原文档同时建议参考一份官方提供的 spec 模板文档该模板来自 Windows App SDK 仓库不在本仓库内这里不做外链。仓库中已经沉淀了一批按此流程产出的真实 Spec可以直接作为学习范本例如PipsPager-IsWrapEnabled-spec.mdScrollPresenter-Scroll-Zoom-Starting-spec.mdShouldConstrainPopupsToWorkArea-spec.mdWindow-MinMaxSize-spec.md面向的读者写给谁看撰写 Spec 时受众定位直接决定写作质量。原文档给出了两条明确的受众要求假设读者对 XAML 有大致了解但不是专家。不要以 XAML 开发团队成员为假想读者这份 Spec 文档将构成公开文档的基础同时会被Windows API review board 的成员审阅而他们大多不是 XAML 专家。由此得出两条写作禁忌不要使用内部代号不要涉及过于圈内inside baseball的话题。一份好的 Spec 应当让一个熟悉 XAML 但不懂内部实现的普通开发者以及一群跨领域的评审委员都能看懂这个 API 解决什么问题、语义是什么、边界在哪里。Spec Note内部讨论与公开内容的分离有些信息对内部讨论有价值但不适合进入公开文档。原文档规定这样的内容可以写成Spec Note做法是以 Spec Note 作为前缀并使用斜体与正文区分开来。仓库中的 PipsPager-IsWrapEnabled-spec.md 第 35–37 行就是一个标准的实际案例Spec note: PipsPager documentation should be updated to reflect two changes. First is to update the part which describes what happens when setting different navigation button visibility options (see above for new content). Second is to remove the line that says Wrapping between the first and last items is not supported.这条 Spec Note 记录了正式发布后需要同步更新哪些公开文档的内部待办正文中完全不体现两者互不干扰。仓库中的真实 Spec 结构示范以 PipsPager-IsWrapEnabled-spec.md 为例一份通过评审的 API Spec 通常包含以下典型章节可作为撰写时的结构参考Background背景描述现状痛点。例如 PipsPager 在用户位于第一个 pip 时向前导航按钮会消失要跳到最后一个 pip 必须逐一点击穿过所有 pip本 Spec 新增的WrapMode属性让用户在首尾之间一键跳转。API PagesAPI 说明页逐个描述新增 API 的语义、默认值与行为细节。例如WrapMode属性默认为PipsPagerWrapMode::None并详细说明Wrap模式下导航按钮可见性Collapsed/Visible/VisibleOnPointerOver的完整行为矩阵以及键盘焦点行为的变化。API DetailsAPI 细节以 MIDL3 语法给出精确的接口定义例如namespace Microsoft.UI.Xaml.Controls { enum PipsPagerWrapMode { None, Wrap }; unsealed runtimeclass PipsPager : Microsoft.UI.Xaml.Controls.Control { // ... PipsPagerWrapMode WrapMode; static Microsoft.UI.Xaml.DependencyProperty WrapModeProperty{ get; }; } }这种背景—API 页—API 细节的组织方式正是 Spec 既要说服评审委员、又要能直接指导实现与文档写作的体现。本地评审进入官方评审前的第一道关在把 Spec 提交给官方 API Review Board 之前必须先让本地团队先行评审。原文档规定的本地评审流程是向本仓库 main 分支创建PR带上你的 Spec在评审中包含本地API Rep响应所有反馈一旦 PR 获得 API Rep 批准即可合并到 main。这一步的意义是内部先把关、先收敛把明显的问题挡在本地让官方评审聚焦于更高层的设计问题而不是被琐碎错误消耗。官方 API 评审与 Review Board 的正式会议Spec 完成本地评审后进入官方流程创建新的 PR用于官方评审。原文档给出了两种做法一是对文档做一个微不足道的空白字符改动后创建新 PR二是干脆不合并最初的 PR直接用它作为官方评审载体。通常创建新 PR 更可取因为它能为官方评审提供一个干净整洁的 PR。与 API Rep 协作安排评审日程。评审会议之前API Review Board 成员会先在 PR 上添加评论。评审日程排定之后、评审发生之前不要再对 PR 做任何更新也不要在 PR 评论中应用任何建议的反馈——评审期间保持 PR 冻结是确保会议讨论基于同一版本的硬性要求。评审会议期间API Rep 会逐条过一遍所有活跃评论与会者就如何回应达成共识对文档提出的修改将以前缀RECOMMENDED推荐的评论形式呈现。可见官方评审并非匿名打分而是一个由 API Rep 主持、评审委员与 API 作者共同收敛共识的实时讨论过程产出物是一组带RECOMMENDED标记的明确修改指令。反馈落地同步 Spec 与实现官方评审结束后需要把反馈落实为两件事更新 Spec针对评审反馈修改文档推送变更将 PR 合并到 main如有疑问继续与 API Rep 协作解决。对齐实现Spec 定稿后务必对实现做必要修改确保实现与 Spec 描述完全一致。Spec 描述的设计最终如何在实现中落地可以在 PipsPager 上找到完整闭环。对照 Spec 中的WrapMode属性仓库中controls/dev/PipsPager/PipsPager.idl 第 83–87 行给出了实际 IDL 声明WrapMode属性带有[MUX_PUBLIC_V7]公开契约标记和[MUX_DEFAULT_VALUE(winrt::PipsPagerWrapMode::None)]默认值声明与 Spec 中默认 None的描述完全吻合controls/dev/PipsPager/PipsPager.cpp 第 449 行实现了OnWrapModeChanged()回调第 742–744 行在属性变更时触发它controls/dev/PipsPager/PipsPager.h 第 76 行提供了便捷判断IsWrapEnabled(){ return WrapMode() winrt::PipsPagerWrapMode::Wrap; }。这就是Spec 定稿 → 实现对齐的仓库级证据Spec 里写的每个语义都能在 IDL、头文件与实现中找到对应物。标记为 Stable最后的闸门流程的最后一步是把新 API 标记为 Stable原文档给出了三条刚性约束移除 Experimental 标签并将 API 加入合适的 contract契约在完整走完 API review 流程之前不得将 API 标记为 Stable一旦标记为 Stable不得再做任何改动否则即构成破坏性变更。这与前文提到的 IDL 机制形成了闭环实验性 API 通过Feature_Experimental与[MUX_PREVIEW]挂在可随时变化的预览通道上而稳定 API 则通过[MUX_PUBLIC]/[MUX_PUBLIC_V7]这类版本化属性固化进正式契约。以 PipsPager 的PipsPagerWrapMode枚举为例controls/dev/PipsPager/PipsPager.idl 第 13–19 行中[MUX_PUBLIC_V7]的出现意味着该枚举已进入正式公开契约从此进入不可回退、不可变更的状态。面向社区的公开评审一条并行的反馈通道值得一并了解的是仓库中还有一份配套的姊妹文档 docs/api-specs/public-api-review-process.md它描述了同一 API 工作流中面向外部开发者社区的公开评审版本。核心机制包括Spec 草稿以 PR 形式发布同时创建带spec-review标签的 GitHub issue 跟踪提案并挂入 API Spec Review 看板社区反馈期为固定的 1 个月社区成员可通过 PR 评论或代码建议code suggestion提供反馈反馈被分为四类处理Immediate Action立即处理、Deferred Action延后处理、Not Planned不计划、Discussion讨论每条反馈都会以指定的方式得到确认最终总结帖、行内回复、Resolve comment、直接采纳建议等。这份文档还给出了建设性反馈与无效反馈的对比范例例如这个控件不支持辅助功能无效vs.该控件应如何支持屏幕阅读器以下是状态变更应如何播报的示例有效——对于想参与 WinUI API 公开评审的开发者来说是了解如何提有效意见的直接指南。从 Spec 到测试评审后的验证闭环评审通过、实现对齐之后还有最后一道验证环节测试。Spec 中定义的行为最终都要有自动化测试兜底。以 PipsPager 的 WrapMode 为例controls/dev/PipsPager/InteractionTests/PipsPagerTests.cs 中就包含成组的交互测试PipsPagerWrapModeNavigation第 391 行验证 Wrap 模式下的环绕导航PipsPagerWrapModeNavigationInfinitePages第 418 行验证无限页场景PipsPagerWrapModeNavigationButtonsHiddenInOnePageScenario第 443 行验证单页场景下导航按钮的隐藏行为。配合 PipsPagerTestBase.cs 第 105–107 行的SetWrapMode辅助方法通过TestPipsPagerWrapModeComboBox选择器设置 WrapMode可以看到 Spec 中每个行为分支都被映射为可执行的测试用例——这也再次印证了 API 评审流程的最终产出不只是文档而是文档 实现 测试三者一致的完整闭环。小结回到 api-review-process.md 的主线WinUI 的 API 演进被一条清晰的纪律贯穿——新 API 先以 Experimental 身份进入预览通道自由迭代再通过API Rep 结对 → 编写 Spec → 本地评审 → 官方评审会议 → 反馈落地 → 标记 Stable的七步流程完成固化最后由 IDL 契约机制与自动化测试共同保证一经发布、永不破坏。对于希望参与 WinUI 开发的贡献者这份流程既是行为规范也是理解仓库中每个公开 API 设计来龙去脉的钥匙。【免费下载链接】microsoft-ui-xamlWinUI: a modern UI framework with a rich set of controls and styles to build dynamic and high-performing Windows applications.项目地址: https://gitcode.com/GitHub_Trending/mi/microsoft-ui-xaml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考