Appearance
Popover 弹出框
用于在触发元素附近展示浮层内容，支持 hover、click、manual 触发和 Popper 定位能力。
示例
基础用法
触发方式
内容渲染
虚拟触发
暴露方法
API
Props
| 属性名 | 说明 | 类型 | 默认值 | 示例 |
|---|---|---|---|---|
| trigger | 触发方式 | 'hover' | 'click' | 'manual' | 'hover' | trigger="click" |
| content | 显示内容 | string | '' | content="提示内容" |
| width | 内容宽度 | number | string | 100 | width="240px" |
| placement | 出现位置 | Placement | 'bottom' | placement="top-start" |
| disabled | 是否禁用 | boolean | false | disabled |
| offset | 内容偏移量 | number | - | :offset="16" |
| visible | 手动控制显隐 | boolean | null | null | v-model:visible="visible" |
| show-arrow | 是否显示箭头 | boolean | true | :show-arrow="false" |
| popper-options | Popper 配置 | Partial<Options> | {} | :popper-options="{ strategy: 'fixed' }" |
| strategy | 定位策略 | 'absolute' | 'fixed' | 'absolute' | strategy="fixed" |
| fallback-placements | 回退位置 | Placement[] | - | :fallback-placements="['top', 'right']" |
| gpu-acceleration | 是否开启 GPU 加速 | boolean | true | :gpu-acceleration="false" |
| popper-class | 浮层类名 | string | object | array | '' | popper-class="custom-popper" |
| show-after | 延迟显示时间，单位 ms | number | 0 | :show-after="200" |
| hide-after | 延迟关闭时间，单位 ms | number | 250 | :hide-after="100" |
| auto-close | 是否自动关闭 | boolean | true | :auto-close="false" |
| popper-style | 浮层样式 | StyleValue | {} | :popper-style="{ padding: '12px' }" |
| append-to | 内容挂载目标 | string | HTMLElement | 'body' | append-to="#app" |
| effect | 主题 | 'light' | 'dark' | 'light' | effect="dark" |
| raw-content | 是否将 content 作为 HTML 字符串 | boolean | false | raw-content |
| virtual-triggering | 是否虚拟触发 | boolean | false | virtual-triggering |
| virtual-ref | 虚拟触发元素 | Ref<HTMLElement | null> | null | :virtual-ref="triggerRef" |
| z-index | 浮层层级 | number | - | :z-index="3000" |
| enterable | 鼠标是否可进入浮层 | boolean | true | :enterable="false" |
| teleported | 是否启用 teleport | boolean | true | :teleported="false" |
Events
| 事件名 | 说明 | 回调参数 | 示例 |
|---|---|---|---|
| update:visible | 显隐状态变化时触发 | (visible: boolean) | @update:visible="onUpdate" |
| show | 显示时触发 | - | @show="onShow" |
| hide | 隐藏时触发 | - | @hide="onHide" |
| before-enter | 进入前触发 | - | @before-enter="onBeforeEnter" |
| before-leave | 离开前触发 | - | @before-leave="onBeforeLeave" |
Slots
| 插槽名 | 说明 | 作用域参数 | 示例 |
|---|---|---|---|
| reference | 触发元素 | - | <template #reference> |
| default | 浮层内容；未提供 content 插槽时使用 | - | <template #default> |
| content | 自定义浮层内容；优先级高于 default 插槽 | - | <template #content> |
Exposes
| 方法名 | 说明 | 类型 | 示例 |
|---|---|---|---|
| show | 显示浮层 | () => void | popoverRef.value?.show() |
| hide | 隐藏浮层 | () => void | popoverRef.value?.hide() |
注意事项
- 使用
trigger="manual"时，应通过visible或暴露方法控制显隐。 auto-close当前仅支持boolean，不提供按时间自动关闭的能力。raw-content会渲染 HTML 字符串，请仅用于可信内容。- 使用
virtual-triggering时，virtual-ref需要指向一个真实 DOM 元素或组件根元素。