深入解析 Carbon Web Components 的 cds-radio-button渲染快照、属性语义与组内交互机制【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carboncds-radio-button是 IBM Carbon Design System 的 Web Components 实现carbon/web-components当前仓库版本为 2.63.0中用于互斥单选场景的表单控件。它通过 Shadow DOM 封装原生input typeradio与label配合父组件cds-radio-button-group维护受控状态。本文以仓库中的渲染快照文档 packages/web-components/tests/snapshots/cds-radio-button.md 为主体逐行剖析其 Shadow DOM 渲染结构并结合 radio-button.ts 与 radio-button-group.ts 的源码讲清每个属性的取值、默认值、语义以及组内通信、键盘导航与表单提交的底层实现。一、快照文档说明了什么渲染快照是组件测试体系中的契约文件单元测试通过toMatchSnapshot将组件渲染出的 Shadow DOM 与快照逐一比对任何结构性变更都会造成快照 diff从而驱动开发者审慎评估改动。快照文档记录了cds-radio-button的两类典型渲染结果最小属性渲染Should render with minimum attributes组件不带任何显式属性时的默认 DOM 结构多属性渲染Should render with various attributes同时携带disabled、name、label-position、orientation、hide-label、label-text等属性时的 DOM 结构。对应的测试用例定义在 radio-button_spec.ts 中通过Playground模板渲染cds-radio-button-group再断言document.body.querySelector(cds-radio-button[valuestaging])的快照mode: shadow即只比较 Shadow DOM。这说明快照里的valuestaging来自测试模板传入的value属性而非硬编码。二、Shadow DOM 渲染结构逐层拆解2.1 最小属性渲染组件的默认骨架当cds-radio-button不带任何属性时渲染结果如下摘录自快照文档input classcds--radio-button idinput tabindex-1 typeradio valuestaging label classcds--radio-button__label forinput span classcds--radio-button__appearance /span span slot /slot /span /label这段模板与 radio-button.ts 中的render()方法一一对应共包含三层结构原生input typeradio承载真实的表单语义。默认classcds--radio-button、idinput、tabindex-1type恒为radio。注意tabindex的默认值是-1即默认状态下所有单选项都不在 Tab 键序内——这是单选组内只保留一个可聚焦项这一无障碍约定的直接体现。label forinput通过for/id配对把整块可点击区域圆形外观 文本关联到隐藏的原生 input。__tests__/radio-button-test.js中的should associate the label with the input via matching for/id用例专门验证了这一关联见 radio-button-test.js。外观与插槽span classcds--radio-button__appearance纯 CSS 绘制的圆形外观选中态的小圆点由::before伪元素呈现样式定义在 radio-button.scss内层span包裹一个slot用于投射使用者的自定义标签内容。快照中该slot为空对应最小属性状态。从源码看value属性通过ifDefined(value)注入 input见 radio-button.ts因此未设置value时 input 上不会出现value属性。快照中出现的valuestaging即测试模板显式传入的属性。2.2 多属性渲染状态属性的 DOM 反馈快照文档记录的第二种渲染结果如下input classcds--radio-button disabled idinput namename-foo tabindex0 typeradio valuestaging label classcds--radio-button__label forinput span classcds--radio-button__appearance /span span classcds--visually-hidden slot label-text-foo /slot /span /label与最小属性渲染相比出现了四处差异逐一说明其来源与语义disabled组件的disabled布尔属性开启后?disabled${disabledItem || disabled}将属性透传到原生 inputradio-button.ts。测试模板中cds-radio-button-group传入了disabled: true并通过组的属性传播机制下发到每个子项下文详述。namename-fooname是单选组的分组标识同组单选按钮共享同一个name。测试模板在组上设置了name: name-foo同样被传播到子项。该属性是RadioGroupManager按组管理的键见 radio-group-manager.ts。tabindex0这是快照中一个关键状态。在多属性用例里当前按钮valuestaging被组选中value与组的值匹配因此RadioGroupManager.shouldBeFocusable()返回trueinput 的tabindex被置为0可聚焦其余未选中项保持-1。该逻辑位于 radio-button.ts 的updated()钩子中。classcds--visually-hidden与插槽回退内容label-text-foohideLabel为true时标签文本 span 追加cds--visually-hidden类视觉隐藏但保留给屏幕阅读器且slot内以labelText作为回退内容渲染slot ${labelText} /slot。测试模板传入了label-textlabel-text-foo与hideLabel: true对应快照中的插槽文本。三、属性全景属性名、取值与默认值结合 radio-button.ts、radio-button-group.ts 与 defs.ts将两个组件的核心属性整理如下。3.1cds-radio-button属性属性Attribute类型默认值说明checkedBooleanfalse当前是否选中reflect: true会反映为属性default-checkedBooleanfalse是否默认选中在firstUpdated()中若用户未显式设置checked则应用radio-button.tsdisabledBooleanfalse是否禁用组级禁用会传播到此disabled-itemBooleanfalse仅禁用当前单项hide-labelBooleanfalse视觉隐藏标签但保留可访问性invalidBooleanfalse校验失败状态warn/warn-textBoolean / Stringfalse/警告状态及提示文本label-positionleft \| rightright标签位置枚举定义见 defs.tslabel-textString标签文本作为slot的回退内容nameString未定义分组名组内互斥的键orientationhorizontal \| verticalhorizontal布局方向枚举见 defs.tsread-onlyBooleanfalse只读点击/键盘激活均不改变状态input 上反映aria-readonlyrequiredBooleanfalse必填标记透传到 inputvalueString未定义提交给表单的值3.2cds-radio-button-group属性属性Attribute类型默认值说明legend-textString组标题渲染为fieldset内的legendradio-button-group.tshelper-textString未定义辅助说明文本通过aria-describedby关联到fieldsetinvalid/invalid-textBoolean / Stringfalse/校验失败状态与错误消息消息通过aria-describedby关联warn/warn-textBoolean / Stringfalse/警告状态与警告消息nameString未定义组名传播到所有子项valueString未定义当前选中值变化时同步各子项checkedlabel-positionleft \| rightright传播到子项orientationhorizontal \| verticalhorizontal传播到子项disabled/read-only/requiredBooleanfalse传播到子项disabled还会原生禁用fieldset注意orientation与label-position都带有reflect: true因此组件实例的 HTML 属性会同步反映这些状态SCSS 侧也依赖属性选择器做样式适配见 radio-button.scss。四、组与项受控状态的通信机制cds-radio-button的官方用法强调以cds-radio-button-group为父容器来维护受控状态。在快照测试中所有用例也都是以组为单位渲染的。二者的协作分为三个层面。4.1 属性向下传播在 radio-button-group.ts 的updated()中组会监听disabled、labelPosition、orientation、readOnly、name、required、value、invalid等属性变化并遍历this.querySelectorAll(cds-radio-button)逐个赋值。源码注释明确指出这是为了绕开:host-context()尚未在所有主流浏览器得到完整支持的限制用显式传播保证子树一致性。radio-button_spec.ts的Communication between cds-radio-button-group and cds-radio-button分组radio-button_spec.ts用断言验证了这种传播例如组设置disabled: true后所有cds-radio-button的disabled均为true组设置label-positionleft后所有子项labelPosition均为left。4.2 事件向上冒泡单选按钮点击后CDSRadioButton._handleClick会触发cds-radio-button-changed自定义事件bubbles: true, composed: true见 radio-button.ts。组通过HostListener(eventChangeRadioButton)监听该事件radio-button-group.ts从子项中找出checked的那一个将其value同步为组的value若值确有变化再向上冒泡cds-radio-button-group-changed事件携带{ value, name, event }。4.3 表单参与formdata 事件组继承自FormMixin实现了_handleFormdataradio-button-group.ts当且仅当组未禁用、且name与value均已定义时才向FormData追加name - value。radio-button_spec.ts的Event-based form participation分组radio-button_spec.ts用四个用例覆盖了边界缺name不提交、未选中不提交、disabled不提交而{ name: name-foo, value: staging }时提交结果恰为{ name-foo: staging }。五、键盘导航RadioGroupManager 的实现细节单选组遵循 ARIA 单选组模式组内同一时刻只有一个可聚焦项。这一机制的底层是 radio-group-manager.ts 中的RadioGroupManager——每个 document 只维护一个实例WeakMap缓存见 L218-L227以name为键管理组内成员。核心方法包括shouldBeFocusable(radio)L84-L98可聚焦的条件是该项已选中或组内无选中项且该项是组内第一个由此决定 input 的tabindex是0还是-1。select(radio, readOnly?)L167-L186将被选中项checked置为true、tabIndex置0并聚焦同时把组内其他项checked置false、tabIndex置-1若目标是禁用项则提前返回。readOnly模式下也会同步选中状态但不允许用户改选。navigate(radio, direction)L193-L213在按 DOM 顺序排序后的组内做环形circular查找跳过禁用项若全部禁用则停留在当前项。方向映射在 radio-button.ts 中定义水平布局horizontalArrowLeft/LeftIE为后退ArrowRight/Right为前进垂直布局verticalArrowUp/Up为后退ArrowDown/Down为前进。keydown处理器L196-L237还支持 空格与Enter直接选中当前聚焦项。radio-button_spec.ts的Keyboard navigation分组radio-button_spec.ts验证了水平模式下按ArrowRight后tabindex数组由[-1, 0, -1]变为[0, -1, -1]焦点随选中项移动垂直模式同理。六、样式、校验状态与骨架屏6.1 样式入口radio-button.scss 通过use carbon/styles/scss/components/radio-button/radio-button引入 Carbon 基础样式并针对 Web Components 的:host()选择器做适配:host(cds-radio-button-group)继承cds--form-itemlabel-positionleft时追加cds--radio-button-group--label-left垂直布局下按钮间距改为margin-block-end: 6px且无水平间距L67-L70校验失败时cds--radio-button__appearance的边框使用$support-errorL72-L79disabled/disabled-item下标签变灰$text-disabled、光标为not-allowedL95-L109。6.2 校验与警告状态的优先级组在渲染时计算三个互斥分支radio-button-group.tsshowInvalid !readOnly !disabled invalid showWarning !readOnly !disabled !invalid warn showHelper !invalid !disabled !warn即invalid warn helper的优先级且readOnly、disabled会抑制全部校验文案。错误/警告图标通过iconLoader注入WarningFilled16/WarningAltFilled16。对应单元测试见 radio-button-group-test.js。6.3 骨架屏加载占位由cds-radio-button-skeleton提供其模板仅含两个带cds--skeleton类的 div/span见 radio-button-skeleton.ts在 Storybook 的Skeletonstory 中展示。七、组件入口与使用示例7.1 注册入口index.ts 会同时注册三个元素import ./radio-button; import ./radio-button-group; import ./radio-button-skeleton;在浏览器中可直接按包内子路径引入import carbon/web-components/es/components/radio-button/index.js;与 radio-button-test.js 的引用方式一致。7.2 最小可用示例cds-radio-button-group legend-text部署环境 nameenv valuestaging orientationvertical cds-radio-button label-text生产环境 valueprod/cds-radio-button cds-radio-button label-text预发环境 valuestaging/cds-radio-button cds-radio-button label-text测试环境 valuetest disabled-item/cds-radio-button /cds-radio-button-group7.3 结合校验与辅助文本的完整表单示例cds-radio-button-group legend-text部署环境 nameenv helper-text请选择目标环境 invalid invalid-text必须选择一个环境 warn warn-text该环境即将下线 orientationvertical cds-radio-button label-text生产环境 valueprod/cds-radio-button cds-radio-button label-text预发环境 valuestaging/cds-radio-button /cds-radio-button-group如需监听选中变化可订阅组的自定义事件groupEl.addEventListener(cds-radio-button-group-changed, (event) { console.log(event.detail.value, event.detail.name); });八、快照测试与回归保障快照文档是组件测试契约的一部分仓库中围绕cds-radio-button共有三层测试快照测试radio-button_spec.ts 驱动生成 cds-radio-button.md 快照验证 Shadow DOM 结构Open WC 单元测试radio-button-test.js 与 radio-button-group-test.js 覆盖渲染、属性反射、readOnly防点击、aria-readonly、校验/警告文案展示、legend与fieldset结构、禁用防更改等行为Storybook 交互示例radio-button.stories.ts 提供Default、Vertical、Skeleton、WithAILabel等 story其中argTypes完整罗列了组件 API 与控件类型可直接用于调试。开发者如需更新快照可在packages/web-components目录下运行yarn test:updateSnapshots脚本定义见 package.json但要先确认 DOM 结构变更是有意为之。九、总结cds-radio-button的渲染快照揭示了其原生 input label slot的稳固 DOM 骨架tabindex的-1/0切换体现了单选组只保留一个可聚焦项的无障碍规范hide-label下的cds--visually-hidden兼顾视觉与可访问性而name、value的透传则保证了原生表单语义不被 Shadow DOM 隔离破坏。配合cds-radio-button-group的属性传播、事件冒泡与RadioGroupManager的环形键盘导航整套实现既保持了 Web Components 的封装性又完整继承了原生 radio 的可访问性与表单行为——这正是快照文档背后值得深入理解的设计价值。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入解析 Carbon Web Components 的 cds-radio-button：渲染快照、属性语义与组内交互机制
深入解析 Carbon Web Components 的 cds-radio-button渲染快照、属性语义与组内交互机制【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carboncds-radio-button是 IBM Carbon Design System 的 Web Components 实现carbon/web-components当前仓库版本为 2.63.0中用于互斥单选场景的表单控件。它通过 Shadow DOM 封装原生input typeradio与label配合父组件cds-radio-button-group维护受控状态。本文以仓库中的渲染快照文档 packages/web-components/tests/snapshots/cds-radio-button.md 为主体逐行剖析其 Shadow DOM 渲染结构并结合 radio-button.ts 与 radio-button-group.ts 的源码讲清每个属性的取值、默认值、语义以及组内通信、键盘导航与表单提交的底层实现。一、快照文档说明了什么渲染快照是组件测试体系中的契约文件单元测试通过toMatchSnapshot将组件渲染出的 Shadow DOM 与快照逐一比对任何结构性变更都会造成快照 diff从而驱动开发者审慎评估改动。快照文档记录了cds-radio-button的两类典型渲染结果最小属性渲染Should render with minimum attributes组件不带任何显式属性时的默认 DOM 结构多属性渲染Should render with various attributes同时携带disabled、name、label-position、orientation、hide-label、label-text等属性时的 DOM 结构。对应的测试用例定义在 radio-button_spec.ts 中通过Playground模板渲染cds-radio-button-group再断言document.body.querySelector(cds-radio-button[valuestaging])的快照mode: shadow即只比较 Shadow DOM。这说明快照里的valuestaging来自测试模板传入的value属性而非硬编码。二、Shadow DOM 渲染结构逐层拆解2.1 最小属性渲染组件的默认骨架当cds-radio-button不带任何属性时渲染结果如下摘录自快照文档input classcds--radio-button idinput tabindex-1 typeradio valuestaging label classcds--radio-button__label forinput span classcds--radio-button__appearance /span span slot /slot /span /label这段模板与 radio-button.ts 中的render()方法一一对应共包含三层结构原生input typeradio承载真实的表单语义。默认classcds--radio-button、idinput、tabindex-1type恒为radio。注意tabindex的默认值是-1即默认状态下所有单选项都不在 Tab 键序内——这是单选组内只保留一个可聚焦项这一无障碍约定的直接体现。label forinput通过for/id配对把整块可点击区域圆形外观 文本关联到隐藏的原生 input。__tests__/radio-button-test.js中的should associate the label with the input via matching for/id用例专门验证了这一关联见 radio-button-test.js。外观与插槽span classcds--radio-button__appearance纯 CSS 绘制的圆形外观选中态的小圆点由::before伪元素呈现样式定义在 radio-button.scss内层span包裹一个slot用于投射使用者的自定义标签内容。快照中该slot为空对应最小属性状态。从源码看value属性通过ifDefined(value)注入 input见 radio-button.ts因此未设置value时 input 上不会出现value属性。快照中出现的valuestaging即测试模板显式传入的属性。2.2 多属性渲染状态属性的 DOM 反馈快照文档记录的第二种渲染结果如下input classcds--radio-button disabled idinput namename-foo tabindex0 typeradio valuestaging label classcds--radio-button__label forinput span classcds--radio-button__appearance /span span classcds--visually-hidden slot label-text-foo /slot /span /label与最小属性渲染相比出现了四处差异逐一说明其来源与语义disabled组件的disabled布尔属性开启后?disabled${disabledItem || disabled}将属性透传到原生 inputradio-button.ts。测试模板中cds-radio-button-group传入了disabled: true并通过组的属性传播机制下发到每个子项下文详述。namename-fooname是单选组的分组标识同组单选按钮共享同一个name。测试模板在组上设置了name: name-foo同样被传播到子项。该属性是RadioGroupManager按组管理的键见 radio-group-manager.ts。tabindex0这是快照中一个关键状态。在多属性用例里当前按钮valuestaging被组选中value与组的值匹配因此RadioGroupManager.shouldBeFocusable()返回trueinput 的tabindex被置为0可聚焦其余未选中项保持-1。该逻辑位于 radio-button.ts 的updated()钩子中。classcds--visually-hidden与插槽回退内容label-text-foohideLabel为true时标签文本 span 追加cds--visually-hidden类视觉隐藏但保留给屏幕阅读器且slot内以labelText作为回退内容渲染slot ${labelText} /slot。测试模板传入了label-textlabel-text-foo与hideLabel: true对应快照中的插槽文本。三、属性全景属性名、取值与默认值结合 radio-button.ts、radio-button-group.ts 与 defs.ts将两个组件的核心属性整理如下。3.1cds-radio-button属性属性Attribute类型默认值说明checkedBooleanfalse当前是否选中reflect: true会反映为属性default-checkedBooleanfalse是否默认选中在firstUpdated()中若用户未显式设置checked则应用radio-button.tsdisabledBooleanfalse是否禁用组级禁用会传播到此disabled-itemBooleanfalse仅禁用当前单项hide-labelBooleanfalse视觉隐藏标签但保留可访问性invalidBooleanfalse校验失败状态warn/warn-textBoolean / Stringfalse/警告状态及提示文本label-positionleft \| rightright标签位置枚举定义见 defs.tslabel-textString标签文本作为slot的回退内容nameString未定义分组名组内互斥的键orientationhorizontal \| verticalhorizontal布局方向枚举见 defs.tsread-onlyBooleanfalse只读点击/键盘激活均不改变状态input 上反映aria-readonlyrequiredBooleanfalse必填标记透传到 inputvalueString未定义提交给表单的值3.2cds-radio-button-group属性属性Attribute类型默认值说明legend-textString组标题渲染为fieldset内的legendradio-button-group.tshelper-textString未定义辅助说明文本通过aria-describedby关联到fieldsetinvalid/invalid-textBoolean / Stringfalse/校验失败状态与错误消息消息通过aria-describedby关联warn/warn-textBoolean / Stringfalse/警告状态与警告消息nameString未定义组名传播到所有子项valueString未定义当前选中值变化时同步各子项checkedlabel-positionleft \| rightright传播到子项orientationhorizontal \| verticalhorizontal传播到子项disabled/read-only/requiredBooleanfalse传播到子项disabled还会原生禁用fieldset注意orientation与label-position都带有reflect: true因此组件实例的 HTML 属性会同步反映这些状态SCSS 侧也依赖属性选择器做样式适配见 radio-button.scss。四、组与项受控状态的通信机制cds-radio-button的官方用法强调以cds-radio-button-group为父容器来维护受控状态。在快照测试中所有用例也都是以组为单位渲染的。二者的协作分为三个层面。4.1 属性向下传播在 radio-button-group.ts 的updated()中组会监听disabled、labelPosition、orientation、readOnly、name、required、value、invalid等属性变化并遍历this.querySelectorAll(cds-radio-button)逐个赋值。源码注释明确指出这是为了绕开:host-context()尚未在所有主流浏览器得到完整支持的限制用显式传播保证子树一致性。radio-button_spec.ts的Communication between cds-radio-button-group and cds-radio-button分组radio-button_spec.ts用断言验证了这种传播例如组设置disabled: true后所有cds-radio-button的disabled均为true组设置label-positionleft后所有子项labelPosition均为left。4.2 事件向上冒泡单选按钮点击后CDSRadioButton._handleClick会触发cds-radio-button-changed自定义事件bubbles: true, composed: true见 radio-button.ts。组通过HostListener(eventChangeRadioButton)监听该事件radio-button-group.ts从子项中找出checked的那一个将其value同步为组的value若值确有变化再向上冒泡cds-radio-button-group-changed事件携带{ value, name, event }。4.3 表单参与formdata 事件组继承自FormMixin实现了_handleFormdataradio-button-group.ts当且仅当组未禁用、且name与value均已定义时才向FormData追加name - value。radio-button_spec.ts的Event-based form participation分组radio-button_spec.ts用四个用例覆盖了边界缺name不提交、未选中不提交、disabled不提交而{ name: name-foo, value: staging }时提交结果恰为{ name-foo: staging }。五、键盘导航RadioGroupManager 的实现细节单选组遵循 ARIA 单选组模式组内同一时刻只有一个可聚焦项。这一机制的底层是 radio-group-manager.ts 中的RadioGroupManager——每个 document 只维护一个实例WeakMap缓存见 L218-L227以name为键管理组内成员。核心方法包括shouldBeFocusable(radio)L84-L98可聚焦的条件是该项已选中或组内无选中项且该项是组内第一个由此决定 input 的tabindex是0还是-1。select(radio, readOnly?)L167-L186将被选中项checked置为true、tabIndex置0并聚焦同时把组内其他项checked置false、tabIndex置-1若目标是禁用项则提前返回。readOnly模式下也会同步选中状态但不允许用户改选。navigate(radio, direction)L193-L213在按 DOM 顺序排序后的组内做环形circular查找跳过禁用项若全部禁用则停留在当前项。方向映射在 radio-button.ts 中定义水平布局horizontalArrowLeft/LeftIE为后退ArrowRight/Right为前进垂直布局verticalArrowUp/Up为后退ArrowDown/Down为前进。keydown处理器L196-L237还支持 空格与Enter直接选中当前聚焦项。radio-button_spec.ts的Keyboard navigation分组radio-button_spec.ts验证了水平模式下按ArrowRight后tabindex数组由[-1, 0, -1]变为[0, -1, -1]焦点随选中项移动垂直模式同理。六、样式、校验状态与骨架屏6.1 样式入口radio-button.scss 通过use carbon/styles/scss/components/radio-button/radio-button引入 Carbon 基础样式并针对 Web Components 的:host()选择器做适配:host(cds-radio-button-group)继承cds--form-itemlabel-positionleft时追加cds--radio-button-group--label-left垂直布局下按钮间距改为margin-block-end: 6px且无水平间距L67-L70校验失败时cds--radio-button__appearance的边框使用$support-errorL72-L79disabled/disabled-item下标签变灰$text-disabled、光标为not-allowedL95-L109。6.2 校验与警告状态的优先级组在渲染时计算三个互斥分支radio-button-group.tsshowInvalid !readOnly !disabled invalid showWarning !readOnly !disabled !invalid warn showHelper !invalid !disabled !warn即invalid warn helper的优先级且readOnly、disabled会抑制全部校验文案。错误/警告图标通过iconLoader注入WarningFilled16/WarningAltFilled16。对应单元测试见 radio-button-group-test.js。6.3 骨架屏加载占位由cds-radio-button-skeleton提供其模板仅含两个带cds--skeleton类的 div/span见 radio-button-skeleton.ts在 Storybook 的Skeletonstory 中展示。七、组件入口与使用示例7.1 注册入口index.ts 会同时注册三个元素import ./radio-button; import ./radio-button-group; import ./radio-button-skeleton;在浏览器中可直接按包内子路径引入import carbon/web-components/es/components/radio-button/index.js;与 radio-button-test.js 的引用方式一致。7.2 最小可用示例cds-radio-button-group legend-text部署环境 nameenv valuestaging orientationvertical cds-radio-button label-text生产环境 valueprod/cds-radio-button cds-radio-button label-text预发环境 valuestaging/cds-radio-button cds-radio-button label-text测试环境 valuetest disabled-item/cds-radio-button /cds-radio-button-group7.3 结合校验与辅助文本的完整表单示例cds-radio-button-group legend-text部署环境 nameenv helper-text请选择目标环境 invalid invalid-text必须选择一个环境 warn warn-text该环境即将下线 orientationvertical cds-radio-button label-text生产环境 valueprod/cds-radio-button cds-radio-button label-text预发环境 valuestaging/cds-radio-button /cds-radio-button-group如需监听选中变化可订阅组的自定义事件groupEl.addEventListener(cds-radio-button-group-changed, (event) { console.log(event.detail.value, event.detail.name); });八、快照测试与回归保障快照文档是组件测试契约的一部分仓库中围绕cds-radio-button共有三层测试快照测试radio-button_spec.ts 驱动生成 cds-radio-button.md 快照验证 Shadow DOM 结构Open WC 单元测试radio-button-test.js 与 radio-button-group-test.js 覆盖渲染、属性反射、readOnly防点击、aria-readonly、校验/警告文案展示、legend与fieldset结构、禁用防更改等行为Storybook 交互示例radio-button.stories.ts 提供Default、Vertical、Skeleton、WithAILabel等 story其中argTypes完整罗列了组件 API 与控件类型可直接用于调试。开发者如需更新快照可在packages/web-components目录下运行yarn test:updateSnapshots脚本定义见 package.json但要先确认 DOM 结构变更是有意为之。九、总结cds-radio-button的渲染快照揭示了其原生 input label slot的稳固 DOM 骨架tabindex的-1/0切换体现了单选组只保留一个可聚焦项的无障碍规范hide-label下的cds--visually-hidden兼顾视觉与可访问性而name、value的透传则保证了原生表单语义不被 Shadow DOM 隔离破坏。配合cds-radio-button-group的属性传播、事件冒泡与RadioGroupManager的环形键盘导航整套实现既保持了 Web Components 的封装性又完整继承了原生 radio 的可访问性与表单行为——这正是快照文档背后值得深入理解的设计价值。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考