在 kbone 中实现小程序 svg 渲染
背景
2019 年底，微信小程序已经推出了近三个年头，我身边的前端开发者基本都做过至少一次小程序了。很多友商曾打算推动小程序进入 W3C 标准，而微信并不为所动，个人认为，小程序本身在框架设计上称不上「标准」，微信也并没打算做一个「标准的平台」。
小程序更注重产品形态和交互，注重对开发者能力的制约，尽可能减少对用户的干扰；因此，也许小程序从设计之初就没有过多考虑开发层面的「优雅」，而是以方便上手、容易学习为主。最典型的例子就是 App() 、 Page() 这一类直接注入到模块内的工厂方法，你不知道、也不需要知道它从何处来，来无影去无踪，是与现在 JS 生态中早已普及的模块化开发有点相悖的。
在架构上，小程序选择了将逻辑层与视图层分离的方式来组织业务代码。小程序的源码提交上传时，JS 会被打包成逻辑层代码（ app-service.js ），在运行时与逻辑层基础库 WAService.js 相结合，在逻辑层 Webview（或 JSCore）中执行；WXML/WXSS 将会编译成 JS 并拼接成 page-frame.html ，在运行时与视图层基础库 WAWebview.js 相结合，在视图层堆栈的 Webview 中执行。基础库负责利用客户端提供的通信管道，相互建立联系，对小程序和页面的生命周期、页面上虚拟 DOM 的渲染等进行管理，并在必要时使用客户端提供的原生能力。
熟悉小程序的开发者都知道，这样的架构最主要的目的就是禁止业务代码操作 DOM，迫使开发者使用数据驱动的开发方式，同时在小程序推出初期可以避免良莠不齐的 HTML 项目快速攻占小程序平台，后期则可以缓解小程序平台上的优质产品流失。
kbone 是什么
从 2017 年初小程序推出开始，业界最关心的就是小程序能否转为普通的 Web 开发。最初我们只能简单的用 Babel 进行 JS 的转换；后来小程序推出了 web-view 组件，开发者则开始想办法让 Web 页面使用小程序能力；在知道了 web-view 中的消息不能实时传到小程序逻辑层后，大家则开始选择妥协，改用语法树转换的方式来实现。很多小程序开发框架都是在这一个阶段产生的，如 Wepy、Labrador、mpvue 和 Taro。
语法树转换终究是不可靠的——在 Wepy 和 Taro 的使用中，我们常常会碰到很多语法无法识别的坑，坑的数量与代码量成正比。因此，这些框架更适用于从零开始写，而不适合将一个大型项目移植到小程序。
kbone 是微信团队开源的微信小程序 同构 框架，与基于语法树转换的 Wepy、Taro 等传统框架不同，kbone 的思路是在逻辑层用类似 SSR 的方式模拟出 DOM 和 BOM 结构，让逻辑层的 HTML5 代码正常运行；而 kbone 会负责将逻辑层中的虚拟 DOM 以 setData 的形式传递给视图层，让视图层利用小程序组件递归渲染的能力，产生出真实的 DOM 结构。
使用 kbone 之后，我们可以将小程序页面理解为一个独立的 html 文档（而不是 SPA 中的一个 router page）。在每个页面的 JS 中初始化 kbone，为逻辑层提供虚拟 DOM 和 BOM 的环境，然后就可以像 H5 一样加载各种主流前端框架和业务代码，kbone 会负责逻辑层和视图层之间的 DOM 和事件同步。
让 kbone 支持 HTML5 inline SVG
在 HTML 中，SVG 的引入有很多种不同的方式，可以像图片一样使用 background-image 属性，也可以直接在 HTML 中插入 标签，另外还有 、 等不太常见的方式。
在一些大型 web-view 项目迁移到 kbone 的过程中，常常会遇到 HTML inline SVG（在 HTML 中直接插入 SVG 标签）这种情况；有的页面还会异步加载一个含有很多小图标（ ）的大 SVG、在页面上用 的方式，实现 SVG 的 Sprite 化。
本文针对单个页面上出现大量 HTML inline SVG 的实战场景，通过识别并转换成 background-image ，来实现小程序 kbone 对 SVG 的支持。
构造用例
首先我们以 kbone 官方示例 为基础，导入该项目后，在项目根目录新建 kbone-svg.js ，然后进入 /pages/index/index.js ，在 onLoad() 的结尾先写出调用方式和示例：
Page({
data: ...,
onLoad(query) {
...
init(this.window, this.document)
this.setData({ pageId: this.pageId })
this.app = this.window.createApp()
this.window.$$trigger('load')
this.window.$$trigger('wxload', { event: query })
// 添加我们的调用方式和示例
require('../../svg.js')(this.window)
this.document.body.innerHTML += `
SVG 渲染
SVG Symbol 渲染
SVG 自引用渲染
`
}
})
本例中，结合 和 的 文档 ，给出了三种示例，分别用来代表普通 SVG 的渲染、跨 SVG 引用 Symbol（类似于雪碧图）的渲染、以及 SVG 内引用当前文档中的 Symbol 的渲染情况。
分析和实现
上述示例中，我们模拟 H5 条件下最一般的情况，直接在 body 下添加 HTML。如何支持这样的情况？首先我们打开 kbone 的代码 /miniprogram_npm/miniprogram-render/node/element.js ，观察 innerHTML 的 setter：
set innerHTML(html) {
if (typeof html !== 'string') return
const fragment = this.ownerDocument.$$createElement({
tagName: 'documentfragment',
// ...
})
// ...
ast = parser.parse(html)
// ...
// 生成 dom 树
ast.forEach(item => {
const node = this.$_generateDomTree(item) // {
// ...
})
this.$_children.length = 0
// ...
this.appendChild(fragment)
}
可以看到， innerHTML 被转化成 $_generateDomTree 的调用，生成新的子节点，并替换掉所有旧的子节点。而在 $_generateDomTree 中，最终将会调用 this.ownerDocument.$$createElement 。
根据 /miniprogram_npm/miniprogram-render/document.js 中的定义， Document.prototype.$$createElement 作为我们熟知的 Document.prototype.createElement 的内部实现，因此为了监听 等节点的创建，需要对 $$createElement 方法进行 Hook。
在 kbone 官方文档 DOM/BOM 扩展 API 一章中不难发现，我们可以使用 window.$$addAspect 函数对所需的方法进行 Hook：
window.$$addAspect('document.$$createElement.after', (el) => {
if (el.tagName.toLowerCase() === 'svg') {
setTimeout(() => renderSvg(el), 0);
}
});
在这里，我们监听了 节点的建立，并在下一个宏任务中（即等待 节点的所有子节点挂载完成后）调用我们自己的 renderSvg() 方法。在 renderSvg() 中，我们希望进行下列一些操作：
data:image/svg+xml background-image
在并不知道 Symbol 是否可以再包含 的情况下，为了简化问题，我们可以先假设所有的 Symbol 中不会包含 ，即不存在 Symbol 之间多级依赖和循环依赖的情况。经过反复修改， renderSvg() 方法实现如下：
const symbolMap = {};
const symbolUseMap = {};
const renderSvg = (el) => {
// 如果之前已经完成渲染，就不重复渲染
if (el.style.backgroundImage) return;
// 分析并保存当前 SVG 文档中的所有 Symbol，以便于当前 SVG 文档内部或者其它 SVG 中使用
// 同时，记录这些 Symbol，如果在当前 SVG 中本地使用，则不需要替换他们
const localSymbols = new Set(el.querySelectorAll('symbol').map(resolveSymbol));
// 先假设没有完成渲染
let isFullRendered = true;
// 将当前 SVG 文档中的跨文档 `` 节点替换成对应 Symbol 的 HTML
el.querySelectorAll('use').forEach(use => {
const symbolId = (use.getAttribute('xlink:href') || use.getAttribute('data-xlink-href')).replace(/^#/, '');
// 如果是当前文档内局部的 Symbol，不需要替换，background-image 会直接解析
if (localSymbols.has(symbolId)) return;
const symbol = symbolMap[symbolId];
if (symbol) {
// 如果对应的 Symbol 已经加载，将 替换成对应的 Symbol
// 这里暂时简化考虑，直接覆盖 的父节点的所有内容
const parentNode = use.parentNode;
parentNode.innerHTML = symbol.innerHTML;
parentNode.setAttribute('viewBox', symbol.getAttribute('viewBox'));
if (!symbolUseMap[symbolId]) symbolUseMap[symbolId] = new Set();
symbolUseMap[symbolId].delete(el);
} else {
// 如果对应的 Symbol 还没有加载，则监听其加载完成
if (!symbolUseMap[symbolId]) symbolUseMap[symbolId] = new Set();
symbolUseMap[symbolId].add(el);
isFullRendered = false;
}
});
// 若存在没加载完的 Symbol，先不执行渲染，因为渲染过程是一次性的，需要破坏所有子节点
if (!isFullRendered) return;
// 清理当前 SVG 文档，并转换为 `data:image/svg+xml` 格式的 Data URI
let svg = el.outerHTML;
const svgDataURI = parseSvgToDataURI(svg);
const backgroundImage = `url('${svgDataURI}')`;
if (backgroundImage.length > 5000) {
console.error('[kbone-svg] SVG 长度超限', { svg, data: svgDataURI });
}
// 将当前 SVG 标记为已渲染，清除所有子节点，并将生成的 Data URI 设置为 CSS `background-image` 属性
el.innerHTML = '';
if (el.getAttribute('width')) el.style.width = el.getAttribute('width') + 'px';
if (el.getAttribute('height')) el.style.height = el.getAttribute('height') + 'px';
el.style.backgroundImage = backgroundImage;
el.style.backgroundPosition = 'center';
el.style.backgroundRepeat = 'no-repeat';
console.log('[kbone-svg] 渲染 SVG 元素完成', { svg, data: svgDataURI });
}
接下来我们需要实现 resolveSymbol 方法。当遇到 Symbol 时，需要解析其 ID，保存该 Symbol 节点，并触发所有依赖当前 Symbol 的其他 SVG 的重新渲染。
const resolveSymbol = (el) => {
const symbolId = el.id;
el.id = null;
const symbol = el;
if (symbolMap[symbolId] !== symbol) {
symbolMap[symbolId] = symbol;
setTimeout(() => symbolUseMap[symbolId] && symbolUseMap[symbolId].forEach(renderSvg), 0);
}
console.log('[kbone-svg] 保存 Symbol 完成', symbol);
return symbolId;
}
最后，我们需要定义 SVG 进行清理和渲染（转化为 Data URI）的过程。在此之前，需要对 setAttribute 和 setAttributeNS 进行一个 polyfill，因为 kbone 不支持为节点设置任意属性，很多属性设置之后会丢失。
const _setAttribute = window.Element.prototype.setAttribute;
window.Element.prototype.setAttribute = function (attribute, value) {
const oldHtml = this.outerHTML;
_setAttribute.call(this, attribute, value);
const newHtml = this.outerHTML;
// 如果设置属性后 outerHTML 没有改变，则设置到 dataset 中
if (oldHtml === newHtml) {
this.dataset[attribute] = value;
}
}
// 对设置 xlink:href 时可能出现的报错进行 polyfill，改为 data-xlink-href
window.Element.prototype.setAttributeNS = function (xmlns, attribute, value) {
this.setAttribute('data-' + attribute.replace(':', '-'), value)
}
接下来即可定义 SVG 文档转化为 Data URI 的过程了，这里需要用到很多正则表达式。
const parseSvgToDataURI = (svg) => {
// 将被设置到 dataset 中的属性还原出来
svg = svg.replace(/data-(.*?=(['"]).*?\2)/g, '$1');
// 将被设置到 data-xlink-href 的属性还原出来
svg = svg.replace(/xlink-href=/g, 'xlink:href=');
// 将 dataset 中被变成 kebab-case 写法的 viewBox 还原出来
svg = svg.replace(/view-box=/g, 'viewBox=');
// 清除 SVG 中不应该显示的 title、desc、defs 元素
svg = svg.replace(/[\s\S]*?/g, '');
// 为非标准 XML 的 SVG 添加 xmlns，防止视图层解析出错
if (!/xmlns=/.test(svg)) svg = svg.replace(/<svg/, " parseFloat(parseFloat(match).toFixed(2)));
// 清除注释，缓解数据量过大的问题
svg = svg.replace(//g, '');
// 模拟 HTML 的 white-space 行为，将多个空格或换行符换成一个空格，减少数据量
svg = svg.replace(/\s+/g, " ");
// 对特殊符号进行转义，这里参考了 https://github.com/bhovhannes/svg-url-loader/blob/master/src/loader.js
svg = svg.replace(/[{}\|\\\^~\[\]`"#%]/g, function (match) {
return '%' + match[0].charCodeAt(0).toString(16).toUpperCase();
});
// 单引号替换为 \'，由于 kbone 的 bug，节点属性中的双引号在生成 outerHTML 时不会被转义导致出错
// 因此 background-image: url( 后面只能跟单引号，所以生成的 URI 内部也就只能用斜杠转义单引号了
svg = svg.replace(/'/g, "\\'");
// 最后添加 mime 头部，变成 Webview 可以识别的 Data URI
return 'data:image/svg+xml,' + svg.trim();
}
以上是经过反复 debug 后的相对稳定的代码。放在上文的演示项目中，效果如下图：
可以看出，前两例中已经可以渲染出图片，第三例中，与 MDN 官方文档的表现 不太一致，经过检查，生成的 Data URI 直接打开并没有问题，可能是小程序视图层的环境对 SVG 内的尺寸换算存在问题。
在 Android 和 iOS 真机调试中，本例没有出现无法显示的兼容问题，这也说明了这种方案可行。
问题与总结
kbone 解决了 JS 难题，却留下了 CSS 难题
在上述例子中可以看到，kbone 已经非常类似于 H5 的环境，但有一个很容易忽略的问题：由于实际的操作对象是 的虚拟 DOM，且小程序视图层并不支持 ， 我们已经无法通过 JS 给整个页面（而非特定元素）注入 CSS ，因此也无法通过纯 JS 层面的 polyfill 来为 svg 等某一类元素定义一些优先级较低的默认样式。
例如，在解析 SVG 的过程中，我们可能希望通过获取 SVG 元素的尺寸来设置渲染后背景图的默认尺寸（像 !important 。
同理，可以肯定的是，我们也无法在 JS 中控制诸如媒体查询、字体定义、动画定义、以及 ::before 、 ::after 伪元素的展示行为等，这些都是只能通过静态 WXSS 编译到小程序包内，而无法通过小程序 JS 动态加载的。
数据量消耗
另外，虽然在 HTML5 环境中十分推崇 SVG 格式，但放在 kbone 的特定环境下，把 SVG 转换成 CSS background-image 反而是一种不甚考究的方案，因为这将会占用 setData() （小程序基础库中称为 vdSyncBatch ）的数据量，降低数据层和视图层之间通信的效率，不过好在每个 SVG 图片只会被传输一次。
在写这个项目的同时，我也尝试将经过清理后生成的 SVG 利用小程序接口保存到本地文件，然后将文件的虚拟 URL 交给视图层，结果并不乐观。视图层在向微信 JSSDK 请求该 SVG 文件的过程中，也许因为没有收到 Content-Type 或者收到的 Content-Type 不对，导致 SVG 文件无法被正确解析展示出来。这可能是小程序的 Bug，或者也许是小程序并没有打算支持的灰色地带。
小结
尽管依然存在诸多问题，通过一个 polyfill 来为项目迁移过程中遇到的 SVG 提供一个临时展示方案仍然是有必要的——这让我们可以先搁置图片格式的问题，将更重要的问题处理完之后，再回来批量转换格式、或改用 Canvas 来绘制。
文中完成的 kbone SVG polyfill 只有一个 JS 文件，托管在我个人的 GitHub ，同时为了方便使用也发布到 NPM 。本文存在很多主观推测和评论，如有谬误，欢迎留言指正。
About The Author
maynard
懒散，不想无聊