html2canvas

 

[Homepage](http://html2canvas.hertzen.com) | [Downloads](https://github.com/niklasvh/html2canvas/releases) | [Questions](http://stackoverflow.com/questions/tagged/html2canvas?sort=newest) | [Donate](https://www.gittip.com/niklasvh/)

 

[](https://gitter.im/niklasvh/html2canvas?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [](https://travis-ci.org/niklasvh/html2canvas)

 

#### JavaScript HTML renderer ####

 

 The script allows you to take "screenshots" of webpages or parts of it, directly on the users browser. 

 这个脚本允许浏览器直接通过浏览器将网页或者网页的一部分进行“截屏”。

 The screenshot is based on the DOM and as such may not be 100% accurate(精确) to the real representation as it does not make an actual screenshot, but builds the screenshot based on the information available on the page.

 这个截屏是基于DOM的，做不到跟真实的截屏一样百分百的精确，但是构建的这个截屏是基于页面上可见的元素做的。

 

###How does it work?###

The script renders(渲染) the current page as a canvas image, by reading the DOM and the different styles applied to the elements.

脚本渲染当前的页面为一个画布图片，通过读取DOM以及用在DOM上的样式。

It does **not require any rendering from the server**, as the whole image is created on the **clients browser**. 

不需要来自服务端的补偿，整个图片的创建是基于浏览器的。

However, as it is heavily dependent on the browser, this library is *not suitable* to be used in nodejs.

它重度依赖浏览器，它依赖的JS库不能通过nodeJS从服务器获取。

It doesn't magically(使用魔法般) circumvent(包围) any browser content policy restrictions either, so rendering cross-origin content will require a [proxy](https://github.com/niklasvh/html2canvas/wiki/Proxies) to get the content to the [same origin](http://en.wikipedia.org/wiki/Same_origin_policy).

 

The script is still in a **very experimental state**, so I don't recommend using it in a production environment nor start building applications with it yet, as there will be still major changes made.

整个脚本仍然是一个测试状态，所以我不建议把它用作生产环境，也不建议使用它来构建一个应用，因为整个脚本还在一个重大改变的阶段。

 

###Browser compatibility###

浏览器兼容性

The script should work fine on the following browsers:

 

* Firefox 3.5+

* Google Chrome

* Opera 12+

* IE9+

* Safari 6+

 

As each CSS property needs to be manually built to be supported, there are a number of properties that are not yet supported.

每一个CSS属性都需要手动的去创建对它的支持，现在还有大量的CSS属性没有支持.

 

### Usage ###

 

**Note!** These instructions are for using the current dev version of 0.5, for the latest release version (0.4.1), checkout the [old readme](https://github.com/niklasvh/html2canvas/blob/v0.4/readme.md).

下面的笔记适用于当前0.5的开发版，最新的发布版0.4.1需要在git上下载

To render an `element` with html2canvas, simply call:

` html2canvas(element[, options]);`

要用html2canvas渲染一个元素，简单的通过调用：` html2canvas(element[, options]);`

The function returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) containing the `<canvas>` element. Simply add a promise fullfillment handler to the promise using `then`:

这个方法返回一个包含`<canvas>` element元素的[Promise]对象。

 

    html2canvas(document.body).then(function(canvas) {

        document.body.appendChild(canvas);

    });

 

### Building ###

构建

The library uses [grunt](http://gruntjs.com/) for building. Alternatively, you can download the latest build from [here](https://github.com/niklasvh/html2canvas/blob/master/dist/html2canvas.js).

这个JS库适用[grunt]构建，或者你可以下载最新构建好的库。

 

Clone git repository with submodules:

作为一个插件构建来客隆git库

    $ git clone --recursive git://github.com/niklasvh/html2canvas.git

 

Install Grunt and uglifyjs:

 

    $ npm install -g grunt-cli uglify-js

 

Run the full build process (including lint, qunit and webdriver tests):

 

    $ grunt

 

Skip lint and tests and simply build from source:

 

    $ grunt build

 

### Running tests ###

 

The library has two sets of tests. The first set is a number of qunit tests that check that different values parsed by browsers are correctly converted in html2canvas. To run these tests with grunt you'll need [phantomjs](http://phantomjs.org/).

 

The other set of tests run Firefox, Chrome and Internet Explorer with [webdriver](https://github.com/niklasvh/webdriver.js). The selenium standalone server (runs on Java) is required for these tests and can be downloaded from [here](http://code.google.com/p/selenium/downloads/list). They capture an actual screenshot from the test pages and compare the image to the screenshot created by html2canvas and calculate the percentage differences. These tests generally aren't expected to provide 100% matches, but while commiting changes, these should generally not go decrease from the baseline values.

 

Start by downloading the dependencies:

 

    $ npm install

 

Run qunit tests:

 

    $ grunt test

 

### Examples ###

 

For more information and examples, please visit the [homepage](http://html2canvas.hertzen.com) or try the [test console](http://html2canvas.hertzen.com/screenshots.html).

 

### Contributing ###

 

If you wish to contribute to the project, please send the pull requests to the develop branch. Before submitting any changes, try and test that the changes work with all the support browsers. If some CSS property isn't supported or is incomplete, please create appropriate tests for it as well before submitting any code changes.