1.svg渲染输出图片

一灰灰blogQuickMediasvg-plugin约 3012 字大约 10 分钟

svg 是矢量图,前端写海报、名片、证书这类"模板型"图非常顺手,改改文字调调样式就能出新图;但业务上我们往往需要的是一张实实在在的 jpg/png 图片(比如保存、分享、发给下游服务)。svg-plugin 做的就是这件事:把 svg 渲染成图片,对上层使用者只暴露一个 SvgRenderWrapper,一行链式调用搞定。

本篇作为 svg-plugin 的第一篇,先介绍最基础的使用姿势:如何引入依赖、如何把一个 svg 渲染输出为图片,以及输出方式、渲染格式的各种细节。

1. 问题背景

在介绍使用姿势之前,先聊一下这个插件的典型使用场景。

常见的做法是这样的:设计同学或者我们自己,用 svg 画好一张图的底稿——比如一张带背景图、价格、时间占位的商品海报,或者一张个人名片。svg 本质上就是一段 xml 文本,里面的文字、图片、坐标都是可以程序改写的,这就给了后端一个"程序化出图"的机会:

  • 把 svg 当作模板,传不同的参数(价格、时间、图片地址),渲染出不同的图片
  • 一次性把 svg 转成 jpg/png,供后续的业务流程使用

svg-plugin 内部借助的是 Apache Batik(Java 世界里最主流的 svg 渲染库)来完成 svg -> 位图的转换,并在这个基础上做了模板传参、输出方式封装、缓存提效等增强。本篇聚焦在"渲染输出"这个基本能力上,模板传参请移步下一篇。

需要提前说明的一点是:svg 渲染涉及字体、透明度、混合模式等一堆细节,实际测试下来这个接口的性能并不算特别出色,但对于常规的使用场景(单次渲染、模板 + 缓存的批量渲染)还是完全 ok 的。

2. 依赖引入

项目已发布到 maven 中央仓库,因此无需额外操作,直接依赖即可

对于 maven 进行项目管理,可以在 pom.xml 文件中,添加下面的依赖,请注意使用最新的版本

<!-- https://mvnrepository.com/artifact/com.github.liuyueyi.media/svg-core -->
<dependency>
    <groupId>com.github.liuyueyi.media</groupId>
    <artifactId>svg-core</artifactId>
    <version>3.1.0</version>
</dependency>

对于 gradle 进行项目管理,可以在 gradle 文件中,添加下面的依赖

// https://mvnrepository.com/artifact/com.github.liuyueyi.media/svg-core
implementation 'com.github.liuyueyi.media:svg-core:3.1.0'

引入 svg-core 之后,batik 相关的依赖(batik-transcoder、batik-anim 等)以及一个 batik-codec-fix 包会自动带入,不需要我们再显示添加,关于 batik-codec-fix 的作用,见后文的说明。

3. 基本使用姿势

直接将 svg 文件渲染为图片,最简的姿势如下:

public void testPng() {
    BufferedImage img = SvgRenderWrapper.of("test.svg")
            .setType(RenderType.JPG) // 默认输出图片为png格式,因此当输出png时,可以省略这个参数设置
            .asImg();
    System.out.println("---");
}

整个过程与 quick-media 系列插件的其他插件一致,都是 of() -> 配置 -> asXxx() 三段式:

  • SvgRenderWrapper.of(svg):传入 svg,返回 SvgRenderWrapper.Builder 对象
  • 中间的链式调用都是配置项:setType() 设置输出图片格式,addParams() 模板传参(下一篇重点介绍),setCacheEnable()/setCacheSize() 缓存设置
  • asXxx():触发渲染并输出,输出方式见下一节

3.1 of() 的传参说明

of() 的传参非常的灵活,可以是下面任意一种:

  • svg 的文件地址:
    • 本地绝对路径,如 d:/quick-media/test.svg
    • 本地相对路径,如 test.svg,相对的是 classpath,适合把模板放在 resources 目录下
    • 网络地址,如 https://xxx.com/test.svg(http 开头)
  • svg 的文本内容:以 <svg 开头的一段 svg 字符串,适合模板文件写在代码里、或者从数据库/配置中心读取的场景

内部判断逻辑很简单,of() 传参如果以 <svg 开头,就当作 svg 正文直接解析;否则当作文件路径处理(http 开头走网络,否则按 classpath 相对路径解析后加载)。

3.2 四种输出方式

当前支持四种输出方式,覆盖了绝大多数的使用场景:

输出方式返回值典型场景
asImg()BufferedImage拿到图片对象,继续在 Java 里处理(如再合成、再加水印)
asStream()ByteArrayOutputStream需要 IO 流的场景,如直接写往响应流返回给前端下载
asBytes()byte[]需要字节数组的场景,如直接上传 oss、存入数据库
asFile(fileName)void直接落盘保存

另外还有一个隐藏玩法 asSvg():它不做位图渲染,而是完成模板传参之后,将 svg 的 Document 结构重新序列化为 svg 字符串返回。适合"先在 svg 层面替换参数,再把 svg 文本丢给前端或者另一个渲染流程"的场景。

asFile 的两个贴心细节(来自源码 SvgRenderWrapper#autoInitRenderType 与 UriUtil#initFile):

  • 输出文件时,会自动根据文件名后缀,来设置渲染图片类型,如 save.jpg 表示将 svg 渲染为 jpg 格式图片(此时可以省略 setType())
  • 输出文件时,若指定文件的父目录不存在,会递归的创建父目录,无需担心路径不存在的异常

比如下面的用法就是完全合法的:

// 类型、路径都不用操心,直接写
SvgRenderWrapper.of("test.svg").asFile("/tmp/svg/save.jpg");

如果不带文件后缀,如 asFile("/tmp/out"),则会默认按 png 渲染,并自动补上后缀保存为 /tmp/out.png;如果带了不认识的后缀(比如 .gif),则会直接抛 IllegalArgumentException——当前只支持 jpg/png/tiff 三种,明确报错比渲染出一张坏图要友好。

3.3 渲染类型 RenderType

当前支持将 svg 渲染为 jpg、png、tiff 三种格式图片,对应的枚举是 RenderType:

  • png: .setType(RenderType.PNG)
  • jpg: .setType(RenderType.JPG)(RenderType.JPEG 与之等价,都对应 batik 的 JPEGTranscoder)
  • tiff: .setType(RenderType.TIFF)

默认输出的是 png 格式,所以输出 png 时 setType() 可以省略。

需要注意 png 是无损格式且支持透明,svg 里的透明背景、半透明元素可以原样保留;jpg 不支持透明,透明区域会被填充成实色(通常是白底),如果模板里有大量透明元素,输出 jpg 时视觉上可能会和预期有出入。

tiff 需要额外依赖

说明,当希望渲染图片为 tiff 格式时,对于 jdk8 及之下的版本,由于 jdk 本身不支持 tiff 图片,因此需要使用第三方插件来适配,所以请在 pom 中额外添加依赖:

<!-- https://mvnrepository.com/artifact/com.twelvemonkeys.imageio/imageio-tiff -->
<dependency>
  <groupId>com.twelvemonkeys.imageio</groupId>
  <artifactId>imageio-tiff</artifactId>
  <version>3.9.4</version>
</dependency>

jdk9 及之后的版本自带 tiff 的读写支持,不需要额外加这个依赖。svg-core 内部对该依赖使用的是 provided 范围,即按需引入。

4. 完整示例

下面这段 svg 模拟了一张个人名片:左边是图片 + 名字 + 简介,右边是一个公众号推广位,直接复制即可运行:

@Test
public void testRender() {
    String svg = "<svg width=\"480\" height=\"240\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n" +
            "    <rect fill=\"#ffffff\" style=\"stroke:#e6e6e6;stroke-width:2\" id=\"canvas_background\" height=\"100%\" width=\"100%\" y=\"0\" x=\"0\"/>\n" +
            "    <svg width=\"300\" height=\"230\">\n" +
            "        <image y=\"40\" width=\"100%\" height=\"80\" text-anchor=\"middle\" xlink:href=\"http://s3.mogucdn.com/mlcdn/c45406/171105_4keid4g9cbh13eeg3l78e6fae325j_640x960.jpg_220x330.jpg\"/>\n" +
            "        <text y=\"150\" x=\"50%\" font-size=\"18\" text-anchor=\"middle\" style=\"display: block;\">小灰灰Blog</text>\n" +
            "        <text y=\"170\" x=\"50%\" font-size=\"14\" text-anchor=\"middle\" fill='#bbb'>\n" +
            "            <tspan y=\"180\" x=\"50%\">\n" +
            "                码农界新人,Java搬运工一枚\n" +
            "            </tspan>\n" +
            "            <tspan y=\"200\" x=\"50%\">\n" +
            "                关注不定时分享各种边缘or好用知识点\n" +
            "            </tspan>\n" +
            "        </text>\n" +
            "    </svg>\n" +
            "    <line x1=\"300\" y1=\"20\" x2=\"270\" y2=\"220\" style=\"stroke:#e6e6e6;stroke-width:1\"/>\n" +
            "    <svg width=\"170\" height=\"230\" x=\"300\">\n" +
            "        <image y=\"30\" width=\"100%\" height=\"160\" text-anchor=\"middle\" xlink:href=\"https://static.oschina.net/uploads/img/201707/09205944_0PzS.jpg\">\n" +
            "        </image>\n" +
            "        <text y=\"200\" x=\"50%\" font-size=\"12\" text-anchor=\"middle\" fill=\"#999\">\n" +
            "            长按或扫一扫关注\n" +
            "        </text>\n" +
            "    </svg>\n" +
            "</svg>";
    SvgRenderWrapper.of(svg).asFile("/tmp/svg/save.jpg");
    System.out.println("渲染图片完成!");
}

渲染输出的图片效果如下:

效果图

此处应展示渲染输出的名片效果图,实际输出图可运行上方示例后查看;同款模板的渲染效果可参考官方文档中的名片样图。

再演示一下几种输出方式的切换,同一个 svg,四种姿势拿到结果:

// 1. 输出文件,根据后缀自动按 jpg 渲染
SvgRenderWrapper.of("test.svg").asFile("/tmp/out.jpg");

// 2. 输出图片对象,默认 png
BufferedImage img = SvgRenderWrapper.of("test.svg").asImg();

// 3. 输出字节
byte[] bytes = SvgRenderWrapper.of("test.svg").setType(RenderType.TIFF).asBytes();

// 4. 输出流
ByteArrayOutputStream stream = SvgRenderWrapper.of("test.svg").asStream();

// 5. 模板传参后输出 svg 文本(不做位图渲染)
String newSvg = SvgRenderWrapper.of("test.svg").addParams("svg_2", "替换文本").asSvg();

5. batik-codec-fix 是什么

如果去翻 svg-plugin 的源码,会发现 plugin 下面有两个模块:batik-codec-fix 与 svg-core。前面的项目是针对 batik 项目的源码做的一些小改造,把 batik 的 png/jpg/tiff 编解码器(codec 包下的 ImageIOPNGImageWriter、PNGRed 那一大坨类)重新打进了一个 jar,通过 SPI 的方式注册进 batik,确保在新的 batik 版本(当前使用 1.16)下 png 图片可以正常输出。

对于使用者而言,这一层是完全透明的:svg-core 已经依赖了 batik-codec-fix,我们只需要引入 svg-core 一个包,无需关心它的存在;知道它的用途,是为了在排除问题、或者好奇"为什么 batik 官方包渲染 png 会翻车"时,有个方向。

6. 注意事项小结

  • of() 传参要么以 <svg 开头(svg 文本),要么是文件路径;一个普通字符串两边都靠不上时会解析失败
  • 默认输出 png;输出 jpg 时注意透明区域的填充问题
  • tiff 输出在 jdk8 及以下需要额外引入 imageio-tiff
  • asFile() 会根据后缀自动决定渲染格式,未识别的后缀会直接抛异常
  • 渲染性能不算突出,模板场景请配合缓存使用(下一篇介绍),单次渲染的大尺寸 svg 也不建议做成高频接口

7. 旧版本(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);

新旧版本的主要差异:

对比项旧版(≤3.0.0)新版(3.0.1+)
入口静态方法直接传参链式 Builder,可读性更好
渲染格式只支持 pngpng / jpg / tiff 三种
输出方式只返回 BufferedImageasImg / asStream / asBytes / asFile / asSvg
模板传参paramMap 集中传addParams 链式传,支持属性替换

旧版的使用示例(新版写法见下一篇):

Map<String, Object> paramMap = new HashMap<>();
paramMap.put("svg_2", "当前金额: ¥1314.00");
BufferedImage img = SvgRenderWrapper.convertToJpegAsImg("<svg ...>...</svg>", paramMap);

旧版本也内置了模板 Document 的缓存(考虑到 svg 模板通常只有部分文字或图片有差异,缓存解析后的 Document,通过深拷贝来保证每次填充参数互不影响),这一点在新版本中保留并强化了:缓存开关可配置、缓存大小可配置。关于模板渲染与缓存的细节,请看下一篇 2.svg模板渲染。

8. 其他

项目地址:

系列博文

Loading...