1 | # ![jsPDF](https://parall.ax/parallax-2016/img/svg/jspdf-logo.svg)
|
2 |
|
3 | [![Build Status](https://saucelabs.com/buildstatus/jspdf)](https://saucelabs.com/beta/builds/526e7fda50bd4f97a854bf10f280305d)
|
4 | [![Code Climate](https://codeclimate.com/repos/57f943855cdc43705e00592f/badges/2665cddeba042dc5191f/gpa.svg)](https://codeclimate.com/repos/57f943855cdc43705e00592f/feed)
|
5 | [![Test Coverage](https://codeclimate.com/repos/57f943855cdc43705e00592f/badges/2665cddeba042dc5191f/coverage.svg)](https://codeclimate.com/repos/57f943855cdc43705e00592f/coverage)
|
6 | [![GitHub license](https://img.shields.io/github/license/MrRio/jsPDF.svg)](https://github.com/MrRio/jsPDF/blob/master/LICENSE)
|
7 | [![Total alerts](https://img.shields.io/lgtm/alerts/g/MrRio/jsPDF.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/MrRio/jsPDF/alerts/)
|
8 | [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/MrRio/jsPDF.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/MrRio/jsPDF/context:javascript)
|
9 | [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/from-referrer/)
|
10 |
|
11 | **A library to generate PDFs in JavaScript.**
|
12 |
|
13 | You can [catch me on twitter](http://twitter.com/MrRio): [@MrRio](http://twitter.com/MrRio) or head over to [my company's website](http://parall.ax) for consultancy.
|
14 |
|
15 | jsPDF is now co-maintained by [yWorks - the diagramming experts](https://www.yworks.com/).
|
16 |
|
17 | ## [Live Demo](http://raw.githack.com/MrRio/jsPDF/master/) | [Documentation](http://raw.githack.com/MrRio/jsPDF/master/docs/)
|
18 |
|
19 | ## Install
|
20 |
|
21 | Recommended: get jsPDF from npm:
|
22 |
|
23 | ```sh
|
24 | npm install jspdf --save
|
25 | # or
|
26 | yarn add jspdf
|
27 | ```
|
28 |
|
29 | Alternatively, load it from a CDN:
|
30 |
|
31 | ```html
|
32 | <script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.3.0/jspdf.umd.min.js"></script>
|
33 | ```
|
34 |
|
35 | Or always get latest version via [unpkg](https://unpkg.com/browse/jspdf/)
|
36 |
|
37 | ```html
|
38 | <script src="https://unpkg.com/jspdf@latest/dist/jspdf.umd.min.js"></script>
|
39 | ```
|
40 |
|
41 | The `dist` folder of this package contains different kinds of files:
|
42 |
|
43 | - **jspdf.es.\*.js**: Modern ES2015 module format.
|
44 | - **jspdf.node.\*.js**: For running in Node. Uses file operations for loading/saving files instead of browser APIs.
|
45 | - **jspdf.umd.\*.js**: UMD module format. For AMD or script-tag loading.
|
46 | - **polyfills\*.js**: Required polyfills for older browsers like Internet Explorer. The es variant simply imports all
|
47 | required polyfills from `core-js`, the umd variant is self-contained.
|
48 |
|
49 | Usually it is not necessary to specify the exact file in the import statement. Build tools or Node automatically figure
|
50 | out the right file, so importing "jspdf" is enough.
|
51 |
|
52 | ## Usage
|
53 |
|
54 | Then you're ready to start making your document:
|
55 |
|
56 | ```javascript
|
57 | import { jsPDF } from "jspdf";
|
58 |
|
59 | // Default export is a4 paper, portrait, using millimeters for units
|
60 | const doc = new jsPDF();
|
61 |
|
62 | doc.text("Hello world!", 10, 10);
|
63 | doc.save("a4.pdf");
|
64 | ```
|
65 |
|
66 | If you want to change the paper size, orientation, or units, you can do:
|
67 |
|
68 | ```javascript
|
69 | // Landscape export, 2×4 inches
|
70 | const doc = new jsPDF({
|
71 | orientation: "landscape",
|
72 | unit: "in",
|
73 | format: [4, 2]
|
74 | });
|
75 |
|
76 | doc.text("Hello world!", 1, 1);
|
77 | doc.save("two-by-four.pdf");
|
78 | ```
|
79 |
|
80 | ### Running in Node.js
|
81 |
|
82 | ```javascript
|
83 | const { jsPDF } = require("jspdf"); // will automatically load the node version
|
84 |
|
85 | const doc = new jsPDF();
|
86 | doc.text("Hello world!", 10, 10);
|
87 | doc.save("a4.pdf"); // will save the file in the current working directory
|
88 | ```
|
89 |
|
90 | ### Other Module Formats
|
91 |
|
92 | <details>
|
93 | <summary>
|
94 | <b>AMD</b>
|
95 | </summary>
|
96 |
|
97 | ```js
|
98 | require(["jspdf"], ({ jsPDF }) => {
|
99 | const doc = new jsPDF();
|
100 | doc.text("Hello world!", 10, 10);
|
101 | doc.save("a4.pdf");
|
102 | });
|
103 | ```
|
104 |
|
105 | </details>
|
106 |
|
107 | <details>
|
108 | <summary>
|
109 | <b>Globals</b>
|
110 | </summary>
|
111 |
|
112 | ```js
|
113 | const { jsPDF } = window.jspdf;
|
114 |
|
115 | const doc = new jsPDF();
|
116 | doc.text("Hello world!", 10, 10);
|
117 | doc.save("a4.pdf");
|
118 | ```
|
119 |
|
120 | </details>
|
121 |
|
122 | ### Optional dependencies
|
123 |
|
124 | Some functions of jsPDF require optional dependencies. E.g. the `html` method, which depends on `html2canvas` and,
|
125 | when supplied with a string HTML document, `dompurify`. JsPDF loads them dynamically when required
|
126 | (using the respective module format, e.g. dynamic imports). Build tools like Webpack will automatically create separate
|
127 | chunks for each of the optional dependencies. If your application does not use any of the optional dependencies, you
|
128 | can prevent Webpack from generating the chunks by defining them as external dependencies:
|
129 |
|
130 | ```js
|
131 | // webpack.config.js
|
132 | module.exports = {
|
133 | // ...
|
134 | externals: {
|
135 | // only define the dependencies you are NOT using as externals!
|
136 | canvg: "canvg",
|
137 | html2canvas: "html2canvas",
|
138 | dompurify: "dompurify"
|
139 | }
|
140 | };
|
141 | ```
|
142 |
|
143 | In **Vue CLI** projects, externals can be defined via the [configureWebpack](https://cli.vuejs.org/config/#configurewebpack)
|
144 | or [chainWebpack](https://cli.vuejs.org/config/#chainwebpack) properties of the `vue.config.js` file
|
145 | (needs to be created, first, in fresh projects).
|
146 |
|
147 | In **Angular** projects, externals can be defined using
|
148 | [custom webpack builders](https://github.com/just-jeb/angular-builders/tree/master/packages/custom-webpack).
|
149 |
|
150 | In **React** (`create-react-app`) projects, externals can be defined by either using
|
151 | [react-app-rewired](https://github.com/timarney/react-app-rewired) or ejecting.
|
152 |
|
153 | ### TypeScript/Angular/Webpack/React/etc. Configuration:
|
154 |
|
155 | jsPDF can be imported just like any other 3rd party library. This works with all major toolkits and frameworks. jsPDF
|
156 | also offers a typings file for TypeScript projects.
|
157 |
|
158 | ```js
|
159 | import { jsPDF } from "jspdf";
|
160 | ```
|
161 |
|
162 | You can add jsPDF to your meteor-project as follows:
|
163 |
|
164 | ```
|
165 | meteor add jspdf:core
|
166 | ```
|
167 |
|
168 | ### Polyfills
|
169 |
|
170 | jsPDF requires modern browser APIs in order to function. To use jsPDF in older browsers like Internet Explorer,
|
171 | polyfills are required. You can load all required polyfills as follows:
|
172 |
|
173 | ```js
|
174 | import "jspdf/dist/polyfills.es.js";
|
175 | ```
|
176 |
|
177 | Alternatively, you can load the prebundled polyfill file. This is not recommended, since you might end up
|
178 | loading polyfills multiple times. Might still be nifty for small applications or quick POCs.
|
179 |
|
180 | ```html
|
181 | <script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.3.0/polyfills.umd.js"></script>
|
182 | ```
|
183 |
|
184 | ## Use of Unicode Characters / UTF-8:
|
185 |
|
186 | The 14 standard fonts in PDF are limited to the ASCII-codepage. If you want to use UTF-8 you have to integrate a
|
187 | custom font, which provides the needed glyphs. jsPDF supports .ttf-files. So if you want to have for example
|
188 | Chinese text in your pdf, your font has to have the necessary Chinese glyphs. So, check if your font supports
|
189 | the wanted glyphs or else it will show garbled characters instead of the right text.
|
190 |
|
191 | To add the font to jsPDF use our fontconverter in
|
192 | [/fontconverter/fontconverter.html](https://rawgit.com/MrRio/jsPDF/master/fontconverter/fontconverter.html).
|
193 | The fontconverter will create a js-file with the content of the provided ttf-file as base64 encoded string
|
194 | and additional code for jsPDF. You just have to add this generated js-File to your project.
|
195 | You are then ready to go to use setFont-method in your code and write your UTF-8 encoded text.
|
196 |
|
197 | Alternatively you can just load the content of the \*.ttf file as a binary string using `fetch` or `XMLHttpRequest` and
|
198 | add the font to the PDF file:
|
199 |
|
200 | ```js
|
201 | const doc = new jsPDF();
|
202 |
|
203 | const myFont = ... // load the *.ttf font file as binary string
|
204 |
|
205 | // add the font to jsPDF
|
206 | doc.addFileToVFS("MyFont.ttf", myFont);
|
207 | doc.addFont("MyFont.ttf", "MyFont", "normal");
|
208 | ```
|
209 |
|
210 | ## Advanced Functionality
|
211 |
|
212 | Since the merge with the [yWorks fork](https://github.com/yWorks/jsPDF) there are a lot of new features. However, some
|
213 | of them are API breaking, which is why there is an API-switch between two API modes:
|
214 |
|
215 | - In "compat" API mode, jsPDF has the same API as MrRio's original version, which means full compatibility with plugins.
|
216 | However, some advanced features like transformation matrices and patterns won't work. This is the default mode.
|
217 | - In "advanced" API mode, jsPDF has the API you're used from the yWorks-fork version. This means the availability of
|
218 | all advanced features like patterns, FormObjects, and transformation matrices.
|
219 |
|
220 | You can switch between the two modes by calling
|
221 |
|
222 | ```javascript
|
223 | doc.advancedAPI(doc => {
|
224 | // your code
|
225 | });
|
226 | // or
|
227 | doc.compatAPI(doc => {
|
228 | // your code
|
229 | });
|
230 | ```
|
231 |
|
232 | JsPDF will automatically switch back to the original API mode after the callback has run.
|
233 |
|
234 | ## Support
|
235 |
|
236 | Please check if your question is already handled at Stackoverflow <https://stackoverflow.com/questions/tagged/jspdf>.
|
237 | Feel free to ask a question there with the tag `jspdf`.
|
238 |
|
239 | Feature requests, bug reports, etc. are very welcome as issues. Note that bug reports should follow these guidelines:
|
240 |
|
241 | - A bug should be reported as an [mcve](https://stackoverflow.com/help/mcve)
|
242 | - Make sure code is properly indented and [formatted](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) (Use ``` around code blocks)
|
243 | - Provide a runnable example.
|
244 | - Try to make sure and show in your issue that the issue is actually related to jspdf and not your framework of choice.
|
245 |
|
246 | ## Contributing
|
247 |
|
248 | jsPDF cannot live without help from the community! If you think a feature is missing or you found a bug, please consider
|
249 | if you can spare one or two hours and prepare a pull request. If you're simply interested in this project and want to
|
250 | help, have a look at the open issues, especially those labeled with "bug".
|
251 |
|
252 | You can find information about building and testing jsPDF in the
|
253 | [contribution guide](https://github.com/MrRio/jsPDF/blob/master/CONTRIBUTING.md#pull-requests)
|
254 |
|
255 | ## Credits
|
256 |
|
257 | - Big thanks to Daniel Dotsenko from [Willow Systems Corporation](https://github.com/willowsystems) for making huge contributions to the codebase.
|
258 | - Thanks to Ajaxian.com for [featuring us back in 2009](http://ajaxian.com/archives/dynamically-generic-pdfs-with-javascript).
|
259 | - Our special thanks to GH Lee ([sphilee](https://github.com/sphilee)) for programming the ttf-file-support and providing a large and long sought after feature
|
260 | - Everyone else that's contributed patches or bug reports. You rock.
|
261 |
|
262 | ## License (MIT)
|
263 |
|
264 | Copyright
|
265 | (c) 2010-2020 James Hall, https://github.com/MrRio/jsPDF
|
266 | (c) 2015-2020 yWorks GmbH, https://www.yworks.com/
|
267 |
|
268 | Permission is hereby granted, free of charge, to any person obtaining
|
269 | a copy of this software and associated documentation files (the
|
270 | "Software"), to deal in the Software without restriction, including
|
271 | without limitation the rights to use, copy, modify, merge, publish,
|
272 | distribute, sublicense, and/or sell copies of the Software, and to
|
273 | permit persons to whom the Software is furnished to do so, subject to
|
274 | the following conditions:
|
275 |
|
276 | The above copyright notice and this permission notice shall be
|
277 | included in all copies or substantial portions of the Software.
|
278 |
|
279 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
280 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
281 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
282 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
283 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
284 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
285 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
286 |
|
\ | No newline at end of file |