如何在Antora中用<object>替代<img>显示带提示的SVG？

仅靠CSS无法替换HTML标签，你需要通过Antora的supplemental-ui功能修改图片渲染模板，将默认的<img>标签替换为<object>，同时配合CSS确保布局符合需求。以下是具体步骤：

1. 搭建supplemental-ui目录结构 #

在你的Antora项目的docs目录下，创建如下目录（如果不存在）：

docs/
└── supplemental-ui/
    ├── partials/
    │   └── content/
    └── css/

2. 复制并修改图片渲染模板 #

Antora默认使用image-block.hbs（块级图片）和image-inline.hbs（行内图片）模板渲染图片标签。你需要从Antora默认UI中复制这两个文件到supplemental-ui/partials/content/目录，然后修改内容：

修改image-block.hbs（核心修改） #

将原有的<img>标签替换为<object>，同时添加降级的<img>作为备选：

{{#if (eq target "blank")}}
<a href="{{src}}" target="_blank" rel="noopener noreferrer">
{{/if}}
<object data="{{src}}" type="image/svg+xml" width="100%" {{#if alt}}aria-label="{{alt}}"{{/if}}>
  <!-- 降级方案：浏览器不支持object时显示普通图片 -->
  <img src="{{src}}" alt="{{alt}}" width="100%">
</object>
{{#if (eq target "blank")}}
</a>
{{/if}}

（可选）修改image-inline.hbs #

如果你的文档中有行内SVG需要tooltip，同样修改这个模板：

{{#if (eq target "blank")}}
<a href="{{src}}" target="_blank" rel="noopener noreferrer">
{{/if}}
<object data="{{src}}" type="image/svg+xml" {{#if alt}}aria-label="{{alt}}"{{/if}}>
  <img src="{{src}}" alt="{{alt}}">
</object>
{{#if (eq target "blank")}}
</a>
{{/if}}

3. 添加CSS确保布局正确 #

在supplemental-ui/css/目录下创建custom.css，添加以下样式确保<object>占满容器宽度且高度自适应：

/* 全局设置SVG object的样式 */
object[type="image/svg+xml"] {
  display: block;
  width: 100%;
  height: auto;
}

4. 验证与注意事项 #

• 重新构建Antora文档后，所有SVG图片会自动通过<object>加载，内部的<title>/<desc> tooltip应该能正常显示。
• 降级的<img>标签会在不支持<object>的浏览器中生效，避免图片无法显示。
• 确保SVG文件与文档同域（Antora构建后默认满足），否则可能出现跨域限制导致SVG无法加载。

内容的提问来源于stack exchange，提问作者jj2f1