antora 默认使用 `![如何在 Antora 文档中启用 SVG 图像的交互式提示（Tooltips）]()
` 标签嵌入 svg，导致原生 `
` 和 `tooltip` 无法显示；通过 asciidoc 的 `opts=interactive` 选项可自动改用 `<object>` 方式加载 svg，从而完整支持交互功能与响应式缩放。</p>
<p>在 Antora 文档中使用 SVG 图像时，若依赖 </p>
<p><title> 元素或 <tspan> 中的 title 实现悬停提示（tooltips），会发现这些提示在页面中完全不生效——这是因为<a style="color:#f60; text-decoration:underline;" title="浏览器" href="https://www.php.cn/zt/16180.html" target="_blank">浏览器</a>对 <img alt="如何在 Antora 文档中启用 SVG 图像的交互式提示（Tooltips）" > 标签加载的 SVG 实施了安全隔离，禁止其执行脚本、响应事件或渲染内联元数据（如 <title>）。而 <object>标签则将 SVG 视为独立文档上下文，完整保留交互能力。</p>
<p>幸运的是，你无需修改 Antora UI 的 CSS、不需重写 doc.<a style="max-width:90%" title="css" href="https://www.php.cn/zt/15716.html" target="_blank">css</a> 中的图片样式（如第 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>标签（而非 <img alt="如何在 Antora 文档中启用 SVG 图像的交互式提示（Tooltips）" >），并自动注入合适的 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><p>⚠️ 注意：width=3072 并非“100% 宽度”，而是设置 SVG 渲染的最大像素宽度（类似 max-width）。由于 不直接支持 width=”100%”（会失效），推荐结合 CSS 实现真正响应式：.content object[type=”image/svg+xml”] {<br />
display: block;<br />
width: 100%;<br />
height: auto;<br />
}将上述 CSS 加入你的 Antora 自定义 UI 的 src/css/doc.css（或通过 supplemental-ui 注入），即可让所有 opts=interactive 的 SVG 自适应容器宽度。</p></blockquote>
<p>此外，opts=interactive 还带来额外收益： </p>
<div class="aritcle_card flexRow">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="https://www.php.cn/ai/1812" title="一览AI绘图"><img
src="https://img.php.cn/upload/ai_manual/000/000/000/175680372760182.png" alt="一览AI绘图"></a></p>
<div class="aritcle_card_info flexColumn">
<a href="https://www.php.cn/ai/1812" title="一览AI绘图">一览AI绘图</a></p>
<p>一览AI绘图是一览科技推出的AIGC作图工具，用AI灵感助力，轻松创作高品质图片</p>
</p></div>
<p> <a href="https://www.php.cn/ai/1812" title="一览AI绘图" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</p></div>
<ul>
<li>支持 SVG 内部 CSS 样式表（<br />
<style>）和 JavaScript（需显式启用 allow-scripts，生产环境慎用）； </style>
</li>
<li>允许通过 CSS 选择器精确控制 SVG 内部元素（如 object svg path:hover { opacity: 0.8; }）； </li>
<li>保持 SVG 矢量缩放质量，无像素化失真。</li>
</ul>
<p>最后提醒：确保你的 SVG 源文件已正确嵌入 </p>
<p><title>（用于基础 tooltip）或使用 aria-label + role=”img” 提升可访问性。例如：</p>
<pre class="brush:php;toolbar:false;">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
<title>用户认证流程：点击展开详情
综上，opts=interactive 是 Antora 场景下启用 SVG tooltip 的最简、最标准、最可持续的方案——零 CSS 修改、零构建配置变更、零前端侵入，仅需一行 AsciiDoc 属性。
https://www.php.cn/faq/2030639.html