mirror of
https://github.com/niklasvh/html2canvas.git
synced 2023-08-10 21:13:10 +03:00
Begin adding documentation
This commit is contained in:
Niklas von Hertzen
parent
1d1c74a74e
commit
63377d47a4
38
docs/about.md
Normal file
38
docs/about.md
Normal file
@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "About"
|
||||
---
|
||||
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
# 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
|
||||
|
||||
The library should work fine on the following browsers (with `Promise` polyfill):
|
||||
- Firefox 3.5+
|
||||
- Google Chrome
|
||||
- Opera 12+
|
||||
- IE9+
|
||||
- Edge
|
||||
- Safari 6+
|
||||
25
docs/configuration.md
Normal file
25
docs/configuration.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "Configuration"
|
||||
---
|
||||
|
||||
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
|
||||
67
docs/features.md
Normal file
67
docs/features.md
Normal file
@ -0,0 +1,67 @@
|
||||
---
|
||||
title: "Features"
|
||||
---
|
||||
|
||||
Below is a list of all the supported CSS properties and values.
|
||||
|
||||
- background
|
||||
- background-clip (**Does not support `text`**)
|
||||
- background-color
|
||||
- background-image
|
||||
- url()
|
||||
- linear-gradient()
|
||||
- background-origin
|
||||
- background-position
|
||||
- background-size
|
||||
- border
|
||||
- border-color
|
||||
- border-radius
|
||||
- border-style (**Only supports `solid`**)
|
||||
- border-width
|
||||
- bottom
|
||||
- box-sizing
|
||||
- content (**Does not support `attr()`**)
|
||||
- color
|
||||
- display
|
||||
- flex
|
||||
- float
|
||||
- font
|
||||
- font-family
|
||||
- font-size
|
||||
- font-style
|
||||
- font-variant
|
||||
- font-weight
|
||||
- height
|
||||
- left
|
||||
- letter-spacing
|
||||
- margin
|
||||
- opacity
|
||||
- overflow
|
||||
- padding
|
||||
- position
|
||||
- right
|
||||
- text-align
|
||||
- text-decoration
|
||||
- text-decoration-color
|
||||
- text-decoration-line
|
||||
- text-decoration-style (**Only supports `solid`**)
|
||||
- text-shadow
|
||||
- text-transform
|
||||
- top
|
||||
- transform (**Limited support**)
|
||||
- visibility
|
||||
- white-space
|
||||
- width
|
||||
- word-spacing
|
||||
- z-index
|
||||
|
||||
## Unsupported CSS properties
|
||||
These CSS properties are **NOT** currently supported
|
||||
- [background-blend-mode](https://github.com/niklasvh/html2canvas/issues/966)
|
||||
- [box-shadow](https://github.com/niklasvh/html2canvas/pull/1086)
|
||||
- [filter](https://github.com/niklasvh/html2canvas/issues/493)
|
||||
- [font-variant-ligatures](https://github.com/niklasvh/html2canvas/pull/1085)
|
||||
- [list-style](https://github.com/niklasvh/html2canvas/issues/177)
|
||||
- word-break
|
||||
- [writing-mode](https://github.com/niklasvh/html2canvas/issues/1258)
|
||||
|
||||
25
docs/getting-started.md
Normal file
25
docs/getting-started.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: "Getting Started"
|
||||
---
|
||||
|
||||
# Installing
|
||||
|
||||
You can install `html2canvas` through npm or [download a built release](https://github.com/niklasvh/html2canvas/releases).
|
||||
|
||||
### npm
|
||||
|
||||
npm install html2canvas
|
||||
|
||||
```javascript
|
||||
import html2canvas from 'html2canvas';
|
||||
```
|
||||
|
||||
# Usage
|
||||
|
||||
To render an `element` with html2canvas with some (optional) [options](/configuration/), simply call `html2canvas(element, options);`
|
||||
|
||||
```javascript
|
||||
html2canvas(document.body).then(function(canvas) {
|
||||
document.body.appendChild(canvas);
|
||||
});
|
||||
```
|
||||
11
docs/proxy.md
Normal file
11
docs/proxy.md
Normal file
@ -0,0 +1,11 @@
|
||||
---
|
||||
title: "Proxy"
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
- [node.js](https://github.com/niklasvh/html2canvas-proxy-nodejs)
|
||||
Loading…
Reference in New Issue
Block a user