Skip to content

Commit 401c95a

Browse files
eKoopmanseKoopmans
committed
Merge branch 'release/v0.9.1'
2 parents f1b0449 + 3771146 commit 401c95a

15 files changed

+6566
-1787
lines changed

‎README.md

Lines changed: 77 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,31 @@
22

33
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).
44

5+
## Table of contents
6+
7+
- [Getting started](#getting-started)
8+
- [HTML](#html)
9+
- [NPM](#npm)
10+
- [Bower](#bower)
11+
- [Usage](#usage)
12+
- [Advanced usage](#advanced-usage)
13+
- [Workflow](#workflow)
14+
- [Worker API](#worker-api)
15+
- [Options](#options)
16+
- [Page-breaks](#page-breaks)
17+
- [Page-break settings](#page-break-settings)
18+
- [Page-break modes](#page-break-modes)
19+
- [Example usage](#example-usage)
20+
- [Image type and quality](#image-type-and-quality)
21+
- [Progress tracking](#progress-tracking)
22+
- [Dependencies](#dependencies)
23+
- [Contributing](#contributing)
24+
- [Issues](#issues)
25+
- [Tests](#tests)
26+
- [Pull requests](#pull-requests)
27+
- [Credits](#credits)
28+
- [License](#license)
29+
530
## Getting started
631

732
#### HTML
@@ -98,33 +123,64 @@ var opt = {
98123
};
99124

100125
// New Promise-based usage:
101-
html2pdf().from(element).set(opt).save();
126+
html2pdf().set(opt).from(element).save();
102127

103128
// Old monolithic-style usage:
104129
html2pdf(element, opt);
105130
```
106131

107132
The `opt` parameter has the following optional fields:
108133

109-
|Name |Type |Default |Description |
110-
|------------|----------------|------------------------------|------------------------------------------------------------------------------------------------------------|
111-
|margin |number or array |0 |PDF margin (in jsPDF units). Can be a single number, `[vMargin, hMargin]`, or `[top, left, bottom, right]`. |
112-
|filename |string |'file.pdf' |The default filename of the exported PDF. |
113-
|image |object |{type: 'jpeg', quality: 0.95} |The image type and quality used to generate the PDF. See the Extra Features section below. |
114-
|enableLinks |boolean |true |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags. |
115-
|html2canvas |object |{ } |Configuration options sent directly to `html2canvas` ([see here](https://html2canvas.hertzen.com/configuration) for usage).|
116-
|jsPDF |object |{ } |Configuration options sent directly to `jsPDF` ([see here](http://rawgit.com/MrRio/jsPDF/master/docs/jsPDF.html) for usage).|
134+
|Name |Type |Default |Description |
135+
|------------|----------------|--------------------------------|------------------------------------------------------------------------------------------------------------|
136+
|margin |number or array |`0` |PDF margin (in jsPDF units). Can be a single number, `[vMargin, hMargin]`, or `[top, left, bottom, right]`. |
137+
|filename |string |`'file.pdf'` |The default filename of the exported PDF. |
138+
|pagebreak |object |`{mode: ['css', 'legacy']}` |Controls the pagebreak behaviour on the page. See [Page-breaks](#page-breaks) below. |
139+
|image |object |`{type: 'jpeg', quality: 0.95}` |The image type and quality used to generate the PDF. See [Image type and quality](#image-type-and-quality) below.|
140+
|enableLinks |boolean |`true` |If enabled, PDF hyperlinks are automatically added ontop of all anchor tags. |
141+
|html2canvas |object |`{ }` |Configuration options sent directly to `html2canvas` ([see here](https://html2canvas.hertzen.com/configuration) for usage).|
142+
|jsPDF |object |`{ }` |Configuration options sent directly to `jsPDF` ([see here](http://rawgit.com/MrRio/jsPDF/master/docs/jsPDF.html) for usage).|
117143

118144
### Page-breaks
119145

120-
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:
146+
html2pdf has the ability to automatically add page-breaks to clean up your document. Page-breaks can be added by CSS styles, set on individual elements using selectors, or avoided from breaking inside all elements (`avoid-all` mode).
121147

122-
```html
123-
<div id="element-to-print">
124-
<span>I'm on page 1!</span>
125-
<div class="html2pdf__page-break"></div>
126-
<span>I'm on page 2!</span>
127-
</div>
148+
By default, html2pdf will respect most CSS [`break-before`](https://developer.mozilla.org/en-US/docs/Web/CSS/break-before), [`break-after`](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after), and [`break-inside`](https://developer.mozilla.org/en-US/docs/Web/CSS/break-inside) rules, and also add page-breaks after any element with class `html2pdf__page-break` (for legacy purposes).
149+
150+
#### Page-break settings
151+
152+
|Setting |Type |Default |Description |
153+
|----------|----------------|--------------------|------------|
154+
|mode |string or array |`['css', 'legacy']` |The mode(s) on which to automatically add page-breaks. One or more of `'avoid-all'`, `'css'`, and `'legacy'`. |
155+
|before |string or array |`[]` |CSS selectors for which to add page-breaks before each element. Can be a specific element with an ID (`'#myID'`), all elements of a type (e.g. `'img'`), all of a class (`'.myClass'`), or even `'*'` to match every element. |
156+
|after |string or array |`[]` |Like 'before', but adds a page-break immediately after the element. |
157+
|avoid |string or array |`[]` |Like 'before', but avoids page-breaks on these elements. You can enable this feature on every element using the 'avoid-all' mode. |
158+
159+
#### Page-break modes
160+
161+
| Mode | Description |
162+
|-----------|-------------|
163+
| avoid-all | Automatically adds page-breaks to avoid splitting any elements across pages. |
164+
| css | Adds page-breaks according to the CSS `break-before`, `break-after`, and `break-inside` properties. Only recognizes `always/left/right` for before/after, and `avoid` for inside. |
165+
| legacy | Adds page-breaks after elements with class `html2pdf__page-break`. This feature may be removed in the future. |
166+
167+
#### Example usage
168+
169+
```js
170+
// Avoid page-breaks on all elements, and add one before #page2el.
171+
html2pdf().set({
172+
pagebreak: { mode: 'avoid-all', before: '#page2el' }
173+
});
174+
175+
// Enable all 'modes', with no explicit elements.
176+
html2pdf().set({
177+
pagebreak: { mode: ['avoid-all', 'css', 'legacy'] }
178+
});
179+
180+
// No modes, only explicit elements.
181+
html2pdf().set({
182+
pagebreak: { before: '.beforeClass', after: ['#after1', '#after2'], avoid: 'img' }
183+
});
128184
```
129185

130186
### Image type and quality
@@ -138,7 +194,7 @@ You may customize the image type and quality exported from the canvas by setting
138194

139195
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.
140196

141-
## Progress
197+
## Progress tracking
142198

143199
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.
144200

@@ -161,6 +217,10 @@ If using the unbundled `dist/html2pdf.min.js` (or its un-minified version), you
161217

162218
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.
163219

220+
### Tests
221+
222+
html2pdf is currently sorely lacking in unit tests. Any contributions or suggestions of automated (or manual) tests are welcome. This is high on the to-do list for this project.
223+
164224
### Pull requests
165225

166226
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`.

0 commit comments

Comments
 (0)