复合

Composite 在页面上提供单个选项卡停止位，并允许通过方向键导航可聚焦的后代元素。此抽象组件基于 WAI-ARIA Composite Role⁠。

用法

import { Composite } from '@wordpress/components';

<Composite>
  <Composite.Group>
    <Composite.GroupLabel>标签</Composite.GroupLabel>
    <Composite.Item>项目 1</Composite.Item>
    <Composite.Item>项目 2</Composite.Item>
  </CompositeGroup>
</Composite>

组件

Composite

渲染一个组合小部件。

属性

activeId: string | null

当前活动项的 id。活动项是组合小部件中具有 DOM 焦点或虚拟焦点（如果启用了 virtualFocus 属性）的元素。

• null 表示基础组合元素（具有 组合角色 的元素）。用户将能够使用方向键从中导航出去。
• 如果 activeId 初始设置为 null，则基础组合元素本身将获得焦点，用户可以使用方向键导航到它。

• 必需：否

defaultActiveId: string | null

当组合小部件渲染时，默认应为活动的组合项 id。如果为 null，则组合元素本身将获得焦点，用户可以使用方向键导航到它。如果为 undefined，则将聚焦第一个启用的项目。

• 必需：否

setActiveId: ((activeId: string | null | undefined) => void)

当 activeId 状态更改时调用的回调函数。

• 必需：否

focusLoop: boolean | ‘horizontal’ | ‘vertical’ | ‘both’

确定当用户到达组合小部件末尾时焦点的行为方式。

在一维组合小部件上：

• true 从最后一项循环到第一项，反之亦然。
• horizontal 仅当 orientation 为 horizontal 或未设置时才循环。
• vertical 仅当 orientation 为 vertical 或未设置时才循环。
• 如果 activeId 初始设置为 null，则组合元素将在最后一项和第一项之间获得焦点。

在二维组合小部件上（即使用 CompositeRow 时）：

• true 从最后一行/列项目循环到同一行/列中的第一项，反之亦然。如果是最后一行的最后一项，它将移动到第一行的第一项，反之亦然。
• horizontal 仅从最后一行项目循环到同一行中的第一项。
• vertical 仅从最后一列项目循环到该列行中的第一项。
• 如果 activeId 初始设置为 null，垂直循环将无效，因为从最后一行向下移动或从第一行向上移动将聚焦于组合元素。
• 如果 focusWrap 与 focusLoop 的值匹配，它将在最后一行或列的最后一项与第一行或列的第一项之间换行，反之亦然。

• 必需：否

• 默认值：false

focusShift: boolean

仅适用于二维组合小部件。

如果启用，当没有下一个项目或下一个项目被禁用时，向上或向下移动将切换到其前面的项目。

• 必需：否
• 默认值：false

focusWrap: boolean

仅适用于二维组合小部件。

如果启用，从一行或一列中的最后一项移动到下一项
将聚焦于下一行或下一列中的第一项，反之亦然。

• true 在行和列之间换行。
• horizontal 仅在行之间换行。
• vertical 仅在列之间换行。
• 如果 focusLoop 与 focusWrap 的值匹配，它将换行
  最后一行或列的最后一项与第一行或
  列的第一项，反之亦然。

• 必需：否

• 默认值：false

virtualFocus: boolean

如果启用，组合元素将充当 aria-activedescendant
容器而不是 漫游 tabindex。DOM 焦点将保持在组合元素上，而其项目接收
虚拟焦点。

在这两种情况下，聚焦的项目都将带有 data-active-item 属性。

• 必需：否
• 默认值：false

orientation: ‘horizontal’ | ‘vertical’ | ‘both’

定义组合小部件的方向。如果组合体只有一行或一列（一维），orientation 值决定可以使用哪些方向键来移动焦点：

• both：所有方向键都有效。
• horizontal：只有左右方向键有效。
• vertical：只有上下方向键有效。

它对二维组合体没有任何影响。

• 必需：否
• 默认值：both

rtl: boolean

确定 store 的 next 和 previous 函数的行为方式。如果 rtl 设置为 true，它们将被反转。

这仅影响组合小部件的行为。您仍然需要在 HTML/CSS 上设置 dir="rtl"。

• 必需：否
• 默认值：false

render: RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>

允许组件作为不同的 HTML 元素或 React 组件进行渲染。该值可以是一个 React 元素或一个函数，该函数接受原始组件属性并返回一个合并了属性的 React 元素。

• 必需：否

focusable: boolean

使组件成为可聚焦元素。当此元素获得键盘焦点时，它会获得 data-focus-visible 属性并触发 onFocusVisible 属性。

即使对于不支持原生 disabled 属性的元素，组件也支持 disabled 属性。禁用的元素仍可通过使用 accessibleWhenDisabled 属性通过键盘访问。

非原生可聚焦元素将完全失去其可聚焦性。然而，原生可聚焦元素将保留其固有的可聚焦性。

• 必需：否

disabled: boolean

确定元素是否被禁用。这相应地设置了 aria-disabled 属性，从而支持所有元素，包括那些不支持原生 disabled 属性的元素。

此功能可以与 accessibleWhenDisabled 属性结合使用，以
使禁用的元素仍可经由键盘访问。

注意：要使此属性生效，focusable 属性必须设置为
true，如果它不是默认设置的。

• 必需：否
• 默认值：false

accessibleWhenDisabled: boolean

指示元素在被
disabled 时是否应可聚焦。

这在关注可发现性时很重要。例如：

编辑器中的工具栏包含一组特殊的智能粘贴功能
当剪贴板为空或该功能不适用于
剪贴板的当前内容时被禁用。如果主要通过其在工具栏上的存在来发现其
功能，保持禁用按钮的可聚焦性可能会有所帮助。

了解有关 禁用控件的可聚焦性 的更多信息。

• 必需：否

onFocusVisible: (event: SyntheticEvent<HTMLElement>) => void

当元素通过键盘交互获得焦点或在元素处于焦点时发生按键时调用的自定义事件处理程序。这是 data-focus-visible 属性的编程等效项。

注意：要使此属性生效，focusable 属性必须设置为 true，如果它不是默认设置的。

• 必需：否

children: React.ReactNode

组件的内容。

• 必需：否

Composite.Group

为组合项渲染组元素。

render: RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>

允许组件作为不同的 HTML 元素或 React 组件进行渲染。该值可以是一个 React 元素或一个函数，该函数接受原始组件属性并返回一个合并了属性的 React 元素。

• 必需：否

children: React.ReactNode

组件的内容。

• 必需：否

Composite.GroupLabel

在组合组中渲染标签。此组件必须用 Composite.Group 包裹，以便在组合组元素上正确设置 aria-labelledby 属性。

render: RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>

允许将组件渲染为不同的 HTML 元素或 React 组件。该值可以是一个 React 元素，或者是一个接收原始组件 props 并返回合并了 props 的 React 元素的函数。

• 必填：否

children: React.ReactNode

组件的内容。

• 必填：否

Composite.Item

渲染一个组合项。

accessibleWhenDisabled: boolean

指示即使元素处于
disabled（禁用）状态时是否仍应可聚焦。

这在关注可发现性时非常重要。例如：

编辑器中的工具栏包含一组特殊的智能粘贴功能，
当剪贴板为空或该功能不适用于剪贴板的当前内容时，这些功能会被禁用。如果主要通过它们在工具栏上的存在来发现其功能，
保持禁用按钮的可聚焦性可能会有所帮助。

了解更多关于 禁用控件的可聚焦性。

• 必填：否

render: RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>

允许将组件渲染为不同的 HTML 元素或 React 组件。该值可以是一个 React 元素，或者是一个接收原始组件 props 并返回合并了 props 的 React 元素的函数。

• 必填：否

children: React.ReactNode

组件的内容。

• 必填：否

Composite.Row

渲染一个组合行。在 Composite.Row 内包裹 Composite.Item 元素将创建一个二维组合小部件，例如网格。

render: RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>

允许将组件渲染为不同的 HTML 元素或 React 组件。该值可以是一个 React 元素，或者是一个接收原始组件 props 并返回合并了 props 的 React 元素的函数。

• 必填：否

children: React.ReactNode

组件的内容。

• 必填：否

Composite.Hover

在组合小部件中渲染一个元素，该元素在鼠标移动时获得焦点，并在鼠标离开时失去焦点并回到组合基础元素。这应与 Composite.Item 组件结合使用。

render: RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>

允许将组件渲染为不同的 HTML 元素或 React 组件。该值可以是一个 React 元素，或者是一个接收原始组件 props 并返回合并了 props 的 React 元素的函数。

• 必填：否

children: React.ReactNode

组件的内容。

• 必填：否

Composite.Typeahead

渲染一个为组合组件添加类型Ahead（首字母匹配）功能的组件。按下可打印字符键会将焦点移动到下一个以输入字符开头的组合项。

render: RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>

允许将组件渲染为不同的 HTML 元素或 React 组件。该值可以是一个 React 元素，或者是一个接收原始组件 props 并返回合并了 props 的 React 元素的函数。

• 必填：否

children: React.ReactNode

组件的内容。

• 必填：否

Composite.Context

组合组件使用的 React context。它可以用来访问组合 store，并在跨 portals（即 SlotFill 组件）渲染组合子组件时转发 context，否则这些组件不会将 context 转发给 Fill 子组件。