WordPress Gutenberg Composite 组件完全指南基于 WAI-ARIA 的单一 Tab 停靠点与方向键导航【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergComposite是 Gutenberg 项目WordPress 块编辑器中wordpress/components包提供的核心交互组件它基于 WAI-ARIA Composite Role 抽象在页面上提供单一 Tab 停靠点并允许用户通过方向键在可聚焦的子元素之间导航。本文将从快速上手、完整 API 参考、焦点管理机制到源码级实现原理系统讲解如何在 Gutenberg 生态中用它构建无障碍、键盘友好的工具栏、菜单、网格等复合组件。设计动机为什么需要 Composite在原生 HTML 中如果一个容器内有多个可聚焦元素如一组按钮Tab 键会逐个访问它们这要求用户按很多次 Tab 才能遍历完一组控件。对于工具栏、菜单、单选组、网格这类「复合组件」WAI-ARIA 推荐只保留一个 Tab 停靠点进入组件后改用方向键在内部成员之间移动焦点。这正是Composite要解决的抽象问题。从 源码实现 的注释可以看到Composite 是一个可能包含可导航项由 Composite.Item 表示的组件。它受 WAI-ARIA Composite Role 启发实现了所有键盘导航机制确保整个 Composite 元素只有一个 Tab 停靠点。这意味着它可以表现为 roving tabindex 或 aria-activedescendant 容器。也就是说无论底层采用哪种焦点管理策略使用方拿到的 API 都是一致的——这正是该组件「抽象」的价值所在。快速上手从wordpress/components导入Composite即可使用import { Composite } from wordpress/components; function MyMenu() { return ( Composite Composite.Group Composite.GroupLabelLabel/Composite.GroupLabel Composite.ItemItem 1/Composite.Item Composite.ItemItem 2/Composite.Item /Composite.Group /Composite ); }最简用法甚至不需要Groupimport { Composite } from wordpress/components; Composite Composite.ItemItem 1/Composite.Item Composite.ItemItem 2/Composite.Item Composite.ItemItem 3/Composite.Item /Composite使用后Tab 键只会进入组件一次之后的横向/纵向移动全部交给方向键。组件 API 全解Composite通过Object.assign挂载了一组静态子组件index.tsx完整清单如下子组件作用Composite.Group渲染一组复合项的容器Composite.GroupLabel组标签必须包裹在Composite.Group内Composite.Item复合组件中的可导航项Composite.Row复合行包裹 Item 后形成二维复合组件如网格Composite.Hover鼠标悬停时获得焦点、移出时交还基元素的元素Composite.Typeahead为复合组件增加输入定位typeahead能力Composite.Context复合组件使用的 React Context可访问 store下面逐一详解。Composite根组件渲染一个复合组件composite widget支持的 props 如下。活动项控制activeId/defaultActiveId/setActiveIdactiveId:string | null当前活动项的id。活动项指复合组件内拥有 DOM 焦点或虚拟焦点启用了virtualFocus的元素。null表示基础复合元素带 composite role 的那个元素用户可以从它出发用方向键导航进入各项若初始设为null基础复合元素自身获得焦点用户可以用方向键从中导航。defaultActiveId:string | null组件渲染时的默认活动项 id。null基础复合元素获得焦点undefined第一个启用的项被聚焦。setActiveId:(activeId: string | null | undefined) voidactiveId状态变化时的回调用于受控场景。焦点循环focusLoop类型boolean | horizontal | vertical | both默认false。决定用户到达复合组件末尾时的焦点行为。一维复合组件单行或单列true从最后一项循环回第一项反之亦然horizontal仅当orientation为horizontal或未设置时循环vertical仅当orientation为vertical或未设置时循环若activeId初始为null基础复合元素会夹在最后一项与第一项之间被聚焦。二维复合组件使用了Composite.Rowtrue从某行/列的末项循环回同一行/列的首项若处于最后一行/列的末项则跳到第一行/列的首项反之亦然horizontal仅在行内循环行末项回到该行首项vertical仅在列内循环列末项回到该列首项若activeId初始为null垂直循环不生效——从最后一行向下或从第一行向上移动都会聚焦到基础复合元素若focusWrap与focusLoop取值一致则在最后一行/列的末项与第一行/列的首项之间循环。换行换列focusWrap类型boolean | horizontal | vertical默认false。仅对二维复合组件生效。true在行与列之间换行horizontal仅在行之间换行vertical仅在列之间换行若focusLoop与focusWrap一致则在末行/列末项与首行/列首项之间包裹。与focusLoop的区别focusLoop处理「同方向到达边界」的循环focusWrap处理「从一行切到另一行/从一列切到另一列」时的包裹。位移回退focusShift类型boolean默认false。仅对二维复合组件生效。启用后向上/下移动时若下一个位置没有项或该项被禁用焦点会回退到当前位置之前的项。典型场景是行内项数不一致的不规则网格。虚拟焦点virtualFocus类型boolean默认false。启用后复合元素作为aria-activedescendant容器DOM 焦点始终停留在复合元素上各项只获得「虚拟焦点」默认情况下则采用 roving tabindex焦点随导航在各项间真实移动。两种模式下获得焦点的项都会携带data-active-item属性测试代码即通过该属性断言活动项见 test/index.browser.test.tsx。方向orientation类型horizontal | vertical | both默认both。对一维复合组件决定哪些方向键可用both所有方向键都可用horizontal仅左右方向键vertical仅上下方向键。对二维复合组件无影响二维下方向键语义由行列结构决定。从右到左rtl类型boolean默认值为isRTL()由 index.tsx 从wordpress/i18n自动获取当前语言环境方向。设为true时store 的next/previous行为反转左右互换。注意它只影响复合组件的行为HTML/CSS 层面仍需自行设置dirrtl。渲染控制render类型RenderProp... | ReactElement。允许把组件渲染为不同的 HTML 元素或 React 组件值可以是 React 元素也可以是接收原始 props 并返回合并后元素的函数。这是 Ariakit 系组件的通用扩展点常用于把Composite.Item渲染成button、a或自定义组件。焦点可见性focusable/onFocusVisiblefocusable:boolean使组件可聚焦。获得键盘焦点时携带data-focus-visible属性并触发onFocusVisible。非原生可聚焦元素会完全失去可聚焦性而原生可聚焦元素保留其固有可聚焦性。onFocusVisible:(event: SyntheticEventHTMLElement) void元素通过键盘交互获得焦点或聚焦时按键触发的自定义事件处理函数是data-focus-visible属性的编程等价物。注意onFocusVisible生效的前提是focusable为true若其默认值不是 true。禁用状态disabled/accessibleWhenDisableddisabled:boolean默认false设置aria-disabled属性从而支持所有元素包括不原生支持disabled的元素。可与accessibleWhenDisabled组合。accessibleWhenDisabled:boolean指示元素即使在disabled时仍可聚焦。这对「可发现性」很重要——文档中给出了经典例子编辑器中的工具栏包含一组特殊的智能粘贴功能当剪贴板为空或功能不适用于当前剪贴板内容时它们被禁用。如果这些禁用按钮的功能可发现性主要依赖其在工具栏上的存在那么让禁用按钮保持可聚焦是有帮助的。相关规范见 Focusability of disabled controls。children类型React.ReactNode组件内容。Composite.Group与Composite.GroupLabelComposite.Group渲染复合项的分组容器Composite.GroupLabel渲染组标签。后者必须包裹在Composite.Group内部——从 group-label.tsx 的源码可以看到CompositeGroupLabel会通过useCompositeGroupContext()检查自己是否处于CompositeGroupContext.Provider内否则直接throw new Error(Composite.GroupLabel can only be rendered inside Composite.Group.)。正确渲染后aria-labelledby会被正确设置在组元素上屏幕阅读器用户即可感知分组语义。两个组件均支持render与childrenprops。Composite.Item渲染一个复合项是导航的最小单位。支持children、render以及accessibleWhenDisabled语义同根组件。从 item.tsx 源码可见CompositeItem内部会从 Context 读取 store若在Composite之外使用拿不到 store会通过wordpress/warning输出开发警告Composite.Item: Missing composite state. Render inside Composite to enable composite keyboard behavior.——这是排查「方向键不生效」类问题的重要线索。Composite.Row构建二维复合组件将Composite.Item包进Composite.Row即可创建二维复合组件如网格Composite Composite.Row Composite.ItemItem 1.1/Composite.Item Composite.ItemItem 1.2/Composite.Item Composite.ItemItem 1.3/Composite.Item /Composite.Row Composite.Row Composite.ItemItem 2.1/Composite.Item Composite.ItemItem 2.2/Composite.Item Composite.ItemItem 2.3/Composite.Item /Composite.Row /Composite二维模式下focusLoop、focusWrap、focusShift的全部语义见上文才会生效。Composite.Hover渲染一个随鼠标悬停获得焦点、鼠标移出时把焦点交还给复合基础元素的组件通常与Composite.Item组合使用实现菜单悬停展开类体验Composite Composite.Hover render{ Composite.Item / }Item 1/Composite.Hover Composite.Hover render{ Composite.Item / }Item 2/Composite.Hover /CompositeComposite.Typeahead为复合组件增加输入定位能力按下可打印字符键焦点移动到下一个以输入字符开头的复合项类似文件管理器/编辑器的首字母跳转Composite render{ Composite.Typeahead / } Composite.ItemItem 1/Composite.Item Composite.ItemItem 2/Composite.Item /Composite注意示例中的用法是把Composite.Typeahead通过render渲染为Composite的底层元素。Composite.Context复合组件间共享的 React Contextcontext.tsx可用来访问复合 store并在复合子组件通过 portal如SlotFill渲染、Context 无法自动穿透到Fill子组件时手动转发import { Composite } from wordpress/components; import { useContext } from wordpress/element; const compositeContext useContext( Composite.Context );焦点管理机制roving tabindex 与 aria-activedescendantComposite支持两种被 WAI-ARIA APG 认可的标准键盘交互实现由virtualFocus切换Roving tabindex默认容器内始终只有一个元素的tabindex为0其余为-1DOM 焦点随导航真实移动aria-activedescendant虚拟焦点DOM 焦点固定在容器上通过aria-activedescendant指向当前活动项 id适合虚拟列表、巨型网格等需要频繁移动焦点却不想重排 DOM 的场景。无论哪种模式当前活动项都会带有data-active-itemtrue属性前端样式与测试均可据此定位活动项。浏览器测试 验证了「单一 Tab 停靠点」的核心行为Tab 聚焦 Before → 进入组件聚焦 Item 1 → Tab 直接跳到 AfterShiftTab 反向亦然。源码实现剖析Ariakit 之上的 WordPress 封装Composite并非从零实现而是对开源组件库 Ariakit 的二次封装index.tsx。其实现要点store 驱动根组件调用Ariakit.useCompositeStore({ activeId, defaultActiveId, setActiveId, focusLoop, focusWrap, focusShift, virtualFocus, orientation, rtl })创建 storeindex.tsx所有焦点/导航状态都收敛于此Context 分发store 通过useMemo缓存进contextValue再由CompositeContext.Provider提供给所有子组件index.tsxGroup额外通过CompositeGroupContext标记分组层级group.tsx默认值策略focusLoop false、focusWrap false、focusShift false、virtualFocus false、orientation both、rtl isRTL()、disabled falseindex.tsx其中rtl自动跟随wordpress/i18n的isRTL()无需手动配置即可适配阿拉伯语、希伯来语等环境子组件转发Item/Row/Hover/Typeahead/GroupLabel均为对 Ariakit 对应组件的轻量转发统一从 Context 取 store见 item.tsx、row.tsx、hover.tsx、typeahead.tsxstore prop 与 legacy 兼容storeprop 属于未文档化的内部通道仅供 legacy 兼容层使用类型被刻意模糊以阻止外部直接使用源码多处ts-expect-error注释说明了这一点。从类型定义types.ts可以看出所有 props 的类型均直接派生自Ariakit.CompositeStoreProps与对应 Ariakit 组件的 props保证了与上游能力的同步与类型安全。在 Gutenberg 中的实际应用Composite已广泛用于 Gutenberg 内部各组件例如alignment-matrix-control对齐方式选择矩阵利用Composite.Row构建二维网格导航circular-option-picker颜色/图案循环选择器利用方向键快速切换选项。构建类似工具栏、菜单、网格选择器等复合控件时推荐组合方式一维工具栏CompositeComposite.Itemorientationhorizontal可选focusLoop分组菜单外层Composite内部多个Composite.GroupComposite.GroupLabel二维网格Composite 多个Composite.Row按需启用focusWrap、focusLoop、focusShift长列表/虚拟列表开启virtualFocus配合data-active-item做高亮样式。无障碍最佳实践与注意事项不要过度禁用需要「可发现」的禁用项请使用accessibleWhenDisabled而不是简单disabled以避免键盘用户与屏幕阅读器用户「看不见」该功能RTL 双重设置rtlprop 只管导航行为页面级dirrtl与相关 CSS 仍需自行处理子组件必须处于Composite内Composite.Item脱离上下文只会得到开发警告Composite.GroupLabel脱离Group会直接抛错利用data-active-item做样式活动项的高亮、aria-selected等视觉与语义反馈可统一挂在该属性选择器下与内部实现解耦二维组件的循环语义focusLoop与focusWrap取值相同时会产生「跨首末行包裹」行为设计导航时要区分「同方向循环」与「换行包裹」两种意图。至此从 API 用法、焦点机制到实现原理Composite的完整能力已清晰呈现。如需深入交互细节可继续阅读 composite 目录 下的 stories 与浏览器测试用例它们覆盖了禁用项跳过、虚拟焦点、二维导航、typeahead 等全部行为。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WordPress Gutenberg Composite 组件完全指南基于 WAI-ARIA 的单一 Tab 停靠点与方向键导航【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergComposite是 Gutenberg 项目WordPress 块编辑器中wordpress/components包提供的核心交互组件它基于 WAI-ARIA Composite Role 抽象在页面上提供单一 Tab 停靠点并允许用户通过方向键在可聚焦的子元素之间导航。本文将从快速上手、完整 API 参考、焦点管理机制到源码级实现原理系统讲解如何在 Gutenberg 生态中用它构建无障碍、键盘友好的工具栏、菜单、网格等复合组件。设计动机为什么需要 Composite在原生 HTML 中如果一个容器内有多个可聚焦元素如一组按钮Tab 键会逐个访问它们这要求用户按很多次 Tab 才能遍历完一组控件。对于工具栏、菜单、单选组、网格这类「复合组件」WAI-ARIA 推荐只保留一个 Tab 停靠点进入组件后改用方向键在内部成员之间移动焦点。这正是Composite要解决的抽象问题。从 源码实现 的注释可以看到Composite 是一个可能包含可导航项由 Composite.Item 表示的组件。它受 WAI-ARIA Composite Role 启发实现了所有键盘导航机制确保整个 Composite 元素只有一个 Tab 停靠点。这意味着它可以表现为 roving tabindex 或 aria-activedescendant 容器。也就是说无论底层采用哪种焦点管理策略使用方拿到的 API 都是一致的——这正是该组件「抽象」的价值所在。快速上手从wordpress/components导入Composite即可使用import { Composite } from wordpress/components; function MyMenu() { return ( Composite Composite.Group Composite.GroupLabelLabel/Composite.GroupLabel Composite.ItemItem 1/Composite.Item Composite.ItemItem 2/Composite.Item /Composite.Group /Composite ); }最简用法甚至不需要Groupimport { Composite } from wordpress/components; Composite Composite.ItemItem 1/Composite.Item Composite.ItemItem 2/Composite.Item Composite.ItemItem 3/Composite.Item /Composite使用后Tab 键只会进入组件一次之后的横向/纵向移动全部交给方向键。组件 API 全解Composite通过Object.assign挂载了一组静态子组件index.tsx完整清单如下子组件作用Composite.Group渲染一组复合项的容器Composite.GroupLabel组标签必须包裹在Composite.Group内Composite.Item复合组件中的可导航项Composite.Row复合行包裹 Item 后形成二维复合组件如网格Composite.Hover鼠标悬停时获得焦点、移出时交还基元素的元素Composite.Typeahead为复合组件增加输入定位typeahead能力Composite.Context复合组件使用的 React Context可访问 store下面逐一详解。Composite根组件渲染一个复合组件composite widget支持的 props 如下。活动项控制activeId/defaultActiveId/setActiveIdactiveId:string | null当前活动项的id。活动项指复合组件内拥有 DOM 焦点或虚拟焦点启用了virtualFocus的元素。null表示基础复合元素带 composite role 的那个元素用户可以从它出发用方向键导航进入各项若初始设为null基础复合元素自身获得焦点用户可以用方向键从中导航。defaultActiveId:string | null组件渲染时的默认活动项 id。null基础复合元素获得焦点undefined第一个启用的项被聚焦。setActiveId:(activeId: string | null | undefined) voidactiveId状态变化时的回调用于受控场景。焦点循环focusLoop类型boolean | horizontal | vertical | both默认false。决定用户到达复合组件末尾时的焦点行为。一维复合组件单行或单列true从最后一项循环回第一项反之亦然horizontal仅当orientation为horizontal或未设置时循环vertical仅当orientation为vertical或未设置时循环若activeId初始为null基础复合元素会夹在最后一项与第一项之间被聚焦。二维复合组件使用了Composite.Rowtrue从某行/列的末项循环回同一行/列的首项若处于最后一行/列的末项则跳到第一行/列的首项反之亦然horizontal仅在行内循环行末项回到该行首项vertical仅在列内循环列末项回到该列首项若activeId初始为null垂直循环不生效——从最后一行向下或从第一行向上移动都会聚焦到基础复合元素若focusWrap与focusLoop取值一致则在最后一行/列的末项与第一行/列的首项之间循环。换行换列focusWrap类型boolean | horizontal | vertical默认false。仅对二维复合组件生效。true在行与列之间换行horizontal仅在行之间换行vertical仅在列之间换行若focusLoop与focusWrap一致则在末行/列末项与首行/列首项之间包裹。与focusLoop的区别focusLoop处理「同方向到达边界」的循环focusWrap处理「从一行切到另一行/从一列切到另一列」时的包裹。位移回退focusShift类型boolean默认false。仅对二维复合组件生效。启用后向上/下移动时若下一个位置没有项或该项被禁用焦点会回退到当前位置之前的项。典型场景是行内项数不一致的不规则网格。虚拟焦点virtualFocus类型boolean默认false。启用后复合元素作为aria-activedescendant容器DOM 焦点始终停留在复合元素上各项只获得「虚拟焦点」默认情况下则采用 roving tabindex焦点随导航在各项间真实移动。两种模式下获得焦点的项都会携带data-active-item属性测试代码即通过该属性断言活动项见 test/index.browser.test.tsx。方向orientation类型horizontal | vertical | both默认both。对一维复合组件决定哪些方向键可用both所有方向键都可用horizontal仅左右方向键vertical仅上下方向键。对二维复合组件无影响二维下方向键语义由行列结构决定。从右到左rtl类型boolean默认值为isRTL()由 index.tsx 从wordpress/i18n自动获取当前语言环境方向。设为true时store 的next/previous行为反转左右互换。注意它只影响复合组件的行为HTML/CSS 层面仍需自行设置dirrtl。渲染控制render类型RenderProp... | ReactElement。允许把组件渲染为不同的 HTML 元素或 React 组件值可以是 React 元素也可以是接收原始 props 并返回合并后元素的函数。这是 Ariakit 系组件的通用扩展点常用于把Composite.Item渲染成button、a或自定义组件。焦点可见性focusable/onFocusVisiblefocusable:boolean使组件可聚焦。获得键盘焦点时携带data-focus-visible属性并触发onFocusVisible。非原生可聚焦元素会完全失去可聚焦性而原生可聚焦元素保留其固有可聚焦性。onFocusVisible:(event: SyntheticEventHTMLElement) void元素通过键盘交互获得焦点或聚焦时按键触发的自定义事件处理函数是data-focus-visible属性的编程等价物。注意onFocusVisible生效的前提是focusable为true若其默认值不是 true。禁用状态disabled/accessibleWhenDisableddisabled:boolean默认false设置aria-disabled属性从而支持所有元素包括不原生支持disabled的元素。可与accessibleWhenDisabled组合。accessibleWhenDisabled:boolean指示元素即使在disabled时仍可聚焦。这对「可发现性」很重要——文档中给出了经典例子编辑器中的工具栏包含一组特殊的智能粘贴功能当剪贴板为空或功能不适用于当前剪贴板内容时它们被禁用。如果这些禁用按钮的功能可发现性主要依赖其在工具栏上的存在那么让禁用按钮保持可聚焦是有帮助的。相关规范见 Focusability of disabled controls。children类型React.ReactNode组件内容。Composite.Group与Composite.GroupLabelComposite.Group渲染复合项的分组容器Composite.GroupLabel渲染组标签。后者必须包裹在Composite.Group内部——从 group-label.tsx 的源码可以看到CompositeGroupLabel会通过useCompositeGroupContext()检查自己是否处于CompositeGroupContext.Provider内否则直接throw new Error(Composite.GroupLabel can only be rendered inside Composite.Group.)。正确渲染后aria-labelledby会被正确设置在组元素上屏幕阅读器用户即可感知分组语义。两个组件均支持render与childrenprops。Composite.Item渲染一个复合项是导航的最小单位。支持children、render以及accessibleWhenDisabled语义同根组件。从 item.tsx 源码可见CompositeItem内部会从 Context 读取 store若在Composite之外使用拿不到 store会通过wordpress/warning输出开发警告Composite.Item: Missing composite state. Render inside Composite to enable composite keyboard behavior.——这是排查「方向键不生效」类问题的重要线索。Composite.Row构建二维复合组件将Composite.Item包进Composite.Row即可创建二维复合组件如网格Composite Composite.Row Composite.ItemItem 1.1/Composite.Item Composite.ItemItem 1.2/Composite.Item Composite.ItemItem 1.3/Composite.Item /Composite.Row Composite.Row Composite.ItemItem 2.1/Composite.Item Composite.ItemItem 2.2/Composite.Item Composite.ItemItem 2.3/Composite.Item /Composite.Row /Composite二维模式下focusLoop、focusWrap、focusShift的全部语义见上文才会生效。Composite.Hover渲染一个随鼠标悬停获得焦点、鼠标移出时把焦点交还给复合基础元素的组件通常与Composite.Item组合使用实现菜单悬停展开类体验Composite Composite.Hover render{ Composite.Item / }Item 1/Composite.Hover Composite.Hover render{ Composite.Item / }Item 2/Composite.Hover /CompositeComposite.Typeahead为复合组件增加输入定位能力按下可打印字符键焦点移动到下一个以输入字符开头的复合项类似文件管理器/编辑器的首字母跳转Composite render{ Composite.Typeahead / } Composite.ItemItem 1/Composite.Item Composite.ItemItem 2/Composite.Item /Composite注意示例中的用法是把Composite.Typeahead通过render渲染为Composite的底层元素。Composite.Context复合组件间共享的 React Contextcontext.tsx可用来访问复合 store并在复合子组件通过 portal如SlotFill渲染、Context 无法自动穿透到Fill子组件时手动转发import { Composite } from wordpress/components; import { useContext } from wordpress/element; const compositeContext useContext( Composite.Context );焦点管理机制roving tabindex 与 aria-activedescendantComposite支持两种被 WAI-ARIA APG 认可的标准键盘交互实现由virtualFocus切换Roving tabindex默认容器内始终只有一个元素的tabindex为0其余为-1DOM 焦点随导航真实移动aria-activedescendant虚拟焦点DOM 焦点固定在容器上通过aria-activedescendant指向当前活动项 id适合虚拟列表、巨型网格等需要频繁移动焦点却不想重排 DOM 的场景。无论哪种模式当前活动项都会带有data-active-itemtrue属性前端样式与测试均可据此定位活动项。浏览器测试 验证了「单一 Tab 停靠点」的核心行为Tab 聚焦 Before → 进入组件聚焦 Item 1 → Tab 直接跳到 AfterShiftTab 反向亦然。源码实现剖析Ariakit 之上的 WordPress 封装Composite并非从零实现而是对开源组件库 Ariakit 的二次封装index.tsx。其实现要点store 驱动根组件调用Ariakit.useCompositeStore({ activeId, defaultActiveId, setActiveId, focusLoop, focusWrap, focusShift, virtualFocus, orientation, rtl })创建 storeindex.tsx所有焦点/导航状态都收敛于此Context 分发store 通过useMemo缓存进contextValue再由CompositeContext.Provider提供给所有子组件index.tsxGroup额外通过CompositeGroupContext标记分组层级group.tsx默认值策略focusLoop false、focusWrap false、focusShift false、virtualFocus false、orientation both、rtl isRTL()、disabled falseindex.tsx其中rtl自动跟随wordpress/i18n的isRTL()无需手动配置即可适配阿拉伯语、希伯来语等环境子组件转发Item/Row/Hover/Typeahead/GroupLabel均为对 Ariakit 对应组件的轻量转发统一从 Context 取 store见 item.tsx、row.tsx、hover.tsx、typeahead.tsxstore prop 与 legacy 兼容storeprop 属于未文档化的内部通道仅供 legacy 兼容层使用类型被刻意模糊以阻止外部直接使用源码多处ts-expect-error注释说明了这一点。从类型定义types.ts可以看出所有 props 的类型均直接派生自Ariakit.CompositeStoreProps与对应 Ariakit 组件的 props保证了与上游能力的同步与类型安全。在 Gutenberg 中的实际应用Composite已广泛用于 Gutenberg 内部各组件例如alignment-matrix-control对齐方式选择矩阵利用Composite.Row构建二维网格导航circular-option-picker颜色/图案循环选择器利用方向键快速切换选项。构建类似工具栏、菜单、网格选择器等复合控件时推荐组合方式一维工具栏CompositeComposite.Itemorientationhorizontal可选focusLoop分组菜单外层Composite内部多个Composite.GroupComposite.GroupLabel二维网格Composite 多个Composite.Row按需启用focusWrap、focusLoop、focusShift长列表/虚拟列表开启virtualFocus配合data-active-item做高亮样式。无障碍最佳实践与注意事项不要过度禁用需要「可发现」的禁用项请使用accessibleWhenDisabled而不是简单disabled以避免键盘用户与屏幕阅读器用户「看不见」该功能RTL 双重设置rtlprop 只管导航行为页面级dirrtl与相关 CSS 仍需自行处理子组件必须处于Composite内Composite.Item脱离上下文只会得到开发警告Composite.GroupLabel脱离Group会直接抛错利用data-active-item做样式活动项的高亮、aria-selected等视觉与语义反馈可统一挂在该属性选择器下与内部实现解耦二维组件的循环语义focusLoop与focusWrap取值相同时会产生「跨首末行包裹」行为设计导航时要区分「同方向循环」与「换行包裹」两种意图。至此从 API 用法、焦点机制到实现原理Composite的完整能力已清晰呈现。如需深入交互细节可继续阅读 composite 目录 下的 stories 与浏览器测试用例它们覆盖了禁用项跳过、虚拟焦点、二维导航、typeahead 等全部行为。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
