1.svg渲染输出图片
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,可读性更好 |
| 渲染格式 | 只支持 png | png / jpg / tiff 三种 |
| 输出方式 | 只返回 BufferedImage | asImg / 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. 其他
项目地址:
- https://github.com/liuyueyi/quick-media
QuickMedia目标是创建一个专注图文,音视频,二维码处理的开源项目
系列博文