Popover 气泡卡片 - Docs - Artefact

Popover 气泡卡片

Overlays

自动交互

Introduction

Popover 组件是一个交互式浮层元素，用于在相对于锚点触发元素的浮动卡片中显示附加详情、操作或上下文表单。

该组件专为我们的零 JS 静态渲染架构和条件式注水模型而构建，使用高效的页面构建器友好绑定。在作为交互式 Preact 孤岛注水以平滑处理切换和 Esc 触发之前，它在 HTML 布局中始终保持完全静态。

Usage

以下示例展示了内容作者如何配置和绑定 Popover 区块。

1. 基础信息型 Popover

一个干净、纯文本的弹出框，非常适合解释术语、提供定义或显示轻量提示消息，而不会使主页面布局变得杂乱。

{
  "type": "popover",
  "triggerText": "Learn More",
  "title": "Data Residency",
  "description": "Your profile data is stored securely in compliant Frankfurt (EU) server nodes."
}

2. 带正文内容与页脚操作的高级 Popover

一个引导式弹出框，包含不同区块：信息头部、正文文本，以及在页脚插槽中嵌套的自定义操作按钮。

{
  "type": "popover",
  "triggerText": "Setup Account",
  "title": "Configure API Integrations",
  "description": "Connect with external tools seamlessly.",
  "body": "Your subscription allows up to 5 concurrent server channels. Ensure your client secret credentials are copied before proceeding.",
  "footer": "Connect Keys",
  "showArrow": true
}

3. 带自定义 SVG 触发器与嵌套子区块的 Popover

对于更复杂的仪表盘面板，弹出框可以嵌入自定义 SVG 触发器（在 triggerIcon 中使用原始标记），并在浮动卡片内渲染子组件列表（如嵌套 Badge、Text 或额外操作按钮）。

{
  "type": "popover",
  "triggerText": "System Status",
  "triggerIcon": "<circle cx=\"12\" cy=\"12\" r=\"10\" /><line x1=\"12\" y1=\"16\" x2=\"12\" y2=\"12\" /><line x1=\"12\" y1=\"8\" x2=\"12.01\" y2=\"8\" />",
  "triggerAriaLabel": "System Operations Status Info",
  "title": "System Heartbeat",
  "description": "Operational health checks",
  "showArrow": true,
  "closable": true,
  "children": [
    {
      "blockType": "badge",
      "text": "API: OK",
      "colorPalette": "green"
    },
    {
      "blockType": "badge",
      "text": "DB: OK",
      "colorPalette": "green"
    }
  ]
}

Props

属性	CMS 字段类型	默认值	描述 / 支持的选项
触发文本 (`triggerText`)	`string`	`"Click me"`	打印在弹出框切换按钮内部的视觉标签。
触发图标 SVG (`triggerIcon`)	`string`	-	要注入触发按钮（与触发文本并列）的原始 SVG 标记元素（例如 `<path d="..." />`）。
触发 ARIA 标签 (`triggerAriaLabel`)	`string`	-	供屏幕阅读器使用的描述性标签。若触发器仅有图标而无文本，则此项为必填。
标题 (`title`)	`string`	-	渲染在弹出卡片顶部的粗体标题文本。
描述 (`description`)	`string`	-	标题下方显示的配套副标题/描述。
正文文本 (`body`)	`string`	-	渲染在弹出框中部的主要段落文本。
页脚文本 (`footer`)	`string`	-	渲染在卡片底部区域的摘要文本或按钮。
显示箭头指示器 (`showArrow`)	`boolean`	`true`	为 true 时，渲染一个从卡片边缘指向触发器的细小视觉尖角。
可关闭 (`closable`)	`boolean`	`true`	在弹出框顶角渲染一个细小的视觉关闭触发按钮。
子区块 (`children`)	`list`	-	嵌套的页面构建器区块（如文本、徽章或按钮），直接附加到弹出框的正文列表中。

Architecture Notes

智能视口边界对齐： 交互式 Preact 孤岛会动态跟踪屏幕空间。若弹出框在视口边缘附近打开，它会自动翻转方向（例如从底部对齐切换为顶部对齐）并沿其轴线偏移，以防止内容被裁剪。
统一事件委托： 打开与关闭交互，以及点击外部关闭和 Esc 键处理，都从弹出框根元素上的中央监听器干净地委托处理。这最大限度地减少了客户端事件绑定。
语义化浮层： Popover 编译为原生、可访问的布局，开箱即用地包含 role="dialog"、aria-haspopup="dialog" 和 aria-expanded="true|false" 等语义属性，确保完全的屏幕阅读器兼容性。

HoverCard 悬浮卡片

Tooltip 文字提示

外观

外观

外观

外观