2.svg模板渲染

一灰灰blogQuickMediasvg-plugin约 3559 字大约 12 分钟

上一篇介绍了 svg 渲染输出的基本姿势,但只做到"一个 svg 进、一张图片出"还不够。实际业务里更常见的场景是:图的整体样式是固定的,变化的只有个别文字、价格、时间或者配图——比如个人名片、商品海报、分享卡片。这种场景下,把 svg 当作模板、按标签 id 传参替换,才是 svg-plugin 的正确打开方式。

1. 场景与思路

先看一个典型的需求:我们要给一批商品生成分享海报,海报的背景、排版、字体都一样,但每个商品的图片、价格、时间不一样。

两种做法:

  • 做法 A:每种商品画一张 svg,各自渲染。模板数量爆炸,改一个样式要改 N 份
  • 做法 B:只维护一份 svg 模板,把会变化的部分打上 id 标记,渲染时传入不同参数,插件把对应标签的内容/属性替换掉,再输出图片

svg-plugin 走的是做法 B。它的实现思路也很直白:把 svg 解析成 DOM Document 结构,然后按 id 查找标签(document.getElementById(key)),替换标签的正文或属性,最后交给 batik 渲染输出。

所以使用模板渲染的前提只有一个:在 svg 模板里,给需要动态替换的元素加上 id 属性。

2. 基本姿势:addParams 按标签 id 替换

最简的传参方式,addParams(标签id, 替换内容),value 直接传 String,表示把这个标签的正文内容替换掉:

SvgRenderWrapper.of(svg)
        .addParams("svg_2", "当前金额: ¥1314.00")
        .addParams("svg_3", "当前时间: " + LocalDateTime.now())
        .asFile("/tmp/i1.jpg");

对应的 svg 模板片段(节选):

<text ... id="svg_2" ... fill="#000000">¥1314.00</text>
<text ... id="svg_3" ... fill="#999999">2017-01-28 11:02:01</text>

传参之后,两个 text 标签中间的文本分别被替换为 "当前金额: ¥1314.00" 和 "当前时间: xxx"。标签上原有的字体大小、坐标、颜色等样式一概保留,只动内容。

同样可以批量传参,效果等价:

Map<String, Object> map = new HashMap<>();
map.put("price", "当前金额: ¥1314.00");
map.put("time", "当前时间: " + LocalDateTime.now());
SvgRenderWrapper.of(svg).setParams(map).asFile("/tmp/i1.jpg");

3. 正文替换 vs 属性替换

只替换正文显然不够用,有时我们还想改颜色、字号、坐标这些属性。这时传参的 value 换成 Map:

  • key 为 svgContent(保留关键字):表示这一项是替换标签正文
  • 其他的 key/value:表示替换标签的同名属性

一个实例传参如下,表示需要替换 id=svg_3 标签的正文内容和 fill 属性:

{
  "svg_3": {
    "svgContent": "替换后的内容",
    "fill": "#ff0000"
  }
}

对应到代码里:

SvgRenderWrapper.of(svg)
        .addParams("svg_2", "金额: ¥520.00")
        // svgContent 表示替换标签内容值; 后面的 fill: #ff0000 表示替换标签的属性值
        .addParams("svg_3", newMap("svgContent", "当前时间: " + LocalDateTime.now(), "fill", "#ff0000"))
        .asFile("/tmp/i2.jpg");

newMap 是测试代码里组装 Map 的便捷小工具,实现就是把 k/v 依次塞进 HashMap,此处不再展开。

两种替换方式放在一起对比最直观,下面是同一个模板两次不同传参的渲染输出:

正文替换正文 + 属性替换

请注意上面两张图的差别:

  • 价格
  • 图片
  • 时间及颜色

几个容易踩的坑,这里强调一下:

  • svgContent 是保留关键字,在 Map 传参里它单独表示"替换正文",请不要拿它当属性名用
  • 当 value 是 String 时,addParams("svg_2", "xxx") 是 {"svg_2": {"svgContent": "xxx"}} 的简写形式,两者效果一致
  • 属性替换本质是 element.setAttribute(key, value),属性名要和 svg 里的写法对得上(如 fill、font-size、stroke)

4. image 与 a 标签的替换

对于 image 标签,它的"内容"实际上并不是两个标签中间的文本,而是 xlink:href 属性的值,所以插件做了特殊处理:

  • 对 image、a 标签,传 String 等价于替换 xlink:href(图片地址/跳转地址)
  • Map 传参时,key 为 href 或 xlink:href 的项,也会按"替换链接"来处理,而不是当作普通属性覆盖

也就是说,下面两种写法,都是在替换 id=svg_1 这个 image 标签的图片地址:

// 1. 直接传图片地址(推荐,最简洁)
SvgRenderWrapper.of(svg).addParams("svg_1", "https://spring.hhui.top/spring-blog/imgs/221026/logo.jpg").asImg();

// 2. Map 传参,用 xlink:href 或 href 做 key,效果相同
SvgRenderWrapper.of(svg).addParams("svg_1", newMap("xlink:href", "https://spring.hhui.top/spring-blog/imgs/221026/logo.jpg")).asImg();

对于 a 标签,传 String 替换的是跳转链接(xlink:href);如果需要替换 a 标签里 text 子标签的显示文字,请给那个 text 单独设置一个 id,用它的 id 来替换正文。

5. 一个完整的模板 + 传参 case

把上面的知识点串起来,看一个完整的例子。下面是一张 480x855 的分享卡片模板,包含一个配图(id=img)、一个价格(id=price)、一个时间(id=time),以及一个跳转源码地址的超链接(id=source_link 内嵌 id=source 的 text):

private static final String TPL = "<svg width=\"480\" height=\"855\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n" +
        "  <!-- defs 略:定义了一个 id=svg_2_blur 的高斯模糊 filter,供下方 text 引用 -->" +
        "  <g>\n" +
        "    <image xlink:href=\"https://spring.hhui.top/spring-blog/css/images/avatar.jpg\" id=\"img\" height=\"480\" width=\"480\" y=\"-1\" x=\"1\"></image>\n" +
        "    <text filter=\"url(#svg_2_blur)\" opacity=\"0.75\" text-anchor=\"start\" font-family=\"Euphoria, sans-serif\" font-size=\"35\" id=\"price\" y=\"500\" x=\"160.49442\" fill=\"#000000\">¥1314.00</text>\n" +
        "    <text text-anchor=\"start\" font-family=\"Euphoria, sans-serif\" font-size=\"18\" id=\"time\" y=\"525\" x=\"208.5\" fill=\"#999999\">2023-05-31 08:08:08</text>\n" +
        "    <a xlink:href=\"https://github.com/liuyueyi/quick-media\" target=\"_blank\" id=\"source_link\">\n" +
        "    \t<text font-family=\"Euphoria, sans-serif\" font-size=\"18\" y=\"525\" x=\"28.5\" fill=\"#dd0000\" id=\"source\">项目源码地址</text>\n" +
        "    </a>\n" +
        "  </g>\n" +
        "</svg>";

@Test
public void testGenImg() {
    // 传参直接为String,表示替换默认标签内的content
    // 对于image, a标签,表示替换的时 xlink:href 跳转地址
    Map<String, Object> map = new HashMap<>();
    map.put("price", "当前金额: ¥1314.00");
    map.put("time", "当前时间: " + LocalDateTime.now());
    map.put("source", "QuickMedia源码地址");
    map.put("img", "https://spring.hhui.top/spring-blog/imgs/info/wx.jpg");

    // 输出替换后的svg文本
    String svg = SvgRenderWrapper.of(TPL).setParams(map).asSvg();
    System.out.println(svg);

    // 或者直接渲染为图片落盘
    SvgRenderWrapper.of(TPL).setParams(map).asFile("/tmp/card.jpg");
}

传参映射关系一目了然:

标签传参 key替换效果
<image id="img">img替换图片地址
<text id="price">price替换正文"¥1314.00"
<text id="time">time替换正文时间
<text id="source">source替换链接的显示文字

再进阶一点,替换正文的同时改属性(价格换成蓝色、时间换成红色):

@Test
public void testGenImgV2() {
    Map<String, Object> map = new HashMap<>();
    // 直接替换id=time标签的content
    map.put("time", "当前事件:" + LocalDateTime.now());

    // 将标签的内容替换为指定值,并修改颜色
    Map<String, Object> priceMap = new HashMap<>();
    priceMap.put(SvgDocumentHelper.SVG_CONTENT_REPLACE_KEY, "当前金额:¥1314.00");
    priceMap.put("fill", "#0000ff"); // 属性修改,将颜色替换为蓝色
    map.put("price", priceMap);

    // 替换id=img的标签内容 + 修改高度
    Map<String, Object> imgMap = new HashMap<>();
    imgMap.put("xlink:href", "https://spring.hhui.top/spring-blog/imgs/info/wx.jpg");
    imgMap.put("height", "300");
    map.put("img", imgMap);

    String svg = SvgRenderWrapper.of(TPL).setParams(map).asSvg();
    System.out.println(svg);
}

其中 SVG_CONTENT_REPLACE_KEY 就是 SvgDocumentHelper 里定义的保留字常量,值为 "svgContent",用常量比手写字符串更稳。

6. 缓存提效

模板渲染有一个天然的优化点:同一份模板通常会被反复传参渲染,而每次渲染最耗时的操作之一,是把 svg 文本解析成 DOM Document。为此插件内置了 Document 结构的缓存,链式调用里加一个 setCacheEnable(true) 即可开启(官方 readme 中的原话是:对于模板渲染的 case,可以有效提高渲染效率)。

默认规则(来自 SvgRenderWrapper#build() 的源码逻辑):

  • 当 param 传参非空时,开启缓存
  • 当 param 传参为空时,关闭缓存

主动设置的 cacheEnable 的优先级最高,会覆盖默认的规则。

关于缓存的实现细节,SvgDocumentHelper 内部是一个 ConcurrentHashMap<String, Document>,缓存的是"svg 字符串 -> 解析后的 Document",所以只要模板字符串不变,不管传什么参数,命中的都是同一份缓存;每次取缓存时会 cloneNode(true) 深拷贝一份返回,参数替换都是改在拷贝上,不会污染缓存对象——这就是它可以放心复用同模板的原因。

默认最多只缓存 100 个模板对象(CACHE_MAX_SIZE = 100),达到上限后新模板将不再进缓存;如果模板数量比较多,可以通过 setCacheSize() 来更新缓存大小:

SvgRenderWrapper.of(svg)
        .addParams("svg_2", "金额: ¥520.00")
        .setCacheSize(500) // 缓存上限调整为500个模板
        .asFile("/tmp/i2.tiff");

顺带提醒两点:

  • 缓存的 key 是完整的 svg 字符串/路径本身,所以请不要用同一份"字符串拼接"的模板(比如把动态参数直接拼进 svg 文本),那样每个参数组合都会生成一个新 key,缓存就废了;正确姿势是参数全部走 addParams
  • 缓存上限判断是"满了就不再放"的简单策略,不是 LRU 淘汰,模板种类可以预估的话,给个合理的 cacheSize

7. 注意事项

模板渲染的规则不多,但有几个点容易踩坑,集中列一下:

  • 当前仅支持根据标签 id 来实现参数替换;根据 name 传参替换有 bug,因此暂不支持,请给需要替换的元素都加上 id
  • id 在整个 svg 文档内需要唯一,getElementById 只会命中第一个
  • svgContent 是保留关键字,只用来表示"替换标签正文",不要挪作他用
  • image/a 标签的 String 传参替换的是链接地址,不是标签正文;href/xlink:href 的 Map 传参也会被按链接处理
  • 属性替换走 setAttribute,属性名务必与 svg 中的写法一致
  • 替换后的文本如果包含 xml 特殊字符(<、& 等),注意转义,否则模板可能解析失败
  • 模板渲染默认开启缓存,若 svg 文本是运行时动态生成的(每次都不同),建议显式 setCacheEnable(false),避免缓存被无意义的 key 占满

8. 适用场景

svg 模板渲染的甜点区,是那种一套版式、批量出图的场景:

  • 个人名片/推广卡片:模板固定,换名字、简介、头像、二维码
  • 商品分享海报:换商品图、价格、活动时间
  • 邀请函/证书/奖状:换姓名、编号、日期
  • 运营分享图:换标题、配图、跳转链接

如果业务是完全动态的排版(内容多少、布局都随机),svg 模板反而不合适,那个场景更适合 image-plugin 的图文合成能力,或者是 html2image 的方案。

9. 旧版本(3.0.0 及之前)用法对比

3.0.0 及之前的版本,模板渲染的姿势是集中传参的静态方法,与最新版本并不通用,强烈推荐使用最新版本。

/**
 * 将SVG转换成PNG
 *
 * @param path     可以是http开头的SVG文件路径;可以是<svg开头的纯svg内容
 * @param paramMap 变更参数键值对,key为svg元素Id value为替换内容
 */
public static BufferedImage convertToJpegAsImg(String path, Map<String, Object> paramMap);
  • path: svg 的文本内容;或者 http 地址对应的 svg 模板
  • paramMap: 则表示替换的参数,目前只支持根据 id 进行替换

新旧版本在模板能力上的核心差异:

对比项旧版(≤3.0.0)新版(3.0.1+)
传参方式paramMap 一次性传入addParams 链式传参,可分步构建
替换粒度只支持按 id 替换标签正文正文替换 + 属性替换 + image/a 链接替换
缓存控制内部固定开启,不可配置cacheEnable 开关 + setCacheSize 可配置
输出只返回 BufferedImageasImg/asStream/asBytes/asFile/asSvg

旧版内部的缓存思路与新版一脉相承:考虑到某些 svg 模板是通用的,只是部分图片或文字有些微的区别,所以通过 paramMap 来实现对 svg 内容的替换;为了提升性能,内部对 svg 模板解析出的 Document 做了缓存,而允许这么做的原因,就是 Document 对象提供了深拷贝的接口。

最后友情贡献一个旧版本时代的个人名片生成 svg 模板(完整版可查看官方 readme,下面是保留了骨架的关键部分),拿去稍作改造就能用:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="610" height="240">
  <!-- style 块略:通过 #title / #title2 / #name / #ownDesc / #qrDesc 等 id 选择器定义各级文字样式 -->
  <rect class="bgcolor" x="0" y="0" height="100%" width="100%"/>
  <text y="16" x="50%" id="title" lengthAdjust="spacing" rotate="5" textLength="33%">一灰灰Blog</text>
  <svg width="270" height="230">
    <image y="45" height="90" width="62%" xlink:href="logo.jpg地址" id="logo"/>
    <text x="205" y="72" id="name">一灰灰Blog</text>
    <!-- 中部的 github/sina/juejin 简介 tspan、个人简介 ownDesc 标签略 -->
    <text y="170" x="50%" id="ownDesc">全栈转AI ing,不定时分享个人学习收获</text>
  </svg>
  <svg width="150" height="230" x="270">
    <image y="30" width="100%" height="160" xlink:href="公众号二维码地址" id="qrCode"/>
    <text y="200" x="50%" id="qrDesc">一灰灰Blog微信公众号</text>
  </svg>
  <svg width="150" height="230" x="430">
    <image y="30" width="100%" height="160" xlink:href="推广二维码地址" id="qrCode2"/>
    <text y="200" x="50%" style="font-size:12px;fill:#E02222">Hello LLM教程入门</text>
  </svg>
  <text y="235" x="50%" id="title2" lengthAdjust="spacing" textLength="60%">获取技术干货,共同学习成长</text>
</svg>

注意上面模板里的两个二维码 image 标签,原来都叫 id="qrCode",用模板传参时会导致其中一个被 getElementById 命中、另一个永远替换不到——所以我改成了 qrCode2。这正是"id 必须唯一"的活案例。

这个名片的实际输出效果如下:

card
card

10. 其他

项目地址:

系列博文

Loading...