下拉框 - Semi Design Next

代码演示

如何引入

import { Dropdown } from '@fibrous/semi-ui-react';

基本用法

在 Dropdown 的 children 中为它的 Trigger 触发器：默认为 hover 展示，可通过 props.trigger 修改为 click、custom、contextMenu等值指定不同触发方式
通过 render 指定下拉框的具体内容：使用 Dropdown.Menu 作为父容器，组合使用 Dropdown.Item、Dropdown.Divider、Dropdown.Title 。
当然简单场景你也可以仅搭配 Dropdown.Menu 与 Dropdown.Item，其他元素不是必须的。
Dropdown.Item 通过设置 disabled 可以禁用某个选项，配置 type，可以展示不同颜色的文本，上设置 icon 可以快速配置图标。更复杂的自定义结构，你可以通过 children 传入 ReactNode自定义渲染

代码

import { IconBox, IconSetting, IconForward, IconRefresh, IconSearch, IconAlertCircle } from '@fibrous/semi-icons-react';
import { IconToken } from '@fibrous/semi-icons-react/lab';
import { Dropdown, Button, HotKeys } from '@fibrous/semi-ui-react';

export default function DropdownDemo() {
    return (
        <Dropdown
            position="bottomLeft"
            render={
                <Dropdown.Menu>
                    <Dropdown.Title>分组1</Dropdown.Title>
                    <Dropdown.Item icon={<IconBox />}>
                        Menu Item 1
                        <HotKeys style={{ marginLeft: 20 }} hotKeys={[HotKeys.Keys.Control, HotKeys.Keys.B]} content={['Ctrl', 'B']} />
                    </Dropdown.Item>
                    <Dropdown.Item icon={<IconSetting />}>
                        Menu Item 2
                        <HotKeys style={{ marginLeft: 20 }} hotKeys={[HotKeys.Keys.Control, HotKeys.Keys.V]} content={['Ctrl', 'V']} />
                    </Dropdown.Item>
                    <Dropdown.Item disabled icon={<IconForward />}>
                        Menu Item 3
                        <HotKeys style={{ marginLeft: 20 }} hotKeys={[HotKeys.Keys.Control, HotKeys.Keys.F3]} content={['Ctrl', 'F3']} />
                    </Dropdown.Item>
                    <Dropdown.Divider />
                    <Dropdown.Title>分组2</Dropdown.Title>
                    <Dropdown.Item type="tertiary" icon={<IconRefresh />}>
                        tertiary
                    </Dropdown.Item>
                    <Dropdown.Item type="warning" icon={<IconSearch />}>
                        warning
                    </Dropdown.Item>
                    <Dropdown.Item type="danger" icon={<IconAlertCircle />}>
                        danger
                    </Dropdown.Item>
                </Dropdown.Menu>
            }
        >
            <Button theme="outline" type="tertiary" icon={<IconToken />}>
                Hover Me
            </Button>
        </Dropdown>
    );
}

嵌套使用

用户可以对 Dropdown 进行嵌套使用，此类情况适合具有多个子级选项的情况。键盘上 右箭头 打开子菜单、左箭头 回到父项，Enter 或 Space 触发任意层菜单项的 onClick（详见 Accessibility）。

代码

import { useMemo } from 'react';
import { IconToken } from '@fibrous/semi-icons-react/lab';
import { Dropdown, Button, Toast } from '@fibrous/semi-ui-react';

export default function DropdownDemo() {
    // Enter and Space trigger a submenu item's onClick too
    const subDropdown = useMemo(
        () => (
            <Dropdown.Menu>
                {[1, 2, 3].map((n) => (
                    <Dropdown.Item key={n} onClick={() => Toast.info({ content: `点击了 Nested Menu Item ${n}` })}>
                        Nested Menu Item {n}
                    </Dropdown.Item>
                ))}
            </Dropdown.Menu>
        ),
        []
    );

    return (
        <div style={{ margin: 100 }}>
            <Dropdown
                render={
                    <Dropdown.Menu>
                        <Dropdown position="rightTop" render={subDropdown}>
                            <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        </Dropdown>
                        <Dropdown position="leftTop" render={subDropdown}>
                            <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        </Dropdown>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Button theme="outline" type="tertiary" icon={<IconToken />}>
                    Hover Me
                </Button>
            </Dropdown>
        </div>
    );
}

弹出位置

支持的位置同 Tooltip，常用的是："bottom", "bottomLeft", "bottomRight" 这三种。

Bottom

bottomLeft

bottomRight

代码

import { Dropdown, Tag } from '@fibrous/semi-ui-react';

export default function DropdownDemo() {
    return (
        <div>
            <Dropdown
                position="bottom"
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Tag>Bottom</Tag>
            </Dropdown>
            <br />
            <br />
            <Dropdown
                position="bottomLeft"
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Tag>bottomLeft</Tag>
            </Dropdown>
            <br />
            <br />
            <Dropdown
                position="bottomRight"
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Tag>bottomRight</Tag>
            </Dropdown>
        </div>
    );
}

触发方式

默认是移入触发，可通过获取焦点(focus)，点击(click)或自定义事件触发菜单展开。
contextMenu 方式右键打开菜单后焦点会移到第一个可用项。

Hover me

Please use Tab to focus this div

代码

import { Dropdown, Tag, Button } from '@fibrous/semi-ui-react';

export default function DropdownDemo() {
    return (
        <div>
            <Dropdown
                trigger="hover"
                position="bottomLeft"
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Tag>Hover me</Tag>
            </Dropdown>
            <br />
            <br />
            <Dropdown
                trigger="focus"
                position="bottomLeft"
                render={
                    <Dropdown.Menu tabIndex={-1}>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <div
                    style={{
                        border: '1px solid var(--semi-color-border)',
                        borderRadius: 4,
                        height: 36,
                        width: 220,
                    }}
                >
                    Please use Tab to focus this div
                </div>
            </Dropdown>
            <br />
            <br />
            <Dropdown
                trigger="click"
                position="bottomLeft"
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Button>Click me</Button>
            </Dropdown>
            <br />
            <br />
            <Dropdown
                trigger="contextMenu"
                position="bottomRight"
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Button theme="solid" type="secondary" style={{ marginBottom: 20 }}>
                    Right click (ContextMenu)
                </Button>
            </Dropdown>
        </div>
    );
}

触发事件

点击菜单项后可触发不同鼠标事件，支持 onClick，onMouseEnter， onMouseLeave 和 onContextMenu。

代码

import { IconToken } from '@fibrous/semi-icons-react/lab';
import { Dropdown, Button, Toast } from '@fibrous/semi-ui-react';

export default function DropdownDemo() {
    return (
        <Dropdown
            trigger="click"
            position="bottomLeft"
            render={
                <Dropdown.Menu>
                    <Dropdown.Item onClick={() => Toast.info({ content: 'You clicked me!' })}>1: click me!</Dropdown.Item>
                    <Dropdown.Item onMouseEnter={() => Toast.info({ content: 'Nice to meet you!' })}>2: mouse enter</Dropdown.Item>
                    <Dropdown.Item onMouseLeave={() => Toast.info({ content: 'See ya!' })}>3: mouse leave</Dropdown.Item>
                    <Dropdown.Item onContextMenu={() => Toast.info({ content: 'Right clicked!' })}>4: right click</Dropdown.Item>
                </Dropdown.Menu>
            }
        >
            <Button theme="outline" type="tertiary" icon={<IconToken />}>
                Click Me
            </Button>
        </Dropdown>
    );
}

Json 用法

可以通过 menu 属性，传入 JSON Array 快速配置出下拉框菜单

代码

import { IconToken } from '@fibrous/semi-icons-react/lab';
import { Dropdown, Button, type DropDownMenuItem } from '@fibrous/semi-ui-react';

export default function DropdownDemo() {
    const menu: DropDownMenuItem[] = [
        { node: 'title', name: '分组1' },
        { node: 'item', name: 'primary1', type: 'primary', onClick: () => console.log('click primary') },
        { node: 'item', name: 'secondary', type: 'secondary' },
        { node: 'divider' },
        { node: 'title', name: '分组2' },
        { node: 'item', name: 'tertiary', type: 'tertiary' },
        { node: 'item', name: 'warning', type: 'warning', active: true },
        { node: 'item', name: 'danger', type: 'danger' },
    ];
    return (
        <Dropdown trigger="click" showTick position="bottomLeft" menu={menu}>
            <Button theme="outline" type="tertiary" icon={<IconToken />}>
                Click Me
            </Button>
        </Dropdown>
    );
}

API 参考

Props

属性	说明	类型	默认值
afterClose	菜单关闭且离场动画结束后调用。	`Type`	-
afterOpen	菜单打开且进场动画结束后调用；没有进场动画时打开后即调用；进场结束前被关闭的打开不调用。	`Type`	-
aria-label	弹出层 `role` 为 `dialog` 时的 `aria-label`。	`string`	-
aria-labelledby	弹出层 `role` 为 `dialog` 时的 `aria-labelledby`。	`string`	-
arrowPointAtCenter	箭头是否指向触发元素的中心，只在 `showArrow` 为 `true` 时生效，默认 `true`。	`boolean`	-
autoAdjustOverflow	弹出层被遮挡时是否自动调整方向，默认 `true`。	`boolean`	-
children	触发元素。传入单个元素时由它接收触发事件与 ARIA 属性；文本或多个节点由 `span` 包裹后作为触发元素。	`React.ReactNode`	-
className	弹出层外层 `.semi-dropdown-wrapper` 的类名。	`string`	-
clickToHide	在弹出层内点击时是否自动关闭弹出层，默认 `false`。	`boolean`	-
clickTriggerToHide	点击触发元素时是否关闭已打开的菜单。	`boolean`	-
closeOnEsc	在触发元素或弹出层按 Esc 是否关闭菜单。`trigger` 为 `custom` 时只调用 `onEscKeyDown`，由使用方决定是否关闭。	`TooltipProps['closeOnEsc']`	`true`
condition	是否允许触发显示，默认 `true`；仅显式设为 `false` 时，hover、click、focus 等触发行为不生效，`trigger` 为 `custom` 时仍按 `visible` 显示。由 `true` 变为 `false` 时立即关闭已显示的菜单。	`boolean`	-
content	由 Dropdown 固定为菜单内容，传入的值无效；菜单内容请使用 `render` 或 `menu`。	`React.ReactNode \| RenderContent`	-
contentClassName	下拉菜单容器 `.semi-dropdown` 的类名。	`string \| any[]`	-
disableArrowKeyDown	由 Dropdown 固定为 `true`，方向键由 Dropdown 自行处理，传入的值无效。	`boolean`	-
disableFocusListener	`trigger` 为 `hover` 时，是否不响应键盘聚焦打开菜单，默认 `false`。	`boolean`	-
guardFocus	焦点位于弹出层内时，Tab 是否在弹出层内循环，默认 `false`。	`boolean`	-
keepDOM	关闭时是否保留菜单的 DOM 而不销毁，默认 `false`。	`boolean`	-
menu	通过数据快速配置菜单，数据项为 `node` 为 `item`、`title` 或 `divider` 的对象，见下方 DropdownMenuItem；提供 `render` 时以 `render` 为准。	`DropDownMenuItem[]`	-
motion	是否展示弹出层的进出场动画。	`boolean`	`true`
mouseEnterDelay	指针移入触发元素后延迟显示的毫秒数，默认 `50`，仅 `trigger` 为 `hover` 或 `focus` 时生效。	`number`	-
mouseLeaveDelay	指针移出弹出层后延迟隐藏的毫秒数，仅 `trigger` 为 `hover` 或 `focus` 时生效。	`number`	`100`
onClickOutSide	按下触发元素与弹出层以外的区域时调用，参数是原生 `MouseEvent`。仅 `trigger` 为 `click`、`contextMenu`、`custom` 或开启 `clickTriggerToHide` 时生效。	`Type`	-
onEscKeyDown	菜单打开期间按 Esc 时调用，参数是原生 `KeyboardEvent`。	`TooltipProps['onEscKeyDown']`	-
onOpen	菜单显示、进场动画开始时调用，每次打开调用一次，早于 `afterOpen`；悬停打开后指针已离开而撤回的打开不调用。	`Type`	-
onVisibleChange	菜单显示状态变化时调用，参数为 `visible`。`visible` 受控时只报告用户交互发起的请求，使用方自己改变 `visible` 不调用。	`Type`	-
position	弹出菜单相对触发元素的位置，常用 `bottom`、`bottomLeft`、`bottomRight`，更多见 Tooltip 的位置。	`Position`	`"bottom"`
prefixCls	弹出层类名前缀。	`string`	`"semi-dropdown"`
preventScroll	聚焦时是否阻止浏览器滚动到被聚焦元素，默认 `false`。	`boolean`	-
ref	挂载时接收 `DropdownHandle`，卸载时为 `null`。	`Type`	-
render	弹出层的内容，由 `Dropdown.Menu` 及 `Dropdown.Item`、`Dropdown.Title`、`Dropdown.Divider` 构成。传入时优先于 `menu`。	`React.ReactNode`	-
returnFocusOnClose	菜单关闭后焦点是否回到触发元素，默认 `true`。	`boolean`	-
role	包裹菜单的弹层容器的 ARIA role，默认 `presentation`；菜单本身的 role 为 `menu`。	`string`	-
selectionMode	本层菜单项的选择方式，已选项由 `active` 标记：`single` 时菜单项为带 `aria-checked` 的 `menuitemradio`，`multiple` 时为带 `aria-checked` 的 `menuitemcheckbox`；未设置时 `showTick` 开启则为带 `aria-checked` 的 `menuitemcheckbox`，否则为 `menuitem`。只影响角色与状态，勾的显示仍由 `showTick` 决定；嵌套的子菜单不继承。	`DropdownSelectionMode`	-
showArrow	是否显示箭头，默认 `false`。	`boolean \| React.ReactNode`	-
showTick	是否在 `active` 的 `Dropdown.Item` 左侧展示表示选中的勾；只作用于本 Dropdown 的菜单，嵌套的子菜单不继承。	`boolean`	`false`
spacing	弹出层与触发元素的距离，单位为像素；缺省时顶层菜单为 `4`，嵌套的子菜单为 `2`。	`number \| { x: number; y: number }`	-
stopPropagation	是否阻止弹出层上的 click、mousedown 与焦点进出事件冒泡，默认 `false`。	`boolean`	-
style	下拉菜单容器 `.semi-dropdown` 的内联样式。	`React.CSSProperties`	-
trigger	触发菜单显示的行为，可选 `hover`、`focus`、`click`、`custom`、`contextMenu`；`custom` 时显示与否完全由 `visible` 决定。	`Trigger`	`"hover"`
visible	菜单是否显示。配合 `trigger` 为 `custom` 使用；传入后由该值决定显示，触发器、点击外部与 Esc 只通过 `onVisibleChange` 请求打开或关闭。	`boolean`	-
wrapperClassName	触发元素被 `span` 包裹时，该 `span` 的类名。	`string`	-
wrapperId	弹出层节点的 id，触发元素的 ARIA 属性指向它；缺省时自动生成。	`string`	-
wrapWhenSpecial	触发元素为禁用或加载中的 Button 等特殊触发器时，是否在外层包裹 `span` 以保证触发行为，默认 `true`。	`boolean`	-

Methods

方法	说明	类型
focusTrigger	让触发元素获得焦点，仅在 `returnFocusOnClose` 为 `true` 且 `trigger` 不是 `custom` 时生效。	`Type`
rePosition	按触发器当前位置立即重新计算弹出层位置。弹出层已随滚动、窗口尺寸变化、触发器移动以及触发器或弹出层的尺寸变化自动重新定位，一般无需调用；跟随触发器移动会晚一帧，需要同一帧内对齐时调用。	`Type`

Dropdown 没有自己的根元素：className 落在弹层外层 .semi-dropdown-wrapper 上，style 与 contentClassName 落在菜单容器 .semi-dropdown 上，ref 收到 DropdownHandle，其余未声明的属性被丢弃。

Props

属性	说明	类型	默认值
children	菜单的子元素，一般为 `Dropdown.Item` 或 `Dropdown.Title`。	`React.ReactNode`	-
className	菜单 `ul` 元素的类名。	`string`	-
ref	菜单 `ul` 元素的引用。	`Type`	-
style	菜单 `ul` 元素的内联样式。	`CSSProperties`	-

其他原生属性（如 id、aria-*）落在菜单的 ul 上；role 与 aria-orientation 可以被覆盖，onKeyDown 先于内置的键盘处理执行。

Props

属性	说明	类型	默认值
active	当前项是否处于激活态，激活态时字体加粗、颜色加深；展示勾时（`showTick` 为 `true`）左侧还会展示 √。	`boolean`	-
children	菜单项的内容，渲染在图标之后。	`ReactNode`	-
className	根 `li` 元素的类名。	`string`	-
disabled	是否禁用该项；禁用项不响应点击与鼠标事件，并带 `aria-disabled` 为 `true`。	`boolean`	`false`
forwardRef	根 `li` 元素挂载时以该元素调用，供包装 `Dropdown.Item` 的组件获取元素。	`Type`	-
icon	菜单项的图标，渲染在内容之前。	`React.ReactNode`	-
onClick	单击时调用，参数为 `MouseEvent`；位于嵌套子菜单内的项在鼠标左键按下时调用，键盘激活时也调用；禁用项不调用。	`Type`	-
onContextMenu	右键点击时调用。禁用项不调用。	`Type`	-
onMouseEnter	指针移入时调用。禁用项不调用。	`Type`	-
onMouseLeave	指针移出时调用。禁用项不调用。	`Type`	-
ref	根 `li` 元素的引用。	`Type`	-
showTick	仅在 Dropdown 之外使用时生效；在 Dropdown 内以 Dropdown 的 `showTick` 为准。	`boolean`	-
style	根 `li` 元素的内联样式。	`CSSProperties`	-
type	文本颜色类型，可选 `primary`、`secondary`、`tertiary`、`warning`、`danger`。	`Type`	-

其他原生属性（如 id、data-*）落在根 li 上；role、aria-checked 与 aria-disabled 由 Dropdown 决定，不能被覆盖。

Props

属性	说明	类型	默认值
children	标题的文字或内容。	`ReactNode`	-
className	根 `li` 元素的类名。	`string`	-
ref	根 `li` 元素的引用。	`Type`	-
style	根 `li` 元素的内联样式。	`CSSProperties`	-

其他原生属性（如 id、data-*）落在根 li 上，role 可以被覆盖。

DropdownMenuItem

属性	说明	类型
node	按钮类型，可选：`title`，`item`，`divider`	string
name	菜单文本，标题或 Item 的内容	string
其他属性与 Title、Item、Divider 属性对应

数据项不接受 children，标签只由 name 提供。

Methods

通过 ref 接收 DropdownHandle，挂载时收到一次，之后调用其中的 focusTrigger() 与 rePosition()，方法说明见上方 Dropdown 的 Methods 表。

Accessibility

Dropdown 按 WAI-ARIA APG 的 Menu Button 与 Menu and Menubar 模式实现。

ARIA

触发元素带 aria-haspopup="menu" 与 aria-expanded，菜单显示时 aria-expanded 为 true，否则为 false
Dropdown.Menu 的 role 为 menu，aria-orientation 为 vertical
Dropdown.Item 的 role 为 menuitem；Dropdown 的 selectionMode 为 single 时为 menuitemradio，为 multiple 或开启 showTick 时为 menuitemcheckbox，这三种情况都以 aria-checked 暴露 active；√ 图标不计入菜单项名称；禁用项带 aria-disabled="true"
作为嵌套 Dropdown 触发元素的 Dropdown.Item（父项）同样带 aria-haspopup="menu" 与 aria-expanded
Dropdown.Divider 渲染为 role="separator" 的 li，Dropdown.Title 渲染为 role="presentation" 的 li
包裹菜单的弹层容器 role 为 presentation，不是 tooltip

键盘和焦点

焦点在触发元素上时：

按键	行为
`Enter`、`Space`	trigger 为 `click` 时打开菜单，焦点移到第一个可用项
`下箭头`	菜单已打开时，焦点移到第一个可用项；触发元素是按钮（`button`、带 `href` 的链接、Semi Button 等）且菜单关闭时，打开菜单并聚焦第一个可用项
`上箭头`	菜单已打开时，焦点移到最后一个可用项；触发元素是按钮且菜单关闭时，打开菜单并聚焦最后一个可用项
`Tab`	菜单已打开时关闭菜单，焦点按浏览器默认顺序移动

render（Vue 中为 #content 插槽）中没有菜单项时，弹层打开后按 下箭头、上箭头 分别聚焦弹层中第一个、最后一个可聚焦元素。

触发元素是文本或多个节点时，Dropdown 用一个 span 包裹它们，上表按键对这个 span 同样生效。

trigger 为 hover 或 focus 时，键盘聚焦触发元素即打开菜单（disableFocusListener 可关闭），失焦后关闭。

trigger 为 contextMenu 时，右键打开菜单后焦点移到第一个可用项。

焦点在菜单项上时：

按键	行为
`下箭头`、`上箭头`	移到当前层的下一项、上一项，跳过禁用项，到首尾后循环
`Home`、`End`	移到当前层的第一项、最后一项
`Enter`、`Space`	父项：打开子菜单并把焦点移到子菜单第一项；其他项：触发 `onClick`（Vue 中为 `@click`），开启 `clickToHide` 时随后关闭菜单
`右箭头`	父项：打开子菜单并把焦点移到子菜单第一项；其他项无效果
`左箭头`	在子菜单中：关闭子菜单，焦点回到父项，与 `closeOnEsc` 无关
`Tab`	关闭全部菜单（含子菜单），焦点按浏览器默认顺序移动，不回到触发元素
`Esc`	关闭焦点所在的那一层菜单，焦点回到打开它的元素（父项或触发元素）；焦点在父项且其子菜单已打开时先关闭子菜单；`closeOnEsc` 为 false 时不关闭
字母键	移到当前层下一个以该字符开头的项

RTL（ConfigProvider direction="rtl"）下 左箭头 与 右箭头 的行为互换。
菜单项的 onKeyDown（Vue 中为 @keydown）中调用 e.preventDefault() 可以阻止 Enter、Space 触发 onClick（Vue 中为 @click）。
嵌套 Dropdown 的子菜单项由键盘激活时 onClick（Vue 中为 @click）收到的是 click 事件；鼠标操作时仍在左键按下时触发。

文案规范

下拉框内选项内容需要表述准确且包含信息，使用户在浏览时更加容易在选项中选择
使用语句式的大小写，并且简洁明了地书写选项
如果是动作选项，使用动词或者动词短语来描述用户选择该选项后会发生的动作。举个例子，"Move", "Log time", or "Hide labels"
不使用介词

✅ 推荐用法	❌ 不推荐用法

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$transition_duration-dropdown_item-bg	var(--semi-transition_duration-none)	下拉菜单项-背景颜色-动画持续时间
$transition_function-dropdown_item-bg	var(--semi-transition_function-easeOut)	下拉菜单项-背景颜色-过渡曲线
$transition_delay-dropdown_item-bg	0ms	下拉菜单项-背景颜色-延迟时间
$radius-dropdown	var(--semi-border-radius-medium)	下拉菜单圆角大小
$radius-dropdown_item	0px	下拉菜单项圆角大小
$color-dropdown-bg-default	var(--semi-color-bg-3)	下拉菜单背景颜色
$color-dropdown_title-text-default	var(--semi-color-text-2)	下拉菜单分组标题文字颜色
$spacing-dropdown_menu-paddingY	$spacing-extra-tight	下拉菜单垂直内边距
$spacing-dropdown_menu-paddingX	0	下拉菜单水平内边距
$spacing-dropdown_title-paddingTop	$spacing-tight	下拉菜单分组标题顶部内边距
$spacing-dropdown_title-paddingBottom	$spacing-extra-tight	下拉菜单分组标题底部内边距
$spacing-dropdown_title-paddingLeft	$spacing-base	下拉菜单分组标题左侧内边距
$spacing-dropdown_title-paddingRight	$spacing-base	下拉菜单分组标题右侧内边距
$spacing-dropdown_title_withTick-paddingLeft	31px	可选中的下拉菜单，分组标题左侧内边距
$spacing-dropdown_item_withTick-paddingLeft	$spacing-base-tight	可选中弄的下拉菜单项，对勾 icon 左侧内边距
$spacing-dropdown_item-paddingY	$spacing-tight	下拉菜单项垂直内边距
$spacing-dropdown_item-paddingX	$spacing-base	下拉菜单项水平内边距
$color-dropdown_item-text-default	var(--semi-color-text-0)	下拉菜单项文字颜色
$color-dropdown_item-bg-hover	var(--semi-color-fill-0)	下拉菜单项背景颜色 - 悬浮
$color-dropdown_item-bg-active	var(--semi-color-fill-1)	下拉菜单项背景颜色 - 按下
$color-dropdown_item_danger-text-default	var(--semi-color-danger)	下拉菜单项背景颜色 - 悬浮
$color-dropdown_item_secondary-text-default	var(--semi-color-secondary)	二级菜单项文字颜色
$color-dropdown_item_warning-text-default	var(--semi-color-warning)	警告菜单项文字颜色
$color-dropdown_item_tertiary-text-default	var(--semi-color-tertiary)	第三菜单项文字颜色
$color-dropdown_item_primary-text-default	var(--semi-color-primary)	主要菜单项文字颜色
$color-dropdown_item_disabled-text-default	var(--semi-color-disabled-text)	禁用菜单项文字颜色
$color-dropdown_item_disabled-bg-default	transparent	禁用菜单项背景颜色
$color-dropdown_seperator-bg-default	var(--semi-color-border)	菜单项分隔线颜色
$spacing-dropdown_icon-marginRight	9px	菜单项分隔线颜色
$spacing-dropdown_seperator-marginY	$spacing-extra-tight	菜单项分隔线垂直内边距
$spacing-dropdown_seperator-marginX	0	菜单项分隔线水平内边距
$width-dropdown	280px	菜单最大宽度
$size-dropdown-icon-width	12px	菜单项图标宽度
$height-dropdown_seperator	1px	菜单项分隔线宽度
$font-dropdown_item_active-fontWeight	600	选中菜单项字重
$filter-dropdown-bg	none

FAQ

为什么 Dropdown 浮层在靠近屏幕边界宽度不够时，丢失宽度意外换行?
在 chromium 104 后对于屏幕边界文本宽度不够时的换行渲染策略发生变化，详细原因可查看 issue #1022，semi 侧已经在 v2.17.0 版本修复了这个问题。