使用方法

Popover 在点击触发按钮时，在它旁边打开一个浮层。和只放纯文字的 Tooltip 不同，浮层可以承载简短的交互内容，例如一个小表单、一段补充说明或一组操作。触发元素放进默认插槽，浮层内容放进 content 插槽：

<script setup lang="ts">
import { Button } from '@astryx-vue/core/Button'
import { Popover } from '@astryx-vue/core/Popover'
</script>

<template>
  <Popover label="项目详情">
    <Button label="详情" variant="secondary" />
    <template #content>
      <p>这里放置简短内容。</p>
    </template>
  </Popover>
</template>

最佳实践

指引	实践
推荐	弹出层内容只聚焦一项任务或一条信息。
推荐	提供明确的关闭方式：点击外部区域，或使用显式的关闭按钮。
避免	在弹出层中嵌套弹出层。这会造成混乱的焦点和导航。
避免	需要大量用户输入的内容，避免放在弹出层中。应使用 Dialog。
避免	在弹出层中放入过多内容。若需要滚动，应改用 Dialog。

示例

基本用法

点击触发元素打开浮层。按下 Escape、点击浮层外部或点击关闭按钮可以关闭。

位置

placement 设置浮层相对触发元素的方向，alignment 设置沿该方向的对齐方式。空间不足时自动翻转。

表单内容

对话框类浮层可以包含交互控件。打开时焦点移入浮层，关闭时焦点回到触发元素。

操作列表

role 为 none 时不添加对话框语义，适用于内容自带角色的菜单类内容。焦点保留在触发元素上。

无障碍

弹出层要把自己的存在、当前的开合状态和内部内容告诉使用屏幕阅读器或键盘的用户。组件会自动把触发元素和浮层关联起来，并在浮层打开、关闭时管理焦点，你只需要提供必要的无障碍名称。

• 触发元素上带有 aria-haspopup、aria-expanded 与 aria-controls，辅助技术由此知道这是一个会打开浮层的按钮，并能读出浮层当前是展开还是收起。
• dialog 类型的浮层带有 role="dialog"；设置 isModal 时还会带有 aria-modal="true"，并以 label 作为无障碍名称。
• 打开时焦点移入浮层中的第一个可聚焦元素；用户按下 Escape 或关闭浮层时，焦点回到触发元素。
• 设置 isModal 后，浮层打开期间 Tab 焦点保持在浮层内。
• 内置关闭按钮在获得焦点前视觉隐藏，键盘聚焦到它时才显示出来。

布局

浮层通过 JavaScript 定位。页面滚动或窗口尺寸变化时会重新计算位置；所选方向空间不足时翻转到另一侧。