From 63377d47a458f56872b3e2704c0e599bb38ba4cd Mon Sep 17 00:00:00 2001 From: Niklas von Hertzen Date: Thu, 7 Dec 2017 23:49:40 +0800 Subject: [PATCH] Begin adding documentation --- docs/about.md | 38 +++++++++++++++++++++++ docs/configuration.md | 25 +++++++++++++++ docs/features.md | 67 +++++++++++++++++++++++++++++++++++++++++ docs/getting-started.md | 25 +++++++++++++++ docs/proxy.md | 11 +++++++ 5 files changed, 166 insertions(+) create mode 100644 docs/about.md create mode 100644 docs/configuration.md create mode 100644 docs/features.md create mode 100644 docs/getting-started.md create mode 100644 docs/proxy.md diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..e6794eb --- /dev/null +++ b/docs/about.md @@ -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+ diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..ec9ce81 --- /dev/null +++ b/docs/configuration.md @@ -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 diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..b708b4d --- /dev/null +++ b/docs/features.md @@ -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) + diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..3fd5300 --- /dev/null +++ b/docs/getting-started.md @@ -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); +}); +``` diff --git a/docs/proxy.md b/docs/proxy.md new file mode 100644 index 0000000..455becb --- /dev/null +++ b/docs/proxy.md @@ -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)