Dropdown 下拉菜单

下拉菜单用于显示一组可操作的项。支持图标、分隔线、分组标题、激活/禁用状态、徽章、头像、复选框/单选框、深色主题等多种变体。

基础用法

通过 items 属性传入菜单项数组，或使用 default 插槽自定义内容。

vue


<TDropdown>
  <template #trigger-text>展开菜单</template>
  <TDropdownItem>操作项</TDropdownItem>
  <TDropdownItem>另一个操作项</TDropdownItem>
</TDropdown>

分隔线 & 分组标题

使用 TDropdownItem 的 divider 和 header 属性，或直接使用原始 HTML 类名划分菜单组。

查看代码

vue

<!-- 原始 HTML 方式 -->
<TDropdown>
  <template #trigger-text>分隔线</template>
  <TDropdownItem>操作项</TDropdownItem>
  <TDropdownItem divider/>
  <TDropdownItem>分开的链接</TDropdownItem>
</TDropdown>

<!-- TDropdownItem 组件方式（推荐） -->
<TDropdown>
  <template #trigger-text>组件方式</template>
  <TDropdownItem>操作项</TDropdownItem>
  <TDropdownItem divider/>
  <TDropdownItem header text="分组标题"/>
  <TDropdownItem>另一个操作项</TDropdownItem>
</TDropdown>

状态

激活状态

添加 active 类高亮某个菜单项。

vue


<TDropdown>
  <template #trigger-text>激活态</template>
  <TDropdownItem active>当前选中</TDropdownItem>
</TDropdown>

禁用状态

添加 disabled 类禁用某个菜单项。

vue


<TDropdown>
  <TDropdownItem disabled>禁用项</TDropdownItem>
</TDropdown>

带图标

每个菜单项可通过 items 属性的 icon 字段传入 @tabler/icons-vue 图标组件。

查看代码

vue


<script setup>
  import {IconSettings, IconEdit, IconActivity, IconLogout} from '@tabler/icons-vue'
</script>

<template>
  <TDropdown :items="[
    { text: '活动', icon: IconActivity },
    { text: '编辑', icon: IconEdit },
    { text: '设置', icon: IconSettings },
    { divider: true },
    { text: '退出登录', icon: IconLogout },
  ]">
    <template #trigger-text>图标菜单</template>
  </TDropdown>
</template>

带箭头

设置 arrow 属性可在菜单上显示指向触发器的箭头。

vue


<TDropdown arrow>
  <template #trigger-text>带箭头</template>
  <TDropdownItem>操作项</TDropdownItem>
</TDropdown>

带徽章

通过 items 属性的 badge 和 badgeColor 字段在菜单项右侧显示徽章。

vue


<TDropdown :items="[
  { text: '通知', badge: '12', badgeColor: 'primary' },
  { text: '消息', badge: '', badgeColor: 'green' },
]">
  <template #trigger-text>徽章</template>
</TDropdown>

复选框 & 单选框

使用 TDropdownItem 的 type="checkbox" 或 type="radio" 实现表单选择项，通过 v-model:checked 绑定选中状态。

查看代码

vue


<script setup lang="ts">
  import {ref} from 'vue'

  const checked1 = ref(true)
  const checked2 = ref(false)

  const radioValue = ref('option1')
</script>

<template>
  <!-- 复选框（v-model:checked） -->
  <TDropdown>
    <template #trigger-text>复选框</template>
    <TDropdownItem type="checkbox" v-model:checked="checked1">选项一</TDropdownItem>
    <TDropdownItem type="checkbox" v-model:checked="checked2">选项二</TDropdownItem>
  </TDropdown>

  <!-- 单选框（通过 checked 和 @update:checked 控制分组） -->
  <TDropdown>
    <template #trigger-text>单选框</template>
    <TDropdownItem
        type="radio" name="demo"
        :checked="radioValue === 'option1'"
        @update:checked="radioValue = 'option1'"
    >选项一
    </TDropdownItem>
    <TDropdownItem
        type="radio" name="demo"
        :checked="radioValue === 'option2'"
        @update:checked="radioValue = 'option2'"
    >选项二
    </TDropdownItem>
  </TDropdown>
</template>

右侧对齐

设置 end 属性使菜单从右侧对齐。

vue


<TDropdown end>
  <template #trigger-text>右对齐</template>
  <TDropdownItem>操作项</TDropdownItem>
</TDropdown>

自定义触发器

通过 trigger 插槽完全自定义触发器按钮。

查看代码

vue


<TDropdown>
  <template #trigger>
    <button class="btn btn-outline-primary dropdown-toggle">
      <IconBell class="icon"/>
      通知
    </button>
  </template>
  <TDropdownItem>新通知</TDropdownItem>
</TDropdown>

触发方式

通过 trigger 属性设置触发方式：click（默认）、hover（悬浮）、contextMenu（右键菜单）。

查看代码

vue

<!-- Click 触发（默认） -->
<TDropdown trigger="click">
  <template #trigger-text>点击我</template>
  <TDropdownItem>操作项</TDropdownItem>
</TDropdown>

<!-- Hover 触发 -->
<TDropdown trigger="hover">
  <template #trigger-text>悬浮我</template>
  <TDropdownItem>操作项</TDropdownItem>
</TDropdown>

<!-- 右键触发 -->
<TDropdown trigger="contextMenu">
  <template #trigger-text>右键点击这里</template>
  <TDropdownItem>操作项</TDropdownItem>
</TDropdown>

弹出位置

通过 placement 属性设置菜单弹出位置，支持 6 个方向。

注意：arrow（箭头）与 placement 不兼容。带箭头时箭头始终朝上指向触发器，且无法自适应弹出方向。如需调整弹出位置，请勿同时使用 arrow 属性。

vue


<TDropdown placement="topLeft">...</TDropdown>
<TDropdown placement="top">...</TDropdown>
<TDropdown placement="topRight">...</TDropdown>
<TDropdown placement="bottomLeft">...</TDropdown>
<TDropdown placement="bottom">...</TDropdown>
<TDropdown placement="bottomRight">...</TDropdown>

多级菜单

菜单项支持 children 字段实现多级嵌套。

查看代码

vue


<TDropdown :items="[
  { text: '邮件', icon: IconMail, children: [
    { text: '收件箱', icon: IconMessage },
    { text: '已发送', icon: IconMessage },
    { divider: true },
    { text: '垃圾箱' },
  ]},
  { text: '设置', icon: IconSettings },
]">
  <template #trigger-text>多级菜单</template>
</TDropdown>

保持菜单打开

设置 :hideOnClick="false" 使点击菜单项后不自动关闭。

vue


<TDropdown :hideOnClick="false">
  <template #trigger-text>点击保持打开</template>
  <TDropdownItem>操作项</TDropdownItem>
</TDropdown>

组件的组合使用

将 TDropdown 与其他组件结合，构建更丰富的交互场景。

头像 + 下拉菜单

使用 trigger 插槽自定义触发器，将 TAvatar 作为点击触发区域。

查看代码

vue


<TDropdown>
  <template #trigger>
    <TAvatar text="张三" color="primary-lt" style="cursor: pointer" />
  </template>
  <TDropdownItem icon="IconUser">个人中心</TDropdownItem>
  <TDropdownItem icon="IconMessage">我的消息</TDropdownItem>
  <TDropdownItem icon="IconPhoto">我的相册</TDropdownItem>
  <TDropdownItem divider />
  <TDropdownItem icon="IconSettings">账号设置</TDropdownItem>
  <TDropdownItem icon="IconLogout">退出登录</TDropdownItem>
</TDropdown>

徽章 + 下拉菜单

触发器上显示通知徽章，菜单项内也支持使用 badge 属性显示徽章。

查看代码

vue


<TDropdown>
  <template #trigger>
    <span class="position-relative d-inline-block" style="cursor: pointer">
      <IconBell size="24" />
      <TBadge color="red" pill notification blink>3</TBadge>
    </span>
  </template>
  <TDropdownItem icon="IconMessage" badge="2" badgeColor="primary">新回复</TDropdownItem>
  <TDropdownItem icon="IconUser" badge="1" badgeColor="green">新粉丝</TDropdownItem>
  <TDropdownItem icon="IconActivity">系统通知</TDropdownItem>
</TDropdown>

按钮 + 下拉菜单

使用 TButton 作为触发器，搭配不同的按钮样式。

查看代码

vue


<TDropdown>
  <template #trigger>
    <TButton color="primary" pill>主色按钮</TButton>
  </template>
  <TDropdownItem>操作项</TDropdownItem>
  <TDropdownItem>另一个操作项</TDropdownItem>
</TDropdown>

<TDropdown>
  <template #trigger>
    <TButton color="red" outline iconOnly>
      <IconTrash size="18" />
    </TButton>
  </template>
  <TDropdownItem>删除选中</TDropdownItem>
  <TDropdownItem>清空回收站</TDropdownItem>
</TDropdown>

<TDropdown>
  <template #trigger>
    <TButton color="green" ghost size="sm"><IconDots size="18" /> 更多</TButton>
  </template>
  <TDropdownItem>导出数据</TDropdownItem>
  <TDropdownItem>打印报表</TDropdownItem>
</TDropdown>

卡片右键菜单

设置 trigger="contextMenu" 使菜单在右键点击时弹出，适合对卡片、列表项等元素使用。

查看代码

vue


<TDropdown trigger="contextMenu">
  <template #trigger>
    <div class="card" style="cursor: context-menu">
      <div class="card-body text-center text-secondary py-4">
        <div class="mb-2"><IconPhoto size="32" /></div>
        <div class="fw-bold">图片卡片</div>
        <div class="text-muted small">在此区域右键点击试试</div>
      </div>
    </div>
  </template>
  <TDropdownItem icon="IconEdit">编辑</TDropdownItem>
  <TDropdownItem icon="IconPhoto">查看大图</TDropdownItem>
  <TDropdownItem divider />
  <TDropdownItem icon="IconTrash" disabled>删除</TDropdownItem>
</TDropdown>

API

Props

属性	类型	默认	说明
`modelValue`	`boolean`	`false`	v-model 绑定，控制展开/收起
`items`	`DropdownItem[]`	—	菜单项列表（使用该属性时 default 插槽被忽略）
`size`	`'sm' \| 'md' \| 'lg'`	—	菜单尺寸
`end`	`boolean`	`false`	菜单右侧对齐
`arrow`	`boolean`	`false`	菜单显示箭头
`dark`	`boolean`	`false`	深色主题
`disabled`	`boolean`	`false`	禁用展开
`menuClass`	`string`	—	附加到菜单的 CSS 类
`trigger`	`'click' \| 'hover' \| 'contextMenu'`	`'click'`	触发方式
`placement`	`'bottomLeft' \| 'bottom' \| 'bottomRight' \| 'topLeft' \| 'top' \| 'topRight'`	—	弹出位置
`hideOnClick`	`boolean`	`true`	点击菜单项后是否自动关闭
`destroyOnClose`	`boolean`	`false`	关闭后是否销毁 DOM

Slots

插槽	说明
`trigger`	触发器（完全自定义）
`trigger-text`	触发器的按钮文本（使用默认触发器按钮时）
`default`	菜单内容（未提供 `items` 时有效）

Emits

事件	载荷	说明
`update:modelValue`	`(value: boolean)`	v-model 更新事件
`toggle`	`(open: boolean)`	展开/收起时触发
`openChange`	`(open: boolean)`	菜单显示状态改变时触发

DropdownItem 类型

属性	类型	默认	说明
`text`	`string`	—	显示文本
`href`	`string`	—	链接地址（不传则渲染为 `<span>`）
`icon`	`Component / Icon`	—	图标组件
`active`	`boolean`	`false`	激活高亮状态
`disabled`	`boolean`	`false`	禁用状态
`divider`	`boolean`	`false`	渲染为分隔线
`header`	`boolean`	`false`	渲染为分组标题
`badge`	`string \| number`	—	徽章内容
`badgeColor`	`string`	—	徽章颜色（如 `primary`、`green`）
`children`	`DropdownItem[]`	—	子菜单项（支持多级嵌套）

TDropdownItem Props

属性	类型	默认	说明
`text`	`string`	—	显示文本
`href`	`string`	—	链接地址（不传则渲染为 `<span>`，传了渲染为 `<a>`）
`icon`	`Component / Icon`	—	图标组件（从 `@tabler/icons-vue` 导入）
`type`	`'item' \| 'checkbox' \| 'radio'`	`'item'`	元素类型
`name`	`string`	—	radio 分组名称
`checked`	`boolean`	—	checkbox/radio 选中状态（支持 `v-model:checked`）
`active`	`boolean`	`false`	激活高亮状态
`disabled`	`boolean`	`false`	禁用状态
`divider`	`boolean`	`false`	渲染为分隔线
`header`	`boolean`	`false`	渲染为分组标题
`badge`	`string \| number`	—	徽章内容
`badgeColor`	`string`	—	徽章颜色（如 `primary`、`green`）
`avatar`	`{ src?: string; name?: string }`	—	头像配置
`children`	`DropdownItem[]`	—	子菜单项

TDropdownItem Slots

插槽	说明
`default`	菜单项文本内容

TDropdownItem Emits

事件	载荷	说明
`update:checked`	`(value: boolean)`	`v-model:checked` 绑定事件
`click`	`(e: MouseEvent)`	点击菜单项时触发

Dropdown 下拉菜单 ​

基础用法 ​

分隔线 & 分组标题 ​

状态 ​

激活状态 ​

禁用状态 ​

带图标 ​

带箭头 ​

带徽章 ​

复选框 & 单选框 ​

右侧对齐 ​

自定义触发器 ​

触发方式 ​

弹出位置 ​

多级菜单 ​

保持菜单打开 ​

组件的组合使用 ​

头像 + 下拉菜单 ​

徽章 + 下拉菜单 ​

按钮 + 下拉菜单 ​

卡片右键菜单 ​

API ​

Props ​

Slots ​

Emits ​

DropdownItem 类型 ​

TDropdownItem Props ​

TDropdownItem Slots ​

TDropdownItem Emits ​

Dropdown 下拉菜单

基础用法

分隔线 & 分组标题

状态

激活状态

禁用状态

带图标

带箭头

带徽章

复选框 & 单选框

右侧对齐

自定义触发器

触发方式

弹出位置

多级菜单

保持菜单打开

组件的组合使用

头像 + 下拉菜单

徽章 + 下拉菜单

按钮 + 下拉菜单

卡片右键菜单

API

Props

Slots

Emits

DropdownItem 类型

TDropdownItem Props

TDropdownItem Slots

TDropdownItem Emits