2.markdown转图片

一灰灰blogQuickMediamarkdown-plugin约 2002 字大约 7 分钟

上一篇讲了 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. 设计思路

整个链路分三步,每一步在插件里都有一个明确的落点:

  1. md 转 html:上一篇的 MarkDown2HtmlWrapper.ofFile/ofContent 干的事,输出一个带 css 的 MarkdownEntity
  2. html 字符串转 Document:借助 nekohtml 的 DOMParser,把 html 字符串解析成 w3c 的 Document 对象
  3. 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 上可配置的参数如下:

参数默认值说明
w600输出图片的宽,同时会作为 html 内容 div 的 width 样式
hnull输出图片的高,为 null 时默认按 1024 起始、最终自适应
autoWtruetrue 表示根据网页的实际宽渲染;false 则按指定的 w 渲染
autoHfalsetrue 表示根据网页的实际高渲染;false 则按指定的 h 渲染
outTypejpg输出图片的格式,jpg、png 等
cssnull自定义样式,设置后替换默认的 MD_CSS
fontFamilynullcss 的 font-family,建议设置通用字体避免乱码
font宋体 18AWT 绘制用字体
fontColornull字体颜色,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 服务器上之后,图片里的中文全部变成了方框「□□□」,但同一张图里用自定义字体绘制的中文签名却正常显示

排查过程:

  1. 第一反应是传参时中文就乱码了,打日志、远程 debug 确认服务收到的就是正常的 utf8 中文,排除
  2. 怀疑编码问题,设置编码格式,依然排除
  3. 直到注意到一个细节:中文签名正常(它显式指定了字体文件),markdown 里的中文乱码(走的是系统默认字体),方向才转到了系统字体支持上
  4. 查资料确认: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 文档)单独拿出来讲

项目地址:

Loading...