|
1 | 1 | # PDFKit |
2 | 2 |
|
3 | | -A JavaScript PDF generation library for Node and the browser. |
4 | | - |
5 | | -## Description |
6 | | - |
7 | | -PDFKit is a PDF document generation library for Node and the browser that makes creating complex, multi-page, printable |
8 | | -documents easy. The API embraces chainability, and includes both low level functions as well as abstractions for higher |
9 | | -level functionality. The PDFKit API is designed to be simple, so generating complex documents is often as simple as |
10 | | -a few function calls. |
11 | | - |
12 | | -Check out some of the [documentation and examples](http://pdfkit.org/docs/getting_started.html) to see for yourself! |
13 | | -You can also read the guide as a [self-generated PDF](http://pdfkit.org/docs/guide.pdf) with example output displayed inline. |
14 | | -If you'd like to see how it was generated, check out the README in the [docs](https://github.com/devongovett/pdfkit/tree/master/docs) |
15 | | -folder. |
16 | | - |
17 | | -You can also try out an interactive in-browser demo of PDFKit [here](http://pdfkit.org/demo/browser.html). |
18 | | - |
19 | | -## Installation |
20 | | - |
21 | | -Installation uses the [npm](http://npmjs.org/) package manager. Just type the following command after installing npm. |
22 | | - |
23 | | - npm install pdfkit |
24 | | - |
25 | | -## Features |
26 | | - |
27 | | -* Vector graphics |
28 | | - * HTML5 canvas-like API |
29 | | - * Path operations |
30 | | - * SVG path parser for easy path creation |
31 | | - * Transformations |
32 | | - * Linear and radial gradients |
33 | | -* Text |
34 | | - * Line wrapping |
35 | | - * Text alignments |
36 | | - * Bulleted lists |
37 | | -* Font embedding |
38 | | - * Supports TrueType (.ttf), OpenType (.otf), WOFF, WOFF2, TrueType Collections (.ttc), and Datafork TrueType (.dfont) fonts |
39 | | - * Font subsetting |
40 | | - * See [fontkit](http://github.com/devongovett/fontkit) for more details on advanced glyph layout support. |
41 | | -* Image embedding |
42 | | - * Supports JPEG and PNG files (including indexed PNGs, and PNGs with transparency) |
43 | | -* Annotations |
44 | | - * Links |
45 | | - * Notes |
46 | | - * Highlights |
47 | | - * Underlines |
48 | | - * etc. |
49 | | -* Outlines |
50 | | -* PDF security |
51 | | - * Encryption |
52 | | - * Access privileges (printing, copying, modifying, annotating, form filling, content accessibility, document assembly) |
53 | | - |
54 | | -## Coming soon! |
55 | | - |
56 | | -* Patterns fills |
57 | | -* Higher level APIs for creating tables and laying out content |
58 | | -* More performance optimizations |
59 | | -* Even more awesomeness, perhaps written by you! Please fork this repository and send me pull requests. |
60 | | - |
61 | | -## Example |
62 | | - |
63 | | -```javascript |
64 | | -const PDFDocument = require('pdfkit'); |
65 | | - |
66 | | -// Create a document |
67 | | -const doc = new PDFDocument; |
68 | | - |
69 | | -// Pipe its output somewhere, like to a file or HTTP response |
70 | | -// See below for browser usage |
71 | | -doc.pipe(fs.createWriteStream('output.pdf')); |
72 | | - |
73 | | -// Embed a font, set the font size, and render some text |
74 | | -doc.font('fonts/PalatinoBold.ttf') |
75 | | - .fontSize(25) |
76 | | - .text('Some text with an embedded font!', 100, 100); |
77 | | - |
78 | | -// Add an image, constrain it to a given size, and center it vertically and horizontally |
79 | | -doc.image('path/to/image.png', { |
80 | | - fit: [250, 300], |
81 | | - align: 'center', |
82 | | - valign: 'center' |
83 | | -}); |
84 | | - |
85 | | -// Add another page |
86 | | -doc.addPage() |
87 | | - .fontSize(25) |
88 | | - .text('Here is some vector graphics...', 100, 100); |
89 | | - |
90 | | -// Draw a triangle |
91 | | -doc.save() |
92 | | - .moveTo(100, 150) |
93 | | - .lineTo(100, 250) |
94 | | - .lineTo(200, 250) |
95 | | - .fill("#FF3300"); |
96 | | - |
97 | | -// Apply some transforms and render an SVG path with the 'even-odd' fill rule |
98 | | -doc.scale(0.6) |
99 | | - .translate(470, -380) |
100 | | - .path('M 250,75 L 323,301 131,161 369,161 177,301 z') |
101 | | - .fill('red', 'even-odd') |
102 | | - .restore(); |
103 | | - |
104 | | -// Add some text with annotations |
105 | | -doc.addPage() |
106 | | - .fillColor("blue") |
107 | | - .text('Here is a link!', 100, 100) |
108 | | - .underline(100, 100, 160, 27, {color: "#0000FF"}) |
109 | | - .link(100, 100, 160, 27, 'http://google.com/'); |
110 | | - |
111 | | -// Finalize PDF file |
112 | | -doc.end(); |
113 | | -``` |
114 | | - |
115 | | -[The PDF output from this example](http://pdfkit.org/demo/out.pdf) (with a few additions) shows the power of PDFKit — producing |
116 | | -complex documents with a very small amount of code. For more, see the `demo` folder and the |
117 | | -[PDFKit programming guide](http://pdfkit.org/docs/getting_started.html). |
118 | | - |
119 | | -## Browser Usage |
120 | | - |
121 | | -There are two ways to use PDFKit in the browser. The first is to use [Browserify](http://browserify.org/), |
122 | | -which is a Node module packager for the browser with the familiar `require` syntax. The second is to use |
123 | | -a prebuilt version of PDFKit, which you can [download from Github](https://github.com/devongovett/pdfkit/releases). |
124 | | - |
125 | | -In addition to PDFKit, you'll need somewhere to stream the output to. HTML5 has a |
126 | | -[Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object which can be used to store binary data, and |
127 | | -get URLs to this data in order to display PDF output inside an iframe, or upload to a server, etc. In order to |
128 | | -get a Blob from the output of PDFKit, you can use the [blob-stream](https://github.com/devongovett/blob-stream) |
129 | | -module. |
130 | | - |
131 | | -The following example uses Browserify to load `PDFKit` and `blob-stream`, but if you're not using Browserify, |
132 | | -you can load them in whatever way you'd like (e.g. script tags). |
133 | | - |
134 | | -```javascript |
135 | | -// require dependencies |
136 | | -const PDFDocument = require('pdfkit'); |
137 | | -const blobStream = require('blob-stream'); |
138 | | - |
139 | | -// create a document the same way as above |
140 | | -const doc = new PDFDocument; |
141 | | - |
142 | | -// pipe the document to a blob |
143 | | -const stream = doc.pipe(blobStream()); |
144 | | - |
145 | | -// add your content to the document here, as usual |
146 | | - |
147 | | -// get a blob when you're done |
148 | | -doc.end(); |
149 | | -stream.on('finish', function() { |
150 | | - // get a blob you can do whatever you like with |
151 | | - const blob = stream.toBlob('application/pdf'); |
152 | | - |
153 | | - // or get a blob URL for display in the browser |
154 | | - const url = stream.toBlobURL('application/pdf'); |
155 | | - iframe.src = url; |
156 | | -}); |
157 | | -``` |
158 | | - |
159 | | -You can see an interactive in-browser demo of PDFKit [here](http://pdfkit.org/demo/browser.html). |
160 | | - |
161 | | -Note that in order to Browserify a project using PDFKit, you need to install the `brfs` module with npm, |
162 | | -which is used to load built-in font data into the package. It is listed as a `devDependency` in |
163 | | -PDFKit's `package.json`, so it isn't installed by default for Node users. |
164 | | -If you forget to install it, Browserify will print an error message. |
165 | | - |
166 | | -## Documentation |
167 | | - |
168 | | -For complete API documentation and more examples, see the [PDFKit website](http://pdfkit.org/). |
| 3 | +Source for pdfkit.org website, see the [PDFKit website](http://pdfkit.org/). |
169 | 4 |
|
170 | 5 | ## License |
171 | 6 |
|
|
0 commit comments