html2canvas 0.5.0文档

html2canvas是一个将HTML页面渲染成canvas图像的JavaScript库。以下是html2canvas 0.5.0的文档：

## 安装

使用npm安装：

npm install html2canvas

或者直接在HTML文件中引入：

<script src="https://html2canvas.hertzen.com/dist/html2canvas.min.js"></script>

## 使用

### 基本用法

html2canvas(document.body).then(function(canvas) {
    document.body.appendChild(canvas);
});

上面的代码将把当前页面的HTML元素渲染成canvas元素，并将其插入到页面中。

### 配置项

html2canvas还提供了一些配置选项，可以通过传递一个选项对象来设置这些选项。

html2canvas(document.body, {
    allowTaint: true,
    backgroundColor: '#ffffff',
    useCORS: true
}).then(function(canvas) {
    document.body.appendChild(canvas);
});

下面是html2canvas支持的全部选项：

- `allowTaint`（布尔值，默认为`false`）：允许绘制跨域图片。如果设置为`true`，将会禁用tainted canvas错误的检查。
- `backgroundColor`（字符串，默认为`#ffffff`）：指定背景颜色。可以是任何CSS颜色值。
- `canvas`（HTMLCanvasElement）：使用给定的canvas元素进行绘制，而不是创建新的canvas元素。
- `foreignObjectRendering`（布尔值，默认为`false`）：允许在canvas中绘制外部对象，如`<iframe>`、`<video>`或`<embed>`。如果设置为`true`，将会使用带有外部内容的`<foreignObject>`元素进行绘制。
- `height`（数字）：指定canvas的高度。如果未指定，将使用元素的高度。
- `letterRendering`（布尔值，默认为`false`）：允许在canvas中绘制字母。如果设置为`true`，将会使用单独的canvas元素进行绘制，以使字母更加清晰。
- `logging`（布尔值，默认为`false`）：启用日志记录。
- `proxy`（字符串）：跨域代理的URL地址。html2canvas将会使用这个URL来加载跨域资源。
- `scale`（数字，默认为`window.devicePixelRatio`）：指定绘制时的比例。可以是任何数字，但通常使用`window.devicePixelRatio`来绘制高清图像。
- `scrollX`（数字）：指定水平滚动条的位置。可以是任何数字，但通常使用元素的`scrollLeft`属性来指定位置。
- `scrollY`（数字）：指定垂直滚动条的位置。可以是任何数字，但通常使用元素的`scrollTop`属性来指定位置。
- `useCORS`（布尔值，默认为`false`）：使用跨域资源共享（CORS）来加载跨域图片。

### 方法

html2canvas还提供了一些方法，可以在渲染过程中进行操作。

#### `html2canvas.cancel()`

取消当前的渲染过程。

var promise = html2canvas(document.body);
promise.cancel();

#### `html2canvas.punish()` 和 `html2canvas.reward()`

这两个方法用于惩罚或奖励html2canvas的性能。默认情况下，html2canvas会尝试使用最快速的方式进行渲染，但在某些情况下，它可能会导致渲染失败或产生低质量的图像。使用`punish()`方法可以告诉html2canvas尝试使用更准确的但更慢的渲染方法，而使用`reward()`方法可以告诉html2canvas尝试使用更快的但可能会产生低质量图像的渲染方法。

html2canvas(document.body, {
    onrendered: function(canvas) {
        if (canvas.width > 500) {
            html2canvas.punish();
            html2canvas(document.body, {
                onrendered: function(canvas) {
                    // ...
                }
            });
        } else {
            html2canvas.reward();
        }
    }
});

### 事件

html2canvas还提供了一些事件，可以在渲染过程中进行操作。

#### `onbeforeload`

在加载跨域图片之前触发。可以使用它来修改图片的URL。

html2canvas(document.body, {
    onbeforeload: function(image) {
        if (image.src.indexOf('http://example.com/') === 0) {
            image.src = 'http://proxy.example.com/?url=' + encodeURIComponent(image.src);
        }
    }
});

#### `onload`

在图片加载完成后触发。

html2canvas(document.body, {
    onload: function(image) {
        console.log('Image loaded:', image.src);
    }
});

#### `onclone`

在克隆DOM元素之前触发。可以使用它来修改DOM元素的样式或内容。

html2canvas(document.body, {
    onclone: function(clone) {
        clone.querySelectorAll('img').forEach(function(img) {
            img.src = '/path/to/placeholder.png';
        });
    }
});

#### `onrendered`

在渲染完成后触发。渲染结果将作为参数传递给该事件处理函数。

html2canvas(document.body, {
    onrendered: function(canvas) {
        console.log('Canvas rendered:', canvas);
    }
});

### 错误处理

html2canvas可能会产生一些错误，例如渲染失败或跨域资源不可用。以下是一些常见的错误类型及其处理方法。

#### tainted canvas

当尝试从包含跨域图片的canvas中提取数据时，浏览器会抛出`tainted canvas`错误。如果要允许绘制跨域图片，请将`allowTaint`选项设置为`true`。

html2canvas(document.body, {
    allowTaint: true
});

#### SecurityError

当尝试读取跨域iframe中的内容时，浏览器会抛出`SecurityError`错误。如果要允许在canvas中绘制外部对象，请将`foreignObjectRendering`选项设置为`true`。

html2canvas(document.body, {
    foreignObjectRendering: true
});

#### NS_ERROR_NOT_AVAILABLE

当尝试读取跨域资源时，浏览器会抛出`NS_ERROR_NOT_AVAILABLE`错误。如果要使用跨域代理来加载跨域资源，请将`proxy`选项设置为代理的URL地址。

html2canvas(document.body, {
    proxy: 'http://proxy.example.com/'
});

### 支持的浏览器

html2canvas支持所有现代浏览器和IE9及以上版本。请注意，它需要浏览器支持`<canvas>`元素和`<foreignObject>`元素。

## 参考资料

- [html2canvas官网](https://html2canvas.hertzen.com/)
- [html2canvas Github仓库](https://github.com/niklasvh/html2canvas)