Popover

一个非模态对话框，围绕触发元素浮动。

用法

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

然后，使用#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。

mode

<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。

content.align

content.side

content.sideOffset

<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>

使用modal属性来控制 Popover 是否阻止与外部内容的交互。默认为false。

modal

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

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

可关闭

使用dismissible属性来控制 Popover 是否可以通过点击外部或按 Esc 键关闭。默认为true。

当用户尝试关闭时，将发出一个close:prevent事件。

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

    <template #content="{ close }">
      <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="close" />
      </div>

      <Placeholder class="size-full min-h-48" />
    </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。

带命令面板

您可以在 Popover 的内容中包含命令面板组件。

<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>

跟随光标

您可以通过使用以下方式使 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插槽将 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"` 弹出框的显示模式。
`内容`	`{ 侧面: '底部', 侧面偏移量: 8, 碰撞填充: 8 }`	`PopoverContentProps & Partial<EmitsToProps<PopoverContentImplEmits>>` 弹出框的内容。
`arrow`	`false`	`boolean \| PopoverArrowProps` 在弹出框旁边显示一个箭头。
`portal`	`true`	`string \| false \| true \| HTMLElement` 在传送门中渲染弹出框。
`参考`		`元素 \| 虚拟元素` 用于定位的引用（或锚点）元素。如果未提供，将使用当前组件作为锚点。
`可关闭的`	`true`	`boolean` 当`false`时，点击外部或按 Esc 键弹出框将不会关闭。
`defaultOpen`		`boolean` 弹出框最初渲染时的打开状态。当您不需要控制其打开状态时使用。
`open`		`boolean` 弹出框的受控打开状态。
`modal`	`false`	`boolean` 弹出框的模态。当设置为 true 时，与外部元素的交互将被禁用，并且屏幕阅读器将只能看到弹出框内容。
`打开延迟`	`0`	`number` 鼠标进入触发器到悬停卡片打开的持续时间。
`关闭延迟`	`0`	`number` 鼠标离开触发器或内容到悬停卡片关闭的持续时间。
`ui`		`{ content?: ClassNameValue; arrow?: ClassNameValue; }`

插槽

插槽	类型
`default`	`{ open: boolean; }`
`内容`	`{ close: () => void; }`
`锚点`	`{ close: () => void; }`

close函数仅当mode设置为click时才可用，因为 Reka UI 为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'
          }
        }
      }
    })
  ]
})

更新日志

dd81d— feat: 添加 data-slot 属性 (#5447)

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 属性中的事件

模态框

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

侧滑框

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