FxDropdown 下拉菜单

可展开的菜单，用于展示链接或操作列表。不依赖任何 UI 框架，基于 FxTooltip 浮层 + FxScrollbar 滚动 + FxBtn split-button。

基础用法

悬停在下拉菜单上展开。

<template>
  <FxDropdown>
    <span class="link">
      下拉菜单<FxIcon name="ep:arrow-down" />
    </span>
    <template #dropdown>
      <FxDropdownMenu>
        <FxDropdownItem>Action 1</FxDropdownItem>
        <FxDropdownItem>Action 2</FxDropdownItem>
        <FxDropdownItem>Action 3</FxDropdownItem>
        <FxDropdownItem disabled>Action 4</FxDropdownItem>
        <FxDropdownItem divided>Action 5</FxDropdownItem>
      </FxDropdownMenu>
    </template>
  </FxDropdown>
</template>

<style scoped>
.link {
  cursor: pointer;
  color: var(--fx-color-primary);
  display: flex;
  align-items: center;
  gap: 6px;
}
</style>

触发元素由默认 slot 渲染，下拉部分由 dropdown 具名插槽渲染。默认 hover 触发。

位置（placement）

支持 6 个位置。

<template>
  <div class="flex flex-wrap gap-4" style="padding: 60px 0">
    <FxDropdown placement="top-start">
      <FxBtn>top-start</FxBtn>
      <template #dropdown>
        <FxDropdownMenu><FxDropdownItem>1</FxDropdownItem></FxDropdownMenu>
      </template>
    </FxDropdown>
    <FxDropdown placement="top">
      <FxBtn>top</FxBtn>
      <template #dropdown>
        <FxDropdownMenu><FxDropdownItem>1</FxDropdownItem></FxDropdownMenu>
      </template>
    </FxDropdown>
    <FxDropdown placement="top-end">
      <FxBtn>top-end</FxBtn>
      <template #dropdown>
        <FxDropdownMenu><FxDropdownItem>1</FxDropdownItem></FxDropdownMenu>
      </template>
    </FxDropdown>
    <FxDropdown placement="bottom-start">
      <FxBtn>bottom-start</FxBtn>
      <template #dropdown>
        <FxDropdownMenu><FxDropdownItem>1</FxDropdownItem></FxDropdownMenu>
      </template>
    </FxDropdown>
    <FxDropdown placement="bottom">
      <FxBtn>bottom</FxBtn>
      <template #dropdown>
        <FxDropdownMenu><FxDropdownItem>1</FxDropdownItem></FxDropdownMenu>
      </template>
    </FxDropdown>
    <FxDropdown placement="bottom-end">
      <FxBtn>bottom-end</FxBtn>
      <template #dropdown>
        <FxDropdownMenu><FxDropdownItem>1</FxDropdownItem></FxDropdownMenu>
      </template>
    </FxDropdown>
  </div>
</template>

通过 placement 属性设置下拉出现位置：top / top-start / top-end / bottom / bottom-start / bottom-end。

触发元素

用按钮触发下拉列表。

<template>
  <div class="flex flex-wrap items-center gap-4">
    <FxDropdown>
      <FxBtn type="primary">
        Dropdown List<FxIcon name="ep:arrow-down" style="margin-left: 6px" />
      </FxBtn>
      <template #dropdown>
        <FxDropdownMenu>
          <FxDropdownItem>Action 1</FxDropdownItem>
          <FxDropdownItem>Action 2</FxDropdownItem>
          <FxDropdownItem>Action 3</FxDropdownItem>
          <FxDropdownItem>Action 4</FxDropdownItem>
          <FxDropdownItem>Action 5</FxDropdownItem>
        </FxDropdownMenu>
      </template>
    </FxDropdown>
    <FxDropdown split-button type="primary" @click="handleClick">
      Dropdown List
      <template #dropdown>
        <FxDropdownMenu>
          <FxDropdownItem>Action 1</FxDropdownItem>
          <FxDropdownItem>Action 2</FxDropdownItem>
          <FxDropdownItem>Action 3</FxDropdownItem>
          <FxDropdownItem divided>Action 4</FxDropdownItem>
          <FxDropdownItem>Action 5</FxDropdownItem>
        </FxDropdownMenu>
      </template>
    </FxDropdown>
  </div>
</template>

<script setup lang="ts">
import { fxMsg } from "@fx/components"
const handleClick = () => {
  fxMsg.info("主按钮点击")
}
</script>

用 split-button 将触发元素拆成按钮组：左侧普通按钮、右侧触发箭头。给某项加 divided 显示分隔线。

触发方式

点击或悬停触发。

<template>
  <div class="flex flex-wrap gap-8">
    <div>
      <span class="demonstration">hover 触发</span>
      <FxDropdown>
        <span class="link">Dropdown List <FxIcon name="ep:arrow-down" /></span>
        <template #dropdown>
          <FxDropdownMenu>
            <FxDropdownItem icon="ep:plus">Action 1</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-plus-filled">Action 2</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-plus">Action 3</FxDropdownItem>
            <FxDropdownItem icon="ep:check">Action 4</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-check">Action 5</FxDropdownItem>
          </FxDropdownMenu>
        </template>
      </FxDropdown>
    </div>
    <div>
      <span class="demonstration">click 触发</span>
      <FxDropdown trigger="click">
        <span class="link">Dropdown List <FxIcon name="ep:arrow-down" /></span>
        <template #dropdown>
          <FxDropdownMenu>
            <FxDropdownItem icon="ep:plus">Action 1</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-plus-filled">Action 2</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-plus">Action 3</FxDropdownItem>
            <FxDropdownItem icon="ep:check">Action 4</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-check">Action 5</FxDropdownItem>
          </FxDropdownMenu>
        </template>
      </FxDropdown>
    </div>
    <div>
      <span class="demonstration">右键触发</span>
      <FxDropdown trigger="contextmenu">
        <span class="link">Dropdown List <FxIcon name="ep:arrow-down" /></span>
        <template #dropdown>
          <FxDropdownMenu>
            <FxDropdownItem icon="ep:plus">Action 1</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-plus-filled">Action 2</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-plus">Action 3</FxDropdownItem>
            <FxDropdownItem icon="ep:check">Action 4</FxDropdownItem>
            <FxDropdownItem icon="ep:circle-check">Action 5</FxDropdownItem>
          </FxDropdownMenu>
        </template>
      </FxDropdown>
    </div>
  </div>
</template>

<style scoped>
.demonstration {
  display: block;
  color: var(--fx-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}

.link {
  display: flex;
  align-items: center;
  gap: 4px;
  cursor: pointer;
  color: var(--fx-color-primary);
}
</style>

用 trigger 属性，默认 hover，可选 click / contextmenu。

菜单隐藏行为（hide-on-click）

<template>
  <FxDropdown :hide-on-click="false">
    <span class="link">点击菜单项不关闭 <FxIcon name="ep:arrow-down" /></span>
    <template #dropdown>
      <FxDropdownMenu>
        <FxDropdownItem>Action 1</FxDropdownItem>
        <FxDropdownItem>Action 2</FxDropdownItem>
        <FxDropdownItem>Action 3</FxDropdownItem>
        <FxDropdownItem disabled>Action 4</FxDropdownItem>
        <FxDropdownItem divided>Action 5</FxDropdownItem>
        <FxDropdownItem divided>Action 6</FxDropdownItem>
      </FxDropdownMenu>
    </template>
  </FxDropdown>
</template>

<style scoped>
.link {
  display: flex;
  align-items: center;
  gap: 4px;
  cursor: pointer;
  color: var(--fx-color-primary);
}
</style>

默认点击菜单项后关闭，设 hide-on-click 为 false 可保持打开。

命令事件（command）

点击每个菜单项触发事件，参数由各项的 command 指定。

<template>
  <FxDropdown @command="handleCommand">
    <span class="link">查看命令输出 <FxIcon name="ep:arrow-down" /></span>
    <template #dropdown>
      <FxDropdownMenu>
        <FxDropdownItem command="a">Action 1</FxDropdownItem>
        <FxDropdownItem command="b">Action 2</FxDropdownItem>
        <FxDropdownItem command="c">Action 3</FxDropdownItem>
        <FxDropdownItem command="d" disabled>Action 4</FxDropdownItem>
        <FxDropdownItem command="e" divided>Action 5</FxDropdownItem>
      </FxDropdownMenu>
    </template>
  </FxDropdown>
</template>

<script setup lang="ts">
import { fxMsg } from "@fx/components"
const handleCommand = (command: string | number | object) => {
  fxMsg(`click on item ${command}`)
}
</script>

<style scoped>
.link {
  display: flex;
  align-items: center;
  gap: 4px;
  cursor: pointer;
  color: var(--fx-color-primary);
}
</style>

方法（methods）

手动用 open / close 打开或关闭菜单。

<template>
  <div style="font-size: 14px; margin-bottom: 12px">
    <p>打开（关闭）Dropdown List2 会关闭（打开）Dropdown List1。</p>
  </div>
  <div style="margin: 0 15px 15px 0">
    <FxBtn @click="showClick">show</FxBtn>
  </div>
  <FxDropdown ref="dropdown1" trigger="contextmenu" style="margin-right: 30px">
    <span class="link">Dropdown List1</span>
    <template #dropdown>
      <FxDropdownMenu>
        <FxDropdownItem>Action 1</FxDropdownItem>
        <FxDropdownItem>Action 2</FxDropdownItem>
        <FxDropdownItem>Action 3</FxDropdownItem>
        <FxDropdownItem disabled>Action 4</FxDropdownItem>
        <FxDropdownItem divided>Action 5</FxDropdownItem>
      </FxDropdownMenu>
    </template>
  </FxDropdown>

  <FxDropdown trigger="contextmenu" @visible-change="handleVisible2">
    <span class="link">Dropdown List2</span>
    <template #dropdown>
      <FxDropdownMenu>
        <FxDropdownItem>Action 1</FxDropdownItem>
        <FxDropdownItem>Action 2</FxDropdownItem>
        <FxDropdownItem>Action 3</FxDropdownItem>
        <FxDropdownItem disabled>Action 4</FxDropdownItem>
        <FxDropdownItem divided>Action 5</FxDropdownItem>
      </FxDropdownMenu>
    </template>
  </FxDropdown>
</template>

<script setup lang="ts">
import { ref } from "vue"
import type { FxDropdownInstance } from "@fx/components"
const dropdown1 = ref<FxDropdownInstance>()
function handleVisible2(visible: boolean) {
  if (!dropdown1.value) return
  if (visible) {
    dropdown1.value.handleClose()
  } else {
    dropdown1.value.handleOpen()
  }
}
function showClick() {
  dropdown1.value?.handleOpen()
}
</script>

<style scoped>
.link {
  cursor: pointer;
  color: var(--fx-color-primary);
}
</style>

尺寸（size）

除默认尺寸外，Dropdown 提供 large / default / small 三种额外尺寸。

<template>
  <div class="flex flex-wrap items-center gap-4">
    <FxDropdown size="large" split-button type="primary">
      Large
      <template #dropdown>
        <FxDropdownMenu>
          <FxDropdownItem>Action 1</FxDropdownItem>
          <FxDropdownItem>Action 2</FxDropdownItem>
          <FxDropdownItem>Action 3</FxDropdownItem>
          <FxDropdownItem>Action 4</FxDropdownItem>
        </FxDropdownMenu>
      </template>
    </FxDropdown>
    <FxDropdown split-button type="primary">
      Default
      <template #dropdown>
        <FxDropdownMenu>
          <FxDropdownItem>Action 1</FxDropdownItem>
          <FxDropdownItem>Action 2</FxDropdownItem>
          <FxDropdownItem>Action 3</FxDropdownItem>
          <FxDropdownItem>Action 4</FxDropdownItem>
        </FxDropdownMenu>
      </template>
    </FxDropdown>
    <FxDropdown size="small" split-button type="primary">
      Small
      <template #dropdown>
        <FxDropdownMenu>
          <FxDropdownItem>Action 1</FxDropdownItem>
          <FxDropdownItem>Action 2</FxDropdownItem>
          <FxDropdownItem>Action 3</FxDropdownItem>
          <FxDropdownItem>Action 4</FxDropdownItem>
        </FxDropdownMenu>
      </template>
    </FxDropdown>
  </div>
</template>

虚拟触发（virtual-triggering）

需要把下拉渲染到其他触发元素上时，可分离触发器与内容。

<template>
  <div
    class="content"
    style="
      display: flex;
      justify-content: center;
      align-items: center;
      height: 200px;
      background: var(--fx-bg-color);
      border: 1px solid var(--fx-border-color);
      border-radius: var(--fx-border-radius-md);
      cursor: pointer;
    "
    @click="handleClick"
    @contextmenu="handleContextmenu"
  >
    Right click
  </div>
  <FxDropdown
    ref="dropdownRef"
    :virtual-ref="triggerRef"
    :show-arrow="false"
    virtual-triggering
    trigger="contextmenu"
    placement="bottom-start"
  >
    <template #dropdown>
      <FxDropdownMenu>
        <FxDropdownItem icon="ep:plus">Action 1</FxDropdownItem>
        <FxDropdownItem icon="ep:circle-plus-filled">Action 2</FxDropdownItem>
        <FxDropdownItem icon="ep:circle-plus">Action 3</FxDropdownItem>
        <FxDropdownItem icon="ep:check">Action 4</FxDropdownItem>
        <FxDropdownItem icon="ep:circle-check">Action 5</FxDropdownItem>
      </FxDropdownMenu>
    </template>
  </FxDropdown>
</template>

<script setup lang="ts">
import { ref } from "vue"
import type { FxDropdownInstance } from "@fx/components"

const dropdownRef = ref<FxDropdownInstance>()
const position = ref({
  top: 0,
  left: 0,
  bottom: 0,
  right: 0,
  width: 0,
  height: 0,
  x: 0,
  y: 0,
  toJSON: () => {},
}) as unknown as DOMRect

const triggerRef = ref({
  getBoundingClientRect: () => position.value,
})

const handleClick = () => {
  dropdownRef.value?.handleClose()
}

const handleContextmenu = (event: MouseEvent) => {
  const { clientX, clientY } = event
  position.value = DOMRect.fromRect({ x: clientX, y: clientY } as DOMRectInit)
  event.preventDefault()
  dropdownRef.value?.handleOpen()
}
</script>

用 virtual-triggering + virtual-ref 把下拉挂到指定元素上，此时默认 slot 不再渲染。

FxDropdown API

Attributes

属性	说明	类型	默认值
type	菜单按钮类型（split-button 为 true 时生效）	'' | 'default' | 'primary' | 'success' | 'warning' | 'info' | 'danger' | 'text'	''
size	菜单尺寸（也作用于 split-button）	'' | 'large' | 'default' | 'small'	''
button-props	split-button 按钮 props	object	—
max-height	菜单最大高度	string / number	''
split-button	是否按钮组形式	boolean	false
disabled	是否禁用	boolean	false
placement	菜单位置	'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'	bottom
effect	tooltip 主题	'dark' | 'light'	light
trigger	触发方式	'click' | 'hover' | 'contextmenu' | Array<'click' | 'hover' | 'contextmenu'>	hover
trigger-keys	触发按键	string[]	['Enter','Space','ArrowDown','NumpadEnter']
virtual-triggering	是否虚拟触发	boolean	—
virtual-ref	虚拟触发参考元素	HTMLElement	—
hide-on-click	点击菜单项后是否隐藏	boolean	true
show-arrow	是否显示箭头	boolean	true
show-timeout	显示延迟（trigger 为 hover）	number	150
hide-timeout	隐藏延迟（trigger 为 hover）	number	150
role	菜单 ARIA role	'menu' | 'navigation' | …	menu
tabindex	tabindex	number / string	0
popper-class	菜单自定义类名	string / object	—
popper-style	菜单自定义样式	string / object	—
popper-options	浮层配置（仅读取 placement/strategy）	object	{}
teleported	是否 teleport 到 body	boolean	true
append-to	teleport 目标	string / HTMLElement	—
persistent	失活时是否销毁	boolean	true

Slots

插槽名	说明	子标签
default	触发器内容	—
dropdown	菜单内容，通常是 <FxDropdownMenu>	Dropdown-Menu

Events

事件名	说明	类型
click	split-button 主按钮点击	(e: MouseEvent) => void
command	菜单项点击时触发，参数为该项的 command	(...args: any[]) => void
visible-change	显隐变化（true=显示，false=隐藏）	(val: boolean) => void

Exposes

方法	说明	类型
open	打开下拉菜单	() => void
close	关闭下拉菜单	() => void
handleOpen	打开下拉菜单（open 别名）	() => void
handleClose	关闭下拉菜单（close 别名）	() => void

FxDropdownMenu API

Slots

插槽名	说明	子标签
default	菜单内容	Dropdown-Item

FxDropdownItem API

Attributes

属性	说明	类型	默认值
command	派发给 command 回调的值	string / number /	—
disabled	是否禁用	boolean	false
divided	是否显示分隔线	boolean	false
textValue	文本值（无障碍 aria-label 用）	string	—
icon	自定义图标。字符串为 IconString 类型（即 FxIcon 图标名，如 ep:edit、ant-design:home、svg:xxx），亦可传组件	string / Component	—

Slots

插槽名	说明
default	自定义菜单项内容
icon	自定义图标（覆盖 icon prop）