antora 默认使用 `` 标签嵌入 svg，导致其中的 `
` 或 `tooltip` 无法显示；通过 asciidoc 的 `opts=interactive` 选项可自动改用 `<object>` 方式嵌入，完美支持 svg 内置提示、缩放与矢量交互，无需修改 css 或 ui 模板。<p>在 Antora 构建的文档中，SVG 图像常被用于展示架构图、流程图等富含语义信息的可视化内容。许多作者会直接在 SVG 源码中添加 </p>
<title> 元素（或使用 toolTip 类库）来提供悬停提示，例如：<pre class="brush:php;toolbar:false;"><!-- sample.svg 片段 -->
<circle cx="50" cy="50" r="30" fill="#4285f4">
<title>用户服务模块：负责身份认证与会话管理
然而，当该 SVG 以 方式嵌入 HTML 时，浏览器完全隔离 SVG 内部结构——所有
、<desc>、JavaScript 和 CSS 均失效，Tooltip 自然不可见。<p>✅ 正确解法：使用 AsciiDoc 原生支持的 opts=interactive<br>
该选项会令 Asciidoctor（Antora 底层渲染引擎）自动将图像渲染为 <object type="image/svg+xml" data="...">，使 SVG 完整上下文（包括 DOM、事件、CSS、标题）在页面中可访问：</object></p><pre class="brush:php;toolbar:false;">// ✅ 推荐写法：启用交互式 SVG
image::architecture.svg[系统架构图,opts=interactive,width=100%]
// <p style="text-align:center"><img src="//public-space.oss-cn-hongkong.aliyucs.com/gz/205.jpg" /></p>⚠️ 注意：width=100% 在 interactive 模式下可能受限于容器
// 若需响应式铺满，建议搭配 CSS 容器控制（见下方）</pre><p>? 补充说明： </p>
<ul>
<li>
<p>width=100% 在 opts=interactive 下<strong>部分浏览器（如 Safari）可能不生效</strong>，因 <object> 默认采用固有尺寸。此时推荐组合使用： </object></p><pre class="brush:php;toolbar:false;">image::diagram.svg[流程图,opts=interactive,width=3072]</pre><p>width=3072 并非固定像素值，而是设为一个足够大的“最大宽度”（max-width），配合 SVG 自身的 viewBox 属性，可实现高质量响应式缩放（矢量无损）。 </p>
</li>
<li>
<p>如需严格 100% 宽度且保持比例，可在 Antora UI 的 doc.css 中追加轻量样式（非必需，但增强兼容性）：</p><pre class="brush:php;toolbar:false;">.imageblock > .content > object {
display: block;
width: 100%;
height: auto;
}</pre></li>
</ul>
<p>? 总结： </p>
<ul>
<li>
<strong>无需修改 Antora UI 的 CSS 或模板文件</strong>（如 doc.css#L435–440）； </li>
<li>
<strong>无需手动替换 为 <object></object></strong>——opts=interactive 由 Asciidoctor 自动处理； </li>
<li>Tooltip、缩放、无障碍描述（<desc>）、甚至内联 JS 交互均可原生支持； </desc>
</li>
<li>对初学者极友好：只需在 AsciiDoc 图像宏中增加一个属性，零前端知识门槛。</li>
</ul>
<p>立即尝试：将你的 image::xxx.svg[alt] 改为 image::xxx.svg[alt,opts=interactive,width=2048]，重建文档即可验证 Tooltip 是否正常悬停显示。</p></desc>
