Gutenberg 组件库中的 ToolbarDropdownMenu让工具栏内的下拉菜单遵循 WAI-ARIA 键盘交互模式【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本文围绕 WordPress Gutenberg 仓库中wordpress/components包的ToolbarDropdownMenu组件展开覆盖它的完整用法独立工具栏与块编辑器BlockControls两种场景、全部 Props API并结合 组件源码 与 Toolbar 容器实现 解释它为什么比直接使用DropdownMenu更“贴合工具栏键盘规范”。读完本文你将能在 Gutenberg 界面开发中正确选型并落地该组件并理解其与 Ariakit Toolbar Store、ToolbarContext的协作机制。组件定位DropdownMenu 的“工具栏版本”ToolbarDropdownMenu用于向工具栏Toolbar中添加一组动作通常渲染在 Toolbar 或 ToolbarGroup 内部用于构建通用界面。官方文档组件 README给出的选型建议是如果你是在为自定义块添加工具栏控件应优先通过 BlockControls 来挂载见下文示例它的功能与 DropdownMenu 组件基本相同核心差异在于把ToolbarDropdownMenu放进工具栏后键盘交互会自动与 WAI-ARIA toolbar 模式工具栏的无障碍键盘导航规范保持一致而不是以普通下拉菜单的方式响应按键。这一差异不是 CSS 层面的而是由组件源码中的条件渲染逻辑实现的下面先给出用法再回到源码拆解。基本用法渲染在 Toolbar 中构建通用界面时推荐将ToolbarDropdownMenu渲染在Toolbar组件内。完整示例继承自组件 READMEimport { Toolbar, ToolbarDropdownMenu } from wordpress/components; import { more, arrowLeft, arrowRight, arrowUp, arrowDown, } from wordpress/icons; function MyToolbar() { return ( Toolbar labelOptions ToolbarDropdownMenu icon{ more } labelSelect a direction controls{ [ { title: Up, icon: arrowUp, onClick: () console.log( up ), }, { title: Right, icon: arrowRight, onClick: () console.log( right ), }, { title: Down, icon: arrowDown, onClick: () console.log( down ), }, { title: Left, icon: arrowLeft, onClick: () console.log( left ), }, ] } / /Toolbar ); }几个值得注意的使用要点Toolbar必须提供label。从 Toolbar 源码 可以看到若不传label自 5.6 版本起会触发deprecated警告并退化为渲染ToolbarGroup——因此新代码请始终显式传入labellabel同时会作为aria-label挂在底层Ariakit.Toolbar节点上见 toolbar-container.tsx是屏幕阅读器识别该工具栏的唯一依据controls数组中每一项的title是菜单项文案onClick在选项被选中时触发完整字段说明见下文 Props 部分。块编辑器场景放在 BlockControls 中如果你正在开发自定义块希望往块工具栏里加一组动作官方建议通过BlockControls挂载ToolbarDropdownMenuimport { BlockControls } from wordpress/block-editor; import { Toolbar, ToolbarDropdownMenu } from wordpress/components; import { more, arrowLeft, arrowRight, arrowUp, arrowDown, } from wordpress/icons; function Edit() { return ( BlockControls groupblock ToolbarDropdownMenu icon{ more } labelSelect a direction controls{ [ { title: Up, icon: arrowUp, onClick: () console.log( up ), }, { title: Right, icon: arrowRight, onClick: () console.log( right ), }, { title: Down, icon: arrowDown, onClick: () console.log( down ), }, { title: Left, icon: arrowLeft, onClick: () console.log( left ), }, ] } / /BlockControls ); }BlockControls会将子节点投射到块编辑器的工具栏插槽中因此这里的ToolbarDropdownMenu依然处于Toolbar语义环境内享受相同的键盘导航行为。源码解析为什么它能自动适配工具栏键盘规范ToolbarDropdownMenu的实现非常精炼全部逻辑在 index.tsx 中function UnforwardedToolbarDropdownMenu( props: DropdownMenuProps, ref: ForwardedRef any ) { const accessibleToolbarState useContext( ToolbarContext ); if ( ! accessibleToolbarState ) { return DropdownMenu { ...props } /; } // ToolbarItem will pass all props to the render prop child, which will pass // all props to the toggle of DropdownMenu. This means that ToolbarDropdownMenu // has the same API as DropdownMenu. return ( ToolbarItem ref{ ref } { ...props.toggleProps } { ( toolbarItemProps ) ( DropdownMenu { ...props } popoverProps{ { ...props.popoverProps, } } toggleProps{ toolbarItemProps } / ) } /ToolbarItem ); }从源码结构看它的工作机制分三层1. 无工具栏上下文时的降级直接渲染 DropdownMenu组件首先通过useContext( ToolbarContext )读取工具栏状态。ToolbarContext 是一个存放Ariakit.ToolbarStore | undefined的 React Context。当取不到 store即组件没有渲染在任何Toolbar内部时直接返回一个普通DropdownMenu { ...props } /。这意味着ToolbarDropdownMenu在任意位置都能渲染不会报错只是失去了工具栏键盘规范这一增强特性。2. 有工具栏上下文时借用 ToolbarItem 注入 ARIA 角色当存在 store 时组件用 ToolbarItem 包裹菜单ToolbarItem是 headless 组件内部渲染Ariakit.ToolbarItem并把 store 传入见 toolbar-item/index.tsx。Ariakit 的 Toolbar 体系负责实现 WAI-ARIA toolbar 模式的键盘语义左右方向键在工具栏各项之间移动焦点、聚焦工具栏项时按 Enter/空格/ArrowDown 打开菜单等ToolbarDropdownMenu通过render prop拿到toolbarItemProps包含 ARIA 关联属性如aria-controls、aria-haspopup等再把它作为toggleProps传给内层DropdownMenu最终落到切换按钮Button上。源码中的注释明确说明了这一设计意图正因为 ToolbarItem 会把 props 一路透传到 DropdownMenu 的 toggleToolbarDropdownMenu才与DropdownMenu保持完全一致的 API。3. store 由 Toolbar 容器创建并自动感知 RTLstore 本身由 ToolbarContainer 创建const toolbarStore Ariakit.useToolbarStore( { focusLoop: true, rtl: isRTL(), } );focusLoop: true使焦点在工具栏首尾之间循环符合 toolbar 模式的键盘行为rtl从wordpress/i18n的isRTL()读取保证阿拉伯语、希伯来语等 RTL 语言环境下方向键语义依然正确。另外Toolbar 组件 还会通过ContextSystemProvider向下级联DropdownMenu: { variant: toolbar }的样式上下文使工具栏内的下拉菜单采用适配工具栏的视觉变体DropdownMenuInternalContext中定义了variant?: toolbar见 dropdown-menu/types.ts如果显式给Toolbar传了variant如variantunstyled该上下文置空、由 variant 类名is-${variant}控制外观。Props 完整参考ToolbarDropdownMenu接受与 DropdownMenu 完全相同的 API组件入参类型即DropdownMenuProps定义于 dropdown-menu/types.tsProp类型必填说明labelstring是折叠状态按钮的无障碍文本同时是菜单的触发按钮描述iconIconProps[icon] \| null否折叠按钮显示的图标默认menucontrolsDropdownOption[] \| DropdownOption[][]否*菜单项数组嵌套数组表示分组children(callbackProps) ReactNode否*render prop返回MenuItem/MenuItemsChoice/MenuGroup回调参数含isOpen、onToggle、onCloseclassNamestring否应用于切换按钮容器的类名popoverPropsDropdownProps[popoverProps]否透传给内部Popover如控制弹出方向positiontogglePropsToggleProps否透传给内部Button如设置 tooltip在ToolbarDropdownMenu中会与工具栏项属性合并menuPropsNavigableMenuProps不含 children否透传给内部NavigableMenu如菜单朝向orientationdisableOpenOnArrowDownboolean否禁用 ArrowDown 打开菜单当该键被占用时默认falsetextstring否显示在切换按钮上的文本noIconsboolean否是否给菜单添加no-icons类名隐藏图标openboolean否受控的展开状态需与onToggle配合defaultOpenboolean否非受控的初始展开状态首次渲染时会被open覆盖onToggle(willOpen: boolean) void否展开状态变化回调*controls与children至少指定一个也可以同时提供。其中controls的每一项为DropdownOptiontypes.ts字段类型说明titlestring菜单项文案必填icon图标菜单项图标可选isDisabledboolean是否禁用默认falseonClick(event?) void选中时的回调isActiveboolean该项是否处于激活状态labelstring内部按钮 tooltip 文本roleHTML role 字符串覆盖菜单项 HTML 元素的 role需要特别注意的是在工具栏场景下你传给ToolbarDropdownMenu的toggleProps会先被解构到外层ToolbarItem上见源码ToolbarItem ref{ ref } { ...props.toggleProps }同时 ToolbarItem 的 render prop 输出会再覆盖toggleProps——因此工具栏相关的 ARIA 属性由框架接管你传入的tooltip、className等普通 Button 属性不受影响。测试与验证参考仓库内的 jsdom 测试验证了工具栏体系的基础渲染与无障碍角色toolbar/test/index.jsdom.test.tsx 中通过screen.getByRole( toolbar )断言工具栏角色存在并通过getByLabelText验证每个ToolbarButton的无障碍标签可用。你可以在 该测试目录 下查看toolbar-group等相关测试了解工具栏组件族的断言方式。小结ToolbarDropdownMenu对外暴露与DropdownMenu完全一致的 API可直接替换使用放在Toolbar内时它借助ToolbarContext中的 Ariakit Toolbar Store 与ToolbarItem自动获得符合 WAI-ARIA toolbar 模式的键盘导航放在工具栏外则降级为普通DropdownMenu自定义块的控件请经由BlockControls挂载Toolbar必须传label否则自 5.6 起会收到废弃警告。更多组件说明可继续查阅 Toolbar README、ToolbarGroup README 与 DropdownMenu README。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考