Dropdown 下拉菜单

将动作或菜单折叠到下拉菜单中。

名称	分类	说明	类型	默认值
`type`	风格	按钮类型	`ButtonType`	—
`splitButton`	风格	是否使用分割按钮	`boolean`	`false`
`maxHeight`	风格	菜单最大高度，超出后可滚动	`number \| string`	—
`showArrow`	风格	是否显示指向触发器的像素箭头	`boolean`	`false`
`hoverColor`	风格	自定义菜单项悬停背景色	`string`	—
DropdownItem`divided`	风格	是否显示分割线	`boolean`	`false`
`size`	尺寸	按钮大小	`'large' \| 'default' \| 'small'`	`'default'`
`disabled`	状态	是否禁用	`boolean`	`false`
DropdownItem`disabled`	状态	是否禁用	`boolean`	`false`
`trigger`	行为	触发方式	`'hover' \| 'click' \| 'contextmenu'`	`'hover'`
`hideOnClick`	行为	点击后是否隐藏菜单	`boolean`	`true`
`placement`	行为	菜单位置	`Placement`	`'bottom'`
`↑ / ↓`	行为	在菜单项之间移动焦点（跳过禁用项）		—
`Enter / Space`	行为	选择当前聚焦的菜单项		—
`Escape`	行为	关闭菜单并返回焦点到触发器		—
`Home / End`	行为	跳到第一个/最后一个可用菜单项		—
`items`	内容	菜单项	`DropdownItemProps[]`	—
DropdownItem`command`	内容	指令	`string \| number`	—
DropdownItem`label`	内容	显示文本	`string \| VNode`	—
DropdownItem`icon`	内容	菜单项图标名称	`string`	—
`command`	事件	点击菜单项触发	`(command: string \| number) => void`	—
`visible-change`	事件	菜单显示/隐藏时触发	`(visible: boolean) => void`	—
`click`	事件	点击分割按钮左侧时触发	`(event: MouseEvent) => void`	—
`default`	插槽	触发下拉菜单的元素		—
`dropdown`	插槽	下拉菜单内容，通常是 <px-dropdown-item>		—
`open`	暴露	打开下拉菜单	`() => void`	—
`close`	暴露	关闭下拉菜单	`() => void`	—

基础用法

悬停在下拉菜单上以展开更多操作。

<template>
  <px-dropdown :items="items" @command="handleCommand">
    <px-button>
      Dropdown Menu <px-icon icon="chevron-down" style="margin-left: 4px" />
    </px-button>
  </px-dropdown>
</template>

<script setup lang="ts">
import { PxMessage } from 'sakana-element';

const items = [
  { label: 'Action 1', command: 'a' },
  { label: 'Action 2', command: 'b' },
  { label: 'Action 3', command: 'c' },
  { label: 'Action 4', command: 'd', divided: true },
];

const handleCommand = (command: string) => {
  PxMessage.info(`Command: ${command}`);
};
</script>

触发方式

可以配置点击或悬停触发。

<template>
  <div class="demo-dropdown">
    <px-dropdown :items="items" trigger="hover">
      <px-button>Hover</px-button>
    </px-dropdown>
    <px-dropdown :items="items" trigger="click">
      <px-button>Click</px-button>
    </px-dropdown>
  </div>
</template>

<script setup lang="ts">
const items = [
  { label: 'Action 1', command: 'a' },
  { label: 'Action 2', command: 'b' },
  { label: 'Action 3', command: 'c' },
];
</script>

<style scoped>
.demo-dropdown {
  display: flex;
  gap: 12px;
}
</style>

分割按钮

可以使用 split-button 来拆分下拉菜单按钮。

<template>
  <px-dropdown :items="items" split-button type="primary" trigger="click" @click="handleClick" @command="handleCommand">
    Actions
  </px-dropdown>
</template>

<script setup lang="ts">
import { PxMessage } from 'sakana-element';

const items = [
  { label: 'Action 1', command: 'a' },
  { label: 'Action 2', command: 'b' },
  { label: 'Action 3', command: 'c' },
];

const handleClick = () => {
  PxMessage.info('Button clicked');
};

const handleCommand = (command: string) => {
  PxMessage.info(`Command: ${command}`);
};
</script>

禁用项

使用 disabled 属性禁用某些选项。

<template>
  <px-dropdown :items="items" @command="handleCommand">
    <px-button>
      Dropdown <px-icon icon="chevron-down" style="margin-left: 4px" />
    </px-button>
  </px-dropdown>
</template>

<script setup lang="ts">
import { PxMessage } from 'sakana-element';

const items = [
  { label: 'Action 1', command: 'a' },
  { label: 'Action 2 (disabled)', command: 'b', disabled: true },
  { label: 'Action 3', command: 'c' },
  { label: 'Action 4 (disabled)', command: 'd', disabled: true },
];

const handleCommand = (command: string) => {
  PxMessage.info(`Command: ${command}`);
};
</script>

图标菜单项

使用 icon 属性可以在菜单项标签旁显示像素图标。

<template>
  <px-dropdown :items="items" @command="handleCommand">
    <px-button>
      Icon Menu <px-icon icon="chevron-down" style="margin-left: 4px" />
    </px-button>
  </px-dropdown>
</template>

<script setup lang="ts">
import { PxMessage } from 'sakana-element';

const items = [
  { label: 'Edit', command: 'edit', icon: 'edit' },
  { label: 'Search', command: 'search', icon: 'search' },
  { label: 'Bookmark', command: 'bookmark', icon: 'bookmark' },
  { label: 'Delete', command: 'delete', icon: 'trash', divided: true },
];

const handleCommand = (command: string) => {
  PxMessage.info(`Command: ${command}`);
};
</script>

最大高度

使用 max-height 限制菜单项过多时的菜单高度。

<template>
  <px-dropdown :items="items" :max-height="200" @command="handleCommand">
    <px-button>
      Long Menu <px-icon icon="chevron-down" style="margin-left: 4px" />
    </px-button>
  </px-dropdown>
</template>

<script setup lang="ts">
import { PxMessage } from 'sakana-element';

const items = Array.from({ length: 20 }, (_, i) => ({
  label: `Action ${i + 1}`,
  command: `action-${i + 1}`,
}));

const handleCommand = (command: string) => {
  PxMessage.info(`Command: ${command}`);
};
</script>

箭头

使用 show-arrow 显示从下拉面板指向触发器的像素风格箭头。

<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap">
    <px-dropdown :items="items" show-arrow @command="handleCommand">
      <px-button>
        Bottom (default) <px-icon icon="chevron-down" style="margin-left: 4px" />
      </px-button>
    </px-dropdown>

    <px-dropdown :items="items" show-arrow placement="right" @command="handleCommand">
      <px-button>
        Right <px-icon icon="chevron-down" style="margin-left: 4px" />
      </px-button>
    </px-dropdown>

    <px-dropdown :items="items" show-arrow placement="top" @command="handleCommand">
      <px-button>
        Top <px-icon icon="chevron-down" style="margin-left: 4px" />
      </px-button>
    </px-dropdown>
  </div>
</template>

<script setup lang="ts">
import { PxMessage } from 'sakana-element';

const items = [
  { label: 'Action 1', command: 'a' },
  { label: 'Action 2', command: 'b' },
  { label: 'Action 3', command: 'c' },
];

const handleCommand = (command: string) => {
  PxMessage.info(`Command: ${command}`);
};
</script>

自定义悬停颜色

使用 hover-color 自定义菜单项悬停时的背景色。

<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap">
    <px-dropdown :items="items" hover-color="#22c55e" @command="handleCommand">
      <px-button>
        Green <px-icon icon="chevron-down" style="margin-left: 4px" />
      </px-button>
    </px-dropdown>

    <px-dropdown :items="items" hover-color="#ef4444" @command="handleCommand">
      <px-button>
        Red <px-icon icon="chevron-down" style="margin-left: 4px" />
      </px-button>
    </px-dropdown>

    <px-dropdown :items="items" hover-color="#f59e0b" @command="handleCommand">
      <px-button>
        Amber <px-icon icon="chevron-down" style="margin-left: 4px" />
      </px-button>
    </px-dropdown>
  </div>
</template>

<script setup lang="ts">
import { PxMessage } from 'sakana-element';

const items = [
  { label: 'Action 1', command: 'a' },
  { label: 'Action 2', command: 'b' },
  { label: 'Action 3', command: 'c' },
  { label: 'Action 4', command: 'd', divided: true },
];

const handleCommand = (command: string) => {
  PxMessage.info(`Command: ${command}`);
};
</script>

键盘导航

下拉菜单支持完整的键盘导航。按方向键在菜单项之间移动，Enter 选择，Escape 关闭。

<template>
  <px-dropdown :items="items" trigger="click" @command="handleCommand">
    <px-button>
      Click &amp; Navigate <px-icon icon="chevron-down" style="margin-left: 4px" />
    </px-button>
  </px-dropdown>
</template>

<script setup lang="ts">
import { PxMessage } from 'sakana-element';

const items = [
  { label: 'Home', command: 'home', icon: 'home' },
  { label: 'Edit', command: 'edit', icon: 'edit' },
  { label: 'Disabled', command: 'disabled', disabled: true },
  { label: 'Search', command: 'search', icon: 'search' },
  { label: 'Settings', command: 'settings', icon: 'sliders', divided: true },
];

const handleCommand = (command: string) => {
  PxMessage.info(`Selected: ${command}`);
};
</script>

Dropdown 下拉菜单 ​

基础用法 ​

触发方式 ​

分割按钮 ​

禁用项 ​

图标菜单项 ​

最大高度 ​

箭头 ​

自定义悬停颜色 ​

键盘导航 ​