Popover

悬停卡片PopoverGitHub
一个非模态对话框，围绕触发元素浮动。

用法

在 Popover 的默认插槽中使用Button或其他任何组件。

然后，使用#content插槽来添加 Popover 打开时显示的内容。

<template>
  <UPopover>
    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template>
  </UPopover>
</template>

模式

使用mode属性来更改 Popover 的模式。默认为click。

<template>
  <UPopover mode="hover">
    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template>
  </UPopover>
</template>
当使用hover模式时，Reka UI悬停卡片组件被使用，而不是Popover.

延迟

当使用hover模式时，您可以使用open-delay和close-delay属性来控制 Popover 打开或关闭前的延迟。

<template>
  <UPopover mode="hover" :open-delay="500" :close-delay="300">
    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template>
  </UPopover>
</template>

内容

使用content属性来控制 Popover 内容的渲染方式，例如它的align或side。

<template>
  <UPopover
    :content="{
      align: 'center',
      side: 'bottom',
      sideOffset: 8
    }"
  >
    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template>
  </UPopover>
</template>

箭头

使用arrow属性在 Popover 上显示一个箭头。

<template>
  <UPopover arrow>
    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template>
  </UPopover>
</template>

示例

控制打开状态

您可以通过使用default-open prop 或v-model:open指令来控制打开状态。

<script setup lang="ts">
const open = ref(false)

defineShortcuts({
  o: () => open.value = !open.value
})
</script>

<template>
  <UPopover v-model:open="open">
    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template>
  </UPopover>
</template>
在此示例中，利用defineShortcuts，您可以通过按下O来切换 Popover。

禁用关闭

将dismissible属性设置为false，以防止 Popover 在点击其外部或按下 escape 时关闭。当用户尝试关闭时，将发出close:prevent事件。

<script setup lang="ts">
const open = ref(false)
</script>

<template>
  <UPopover v-model:open="open" :dismissible="false" :ui="{ content: 'p-4' }">
    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <div class="flex items-center gap-4 mb-4">
        <h2 class="text-highlighted font-semibold">
          Popover non-dismissible
        </h2>

        <UButton color="neutral" variant="ghost" icon="i-lucide-x" @click="open = false" />
      </div>

      <Placeholder class="size-full min-h-48" />
    </template>
  </UPopover>
</template>

带命令面板

您可以在 Popover 内容中使用CommandPalette组件。

<script setup lang="ts">
const items = ref([
  {
    label: 'bug',
    value: 'bug',
    chip: {
      color: 'error' as const
    }
  },
  {
    label: 'feature',
    value: 'feature',
    chip: {
      color: 'success' as const
    }
  },
  {
    label: 'enhancement',
    value: 'enhancement',
    chip: {
      color: 'info' as const
    }
  }
])
const label = ref([])
</script>

<template>
  <UPopover :content="{ side: 'right', align: 'start' }">
    <UButton
      icon="i-lucide-tag"
      label="Select labels"
      color="neutral"
      variant="subtle"
    />

    <template #content>
      <UCommandPalette
        v-model="label"
        multiple
        placeholder="Search labels..."
        :groups="[{ id: 'labels', items }]"
        :ui="{ input: '[&>input]:h-8 [&>input]:text-sm' }"
      />
    </template>
  </UPopover>
</template>

带有以下光标

您可以使用reference属性，让 Popover 跟随鼠标悬停在元素上。

<script setup lang="ts">
const open = ref(false)
const anchor = ref({ x: 0, y: 0 })

const reference = computed(() => ({
  getBoundingClientRect: () =>
    ({
      width: 0,
      height: 0,
      left: anchor.value.x,
      right: anchor.value.x,
      top: anchor.value.y,
      bottom: anchor.value.y,
      ...anchor.value
    } as DOMRect)
}))
</script>

<template>
  <UPopover
    :open="open"
    :reference="reference"
    :content="{ side: 'top', sideOffset: 16, updatePositionStrategy: 'always' }"
  >
    <div
      class="flex items-center justify-center rounded-md border border-dashed border-accented text-sm aspect-video w-72"
      @pointerenter="open = true"
      @pointerleave="open = false"
      @pointermove="(ev) => {
        anchor.x = ev.clientX
        anchor.y = ev.clientY
      }"
    >
      Hover me
    </div>

    <template #content>
      <div class="p-4">
        {{ anchor.x.toFixed(0) }} - {{ anchor.y.toFixed(0) }}
      </div>
    </template>
  </UPopover>
</template>

使用 anchor 插槽

您可以使用#anchor插槽将 Popover 定位到自定义元素。

此插槽仅在mode设置为click时有效。
<script lang="ts" setup>
const open = ref(false)
</script>

<template>
  <UPopover
    v-model:open="open"
    :dismissible="false"
    :ui="{ content: 'w-(--reka-popper-anchor-width) p-4' }"
  >
    <template #anchor>
      <UInput placeholder="Focus to open" @focus="open = true" @blur="open = false" />
    </template>

    <template #content>
      <Placeholder class="w-full aspect-square" />
    </template>
  </UPopover>
</template>

API

属性

属性默认值类型
mode

'click'

"click" | "hover"

Popover 的显示模式。

内容

{ side: 'bottom', sideOffset: 8, collisionPadding: 8 }

PopoverContentProps & Partial<EmitsToProps<PopoverContentImplEmits>>

Popover 的内容。

arrow

false

boolean | PopoverArrowProps

在 Popover 旁边显示一个箭头。

portal

true

string | false | true | HTMLElement

在 Portal 中渲染 Popover。

reference

Element | VirtualElement

用于定位的引用（或锚点）元素。

如果未提供，将使用当前组件作为锚点。

可关闭的

true

boolean

当false时，点击外部或按下 escape 时，Popover 不会关闭。

defaultOpen

boolean

Popover 初始渲染时的打开状态。当您不需要控制其打开状态时使用。

open

boolean

Popover 的受控打开状态。

modal

false

boolean

Popover 的模态。当设置为 true 时，与外部元素的交互将被禁用，并且只有 Popover 内容对屏幕阅读器可见。

openDelay

0

number

从鼠标进入触发器到悬停卡片打开的持续时间。

closeDelay

0

number

从鼠标离开触发器或内容到悬停卡片关闭的持续时间。

ui

{ content?: ClassNameValue; arrow?: ClassNameValue; }

插槽

插槽类型
default

{ open: boolean; }

内容

{ close: () => void; }

anchor

{ close: () => void; }

因为 Reka UI 提供了此功能，所以close函数仅在mode设置为click时可用。Popover但不是用于悬停卡片.

事件

事件类型
close:prevent

[]

update:open

[value: boolean]

主题

app.config.ts
export default defineAppConfig({
  ui: {
    popover: {
      slots: {
        content: 'bg-default shadow-lg rounded-md ring ring-default data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-popover-content-transform-origin) focus:outline-none pointer-events-auto',
        arrow: 'fill-default'
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        popover: {
          slots: {
            content: 'bg-default shadow-lg rounded-md ring ring-default data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-popover-content-transform-origin) focus:outline-none pointer-events-auto',
            arrow: 'fill-default'
          }
        }
      }
    })
  ]
})

更新日志

53c65— 新增：在插槽中添加close方法 (#5176)

5cb65— 特性：导入 @nuxt/ui-pro 组件

b00e0— feat: 添加reference属性

150b3— 修复：在closeAutoFocus上不发出close:prevent

47351— feat: 添加anchor插槽 (#4119)

f4864— 新增：添加close:prevent事件 (#3958)

29fa4— 特性：添加全局 portal 属性 (#3688)

39c86— fix：@nuxt/module-builder 升级后重构类型（#3855)

5dec0— feat: 处理 content 属性中的事件

Modal

一个对话框，可用于显示消息或请求用户输入。

Slideover

一个从屏幕任何一侧滑入的对话框。