TDropdown / 下拉菜单

Dropdown displays a contextual menu triggered by click, hover, or right-click. Supports item lists, custom content via slots, placement control, and dark theme. / 下拉菜单显示上下文菜单，支持点击、悬停或右键触发，支持数据驱动的菜单项列表、自定义插槽内容、弹出位置控制和深色主题。

Props / 属性

Prop	Type / 类型	Default / 默认值	Description / 说明
modelValue	boolean	false	v-model visibility
items	DropdownItem[]	—	Menu items (overrides default slot)
trigger	'click' | 'hover' | 'contextMenu'	'click'	Trigger method
placement	'bottomLeft' | 'bottom' | 'bottomRight' | 'topLeft' | 'top' | 'topRight'	—	Menu placement
size	'sm' | 'md' | 'lg'	—	Menu item size
end	boolean	false	Right-aligned menu
arrow	boolean	false	Show arrow indicator
dark	boolean	false	Dark theme
disabled	boolean	false	Disabled
hideOnClick	boolean	true	Auto-close on item click
destroyOnClose	boolean	false	Destroy DOM on close

DropdownItem 接口

interface DropdownItem {
  text: string            // 显示文本
  href?: string           // 链接地址
  icon?: Icon             // 前置图标
  divider?: boolean       // 是否为分割线
  disabled?: boolean      // 禁用
  active?: boolean        // 激活状态
}

Slots / 插槽

Slot	Description / 说明
default	Trigger element / 触发元素
item	Custom item rendering (when using items prop)

Basic Usage / 基础用法

<script setup lang="ts">
import { TDropdown } from '@gulcc/tabler-vue'

const menuItems = [
  { text: 'Profile / 个人资料', icon: IconUser },
  { text: 'Settings / 设置', icon: IconSettings },
  { divider: true },
  { text: 'Logout / 退出', icon: IconLogout },
]
</script>

<template>
  <TDropdown :items="menuItems">
    <TButton color="primary">Menu / 菜单</TButton>
  </TDropdown>
</template>

Advanced Usage / 进阶场景

<script setup lang="ts">
import { TDropdown } from '@gulcc/tabler-vue'
</script>

<template>
  <!-- Hover trigger / 悬停触发 -->
  <TDropdown :items="items" trigger="hover">
    <span class="cursor-pointer">Hover me / 悬停</span>
  </TDropdown>

  <!-- Right-aligned + arrow / 右对齐 + 箭头 -->
  <TDropdown :items="items" end arrow>
    <TButton>Right / 右侧</TButton>
  </TDropdown>

  <!-- Dark theme / 深色主题 -->
  <TDropdown :items="items" dark>
    <TButton>Dark / 深色</TButton>
  </TDropdown>

  <!-- Context menu (right-click) / 右键菜单 -->
  <TDropdown :items="menuItems" trigger="contextMenu">
    <div class="p-3 border rounded">Right-click me / 右键点击</div>
  </TDropdown>

  <!-- Custom trigger slot / 自定义触发 -->
  <TDropdown placement="bottom" end>
    <template #default>
      <TButton color="secondary">Actions / 操作</TButton>
    </template>
  </TDropdown>
</template>

Tips / 避坑指南

• items prop takes priority over default slot content — if items is set, the slot acts only as a trigger
• DropdownItem with divider: true renders a separator line, all other props are ignored
• hideOnClick={true} auto-closes the menu when an item is clicked (default). Set to false for multi-select menus
• Uses @floating-ui/vue for smart positioning — auto-flips when space is limited
• placement accepts: bottomLeft (default), bottom, bottomRight, topLeft, top, topRight