悬浮卡片 | Reka UI 组件库

供视觉用户预览链接后的可用内容。

查看代码

特性

可受控或非受控。
可自定义侧边、对齐方式、偏移量和碰撞处理。
可选择渲染一个指向箭头。
支持自定义打开和关闭延迟。
被屏幕阅读器忽略。

安装

从命令行安装此组件。

$ npm add reka-ui

结构

导入所有部分并将其组合。

vue

<script setup>
import { HoverCardArrow, HoverCardContent, HoverCardPortal, HoverCardRoot, HoverCardTrigger } from 'reka-ui'
</script>

<template>
  <HoverCardRoot>
    <HoverCardTrigger />
    <HoverCardPortal>
      <HoverCardContent>
        <HoverCardArrow />
      </HoverCardContent>
    </HoverCardPortal>
  </HoverCardRoot>
</template>

API 参考

根

包含悬浮卡片的所有部分。

属性	默认	类型
`closeDelay`	`300`	`数字` 鼠标离开触发器或内容后，悬浮卡片关闭的持续时间。
`defaultOpen`	`false`	`布尔值` 悬浮卡片初始渲染时的打开状态。当您不需要控制其打开状态时使用。
`open`		`布尔值` 悬浮卡片的受控打开状态。可绑定为 `v-model:open`。
`openDelay`	`700`	`数字` 鼠标进入触发器后，悬浮卡片打开的持续时间。

事件触发	载荷
`update:open`	`[value: boolean]` 当悬浮卡片打开状态改变时调用的事件处理程序。

插槽（默认）	载荷
`open`	`布尔值` 当前打开状态

触发器

悬停时打开悬浮卡片的链接。

属性	默认	类型
`as`	`'a'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`reference`		`ReferenceElement` 用于定位的参考（或锚点）元素。如果未提供，将使用当前组件作为锚点。

数据属性	值
`[data-state]`	`"打开" \| "关闭"`

传送门

使用时，将内容部分传送到 body 中。

属性	默认	类型
`defer`		`布尔值` 延迟解析 Teleport 目标，直到应用程序的其他部分挂载（需要 Vue 3.5.0+） reference
`disabled`		`布尔值` 禁用传送并内联渲染组件 reference
`forceMount`		`布尔值` 当需要更多控制时，用于强制挂载。在与 Vue 动画库控制动画时很有用。
`to`		`字符串 \| HTMLElement` Vue 原生传送组件属性 `:to` reference

内容

悬浮卡片打开时弹出的组件。

提示

使用 Presence 组件构建 - 支持任何动画技术，同时保持对 Presence 发出事件的访问。

属性	默认	类型
`align`		`'start' \| 'center' \| 'end'` 相对于触发器的首选对齐方式。当发生碰撞时可能会改变。
`alignOffset`		`数字` 与 `start` 或 `end` 对齐选项的像素偏移量。
`arrowPadding`		`数字` 箭头与内容边缘之间的内边距。如果您的内容有 border-radius，这将防止它溢出角落。
`as`	`'div'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`avoidCollisions`		`布尔值` 当为 `true` 时，覆盖侧边和对齐偏好，以防止与边界边缘发生碰撞。
`collisionBoundary`		`Element \| (Element \| null)[] \| null` 用作碰撞边界的元素。默认情况下是视口，但您可以提供其他元素以包含在此检查中。
`collisionPadding`		`数字 \| Partial<Record<'top' \| 'right' \| 'bottom' \| 'left', number>>` 碰撞检测应发生的距边界边缘的像素距离。接受一个数字（所有边相同），或一个部分填充对象，例如：{ top: 20, left: 20 }。
`disableUpdateOnLayoutShift`		`布尔值` 当布局发生偏移时，是否禁用更新内容位置。
`forceMount`		`布尔值` 当需要更多控制时，用于强制挂载。在与 Vue 动画库控制动画时很有用。
`hideWhenDetached`		`布尔值` 当触发器完全被遮挡时，是否隐藏内容。
`positionStrategy`		`'fixed' \| 'absolute'` 要使用的 CSS position 属性类型。
`prioritizePosition`		`布尔值` 强制内容在视口内定位。可能与参考元素重叠，这可能不是期望的结果。
`reference`		`ReferenceElement` 将设置为浮动元素定位参考的自定义元素或虚拟元素。如果提供，它将替换默认的锚点元素。
`side`		`'top' \| 'right' \| 'bottom' \| 'left'` 打开时，相对于触发器渲染的首选侧边。当发生碰撞且启用 avoidCollisions 时，将反转。
`sideOffset`		`数字` 与触发器的像素距离。
`sticky`		`'部分' \| '始终'` 对齐轴上的粘性行为。`partial` 将使内容保持在边界内，只要触发器至少部分在边界内；而 "always" 则无论如何都会将内容保持在边界内。
`updatePositionStrategy`		`'始终' \| '优化'` 在每个动画帧更新浮动元素位置的策略。

事件触发	载荷
`escapeKeyDown`	`[事件: KeyboardEvent]` 按下 Esc 键时调用的事件处理程序。可阻止其默认行为。
`focusOutside`	`[事件: FocusOutsideEvent]` 当焦点移出 `DismissableLayer` 时调用的事件处理程序。可阻止其默认行为。
`interactOutside`	`[事件: PointerDownOutsideEvent \| FocusOutsideEvent]` 当 `DismissableLayer` 外部发生交互时调用的事件处理程序。具体来说，当 `pointerdown` 事件在外部发生或焦点移出时。可阻止其默认行为。
`pointerDownOutside`	`[事件: PointerDownOutsideEvent]` 当 `pointerdown` 事件在 `DismissableLayer` 外部发生时调用的事件处理程序。可阻止其默认行为。

数据属性	值
`[data-state]`	`"打开" \| "关闭"`
`[data-side]`	`"左" \| "右" \| "下" \| "上"`
`[data-align]`	`"开始" \| "结束" \| "居中"`

CSS 变量	描述
`--reka-hover-card-content-transform-origin`	从内容和箭头位置/偏移量计算的 `transform-origin`
`--reka-hover-card-content-available-width`	触发器与边界边缘之间的剩余宽度
`--reka-hover-card-content-available-height`	触发器与边界边缘之间的剩余高度
`--reka-hover-card-trigger-width`	触发器的宽度
`--reka-hover-card-trigger-height`	触发器的高度

箭头

一个可选的箭头元素，与悬浮卡片一起渲染。这可以用于帮助将触发器与 HoverCardContent 视觉连接起来。必须在 HoverCardContent 内部渲染。

属性	默认	类型
`as`	`'svg'`	`AsTag \| Component` 此组件应渲染为的元素或组件。可通过 `asChild` 覆盖。
`asChild`		`布尔值` 更改默认渲染元素为作为子项传递的元素，合并它们的属性和行为。阅读我们的组合指南了解更多详情。
`高度`	`5`	`数字` 箭头的像素高度。
`rounded`		`布尔值` 当为 `true` 时，渲染圆角版本的箭头。不适用于 `as`/`asChild`
`宽度`	`10`	`数字` 箭头的像素宽度。

示例

即时显示

使用 openDelay 属性控制悬浮卡片打开所需的时间。

vue

<script setup>
import {
  HoverCardArrow,
  HoverCardContent,
  HoverCardPortal,
  HoverCardRoot,
  HoverCardTrigger,
} from 'reka-ui'
</script>

<template>
  <HoverCardRoot :open-delay="0">
    <HoverCardTrigger>…</HoverCardTrigger>
    <HoverCardContent>…</HoverCardContent>
  </HoverCardRoot>
</template>

约束内容大小

您可能希望限制内容的宽度以匹配触发器的宽度。您可能还希望限制其高度，使其不超过视口。

我们公开了几个 CSS 自定义属性，例如 --reka-hover-card-trigger-width 和 --reka-hover-card-content-available-height 以支持此功能。使用它们来约束内容的尺寸。

vue

// index.vue
<script setup>
import { HoverCardArrow, HoverCardContent, HoverCardPortal, HoverCardRoot, HoverCardTrigger } from 'reka-ui'
</script>

<template>
  <HoverCardRoot>
    <HoverCardTrigger>…</HoverCardTrigger>
    <HoverCardPortal>
      <HoverCardContent
        class="HoverCardContent"
        :side-offset="5"
      >
        …
      </HoverCardContent>
    </HoverCardPortal>
  </HoverCardRoot>
</template>

css

/* styles.css */
.HoverCardContent {
  width: var(--reka-hover-card-trigger-width);
  max-height: var(--reka-hover-card-content-available-height);
}

原点感知动画

我们公开了一个 CSS 自定义属性 --reka-hover-card-content-transform-origin。使用它根据 side、sideOffset、align、alignOffset 和任何碰撞来从其计算出的原点对内容进行动画处理。

vue

<script setup>
import { HoverCardArrow, HoverCardContent, HoverCardPortal, HoverCardRoot, HoverCardTrigger } from 'reka-ui'
</script>

<template>
  <HoverCardRoot>
    <HoverCardTrigger>…</HoverCardTrigger>
    <HoverCardContent class="HoverCardContent">
      …
    </HoverCardContent>
  </HoverCardRoot>
</template>

css

/* styles.css */
.HoverCardContent {
  transform-origin: var(--reka-hover-card-content-transform-origin);
  animation: scaleIn 0.5s ease-out;
}

@keyframes scaleIn {
  from {
    opacity: 0;
    transform: scale(0);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

碰撞感知动画

我们公开了 data-side 和 data-align 属性。它们的值将在运行时改变以反映碰撞。使用它们来创建碰撞和方向感知的动画。

vue

<script setup>
import { HoverCardArrow, HoverCardContent, HoverCardPortal, HoverCardRoot, HoverCardTrigger } from 'reka-ui'
</script>

<template>
  <HoverCardRoot>
    <HoverCardTrigger>…</HoverCardTrigger>
    <HoverCardContent class="HoverCardContent">
      …
    </HoverCardContent>
  </HoverCardRoot>
</template>

css

/* styles.css */
.HoverCardContent {
  animation-duration: 0.6s;
  animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}
.HoverCardContent[data-side="top"] {
  animation-name: slideUp;
}
.HoverCardContent[data-side="bottom"] {
  animation-name: slideDown;
}

@keyframes slideUp {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes slideDown {
  from {
    opacity: 0;
    transform: translateY(-10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

可访问性

悬浮卡片仅供视觉用户使用，键盘用户将无法访问其内容。

键盘交互

键	描述
`Tab`	打开/关闭悬浮卡片。
`回车键`	打开悬浮卡片链接

HoverCard ​

特性 ​

安装 ​

结构 ​

API 参考 ​

根 ​

触发器 ​

传送门 ​

内容 ​

箭头 ​

示例 ​

即时显示 ​

约束内容大小 ​

原点感知动画 ​

碰撞感知动画 ​

可访问性 ​

键盘交互 ​

HoverCard

特性

安装

结构