antora 默认使用 `` 标签嵌入 svg，导致原生 `
` 和 `tooltip` 无法显示；通过 asciidoc 的 `opts=interactive` 选项可自动改用 `<object>` 方式加载 svg，从而完整支持交互功能与响应式缩放。<p>在 Antora 文档中使用 SVG 图像时，若依赖 </p>
<title> 元素或 <tspan> 中的 title 实现悬停提示（tooltips），会发现这些提示在页面中完全不生效——这是因为浏览器对 标签加载的 SVG 实施了安全隔离，禁止其执行脚本、响应事件或渲染内联元数据（如 <title>）。而 <object> 标签则将 SVG 视为独立文档上下文，完整保留交互能力。<p>幸运的是，你无需修改 Antora UI 的 CSS、不需重写 doc.css 中的图片样式（如第 435–440 行），也无需手动注入 <object> 或调整 supplemental-ui 配置。AsciiDoc（由 Asciidoctor 引擎驱动）已原生支持该场景，只需在图像宏中添加 opts=interactive 属性即可：</object></p><pre class="brush:php;toolbar:false;">// ✅ 正确：启用 SVG 交互能力（tooltip、缩放、CSS 样式、JS 响应等）
image::architecture-diagram.svg[系统架构图, opts=interactive, width=3072]</pre><p>该选项会令 Asciidoctor 输出语义正确的 <object> 标签（而非 ），并自动注入合适的 type="image/svg+xml" 与 data 属性，例如：</object></p><pre class="brush:php;toolbar:false;"><object type="image/svg+xml" data="assets/images/architecture-diagram.svg" width="3072">
@@##@@
</object></pre><blockquote>⚠️ 注意：width=3072 并非“100% 宽度”，而是设置 SVG 渲染的最大像素宽度（类似 max-width）。由于 不直接支持 width="100%"（会失效），推荐结合 CSS 实现真正响应式：.content object[type="image/svg+xml"] {
display: block;
width: 100%;
height: auto;
}将上述 CSS 加入你的 Antora 自定义 UI 的 src/css/doc.css（或通过 supplemental-ui 注入），即可让所<p style="text-align:center"><img src="//public-space.oss-cn-hongkong.aliyucs.com/gz/840.jpg" /></p>有 opts=interactive 的 SVG 自适应容器宽度。</blockquote>
<p>此外，opts=interactive 还带来额外收益： </p>
<ul>
<li>支持 SVG 内部 CSS 样式表（<style>）和 JavaScript（需显式启用 allow-scripts，生产环境慎用）； </style>
</li>
<li>允许通过 CSS 选择器精确控制 SVG 内部元素（如 object svg path:hover { opacity: 0.8; }）； </li>
<li>保持 SVG 矢量缩放质量，无像素化失真。</li>
</ul>
<p>最后提醒：确保你的 SVG 源文件已正确嵌入 </p>
<title>（用于基础 tooltip）或使用 aria-label + role="img" 提升可访问性。例如：<pre class="brush:php;toolbar:false;"><!-- sample.svg -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
<title>用户认证流程：点击展开详情
综上，opts=interactive 是 Antora 场景下启用 SVG tooltip 的最简、最标准、最可持续的方案——零 CSS 修改、零构建配置变更、零前端侵入，仅需一行 AsciiDoc 属性。
