mirror of
https://github.com/dyiop/astute.git
synced 2025-04-15 09:40:17 -04:00
177 lines
10 KiB
Markdown
177 lines
10 KiB
Markdown
# html2pdf
|
|
|
|
html2pdf converts any webpage or element into a printable PDF entirely client-side using [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF).
|
|
|
|
## Getting started
|
|
|
|
#### HTML
|
|
|
|
The simplest way to use html2pdf is to download `dist/html2pdf.bundle.min.js` to your project folder and include it in your HTML with:
|
|
|
|
```html
|
|
<script src="html2pdf.bundle.min.js"></script>
|
|
```
|
|
|
|
*Note: [Click here](#dependencies) for more information about using the unbundled version `dist/html2canvas.min.js`.*
|
|
|
|
#### NPM
|
|
|
|
Install html2pdf and its dependencies using NPM with `npm install --save html2pdf.js` (make sure to include `.js` in the package name).
|
|
|
|
*Note: You can use NPM to create your project, but html2pdf **will not run in Node.js**, it must be run in a browser.*
|
|
|
|
#### Bower
|
|
|
|
Install html2pdf and its dependencies using Bower with `bower install --save html2pdf.js` (make sure to include `.js` in the package name).
|
|
|
|
## Usage
|
|
|
|
Once installed, html2pdf is ready to use. The following command will generate a PDF of `#element-to-print` and prompt the user to save the result:
|
|
|
|
```js
|
|
var element = document.getElementById('element-to-print');
|
|
html2pdf(element);
|
|
```
|
|
|
|
### Advanced usage
|
|
|
|
Every step of html2pdf is configurable, using its new Promise-based API. If html2pdf is called without arguments, it will return a `Worker` object:
|
|
|
|
```js
|
|
var worker = html2pdf(); // Or: var worker = new html2pdf.Worker;
|
|
```
|
|
|
|
This worker has methods that can be chained sequentially, as each Promise resolves, and allows insertion of your own intermediate functions between steps. A prerequisite system allows you to skip over mandatory steps (like canvas creation) without any trouble:
|
|
|
|
```js
|
|
// This will implicitly create the canvas and PDF objects before saving.
|
|
var worker = html2pdf().from(element).save();
|
|
```
|
|
|
|
#### Workflow
|
|
|
|
The basic workflow of html2pdf tasks (enforced by the prereq system) is:
|
|
|
|
```
|
|
.from() -> .toContainer() -> .toCanvas() -> .toImg() -> .toPdf() -> .save()
|
|
```
|
|
|
|
#### Worker API
|
|
|
|
| Method | Arguments | Description |
|
|
|--------------|--------------------|-------------|
|
|
| from | src, type | Sets the source (HTML string or element) for the PDF. Optional `type` specifies other sources: `'string'`, `'element'`, `'canvas'`, or `'img'`. |
|
|
| to | target | Converts the source to the specified target (`'container'`, `'canvas'`, `'img'`, or `'pdf'`). Each target also has its own `toX` method that can be called directly: `toContainer()`, `toCanvas()`, `toImg()`, and `toPdf()`. |
|
|
| output | type, options, src | Routes to the appropriate `outputPdf` or `outputImg` method based on specified `src` (`'pdf'` (default) or `'img'`). |
|
|
| outputPdf | type, options | Sends `type` and `options` to the jsPDF object's `output` method, and returns the result as a Promise (use `.then` to access). See the [jsPDF source code](https://rawgit.com/MrRio/jsPDF/master/docs/jspdf.js.html#line992) for more info. |
|
|
| outputImg | type, options | Returns the specified data type for the image as a Promise (use `.then` to access). Supported types: `'img'`, `'datauristring'`/`'dataurlstring'`, and `'datauri'`/`'dataurl'`. |
|
|
| save | filename | Saves the PDF object with the optional filename (creates user download prompt). |
|
|
| set | opt | Sets the specified properties. See [Options](#options) below for more details. |
|
|
| get | key, cbk | Returns the property specified in `key`, either as a Promise (use `.then` to access), or by calling `cbk` if provided. |
|
|
| then | onFulfilled, onRejected | Standard Promise method, with `this` re-bound to the Worker, and with added progress-tracking (see [Progress](#progress) below). Note that `.then` returns a `Worker`, which is a subclass of Promise. |
|
|
| thenCore | onFulFilled, onRejected | Standard Promise method, with `this` re-bound to the Worker (no progress-tracking). Note that `.thenCore` returns a `Worker`, which is a subclass of Promise. |
|
|
| thenExternal | onFulfilled, onRejected | True Promise method. Using this 'exits' the Worker chain - you will not be able to continue chaining Worker methods after `.thenExternal`. |
|
|
| catch, catchExternal | onRejected | Standard Promise method. `catchExternal` exits the Worker chain - you will not be able to continue chaining Worker methods after `.catchExternal`. |
|
|
| error | msg | Throws an error in the Worker's Promise chain. |
|
|
|
|
A few aliases are also provided for convenience:
|
|
|
|
| Method | Alias |
|
|
|-----------|-----------|
|
|
| save | saveAs |
|
|
| set | using |
|
|
| output | export |
|
|
| then | run |
|
|
|
|
## Options
|
|
|
|
html2pdf can be configured using an optional `opt` parameter:
|
|
|
|
```js
|
|
var element = document.getElementById('element-to-print');
|
|
var opt = {
|
|
margin: 1,
|
|
filename: 'myfile.pdf',
|
|
image: { type: 'jpeg', quality: 0.98 },
|
|
html2canvas: { scale: 2 },
|
|
jsPDF: { unit: 'in', format: 'letter', orientation: 'portrait' }
|
|
};
|
|
|
|
// New Promise-based usage:
|
|
html2pdf().from(element).set(opt).save();
|
|
|
|
// Old monolithic-style usage:
|
|
html2pdf(element, opt);
|
|
```
|
|
|
|
The `opt` parameter has the following optional fields:
|
|
|
|
|Name |Type |Default |Description |
|
|
|------------|----------------|------------------------------|------------------------------------------------------------------------------------------------------------|
|
|
|margin |number or array |0 |PDF margin (in jsPDF units). Can be a single number, `[vMargin, hMargin]`, or `[top, left, bottom, right]`. |
|
|
|filename |string |'file.pdf' |The default filename of the exported PDF. |
|
|
|image |object |{type: 'jpeg', quality: 0.95} |The image type and quality used to generate the PDF. See the Extra Features section below. |
|
|
|enableLinks |boolean |true |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags. |
|
|
|html2canvas |object |{ } |Configuration options sent directly to `html2canvas` ([see here](https://html2canvas.hertzen.com/configuration) for usage).|
|
|
|jsPDF |object |{ } |Configuration options sent directly to `jsPDF` ([see here](http://rawgit.com/MrRio/jsPDF/master/docs/jsPDF.html) for usage).|
|
|
|
|
### Page-breaks
|
|
|
|
You may add `html2pdf`-specific page-breaks to your document by adding the CSS class `html2pdf__page-break` to any element (normally an empty `div`). For React elements, use `className=html2pdf__page-break`. During PDF creation, these elements will be given a height calculated to fill the remainder of the PDF page that they are on. Example usage:
|
|
|
|
```html
|
|
<div id="element-to-print">
|
|
<span>I'm on page 1!</span>
|
|
<div class="html2pdf__page-break"></div>
|
|
<span>I'm on page 2!</span>
|
|
</div>
|
|
```
|
|
|
|
### Image type and quality
|
|
|
|
You may customize the image type and quality exported from the canvas by setting the `image` option. This must be an object with the following fields:
|
|
|
|
|Name |Type |Default |Description |
|
|
|------------|----------------|------------------------------|---------------------------------------------------------------------------------------------|
|
|
|type |string |'jpeg' |The image type. HTMLCanvasElement only supports 'png', 'jpeg', and 'webp' (on Chrome). |
|
|
|quality |number |0.95 |The image quality, from 0 to 1. This setting is only used for jpeg/webp (not png). |
|
|
|
|
These options are limited to the available settings for [HTMLCanvasElement.toDataURL()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL), which ignores quality settings for 'png' images. To enable png image compression, try using the [canvas-png-compression shim](https://github.com/ShyykoSerhiy/canvas-png-compression), which should be an in-place solution to enable png compression via the `quality` option.
|
|
|
|
## Progress
|
|
|
|
The Worker object returned by `html2pdf()` has a built-in progress-tracking mechanism. It will be updated to allow a progress callback that will be called with each update, however it is currently a work-in-progress.
|
|
|
|
## Dependencies
|
|
|
|
html2pdf depends on the external packages [html2canvas](https://github.com/niklasvh/html2canvas), [jsPDF](https://github.com/MrRio/jsPDF), and [es6-promise](https://github.com/stefanpenner/es6-promise). These dependencies are automatically loaded when using NPM or the bundled package.
|
|
|
|
If using the unbundled `dist/html2pdf.min.js` (or its un-minified version), you must also include each dependency. Order is important, otherwise html2canvas will be overridden by jsPDF's own internal implementation:
|
|
|
|
```html
|
|
<script src="es6-promise.auto.min.js"></script>
|
|
<script src="jspdf.min.js"></script>
|
|
<script src="html2canvas.min.js"></script>
|
|
<script src="html2pdf.min.js"></script>
|
|
```
|
|
|
|
## Contributing
|
|
|
|
### Issues
|
|
|
|
When submitting an issue, please provide reproducible code that highlights the issue, preferably by creating a fork of [this template jsFiddle](https://jsfiddle.net/u6o6ne41/) (which has html2pdf already loaded). Remember that html2pdf uses [html2canvas](https://github.com/niklasvh/html2canvas) and [jsPDF](https://github.com/MrRio/jsPDF) as dependencies, so it's a good idea to check each of those repositories' issue trackers to see if your problem has already been addressed.
|
|
|
|
### Pull requests
|
|
|
|
If you want to create a new feature or bugfix, please feel free to fork and submit a pull request! Use the [`develop`](/eKoopmans/html2pdf/tree/develop) branch, which features the latest development, and make changes to `/src/` rather than directly to `/dist/`. You can test your changes by rebuilding with `npm run build`.
|
|
|
|
## Credits
|
|
|
|
[Erik Koopmans](https://github.com/eKoopmans)
|
|
|
|
## License
|
|
|
|
[The MIT License](http://opensource.org/licenses/MIT)
|
|
|
|
Copyright (c) 2017 Erik Koopmans <[http://www.erik-koopmans.com/](http://www.erik-koopmans.com/)>
|