useRole

import {useRole} from '@floating-ui/react';

用法

¥Usage

该 Hook 返回 ARIA 属性 props。

¥This Hook returns ARIA attribute props.

要使用它，请将 useFloating() 返回的 context 对象传递给它，然后将其结果输入 useInteractions() 数组。然后将返回的 prop getter 传播到元素上进行渲染。

¥To use it, pass it the context object returned from useFloating(), and then feed its result into the useInteractions() array. The returned prop getters are then spread onto the elements for rendering.

function App() {
  const {refs, floatingStyles, context} = useFloating();
 
  const role = useRole(context);
 
  const {getReferenceProps, getFloatingProps} = useInteractions([
    role,
  ]);
 
  return (
    <>
      <div ref={refs.setReference} {...getReferenceProps()}>
        Reference element
      </div>
      <div
        ref={refs.setFloating}
        style={floatingStyles}
        {...getFloatingProps()}
      >
        Floating element
      </div>
    </>
  );
}

属性

¥Props

interface UseRoleProps {
  enabled?: boolean;
  role?:
    // Native ARIA roles
    | 'dialog'
    | 'tooltip'
    | 'menu'
    | 'listbox'
    | 'grid'
    | 'tree'
    // Custom component roles
    | 'alertdialog'
    | 'label';
    | 'select'
    | 'combobox'
}

enabled

默认：true

¥default: true

有条件地启用/禁用 Hook。

¥Conditionally enable/disable the Hook.

useRole(context, {
  enabled: false,
});

role

默认：'dialog'

¥default: 'dialog'

浮动元素的作用。

¥The role of the floating element.

useRole(context, {
  role: 'tooltip',
});

组件角色

¥Component roles

这些是用于浮动元素的自定义角色，更狭窄地指定要渲染的元素的类型。这为浮动元素内的项目提供了一套更完整的可访问属性。

¥These are custom roles that are used for floating elements that more narrowly specify the type of element being rendered. This enables a more complete set of accessible props for items inside the floating element.

label

此角色应用于充当没有文本/标签的参考元素（例如图标按钮）的标签的浮动元素。

¥This role should be used for floating elements that act as a label for a reference element with no text/label (e.g. an icon button).

alertdialog

当浮动元素具有需要用户操作且无法关闭的任意可选项内容时，应使用此角色。

¥This role should be used when the floating element has arbitrary tabbable content that requires user action and can’t be dismissed.

对于以下两个角色，在传播时应使用 active 和 selected 布尔属性调用 getItemProps 属性 getter。

¥For the following two roles, the getItemProps prop getter should be called with active and selected boolean props when spread.

const {getItemProps} = useInteractions([]);
 
// A given item being rendered in the list
<div
  {...getItemProps({
    active: boolean, // activeIndex === itemIndex
    selected: boolean, // selectedIndex === itemIndex
  })}
/>;

这些 props 源自 useListNavigation 和 useTypeahead Hook 的 activeIndex 和 selectedIndex 状态。

¥These props are derived from the activeIndex and selectedIndex states for the useListNavigation and useTypeahead Hooks.

select

当浮动元素包含可选择的项目列表时，应使用此角色。物品会自动接收 ARIA 属性。

¥This role should be used when the floating element contains a list of items that can be selected. Items receive ARIA props automatically.

combobox

当浮动元素包含可以选择的项目列表并且还具有用于过滤列表的输入时，应使用此角色。物品会自动接收 ARIA 属性。

¥This role should be used when the floating element contains a list of items that can be selected, and also has an input for filtering the list. Items receive ARIA props automatically.

原生角色

¥Native roles

这些角色是原生 ARIA 角色，用于本质上更通用的浮动元素，直接由 aria-haspopup 属性接受。浮动元素内的项目不接收任何角色，必须显式/手动指定。

¥These roles are native ARIA roles that are used for floating elements that are more generic in nature, directly accepted by the aria-haspopup attribute. Items inside the floating elements do not receive any roles and must be explicitly/manually specified.

tooltip

此角色应用于向其所附加的参考元素添加描述的浮动元素。参考元素应该有自己的标签/文本。

¥This role should be used for floating elements that add a description to the reference element they are attached to. The reference element should have its own label/text.

dialog

这是默认角色，当浮动元素具有任意可选项内容（例如弹出框或模式对话框）时应使用。

¥This is the default role, and should be used when the floating element has arbitrary tabbable content (e.g. a popover or modal dialog).

menu

当浮动元素包含执行操作的项目列表时，应使用此角色，类似于操作系统菜单（例如“文件”>）。物品不接收属性，必须手动指定。

¥This role should be used when the floating element contains a list of items that perform an action, similar to an OS menu (e.g. File > ). Items do not receive props and must be manually specified.

listbox

当浮动元素包含可选择的项目列表时，应使用此角色。物品不接收属性，必须手动指定。

¥This role should be used when the floating element contains a list of items that can be selected. Items do not receive props and must be manually specified.

对于上面列出的原生角色，只有引用和浮动元素接收 ARIA 属性 - 如果需要，你需要手动为浮动元素内的项目提供角色，因为这些角色允许多种项目类型。

¥For the native roles listed above, only the reference and floating element receive ARIA props — you’ll need to provide roles for the items inside the floating element manually if required, since these roles allow for a wide variety of item types.

建议你阅读 WAI-ARIA 创作实践 以确保你的项目元素具有语义角色和属性，特别是当你偏离默认角色的简单性质并添加复杂逻辑时。

¥It’s recommended that you read WAI-ARIA Authoring Practices to ensure your item elements have semantic roles and attributes, especially if you’re deviating from the simple nature of the default roles and adding complex logic.