把飞书云文档变成HTML邮件：问题挑战与解决历程

一、背景

云文档转HTML邮件

基于公司内部的飞书办公套件，早在去年6月，我们就建设了将飞书云文档转译成HTML邮件的能力，方便同学们在编写邮件文档和发送邮件时，都能有较好的体验和较高的效率。

当下问题

要被邮件客户端识别，飞书云文档内容需要转译成HtmlEmail格式，该格式为了兼容各种版本的邮箱客户端（特别是Windows Outlook），对于现代HTML5和CSS3的很多特性是不支持的，飞书云文档的多种富文本块格式都需要转译，且部分格式完全不支持，造成编辑和预览发送不一致的情况。

因此，我们对转译工具做了一次大改版和升级，对大部分常用文档块做了高度还原。

实现效果

经过我们的不懈努力，最终实现了较为不错的还原效果：

二、系统架构改版

飞书云文档结构

在展开我们如何做升级之前，先要简单了解下飞书云文档的信息结构（详情可参考官方API），在此仅做简单阐述。

TypeScript简要定义，一个平铺的文档块数组，根据block_id和parent_id确定各块的父子关系，从而形成一个树：

我们用思维导图简单举例，整个文档块的树结构大致是这样的，有些块根据缩进递进，会形成父子关系，有些块天然就会成为父块（比如表格、引用等）：

旧版架构

那么我们初版转译工具是怎么做的呢，比较遗憾的是，由于当时需求的还原度诉求较低，我们的代码主要是复用现有部分实现，整体的架构设计可以用一个词概括，基本是面向过程编程：

上方的图：经过了一些抽取和封装，主流程核心代码仍有528行；下方的图：文档块核心转译渲染代码，基本没有写任何还原样式，通过Switch、Case来一个个渲染文档块。

新版架构设计

这次我们痛定思痛，势必要将转译工具的转译效果做到尽可能还原，也有了多位同学一起投入。因此首要思考和急需解决的问题来了：在老旧的架构下，如何才能做好代码扩展、多人协同、高效样式编写以及样式还原？

IoC 与DI

是的，几乎一刹那，凭借过往丰富的多人协同以及项目经验，很快我们就想到了，这个事需要基于IoC的设计原则，并通过DI的方式来实现。

那么什么是IoC和DI呢，根据维基百科的解释：控制反转（Inversion of Control，缩写为IoC），是面向对象编程中的一种设计原则，可以用来减低计算机代码之间的耦合度，其中最常见的方式叫做依赖注入（Dependency Injection，缩写为DI）。

这么说可能有点抽象，我们可以看下新版的架构设计，从中便能窥见其精妙：

可以看到，关键的文档块预处理和渲染器，在该架构中是反向依赖核心的createDocTranspiler了，与我们常识中的理解（文档转译渲染依赖各个块的预处理和渲染器）是相反的，这就是控制反转（IoC），通过这样的依赖倒置，我们能够把多人协同过程中，由各个同学负责开发的预处理器和渲染器的开发调试解耦出去，互不影响、互不依赖，且合码过程中基本没有代码冲突，大大提效了多人协同合作开发。同时由于实现的方式是依赖注入（DI），或者说注册，未来我们想要支持更加深水区的文档块，比如「画板」、「文档小组件」等，可以很方便地注册新的预处理器和渲染器，做增量且解耦的代码开发；如果想要取消对某一个文档块的渲染，直接unregister即可，由此也实现了文档块渲染的快速插拔和极高的可拓展性。

整个转译主干代码如下：

创建转译器，注册预处理器，注册渲染器

转译渲染，后处理，完成渲染。代码行数缩减到只有138行。

函数式编程

接下来我们将目光聚焦到核心函数createDocTranspiler中，这块是IoC架构的核心实现，根据维基百科描述，IoC是面向对象编程中的一种设计原则，那么我们真的是用面向对象的编程方式吗？

显然不是，我们是高标准的前端同学，在JavaScript编程中，面向对象编程显然不是社区推崇的设计原则，以React框架为例，早在React 16.8版本，就推出了函数组件和Hooks编程，以取代较为臃肿的类组件编程，这些都是前端老生常谈的理念了，大家可以去Google深入学习函数式编程理念，在此不再赘述。

这里说一下为什么核心代码createDocTranspiler我要用函数式编程，说一下我的理解：第一是非常优雅，用起来很舒服；第二是得益于JavaScript函数闭包，一些局部（想要private化）的变量或者方法，直接在函数内声明和定义即可，不用担心像类一样会暴露出去（尽管TS有private关键字，但只是约束，不代表你不能用）；第三是简单，无需维护类的实例，若有主动销毁场景，返回的结构中暴露销毁函数即可。

整个核心代码如下：

上方的图：内置的变量和函数，用于存储各种预处理器和渲染器，并实现文档树的递归渲染；下方的图：返回并暴露出去的函数，用于注册各种预处理器、渲染器，以及转译渲染。整个核心代码只有158行，非常精炼。

“CSS-in-JS”

然后再来说一下如此大量的样式还原工作，我们是如何实现的。由于我们要把文档树转译成最终的一个完整的HTML字符串，在模板字符串中写内联样式（style="width: 100px;..."）会非常痛苦，代码可读性会很差，开发调试的效率也会很低。

为了解决这个问题，我们立即想到了React CSSProperties的写法，并调研了一下它的源码实现，其实就是将CSSProperties中的驼峰属性名，转换成内联样式中连字符属性名，并额外处理了Webkit、ms、Moz、O等浏览器属性前缀，同时针对number 类型的部分属性的值，转换时自动加上了px后缀。详细代码如下：

然后再编写createInlineStyles方法，入参即为Record<string, CSSProperties> 大样式对象：

至此架构优化的差不多了，整个项目组进入了高度协同、紧密沟通合作的开发中，整个开发过程其实并不是特别顺利，尤其是在对Windows Outlook邮箱客户端的支持上，各种样式兼容问题Case层出不穷，以至于我们的开发同学不得不去对邮箱HTML和CSS开发进行“考古”。

三、Outlook麻烦的兼容性问题

在改版系统架构后，我们先试着实现了一版有序列表和无序列表的解决方案，结果在测试中，我们得到了出乎所有人意料之外的结果：

原本文档的样子

网页版Outlook中的样子

Windows的Outlook中的样子

在网页版Outlook中，通过开发工具可以看到每一项的justify-content样式消失了，而在Windows Outlook中，基本没什么样式还留着了。

Outlook糟糕的兼容性

我们之前从未编写过HTML邮件，也就完全没考虑过各个邮件客户端对HTML的兼容性问题。在网上找到一些资料后，我们被Outlook对HTML的兼容性之差所震惊。

首先，Windows Outlook并没有一个自己的HTML渲染引擎，而是使用Word的渲染引擎去解析HTML。它不支持HTML5和CSS3，也就是说我们为了保证最大的兼容性，所有的飞书文档样式还原和文本解析都要用极为陈旧的技术去实现。

据官方文档所示，display、position、max-width、max-height等样式全都不兼容。

总的来说：

• 不能使用任何CSS3新特性，比如flex、grid等；
• 和布局有关的组件，只能使用table来进行布局；
• 只能使用行内样式；尽量只使用table、tr、td、span、img、a、div这几个标签；
• 只有div的margin会偶尔被正确地识别，其它标签都有可能让padding和margin消失；
• 如果一个div内部含有table，它的margin会让table背景色和边框混乱；无法使用line-height；
• 小心使用div，Outlook有时候会把他转换为p，具体逻辑还不明确；
• 图片唯一能够控制大小的方法就是使用img标签上的width属性和height属性。

技术上的限制如此苛刻，就意味着在后面的开发中，我们还会遇到很多特定情况的兼容性问题。在这种情况下，为了最大限度地保证兼容性，我们决定及时止损，重新设计后面各个组件的实现方式，并将无序列表和有序列表的渲染方法推倒重来，再次编写。

四、各类型文档块的还原

首先，我们将转译工具原有的「一级标题」到「九级标题」美化为接近飞书文档的样子。我们需要梳理下将会获得的数据，来看看如何将它们转译为HTML。

标题块（heading 1-9）

标题组件应该是实现难度最低的一个，一个标题组件的数据结构如下：

原版实现方式

在原版的转译工具中，我们编写了通用方法来处理文本内容的下划线、删除线、斜体、粗体、高亮色等进行处理，生成行间元素，然后在外部框上<h1>-<h9>。最终在后面加上它的子节点渲染结果。

新版实现方式

由于默认的heading样式无法满足还原度，且并没有处理对齐方式。我们将使用 <div> 制作heading组件，自行添加样式来还原飞书文档：

其中makeHeadingStyles是我们生成样式的方法，这样可以将各个组件的样式写成配置项，方便后续修改。新的样式中，我们着重对行高、行距、下划线距文字距离、对齐方式进行了调整：

最后发邮件，测试一下生成的HTML的效果：

改版之前

改版之后

无序列表（bullet）与有序列表（ordered）

原版实现方式

列表的数据结构与标题块大致相同，在此不再赘述。在原来的转译工具中，我们使用原生的<ul>和<li>来直接渲染无序列表，<ol><li>来渲染有序列表。我们顺序遍历兄弟节点的列表，为连续的bullet文档块的前后加上<ul></ul>，连续的ordered块前后加上<ol>和</ol>。列表中的每一项，则渲染成<li>。

由于原生<ul>和<ol>的marker样式较丑，我们无法使用伪类元素等手段改善它的样式，为了方便，我们这次改版将自己维护列表的层级关系。

新版实现方式

在飞书文档中，不同层级的列表，marker长得完全不同：

无序列表

有序列表

为了判断我们每个列表项要使用什么样的marker，首先我们需要对飞书给我们的数据进行预处理，为每个列表块标注它的层级和序号。

• 数据预处理器

由于飞书API没有提供有序列表的序号，这个序号用户又可以随便更改，所以我们的思路是：如果有序列表中间被非空文档块以外的文本块截断，序号则重新开始计算。具体方法如下：

这样，每个列表项都知道了自己在文档中的层级，有序列表也知道了自己的序号。

由于原来的方法中完全没有处理过文本块的缩进，我们根据飞书缩进的规律，为普通的文本块（表格、栅格等以外的文本块）在渲染子节点时为子节点的容器添加25px的padding-left。

接下来我们使用一个通用的方法为有序列表和无序列表渲染它们的marker。

• 列表标号渲染器

对于无序列表，标号每三层一循环，顺序为 '•'、'◦'、'▪'。对于有序列表，标号格式也是每三层一循环，顺序为阿拉伯数字、小写字母、罗马数字。

使用列表的标号渲染器渲染标号部分，然后简单的在<div>中将标号<span>和处理过样式的正文<span>组合。

• 无序列表与有序列表渲染器
  • 新版有序列表渲染器
    • 渲染器：

• 无序列表渲染器
  • 渲染器

• 最终呈现结果

可以看到，我们在满足使用的前提下以最高的兼容性比较完美的还原了飞书文档中的有序列表和无序列表。

待办事项

既然漂亮地还原了有序列表和无序列表，待办事项块就简单得多了。代办事项的具体的数据结构如下：

可以看到，待办事项的数据中包含了该条待办事项是否已完成的数据，从飞书文档的样式可以看出，已完成的条目会统一被划上删除线，并删除下划线样式。最终的渲染器和样式生成方法如下：

待办事项渲染器

• 渲染器：

最终呈现效果

表格（非电子表格）块

文档中另一个最重要的模块就是表格。表格是另一类比较特殊的文本块，他内部并不包含正文。整个表格实际上由三层文档块组合而成，它们的数据结构如下：

依据数据结构和我们的代码模式设计，我们需要使用嵌套的渲染器来实现表格的绘制。

表格渲染器（table块）

由于飞书API中清楚地提供了行数、列数以及列宽，我们可以较为轻松地绘制出大致的表格。这里的重点是要准确地处理合并单元格数据，将它们精准地使用在表格的每个 <td>标签上。表格渲染器的代码如下：

• 渲染器：

为了处理合并单元格数据，我们维护了一个已处理标记数组processed，处理完一个单元格后，我们将当前单元格与被它合并的单元格都标记为已处理，来跳过他们的处理与渲染。这里需要特别注意，飞书文档的接口偶尔会返回错误的合并单元格数据：{ row_span: 0, col_span: 0 }，这个现象已经反馈给飞书，我们在34-37行做了兼容处理。

为了最大限度的兼容性，我们坚持能用标签属性设置的样式，就不使用CSS来设置。与列表的渲染不同，在表格中我们没有像列表渲染一样先预处理数据再生成DOM字符串，而是使用了在遍历中边处理数据边生成DOM字符串的方法。

在表格的渲染中，我们没有像之前的代码一样使用renderChildBlocks把所有子文档块都渲染出来添加进HTML字符串中，而是使用了新的renderSpecifyBlock方法，给定block_id来渲染特定的子文档块。

单元格容器渲染器（table cell块）

单元格容器的渲染器则简单的多，他没有任何数据处理，只绘制一个容器用于承载内部的所有子节点，并在内部将单元格内的子节点渲染出来

• 渲染器：

最终呈现效果

图片块

图片块理应也是一个很容易实现的文档块。但在实际处理过程中，由于飞书的API只提供图片源文件的宽高，并没有提供云文档中用户缩放过后的图片宽高，我们需要实现一个能满足绝大多数使用场景的图片缩放算法来尽可能还原文档中的图片样式。

图片块的数据结构如下：

限制图片大小

源文件的宽高一般都远大于图片在云文档中的实际宽高。我决定使用以下的方法来限制住图片在文档中的宽高：

• 若图片处于类似表格的文档块中，则宽度撑满父容器；
• 若图片不在类似表格的文档块中，则按照maxHeight: 780（限制最大高度避免长图过长），maxWidth: 820（飞书文档最大宽度），使用如下的算法来计算缩放后的图片大小：

• 最后我们在样式中设置maxWidth = 100%（在Windows的Outlook中不会生效）来在大多数客户端中保证图片宽度不会撑出父容器。

上述算法的代码实现如下：

• 查找父容器中是否有表格容器：

• 限制图片宽高：

图片渲染器

• 渲染器：

在预览的时候，我们将图片地址设为图片的base64，直接展示。最后传给后端的HTML字符串中，我们将图片地址设为一个占位符，供后端解析并转化为邮件附件地址。

使用表格来布局的几个文档块

由于Windows Outlook对CSS的支持程度很差，我们在对一些复杂文档块进行排版布局的时候不能使用flex、grid等。且display和position属性在大多情况下也不会像预期那样正常生效。我们为了最大的兼容性只能使用表格来解决一切排版问题。代码块、高亮块、栅格等几个文档块就都遵循了这个思路，使用表格来解决排版。我们以最复杂的代码块作为代表来进行介绍。

代码块

飞书云文档中免不了会出现代码，所以较好的进行代码块的还原也是个重要的工作。代码块还原的一个难点就是数据的处理，首先介绍下代码块的数据结构：

理想的话，我们希望element中每一项为一行代码，我们挨个进行渲染即可。但实际上，element的内容和普通文本类似，只要文本的样式不变（比如设为斜体、加粗等），这些文本就都会被塞到同一个element项中。

举例说明，对于下列文档中的代码块，实际飞书API返回的代码只有两项element：

其中，最后一个大括号被单独拆成一项令人费解，不过好在代码块中，只要一项element的后面出现了另一项，那就一定意味着换行。这减少了我们的处理难度。

• 数据处理

我们的大体思路，是将代码拆分成一个二维数组。第一维中的每一维度为一行代码，每行代码中的每一维度为拆分后零碎的代码块。我们先将所有的element中的内容根据换行符\n拆分成一个个细小的子块，同时将与HTML有关的字符替换成HTML编码，避免这些字符混入HTML字符串中被当做标签解析：

然后将这些子块按照换行符进行分组，变成我们需要的二维数组：

至此，我们知道了代码行数n和每行代码中的小代码块有哪些。我们要做的就是将它们放进一个n行2列的表格中

• 代码块渲染器

最终，代码块渲染器的代码如下。为了保证最大的兼容性，我们使用空的表格行作为内边距，尽量避免CSS解析问题：

• 渲染器：

• 样式生成：

我们本次不会实现代码的高亮，只会显示同一种颜色的代码。对表格中的每个单元格，我们使用pre标签包裹来保留代码中的制表符、空格，并将fontFamily设置为'Courier New', Courier, monospace，使用等宽字体来呈现代码。

• 最终呈现效果：

行间公式

飞书云文档除文本外支持多种行间元素的插入，比如@文档、内联文件、内联公式等，在此我们介绍下最为复杂的内联公式是怎么处理的。

行间公式的数据位于各个文档块的内联块中，以文本块为例，具体数据如下：

我们要做的，就是将公式转换为图片，然后在邮件中将公式作为图片附件来处理。

• 公式数据的预处理

我们将使用MathJax来将公式表达式转换为svg，用于用户预览。在发送时，我们将MathJax生成的svg通过cavans转化为png图片，上传到CDN，并将CDN地址给到后端，进行邮件附件转换。

公式的预处理方法如下：

我们先找出所有文档块中的内联公式，将其转换为svg，存储到公式块中。如果当前是发送模式，不是预览模式，我们就做进一步处理，使用allSvgsToImgThenUpload 将svg再转化为图片的CDN地址，此处的allSvgsToImgThenUpload方法让我们并行处理所有的公式图片，具体如下：

核心的svgToImgThenUpload方法如下，它负责将svg转化为图片，并上传CDN：

为了保证图片清晰，渲染使用三倍宽高，实际大小使用两倍宽高。

至此，我们让公式块带上了图片CDN地址。在发送时交给后端，转为邮件附件，即可正常显示了。

• 最终呈现效果

五、向前一步

好在最终我们克服了重重困难，终于来到了转译工具升级的Showcase环节。之前有提到我们有fallbackRenderer，主要用于针对未识别或者未支持的文档块，渲染其默认提示，最初我们渲染的效果只是一个简单的提示，比如：【画板暂不支持解析】这样的文案提示。

但是我们很快发现：1. 这些提示并不明显，可以做一个类似Antd Alert的提示；2. 在发送时要过滤掉这些提示，因为是无效信息；3. 在预览时需要让用户能够看到实际的发送效果，需要有开关能隐藏这些提示；4. 发送时存在这些不支持的块时，需要拦截提示用户是否去调整文档内容，以达到信息更全效果更好的发送效果。往往是这些细枝末节的体验与引导，能够真正抓住用户的心，让用户觉得这个转译工具是真的贴心、好用。

因此，我们快速增加了这些具体的引导与提示优化，具体效果如下：

六、大功告成

经过这一番波折，我们最终成功地将飞书云文档转译为兼容大多数客户端的HTML邮件。这不仅仅是一项技术上的挑战，更是一次心态和耐心的考验。

在这个过程中，我们深刻体会到在前端开发中，面对各种浏览器和客户端的不一致性时，需要的不仅仅是技术能力，还需要灵活应变和坚持不懈的精神。希望本文能为同样遇到这些问题的开发者提供一些思路和帮助。

未来，我们还将继续优化我们的解决方案，并探索更多高效的方法，期待与大家分享更多经验。如果有任何问题或建议，欢迎在评论区留言讨论！感谢阅读！

引用：

• https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document/list
• https://github.com/facebook/react/blob/81d4ee9ca5c405dce62f64e61506b8e155f38d8d/packages/react-dom-bindings/src/shared/CSSProperty.js#L8-L57

*文/Nicolas、Asher

本文属得物技术原创，未经得物技术许可严禁转载，否则依法追究法律责任！