mirror/html2canvas
1
0
Fork 0
mirror of https://github.com/niklasvh/html2canvas.git synced 2023-08-10 21:13:10 +03:00
Code Issues Projects Releases Wiki Activity

Update wip website

Browse Source
This commit is contained in:
Niklas von Hertzen
2017-12-10 16:43:34 +08:00
parent 9bc0fb0bd1
commit 8fd616aed2
23 changed files with 7746 additions and 658 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/about.md
View File

@ -1,33 +1,37 @@
---
title: "About"
description: "Learn about html2canvas, how it works and some of its limitations"
nextUrl: "/getting-started"
nextTitle: "Getting Started"
---
Before you get started with the script, there are a few things that are good to know regarding the
script and some of its limitations.
# Introduction
## Introduction
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.
# How it works
## How it works
The script traverses through the DOM of the page it is loaded on. It gathers information on all the elements
there, which it then uses to build a representation of the page. In other words, it does not actually take a
screenshot of the page, but builds a representation of it based on the properties it reads from the DOM.
As a result, it is only able to render correctly properties that it understands, meaning there are many
CSS properties which do not work. For a full list of supported CSS properties, check out the
[support features](/features/) page.
[supported features](/features/) page.
# Limitations
## Limitations
All the images that the script uses need to reside under the [same origin](http://en.wikipedia.org/wiki/Same_origin_policy)
for it to be able to read them without the assistance of a [proxy](/proxy/). Similarly, if you have other `canvas`
elements on the page, which have been tainted with cross-origin content, they will become dirty and no longer readable by html2canvas.
The script doesn't render plugin content such as Flash or Java applets.
# Browser compatibility
## Browser compatibility
The library should work fine on the following browsers (with `Promise` polyfill):
- Firefox 3.5+

43
docs/configuration.md
View File

@ -1,25 +1,30 @@
---
title: "Configuration"
description: "Explore the different configuration options available for html2canvas"
previousUrl: "/getting-started"
previousTitle: "Getting Started"
nextUrl: "/features"
nextTitle: "Features"
---
These are all of the available configuration options.
| Name | Type | Default | Description |
| ------------- |:-------------:| :------: | ----------- |
| async | Boolean | `true` | Whether to parse and render the element asynchronously
| allowTaint | Boolean | `false` | Whether to allow cross-origin images to taint the canvas
| backgroundColor | String | `#ffffff` | Canvas background color, if none is specified in DOM. Set undefined for transparent
| canvas | `HTMLCanvasElement` | `null` | Existing `canvas` element to use as a base for drawing on
| foreignObjectRendering | Boolean | `false` | Whether to use ForeignObject rendering if the browser supports it
| imageTimeout | Number | `15000` | Timeout for loading an image (in milliseconds). Set to `0` to disable timeout.
| proxy | String | `null` | Url to the [proxy](/proxy/) which is to be used for loading cross-origin images. If left empty, cross-origin images won't be loaded.
| removeContainer | Boolean | `true` | Whether to cleanup the cloned DOM elements html2canvas creates temporarily
| scale | Number | `window.devicePixelRatio` | The scale to use for rendering. Defaults to the browsers device pixel ratio.
| width | Number | `Element` width | The width of the `canvas`
| height | Number | `Element` height | The height of the `canvas`
| x | Number | `Element` x-offset | Crop canvas x-coordinate
| y | Number | `Element` y-offset| Crop canvas y-coordinate
| scrollX | Number | `Element` scrollX | The x-scroll position to used when rendering element, (for example if the Element uses `position: fixed`)
| scrollY | Number | `Element` scrollY | The y-scroll position to used when rendering element, (for example if the Element uses `position: fixed`)
| windowWidth | Number | `Window.innerWidth` | Window width to use when rendering `Element`, which may affect things like Media queries
| windowHeight | Number | `Window.innerHeight` | Window height to use when rendering `Element`, which may affect things like Media queries
| Name | Default | Description |
| ------------- | :------: | ----------- |
| async | `true` | Whether to parse and render the element asynchronously
| allowTaint | `false` | Whether to allow cross-origin images to taint the canvas
| backgroundColor | `#ffffff` | Canvas background color, if none is specified in DOM. Set undefined for transparent
| canvas | `null` | Existing `canvas` element to use as a base for drawing on
| foreignObjectRendering | `false` | Whether to use ForeignObject rendering if the browser supports it
| imageTimeout | `15000` | Timeout for loading an image (in milliseconds). Set to `0` to disable timeout.
| proxy | `null` | Url to the [proxy](/proxy/) which is to be used for loading cross-origin images. If left empty, cross-origin images won't be loaded.
| removeContainer | `true` | Whether to cleanup the cloned DOM elements html2canvas creates temporarily
| scale | `window.devicePixelRatio` | The scale to use for rendering. Defaults to the browsers device pixel ratio.
| width | `Element` width | The width of the `canvas`
| height | `Element` height | The height of the `canvas`
| x | `Element` x-offset | Crop canvas x-coordinate
| y | `Element` y-offset| Crop canvas y-coordinate
| scrollX | `Element` scrollX | The x-scroll position to used when rendering element, (for example if the Element uses `position: fixed`)
| scrollY | `Element` scrollY | The y-scroll position to used when rendering element, (for example if the Element uses `position: fixed`)
| windowWidth | `Window.innerWidth` | Window width to use when rendering `Element`, which may affect things like Media queries
| windowHeight | `Window.innerHeight` | Window height to use when rendering `Element`, which may affect things like Media queries

42
docs/faq.md Normal file
View File

@ -0,0 +1,42 @@
---
title: "FAQ"
description: "Explore Frequently Asked Questions regarding html2canvas"
---
## Why aren't my images rendered?
html2canvas does not get around content policy restrictions set by your browser. Drawing images that reside outside of
the [origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) of the current page [taint the
canvas](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image#What_is_a_tainted_canvas) that they are drawn upon. If the canvas gets tainted, it cannot be read anymore. As such, html2canvas implements
methods to check whether an image would taint the canvas before applying it. If you have set the `allowTaint`
[option](/configuration) to `false`, it will not draw the image.
If you wish to load images that reside outside of your pages origin, you can use a [proxy](/proxy) to load the images.
## Why is the produced canvas empty or cuts off half way through?
Make sure that `canvas` element doesn't hit [browser limitations](https://stackoverflow.com/questions/6081483/maximum-size-of-a-canvas-element) for the `canvas` size.
The limitations vary by browser, operating system and system hardware.
### Chrome
> Maximum height/width: 32,767 pixels
> Maximum area: 268,435,456 pixels (e.g., 16,384 x 16,384)
### Firefox
> Maximum height/width: 32,767 pixels
> Maximum area: 472,907,776 pixels (e.g., 22,528 x 20,992)
### Internet Explorer
> Maximum height/width: 8,192 pixels
> Maximum area: N/A
### iOS
> The maximum size for a canvas element is 3 megapixels for devices with less than 256 MB RAM and 5 megapixels for devices with greater or equal than 256 MB RAM
## Why doesn't CSS property X render correctly or only partially?
As each CSS property needs to be manually coded to render correctly, html2canvas will *never* have full CSS support.
The library tries to support the most [commonly used CSS properties](/features) to the extent that it can. If some CSS property
is missing or incomplete and you feel that it should be part of the library, create test cases for it and a new issue for it.
## How do I get html2canvas to work in a browser extension?
You shouldn't use html2canvas in a browser extension. Most browsers have native support for capturing screenshots from
tabs within extensions. Relevant information for [Chrome](https://developer.chrome.com/extensions/tabs#method-captureVisibleTab) and
[Firefox](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D#drawWindow()).

1
docs/features.md
View File

@ -1,5 +1,6 @@
---
title: "Features"
description: "Discover the different features supported by html2canvas"
---
Below is a list of all the supported CSS properties and values.

9
docs/getting-started.md
View File

@ -1,8 +1,13 @@
---
title: "Getting Started"
description: "Learn how to start using html2canvas"
previousUrl: "/about"
previousTitle: "About"
nextUrl: "/configuration"
nextTitle: "Configuration"
---
# Installing
## Installing
You can install `html2canvas` through npm or [download a built release](https://github.com/niklasvh/html2canvas/releases).
@ -14,7 +19,7 @@ You can install `html2canvas` through npm or [download a built release](https://
import html2canvas from 'html2canvas';
```
# Usage
## Usage
To render an `element` with html2canvas with some (optional) [options](/configuration/), simply call `html2canvas(element, options);`

3
docs/proxy.md
View File

@ -1,11 +1,12 @@
---
title: "Proxy"
description: "Browse different proxies available for supporting CORS content"
---
html2canvas does not get around content policy restrictions set by your browser. Drawing images that reside outside of
the origin of the current page taint the canvas that they are drawn upon. If the canvas gets tainted,
it cannot be read anymore. If you wish to load images that reside outside of your pages origin, you can use a proxy to load the images.
# Available proxies
## Available proxies
- [node.js](https://github.com/niklasvh/html2canvas-proxy-nodejs)