2.markdown转图片
上一篇讲了 markdown 转 html,本篇把链路补完:md -> html -> image,直接把一篇 markdown 文档渲染成一张图,常见于公众号图文消息、数据简报推送这类场景
1. 依赖引入
和上一篇一样,依赖 markdown-plugin 即可(已发布到 maven 中央仓库):
<!-- https://mvnrepository.com/artifact/com.github.liuyueyi.media/markdown-plugin -->
<dependency>
<groupId>com.github.liuyueyi.media</groupId>
<artifactId>markdown-plugin</artifactId>
<version>3.1.0</version>
</dependency>
2. 设计思路
整个链路分三步,每一步在插件里都有一个明确的落点:
- md 转 html:上一篇的
MarkDown2HtmlWrapper.ofFile/ofContent干的事,输出一个带 css 的MarkdownEntity - html 字符串转 Document:借助 nekohtml 的
DOMParser,把 html 字符串解析成 w3c 的Document对象 - Document 渲染成图片:借助 xhtmlrenderer 的
Graphics2DRenderer,在 AWT 的Graphics2D画布上做 layout + render,最后落到BufferedImage
其中第 2、3 步被封装在了 Html2ImageWrapper 里,对 markdown 的输入提供了专门的入口 ofMd,所以对使用者来说,两行核心代码就完事:
MarkdownEntity entity = MarkDown2HtmlWrapper.ofFile("md/test.md");
BufferedImage bf = Html2ImageWrapper.ofMd(entity).setW(800).setAutoH(true).build().asImage();
3. 使用姿势
3.1 最简使用
下面这个 case 直接来自插件的测试类 Md2ImgTest,读取本地 md 文档,渲染输出图片并保存到本地:
@Test
public void testMd2Img() throws Exception {
MarkdownEntity entity = MarkDown2HtmlWrapper.ofFile("md/test.md");
BufferedImage bf = Html2ImageWrapper.ofMd(entity)
.setW(800)
.setAutoW(false)
.setAutoH(true)
.setOutType("jpg")
/*
在其他平台最好设置一个通用字体, 否则可能会出现由于字体字库不全而导致的乱码问题
如在win下设置为'微软雅黑'
.setFontFamily("微软雅黑")
*/
.build()
.asImage();
ImageIO.write(bf, "jpg", new File("md_out.jpg"));
System.out.println("---over---");
}
整体是一个链式的三段式姿势:
Html2ImageWrapper.ofMd(entity):传入 markdown 转出来的MarkdownEntity,返回Builder配置对象.setXxx(...):一堆渲染参数,宽高、自适应、输出格式、字体等,见下文参数说明.build().asImage():build()完成 html 解析和参数装配,asImage()输出BufferedImage,此外还有asFile(存文件)和asString(base64 字符串)两种输出方式
3.2 参数说明
Html2ImageWrapper.Builder 上可配置的参数如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
| w | 600 | 输出图片的宽,同时会作为 html 内容 div 的 width 样式 |
| h | null | 输出图片的高,为 null 时默认按 1024 起始、最终自适应 |
| autoW | true | true 表示根据网页的实际宽渲染;false 则按指定的 w 渲染 |
| autoH | false | true 表示根据网页的实际高渲染;false 则按指定的 h 渲染 |
| outType | jpg | 输出图片的格式,jpg、png 等 |
| css | null | 自定义样式,设置后替换默认的 MD_CSS |
| fontFamily | null | css 的 font-family,建议设置通用字体避免乱码 |
| font | 宋体 18 | AWT 绘制用字体 |
| fontColor | null | 字体颜色,int 值(高两位是透明度,别省略 0xff) |
重点说一下宽高的自适应逻辑,这块藏在渲染实现里,理解了才不会疑惑为什么生成的图有白边或者内容被裁掉:
autoH = true或者h == null时,渲染是两遍进行的:先用临时画布 layout 一遍,拿到内容的实际尺寸getMinimumSize(),然后按实际宽高重新创建画布再渲染;所以最终图片的高度是「刚好装下内容」的高度- 两遍 layout 中,实际宽由
autoW决定:autoW = true时用内容的真实宽,autoW = false时用你设置的w autoH = false且指定了h时,就是固定宽高,内容超出会被裁掉,不足则留白
对于 markdown 这种内容长短不固定的输入,比较推荐的组合是:setW(800).setAutoW(false).setAutoH(true),宽固定、高自适应
3.3 换一套主题 css
默认的 huimarkdown.css 不合口味时,可以像上一篇那样换主题,测试类里的 testMd2Img2 演示了换 heyrain.css 的用法:
@Test
public void testMd2Img2() throws Exception {
MarkdownEntity entity = MarkDown2HtmlWrapper.ofFile("md/test.md");
entity.setCss(MarkDown2HtmlWrapper.buildCssContent("md/heyrain.css"));
File file = new File("out.html");
FileOutputStream out = new FileOutputStream(file);
out.write(entity.toString().getBytes());
out.flush();
out.close();
BufferedImage bf = Html2ImageWrapper.ofMd(entity)
.setW(500)
.setAutoW(false)
.setAutoH(true)
.setOutType("jpg")
/*
在其他平台最好设置一个通用字体, 否则可能会出现由于字体字库不全而导致的乱码问题
如在win下设置为'微软雅黑'
.setFontFamily("微软雅黑")
*/
.build()
.asImage();
ImageIO.write(bf, "jpg", new File("md_out_2.jpg"));
System.out.println("---over---");
}
中间那几行把 entity.toString() 输出到 html 文件的代码不是废话——调试样式的时候,先落一个 html 文件用浏览器打开看效果,比反复跑渲染出图快得多,推荐养成这个习惯
4. build 的时候发生了什么
build() 里的逻辑值得单独拎出来讲,因为它决定了哪些参数真正生效:
public Html2ImageWrapper build() throws Exception {
HtmlRenderOptions options = new HtmlRenderOptions();
// ... 参数装配,省略 ...
if (document != null) {
options.setDocument(document);
} else if (css != null) {
html.setCss(css);
options.setDocument(parseDocument(html.toString()));
} else {
// 没有指定css时,默认配置
if (fontColor != null) {
html.addDivStyle("style", "color:" + options.getFontColor() + ";");
}
if (fontFamily != null) {
html.addDivStyle("style", "font-family:" + fontFamily + ";");
}
html.addDivStyle("style", "width:" + w + ";");
html.addWidthCss("img");
html.addWidthCss("code");
options.setDocument(parseDocument(html.toString()));
}
return new Html2ImageWrapper(options);
}
注意中间那个 else if (css != null) 分支:一旦你通过 Builder 设置了 css,fontColor、fontFamily、width 这些默认处理就全被跳过了,样式完全由你设置的 css 接管。所以走自定义 css 的路子时,字体、颜色、宽度都得自己在 css 里写清楚,不能指望 Builder 上的 set 方法
而走默认分支(不设置 css)时,插件会自动帮你做几件事:
- 把
fontColor、fontFamily拼成 style 追加到外层 div 上 - 给 div 加
width:600px(跟着参数 w 走) - 给 img、code 标签追加
width:85%的限制,防止大图和长代码块撑破画布
5. 中文乱码采坑
这是个实打实的线上坑,完整记录在项目的 docs 采坑目录里:《markdown转图片中文乱码》
问题表征:本机(mac)测试 markdown 转图片一切正常,扔到阿里云的 linux 服务器上之后,图片里的中文全部变成了方框「□□□」,但同一张图里用自定义字体绘制的中文签名却正常显示
排查过程:
- 第一反应是传参时中文就乱码了,打日志、远程 debug 确认服务收到的就是正常的 utf8 中文,排除
- 怀疑编码问题,设置编码格式,依然排除
- 直到注意到一个细节:中文签名正常(它显式指定了字体文件),markdown 里的中文乱码(走的是系统默认字体),方向才转到了系统字体支持上
- 查资料确认:JRE 默认不带中文字体,linux 服务器上又通常没装中文字体,AWT 绘图时中文自然就成了方框
解决方案:给 JRE 装上中文字体,比如宋体
// 登录到服务器
// 下载字体(项目 common 模块的 resources 下有 simsun.ttf)
wget https://github.com/liuyueyi/quick-media/tree/master/common/src/main/resources/font/simsun.ttf
// 安装字体, jdk 的目录与实际环境相关
cp simsun.ttf /usr/local/jdk/jre/lib/fonts/
然后重启应用,问题解决
经验总结:
- 服务端做中文图片渲染,部署前先检查 JRE 字体目录,别等线上图片出方框了再补
- 保险起见,调用链上用
setFontFamily()显式指定一个目标环境存在的中文字体(win 下如「微软雅黑」),让行为不依赖环境默认值 - 出问题时多对比「正常的部分」和「异常的部分」差在哪,本案例里差异就是字体来源,这个线索其实一开始就摆在眼前
6. 小结
本篇把 md -> html -> image 的完整链路走了一遍,重点在 Builder 参数和 build() 的分支逻辑;下一篇我们把 Html2ImageWrapper 的另外两个入口(纯 html 片段、完整 html 文档)单独拿出来讲
项目地址:
- https://github.com/liuyueyi/quick-media
QuickMedia目标是创建一个专注图文,音视频,二维码处理的开源项目