Gitlab中PlantUML生成的PNG图超链接无法跳转问题求助

复现步骤 #

• 创建测试PlantUML文件：

@startuml
actor User
rectangle "web" {
  usecase uc01 as "Use Case 1 - Start
  ----
  [[https://www.google.co.uk/ Details]]
  "
  usecase uc02 as "Use Case 2 - Stop
  ----
  [[https://plantuml.com/ Details]]
  "
  User --> uc01
  User --> uc02
}
@enduml

• 执行命令生成PNG和cmapx文件：

  java -jar /home/user/Documents/misc/plantuml.jar basic-hyperlink-test.txt
  

  PNG显示超链接，但图片编辑器中无法点击；PlantUML网页端SVG格式超链接正常，PNG不行；Gitlab Wiki中嵌入代码后，点击超链接仅放大PNG，无法跳转。
• 环境：Google Chrome 135.0.7049.85、Microsoft Edge最新版，PlantUML 1.2021.7

解决方法 #

PNG是位图格式，本身不支持内置超链接，PlantUML生成的.cmapx文件是客户端图像映射的HTML代码，需要将PNG和图像映射关联才能实现可点击的超链接，具体操作如下：

1. 提取.cmapx文件中的内容，它的结构类似：

<map name="plantuml_map">
  <area shape="rect" coords="x1,y1,x2,y2" href="目标链接" alt="描述" />
  <!-- 所有超链接的坐标区域定义 -->
</map>

2. 将生成的PNG文件上传到Gitlab（可作为Wiki附件或项目文件），获取PNG的访问路径。

3. 在Gitlab Wiki的Markdown中，使用HTML标签将图像映射与PNG关联：

<map name="plantuml_map">
  <!-- 粘贴cmapx文件中的所有<area>标签内容 -->
  <area shape="rect" coords="..." href="https://www.google.co.uk/" alt="Details" />
  <area shape="rect" coords="..." href="https://plantuml.com/" alt="Details" />
</map>
<img src="/uploads/xxx/basic-hyperlink-test.png" usemap="#plantuml_map" style="border:none;" />

4. 保存Wiki页面后，点击PNG中的对应区域即可触发超链接跳转。

另外，若条件允许，可升级PlantUML到最新版本，部分新版本对Gitlab环境的图像映射支持更友好，但核心逻辑仍需依赖图像映射关联PNG。

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