下拉菜单

DropdownMenu 以紧凑的方式显示操作列表（每个操作包含在 MenuItem、MenuItemsChoice 或 MenuGroup 中）。当用户与某个元素（按钮或图标）交互或执行特定操作后，它将以 Popover 的形式出现。

在为 Gutenberg 仓库构建时，请改用来自 @wordpress/ui 的 Menu。否则，请继续暂时使用 DropdownMenu。

结构

1. Popover：包裹 DropdownMenu 的容器组件。
2. 父级按钮：用于切换包含 DropdownMenu 的 Popover 显示的图标或按钮。
3. MenuItem：DropdownMenu 内的列表项。

设计指南

用法

何时使用 DropdownMenu

当您希望用户执行以下操作时，请使用 DropdownMenu：

• 从列表中选择一个操作或更改设置，并且
• 仅在上下文中可见可用选项。

如果您需要始终显示所有可用选项，请考虑改用 Toolbar。

正确做法
在用户与图标交互后，使用 DropdownMenu 显示操作列表。

错误做法
不要将 DropdownMenu 用于频繁使用的操作。请改用 Toolbar。

行为

通常，父级按钮应在图标或文本右侧显示三角形图标，以表明与其交互将显示 DropdownMenu。在极少数情况下，如果父级按钮通过省略号或“更多”标签直接指示还有更多内容，则可以省略该图标。

无论是否显示 DropdownMenu，父级按钮都应保持相同的视觉样式。

位置

DropdownMenu 通常应出现在父级按钮的正下方，或左下方。如果下方空间不足以显示完整的 DropdownMenu，则它可以显示在父级按钮上方。

开发指南

DropdownMenu 是一个 React 组件，用于渲染可展开的按钮菜单。其用途类似于 <select> 元素，区别在于它不维护值。相反，每个选项都表现为一个操作按钮。

用法

使用一组控件渲染 DropdownMenu：

import { DropdownMenu } from '@wordpress/components';
import {
    more,
    arrowLeft,
    arrowRight,
    arrowUp,
    arrowDown,
} from '@wordpress/icons';

const MyDropdownMenu = () => (
    <DropdownMenu
        icon={ more }
        label="Select 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' ),
            },
        ] }
    />
);

或者，指定一个返回对 DropdownMenu 有效的元素的 children 函数：MenuItem、MenuItemsChoice 或 MenuGroup。

import { DropdownMenu, MenuGroup, MenuItem } from '@wordpress/components';
import { more, arrowUp, arrowDown, trash } from '@wordpress/icons';

const MyDropdownMenu = () => (
    <DropdownMenu icon={ more } label="Select a direction">
        { ( { onClose } ) => (
            <>
                <MenuGroup>
                    <MenuItem icon={ arrowUp } onClick={ onClose }>
                        Move Up
                    </MenuItem>
                    <MenuItem icon={ arrowDown } onClick={ onClose }>
                        Move Down
                    </MenuItem>
                </MenuGroup>
                <MenuGroup>
                    <MenuItem icon={ trash } onClick={ onClose }>
                        Remove
                    </MenuItem>
                </MenuGroup>
            </>
        ) }
    </DropdownMenu>
);

属性

该组件接受以下 props：

icon: string | null

要在折叠菜单按钮中显示的 Dashicon 图标 slug。

• 必填：否
• 默认值："menu"

另见：https://developer.wordpress.org/resource/dashicons/

label: string

作为聚焦状态下折叠菜单按钮的可访问性文本呈现的人类可读标签。

• 必填：是

controls: DropdownOption[] | DropdownOption[][]

描述要在展开菜单中显示的选项的对象数组或嵌套数组。

每个对象应包含 icon Dashicon slug 字符串、人类可读的 title 字符串、isDisabled 布尔标志以及在选择选项时调用的 onClick 函数回调。

有效的 DropdownMenu 必须指定 controls 或 children 属性，或两者兼有。
– 必填：否

children: ( callbackProps: DropdownCallbackProps ) => ReactNode

一个 函数渲染属性，应返回对 DropdownMenu 有效的元素：MenuItem、MenuItemsChoice 或 MenuGroup。其第一个参数是一个 props 对象，包括与 Dropdown 的 renderContent 相同的值（isOpen、onToggle、onClose）。

有效的 DropdownMenu 必须指定 controls 或 children 属性，或两者兼有。

• 必填：否

另见：https://developer.wordpress.org/resource/dashicons/

className: string

应用于下拉菜单切换元素包装器的类名。

• 必填：否

popoverProps: DropdownProps[ ‘popoverProps’ ]

popoverProps 对象的属性将作为 props 传递给嵌套的 Popover 组件。
使用此对象修改 Popover 组件可用的但尚未在 DropdownMenu 组件中暴露的 props，例如：相对于父节点设置的 position prop 的弹出方向。

• 必填：否

toggleProps: ToggleProps

toggleProps 对象的属性将作为 props 传递给内部使用的 Dropdown 组件的 renderToggle 实现中的嵌套 Button 组件。
使用此对象修改 Button 组件可用的但尚未在 DropdownMenu 组件中暴露的 props，例如：通过 tooltip prop 设置的悬停时显示的提示文本。

• 必填：否

menuProps: NavigableContainerProps

menuProps 对象的属性将作为 props 传递给内部使用的 Dropdown 组件的 renderContent 实现中的嵌套 NavigableMenu 组件。
使用此对象修改 NavigableMenu 组件可用的但尚未在 DropdownMenu 组件中暴露的 props，例如：通过 orientation prop 设置的菜单方向。

• 必填：否

disableOpenOnArrowDown: boolean

在某些上下文中，可能需要禁用用于打开下拉菜单的下箭头键——例如当该键用于执行其他操作时。

• 必填：否
• 默认值：false

defaultOpen: boolean

初始渲染时下拉菜单的打开状态。当不需要控制其打开状态时使用。如果在组件首次渲染时指定了 open prop，它将被覆盖。

• 必填：否

open: boolean

受控的下拉菜单打开状态。必须与 onToggle 一起使用。

• 必填：否

onToggle: ( willOpen: boolean ) => void

当下拉菜单状态从打开变为关闭或反之调用时的回调函数。

• 必填：否