@4keys/dom-to-image 中文文档教程

Question

DOM to Image

What is it

dom-to-image 是一个可以将任意 DOM 节点转换为图像的库 用 JavaScript 编写的矢量 (SVG) 或光栅（PNG 或 JPEG）图像。 它是 基于 Paul Bakaus 的 domvas 并且已经完全重写，修复了一些错误和一些新的 添加了功能（如网络字体和图像支持）。

Installation

NPM

npm install dom-to-image

然后加载

/* in ES 6 */
import domtoimage from 'dom-to-image';
/* in ES 5 */
var domtoimage = require('dom-to-image');

Bower

bower install dom-to-image

包括 src/dom-to-image.js 或 < code>dist/dom-to-image.min.js 在你的页面 它将使 domtoimage 变量在全局范围内可用。

<script src="path/to/dom-to-image.min.js" />
<script>
  domtoimage.toPng(node)
  //...
</script>

Usage

所有顶级函数都接受 DOM 节点和渲染选项， 并返回承诺，这些承诺由相应的数据 URL 实现。
获取 PNG 图像 base64 编码数据 URL 并立即显示：

var node = document.getElementById('my-node');

domtoimage.toPng(node)
    .then(function (dataUrl) {
        var img = new Image();
        img.src = dataUrl;
        document.body.appendChild(img);
    })
    .catch(function (error) {
        console.error('oops, something went wrong!', error);
    });

获取 PNG 图像 blob 并下载它（使用 FileSaver , 例如）：

domtoimage.toBlob(document.getElementById('my-node'))
    .then(function (blob) {
        window.saveAs(blob, 'my-node.png');
    });

保存并下载压缩的 JPEG 图像：

domtoimage.toJpeg(document.getElementById('my-node'), { quality: 0.95 })
    .then(function (dataUrl) {
        var link = document.createElement('a');
        link.download = 'my-image-name.jpeg';
        link.href = dataUrl;
        link.click();
    });

获取 SVG 数据 URL，但过滤掉所有 元素：

function filter (node) {
    return (node.tagName !== 'i');
}

domtoimage.toSvg(document.getElementById('my-node'), {filter: filter})
    .then(function (dataUrl) {
        /* do something */
    });

获取原始像素数据作为 Uint8Array 每 4 个数组元素代表一个像素的 RGBA 数据：

var node = document.getElementById('my-node');

domtoimage.toPixelData(node)
    .then(function (pixels) {
        for (var y = 0; y < node.scrollHeight; ++y) {
          for (var x = 0; x < node.scrollWidth; ++x) {
            pixelAtXYOffset = (4 * y * node.scrollHeight) + (4 * x);
            /* pixelAtXY is a Uint8Array[4] containing RGBA values of the pixel at (x, y) in the range 0..255 */
            pixelAtXY = pixels.slice(pixelAtXYOffset, pixelAtXYOffset + 4);
          }
        }
    });

---

impl 下的所有函数都不是公共 API，仅公开 用于单元测试。

---

Rendering options

filter

以 DOM 节点作为参数的函数。 如果通过节点应该返回 true 应该包含在输出中（排除节点意味着排除它的 儿童也一样）。 不在根节点上调用。

bgcolor

背景颜色的字符串值，任何有效的 CSS 颜色值。

height, width

渲染前应用于节点的高度和宽度（以像素为单位）。

style

一个对象，其属性在渲染之前被复制到节点的样式。 您可能需要查看此参考资料 用于 CSS 属性的 JavaScript 名称。

quality

一个介于 0 和 1 之间的数字，表示图像质量（例如 0.92 => 92%） JPEG 图片。 默认为 1.0 (100%)

cacheBust

设置为 true 以将当前时间作为查询字符串附加到 URL 请求以启用缓存清除。 默认为 false

imagePlaceholder

获取图像失败时将使用的占位符图像的数据 URL。 默认为 undefined 并且会在失败的图像上抛出错误

Browsers

它在最新的 Chrome 和 Firefox（当时分别为 49 和 45）上进行了测试 写作），Chrome 在大型 DOM 树上的表现要好得多， 可能是因为它对 SVG 的支持更高效，而且它支持 CSSStyleDeclaration.cssText 属性。

Internet Explorer 不受（也不会）支持，因为它不支持 SVG 标签

Safari 不支持，因为它在 > 上使用了更严格的安全模型。 标签。 建议的解决方法是使用 toSvg 并在服务器上呈现。`

Dependencies

Source

目前仅使用标准库，但请确保您的浏览器支持：

• Promise
• SVG <foreignObject> tag

Tests

最重要的是，测试取决于：

• js-imagediff, 比较渲染图像和控制图像

• ocrad.js，对于 无法比较图像时的部分（由于浏览器 渲染差异）并且只需要测试文本是否被渲染

How it works

可能有一天存在（或者可能已经存在？）一个简单和标准的 将部分 HTML 导出为图像的方法（然后此脚本只能 作为我必须跳过的所有箍的证据才能获得 完成了如此明显的事情），但到目前为止我还没有找到。

这个库使用 SVG 的一个特性，允许有任意的 HTML 内容 在 标签内。 所以，为了渲染那个 DOM 节点 对您来说，采取以下步骤：

1. 递归克隆原始 DOM 节点

2. 计算节点和每个子节点的样式并将其复制到 相应的克隆

   • and don't forget to recreate pseudo-elements, as they are not cloned in any way, of course

3. 嵌入网络字体

   • 找到所有可能代表网络字体的@font-face声明

   • 解析文件URL，下载相应的文件

   • base64-encode和内联内容作为data: URLs

   • concatenate所有处理后的 CSS 规则并将它们放入一个

4. 嵌入图像

   • 在 元素中嵌入图像 URL 在 <

   • code>background CSS 属性中使用的内联图像，其方式类似于 fonts

5. 将克隆出来的节点序列化为XML，将XML

6. 包装到标签中，再放入SVG中，然后做成一个 数据 URL

7. 可选地，要将 PNG 内容或原始像素数据作为 Uint8Array，创建一个 以 SVG 为源的图像元素，并将其渲染到屏幕外 画布，你也创建了，然后从画布上读取内容

8. 完成！

Things to watch out for

• 如果要呈现的 DOM 节点包含一个 元素 画在上面的东西，应该处理得很好，除非画布是 被污染 - 在这种情况下渲染不会成功。

• 在撰写本文时，Firefox 存在一些外部样式表问题 （见问题 #13）。 在这种情况下，将捕获并记录错误。

Authors

Anatolii Saienko, Paul Bakaus（原创）

License

麻省理工学院