|
1 | 1 | # jsPDF |
2 | 2 |
|
3 | | -[](https://greenkeeper.io/) |
4 | | -[](https://saucelabs.com/beta/builds/526e7fda50bd4f97a854bf10f280305d) |
5 | | -[](https://codeclimate.com/repos/57f943855cdc43705e00592f/feed) |
6 | | -[](https://codeclimate.com/repos/57f943855cdc43705e00592f/coverage) |
7 | | -[](https://github.com/MrRio/jsPDF/blob/master/LICENSE) |
8 | | -[](https://lgtm.com/projects/g/MrRio/jsPDF/alerts/) |
9 | | -[](https://lgtm.com/projects/g/MrRio/jsPDF/context:javascript) |
| 3 | +**Generate PDF files in client-side JavaScript.** |
10 | 4 |
|
| 5 | +This is a fork of [MrRios' jsPDF](https://github.com/MrRio/jsPDF) modified to work with [svg2pdf.js](https://github.com/yWorks/svg2pdf.js), which converts SVG elements to PDF. Since version 2.0.0 this fork is fully compatible to the original version and comes with a large amount of additional features, making this fork also great for standalone usage. |
11 | 6 |
|
| 7 | +Major changes and new features are: |
12 | 8 |
|
13 | | -**A library to generate PDFs in JavaScript.** |
| 9 | +* A global transformation matrix converts between the usual coordinate system (y axis down) and the PDF coordinate system (y axis up) instead of converting every single coordinate. |
| 10 | +* PDF FormObjects |
| 11 | +* Shading and tiling patterns |
| 12 | +* Basic graphics state support |
| 13 | +* Full line style support |
| 14 | +* ... |
14 | 15 |
|
15 | | -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. |
| 16 | +#### Version 2.x.x |
16 | 17 |
|
17 | | -## [Live Demo](http://raw.githack.com/MrRio/jsPDF/master/) | [Documentation](http://raw.githack.com/MrRio/jsPDF/master/docs/) |
| 18 | +With version 2.x.x, this fork is now completely compatible with MrRio's version of jsPDF, which means that all third-party plugins will now also work with this fork! In order to make this possible, we introduced an API-switch between two API modes: |
18 | 19 |
|
19 | | -## Creating your first document |
20 | | - |
21 | | -The easiest way to get started is to drop the CDN hosted library into your page: |
22 | | - |
23 | | -```html |
24 | | -<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/1.5.3/jspdf.debug.js" integrity="sha384-NaWTHo/8YCBYJ59830LTz/P4aQZK1sS0SneOgAvhsIl3zBu8r9RevNg5lHCHAuQ/" crossorigin="anonymous"></script> |
25 | | -``` |
26 | | - |
27 | | -Integrity-hash generated by https://www.srihash.org/ |
28 | | - |
29 | | -or can always get latest version via [unpkg](https://unpkg.com/#/) |
30 | | - |
31 | | -```html |
32 | | -<script src="https://unpkg.com/jspdf@latest/dist/jspdf.min.js"></script> |
33 | | -``` |
34 | | - |
35 | | -Using yarn: |
36 | | - |
37 | | -```bash |
38 | | -yarn add jspdf |
39 | | -``` |
40 | | - |
41 | | -Using npm: |
42 | | - |
43 | | -```bash |
44 | | -npm install jspdf --save |
45 | | -``` |
46 | | - |
47 | | -Then you're ready to start making your document: |
| 20 | + * In "compat" API mode, jsPDF has the same API as MrRio's version, which means full compatibility with plugins. However, some advanced features like transformation matrices and patterns won't work. This is the default mode. |
| 21 | + * In "advanced" API mode, jsPDF has the API you're used from the yWorks-fork 1.x.x versions. This means the availability of all advanced features like patterns, FormObjects and transformation matrices. |
48 | 22 |
|
| 23 | +You can switch between the two modes by calling |
49 | 24 | ```javascript |
50 | | -// Default export is a4 paper, portrait, using milimeters for units |
51 | | -var doc = new jsPDF() |
52 | | - |
53 | | -doc.text('Hello world!', 10, 10) |
54 | | -doc.save('a4.pdf') |
55 | | -``` |
56 | | - |
57 | | -If you want to change the paper size, orientation, or units, you can do: |
58 | | - |
59 | | -```javascript |
60 | | -// Landscape export, 2×4 inches |
61 | | -var doc = new jsPDF({ |
62 | | - orientation: 'landscape', |
63 | | - unit: 'in', |
64 | | - format: [4, 2] |
| 25 | +doc.advancedAPI(doc => { |
| 26 | + // your code |
| 27 | +}) |
| 28 | +// or |
| 29 | +doc.compatAPI(doc => { |
| 30 | + // your code |
65 | 31 | }) |
66 | | - |
67 | | -doc.text('Hello world!', 1, 1) |
68 | | -doc.save('two-by-four.pdf') |
69 | | - |
70 | 32 | ``` |
| 33 | +JsPDF will automatically switch back to the original API mode after the callback has run. |
71 | 34 |
|
72 | | -## Use of UTF-8 / TTF: |
73 | | - |
74 | | -The 14 standard fonts in PDF are limited to the ASCII-codepage. If you want to use UTF-8 you have to to integrate a custom font, which provides the needed glyphs. jsPDF supports .ttf-files. So if you want to have for example chinese text in your pdf, your font has to have the necessary chinese glyphs. So check if your font supports the wanted glyphs or else it will show a blank space instead of the text. |
| 35 | +In addition to this API switch, here is a list of other API-breaking changes: |
75 | 36 |
|
76 | | -To add the font to jsPDF use our fontconverter in [/fontconverter/fontconverter.html](https://rawgit.com/MrRio/jsPDF/master/fontconverter/fontconverter.html) . The fontconverter will create a js-file with the content of the provided ttf-file as base64 encoded string and additional code for jsPDF. You just have to add this generated js-File to your project. You are then ready to go to use setFont-method in your code and write your UTF-8 encoded text. |
| 37 | + * Some fonts, that don't belong to the 12 standard PDF fonts, had a fallback previously. E.g. "arial" was mapped to "helvetica". Now, these fallbacks don't exist anymore and you have to provide all non-standard fonts yourself. |
| 38 | + * The API of the angle/transform parameter `text(...)` method was clarified. See the API-doc for details. |
| 39 | + * The `style`, `patternKey` and `patternData` of the path drawing methods are now deprecated and were replaced by a new set of path painting methods. Passing `undefined` as style argument will thus no longer result in a "n" path operator! |
| 40 | + * There are four new path construction methods: `moveTo`, `lineTo`, `curveTo` and `close`. |
| 41 | + * There are eight new path painting operators, replacing the `style`, `patternKey` and `patternData` arguments: `stroke`, `fill`, `fillEvenOdd`, `fillStroke`, `fillStrokeEvenOdd`, `clip`, `clipEvenOdd` and `discardPath`. The filling operators accept an optional pattern object. |
77 | 42 |
|
78 | | -## Angular/Webpack/React/etc. Configuration: |
| 43 | +## Creating your first document |
| 44 | +```javascript |
| 45 | +var doc = new jsPDF(); |
| 46 | +doc.text(20, 20, 'Hello world.'); |
| 47 | +doc.save('Test.pdf'); |
| 48 | +``` |
79 | 49 |
|
80 | | -If you are using Webpack (including managed cli tools like angular-cli or create-react-app) you can import like this: |
| 50 | +There's a live editor example at the top-level `index.html`. |
81 | 51 |
|
82 | | -``` |
83 | | -import * as jsPDF from 'jspdf' |
84 | | -``` |
| 52 | +Full API-docs are available through `docs/index.html`. |
85 | 53 |
|
86 | | -In some frameworks you have to import jsPDF like this: |
| 54 | +## Custom Fonts |
| 55 | +jsPDF has built in support for some basic fonts like Helvetica and Times. If you want to add custom fonts you will have |
| 56 | +to pack them into a separate JavaScript file using the `fontconverter/fontconverter.html`. Load this file after jsPDF. |
87 | 57 |
|
88 | | -``` |
89 | | -import jsPDF from 'jspdf'; |
90 | | -``` |
| 58 | +Currently only fonts which are encoded in the TrueType format (*.ttf) are supported. |
91 | 59 |
|
92 | | -You can add jsPDF to your meteor-project as follows: |
| 60 | +Note that the `jspdf-makeFonts` tool is deprecated. |
93 | 61 |
|
| 62 | +## Building |
| 63 | +Build the library with |
94 | 64 | ``` |
95 | | -meteor add jspdf:core |
| 65 | +npm install |
| 66 | +npm run build |
96 | 67 | ``` |
| 68 | +This will fetch all dependencies and then compile the `dist` files. To see the examples locally you can start a web server with `npm start` and go to `localhost:8000`. |
97 | 69 |
|
98 | | -## Support |
99 | | - |
100 | | -Please check if your question is already handled at Stackoverflow <https://stackoverflow.com/questions/tagged/jspdf>. |
101 | | -Feel free to ask a question there with the tag `jspdf`. |
102 | | - |
103 | | -Feature requests, bug reports etc. are very welcome as issues. Note that bug reports should follow these guidelines: |
104 | | - |
105 | | -* A bug should be reported as an [mcve](https://stackoverflow.com/help/mcve) |
106 | | -* Make sure code is properly indented and [formatted](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code) (Use ``` around code blocks) |
107 | | -* Provide a runnable example. |
108 | | -* Try to make sure and show in your issue that the issue is actually related to jspdf and not your framework of choice your setup. |
109 | | - |
110 | | -## Contributing |
111 | | - |
112 | | -Build the library with `npm run build`. This will fetch all dependencies and then compile the `dist` files. To see the examples locally you can start a web server with `npm start` and go to `localhost:8000`. |
113 | | - |
114 | | -Alternatively, you can build jsPDF using these commands in a readily configured online workspace: |
115 | 70 |
|
116 | | -[](https://gitpod.io#https://github.com/MrRio/jsPDF) |
| 71 | +## License |
117 | 72 |
|
118 | | -## Credits |
119 | | -- Big thanks to Daniel Dotsenko from [Willow Systems Corporation](https://github.com/willowsystems) for making huge contributions to the codebase. |
120 | | -- Thanks to Ajaxian.com for [featuring us back in 2009](http://ajaxian.com/archives/dynamically-generic-pdfs-with-javascript). |
121 | | -- 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 |
122 | | -- Everyone else that's contributed patches or bug reports. You rock. |
| 73 | +(MIT License) |
123 | 74 |
|
124 | | -## License (MIT) |
125 | | -Copyright (c) 2010-2017 James Hall, https://github.com/MrRio/jsPDF |
| 75 | +Copyright |
| 76 | + * (c) 2010-2016 James Hall, https://github.com/MrRio/jsPDF |
| 77 | + * (c) 2015-2018 yWorks GmbH, http://www.yworks.com/ |
126 | 78 |
|
127 | 79 | Permission is hereby granted, free of charge, to any person obtaining |
128 | 80 | a copy of this software and associated documentation files (the |
|
0 commit comments