mirror of
https://github.com/foliojs/pdfkit.git
synced 2026-01-25 16:06:44 +00:00
249 lines
16 KiB
HTML
249 lines
16 KiB
HTML
<!DOCTYPE html><html><head><meta charset="utf-8"><title>Getting Started with PDFKit</title><link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Source+Code+Pro:400,700|Alegreya:700|Merriweather"><link rel="stylesheet" href="/docs/css/index.css"><link rel="stylesheet" href="/docs/css/github.css"></head><body><nav class="sidebar"><ul><li><a href="/">Home</a></li><li><a href="/docs/../index.html">Documentation</a><ul><li><a href="/docs/getting_started.html" class="selected">Getting Started </a><ul><li><a href="#installation">Installation</a></li><li><a href="#creating_a_document">Creating a document</a></li><li><a href="#using_pdfkit_in_the_browser">Using PDFKit in the browser</a></li><li><a href="#adding_pages">Adding pages</a></li><li><a href="#switching_to_previous_pages">Switching to previous pages</a></li><li><a href="#setting_document_metadata">Setting document metadata</a></li><li><a href="#encryption_and_access_privileges">Encryption and Access Privileges</a></li><li><a href="#adding_content">Adding content</a></li></ul></li><li><a href="/docs/vector.html">Vector Graphics </a></li><li><a href="/docs/text.html">Text </a></li><li><a href="/docs/images.html">Images </a></li><li><a href="/docs/annotations.html">Annotations </a></li></ul></li><li><a href="/docs/guide.pdf">PDF Guide</a></li><li><a href="/demo/out.pdf">Example PDF</a></li><li><a href="/demo/browser.html">Interactive Browser Demo</a></li><li><a href="http://github.com/devongovett/pdfkit">Source Code</a></li></ul></nav><div class="main"><h1 id="getting_started_with_pdfkit">Getting Started with PDFKit</h1>
|
|
|
|
<h2 id="installation">Installation</h2>
|
|
|
|
<p>Installation uses the <a href="http://npmjs.org/">npm</a> package manager. Just type the
|
|
following command after installing npm.</p>
|
|
|
|
<pre><code>npm install pdfkit</code></pre>
|
|
|
|
<h2 id="creating_a_document">Creating a document</h2>
|
|
|
|
<p>Creating a PDFKit document is quite simple. Just require the <code>pdfkit</code> module
|
|
in your JavaScript source file and create an instance of the
|
|
<code>PDFDocument</code> class.</p>
|
|
|
|
<pre><code>const PDFDocument = require('pdfkit');
|
|
const doc = new PDFDocument;</code></pre>
|
|
|
|
<p><code>PDFDocument</code> instances are readable Node streams. They don't get saved anywhere automatically,
|
|
but you can call the <code>pipe</code> method to send the output of the PDF document to another
|
|
writable Node stream as it is being written. When you're done with your document, call
|
|
the <code>end</code> method to finalize it. Here is an example showing how to pipe to a file or an HTTP response.</p>
|
|
|
|
<pre><code>doc.pipe(fs.createWriteStream('/path/to/file.pdf')); // write to PDF
|
|
doc.pipe(res); // HTTP response
|
|
|
|
// add stuff to PDF here using methods described below...
|
|
|
|
// finalize the PDF and end the stream
|
|
doc.end();</code></pre>
|
|
|
|
<p>The <code>write</code> and <code>output</code> methods found in PDFKit before version 0.5 are now deprecated.</p>
|
|
|
|
<h2 id="using_pdfkit_in_the_browser">Using PDFKit in the browser</h2>
|
|
|
|
<p>As of version 0.6, PDFKit can be used in the browser as well as in Node!
|
|
There are two ways to use PDFKit in the browser. The first is to use <a href="http://browserify.org/">Browserify</a>,
|
|
which is a Node module packager for the browser with the familiar <code>require</code> syntax. The second is to use
|
|
a prebuilt version of PDFKit, which you can <a href="https://github.com/devongovett/pdfkit/releases">download from Github</a>.</p>
|
|
|
|
<p>Using PDFKit in the browser is exactly the same as using it in Node, except you'll want to pipe the
|
|
output to a destination supported in the browser, such as a
|
|
<a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>. Blobs can be used
|
|
to generate a URL to allow display of generated PDFs directly in the browser via an <code>iframe</code>, or they can
|
|
be used to upload the PDF to a server, or trigger a download in the user's browser.</p>
|
|
|
|
<p>To get a Blob from a <code>PDFDocument</code>, you should pipe it to a <a href="https://github.com/devongovett/blob-stream">blob-stream</a>,
|
|
which is a module that generates a Blob from any Node-style stream. The following example uses Browserify to load
|
|
<code>PDFKit</code> and <code>blob-stream</code>, but if you're not using Browserify, you can load them in whatever way you'd like (e.g. script tags).</p>
|
|
|
|
<pre><code>// require dependencies
|
|
const PDFDocument = require('pdfkit');
|
|
const blobStream = require('blob-stream');
|
|
|
|
// create a document the same way as above
|
|
const doc = new PDFDocument;
|
|
|
|
// pipe the document to a blob
|
|
const stream = doc.pipe(blobStream());
|
|
|
|
// add your content to the document here, as usual
|
|
|
|
// get a blob when you're done
|
|
doc.end();
|
|
stream.on('finish', function() {
|
|
// get a blob you can do whatever you like with
|
|
const blob = stream.toBlob('application/pdf');
|
|
|
|
// or get a blob URL for display in the browser
|
|
const url = stream.toBlobURL('application/pdf');
|
|
iframe.src = url;
|
|
});</code></pre>
|
|
|
|
<p>You can see an interactive in-browser demo of PDFKit <a href="http://pdfkit.org/demo/browser.html">here</a>.</p>
|
|
|
|
<p>Note that in order to Browserify a project using PDFKit, you need to install the <code>brfs</code> module with npm,
|
|
which is used to load built-in font data into the package. It is listed as a <code>devDependency</code> in
|
|
PDFKit's <code>package.json</code>, so it isn't installed by default for Node users.
|
|
If you forget to install it, Browserify will print an error message.</p>
|
|
|
|
<h2 id="adding_pages">Adding pages</h2>
|
|
|
|
<p>The first page of a PDFKit document is added for you automatically when you
|
|
create the document unless you provide <code>autoFirstPage: false</code>. Subsequent pages must be added by you. Luckily, it is
|
|
quite simple!</p>
|
|
|
|
<pre><code>doc.addPage()</code></pre>
|
|
|
|
<p>To add some content every time a page is created, either by calling <code>addPage()</code> or automatically, you can use the <code>pageAdded</code> event.</p>
|
|
|
|
<pre><code>doc.on('pageAdded', () => doc.text("Page Title"));</code></pre>
|
|
|
|
<p>You can also set some options for the page, such as its size and orientation.</p>
|
|
|
|
<p>The <code>layout</code> property can be either <code>portrait</code> (the default) or <code>landscape</code>.
|
|
The <code>size</code> property can be either an array specifying <code>[width, height]</code> in PDF
|
|
points (72 per inch), or a string specifying a predefined size. A
|
|
list of the predefined paper sizes can be seen <a href="https://github.com/devongovett/pdfkit/blob/b13423bf0a391ed1c33a2e277bc06c00cabd6bf9/lib/page.coffee#L72-L122">here</a>. The
|
|
default is <code>letter</code>.</p>
|
|
|
|
<p>Passing a page options object to the <code>PDFDocument</code> constructor will
|
|
set the default paper size and layout for every page in the document, which is
|
|
then overridden by individual options passed to the <code>addPage</code> method.</p>
|
|
|
|
<p>You can set the page margins in two ways. The first is by setting the <code>margin</code>
|
|
property (singular) to a number, which applies that margin to all edges. The
|
|
other way is to set the <code>margins</code> property (plural) to an object with <code>top</code>,
|
|
<code>bottom</code>, <code>left</code>, and <code>right</code> values. The default is a 1 inch (72 point) margin
|
|
on all sides.</p>
|
|
|
|
<p>For example:</p>
|
|
|
|
<pre><code>// Add a 50 point margin on all sides
|
|
doc.addPage({
|
|
margin: 50});
|
|
|
|
|
|
// Add different margins on each side
|
|
doc.addPage({
|
|
margins: {
|
|
top: 50,
|
|
bottom: 50,
|
|
left: 72,
|
|
right: 72
|
|
}
|
|
});</code></pre>
|
|
|
|
<h2 id="switching_to_previous_pages">Switching to previous pages</h2>
|
|
|
|
<p>PDFKit normally flushes pages to the output file immediately when a new page is created, making
|
|
it impossible to jump back and add content to previous pages. This is normally not an issue, but
|
|
in some circumstances it can be useful to add content to pages after the whole document, or a part
|
|
of the document, has been created already. Examples include adding page numbers, or filling in other
|
|
parts of information you don't have until the rest of the document has been created.</p>
|
|
|
|
<p>PDFKit has a <code>bufferPages</code> option in versions v0.7.0 and later that allows you to control when
|
|
pages are flushed to the output file yourself rather than letting PDFKit handle that for you. To use
|
|
it, just pass <code>bufferPages: true</code> as an option to the <code>PDFDocument</code> constructor. Then, you can call
|
|
<code>doc.switchToPage(pageNumber)</code> to switch to a previous page (page numbers start at 0).</p>
|
|
|
|
<p>When you're ready to flush the buffered pages to the output file, call <code>flushPages</code>.
|
|
This method is automatically called by <code>doc.end()</code>, so if you just want to buffer all pages in the document, you
|
|
never need to call it. Finally, there is a <code>bufferedPageRange</code> method, which returns the range
|
|
of pages that are currently buffered. Here is a small example that shows how you might add page
|
|
numbers to a document.</p>
|
|
|
|
<pre><code>// create a document, and enable bufferPages mode
|
|
let i;
|
|
let end;
|
|
const doc = new PDFDocument({
|
|
bufferPages: true});
|
|
|
|
// add some content...
|
|
doc.addPage();
|
|
// ...
|
|
doc.addPage();
|
|
|
|
// see the range of buffered pages
|
|
const range = doc.bufferedPageRange(); // => { start: 0, count: 2 }
|
|
|
|
for (i = range.start, end = range.start + range.count, range.start <= end; i < end; i++;) {
|
|
doc.switchToPage(i);
|
|
doc.text(`Page ${i + 1} of ${range.count}`);
|
|
}
|
|
|
|
// manually flush pages that have been buffered
|
|
doc.flushPages();
|
|
|
|
// or, if you are at the end of the document anyway,
|
|
// doc.end() will call it for you automatically.
|
|
doc.end();</code></pre>
|
|
|
|
<h2 id="setting_document_metadata">Setting document metadata</h2>
|
|
|
|
<p>PDF documents can have various metadata associated with them, such as the
|
|
title, or author of the document. You can add that information by adding it to
|
|
the <code>doc.info</code> object, or by passing an info object into the document at
|
|
creation time.</p>
|
|
|
|
<p>Here is a list of all of the properties you can add to the document metadata.
|
|
According to the PDF spec, each property must have its first letter
|
|
capitalized.</p>
|
|
|
|
<ul><li><code>Title</code> - the title of the document</li><li><code>Author</code> - the name of the author</li><li><code>Subject</code> - the subject of the document</li><li><code>Keywords</code> - keywords associated with the document</li><li><code>CreationDate</code> - the date the document was created (added automatically by PDFKit)</li><li><code>ModDate</code> - the date the document was last modified</li></ul>
|
|
|
|
<h2 id="encryption_and_access_privileges">Encryption and Access Privileges</h2>
|
|
|
|
<p>PDF specification allow you to encrypt the PDF file and require a password when opening the file,
|
|
and/or set permissions of what users can do with the PDF file. PDFKit implements standard security
|
|
handler in PDF version 1.3 (40-bit RC4), version 1.4 (128-bit RC4), PDF version 1.7 (128-bit AES),
|
|
and PDF version 1.7 ExtensionLevel 3 (256-bit AES).</p>
|
|
|
|
<p>To enable encryption, provide a user password when creating the <code>PDFDocument</code> in <code>options</code> object.
|
|
The PDF file will be encrypted when a user password is provided, and users will be prompted to enter
|
|
the password to decrypt the file when opening it.</p>
|
|
|
|
<ul><li><code>userPassword</code> - the user password (string value)</li></ul>
|
|
|
|
<p>To set access privileges for the PDF file, you need to provide an owner password and permission
|
|
settings in the <code>option</code> object when creating <code>PDFDocument</code>. By default, all operations are disallowed.
|
|
You need to explicitly allow certain operations.</p>
|
|
|
|
<ul><li><code>ownerPassword</code> - the owner password (string value)</li><li><code>permissions</code> - the object specifying PDF file permissions</li></ul>
|
|
|
|
<p>Following settings are allowed in <code>permissions</code> object:</p>
|
|
|
|
<ul><li><code>printing</code> - whether printing is allowed. Specify <code>"lowResolution"</code> to allow degraded printing, or <code>"highResolution"</code> to allow printing with high resolution</li><li><code>modifying</code> - whether modifying the file is allowed. Specify <code>true</code> to allow modifying document content</li><li><code>copying</code> - whether copying text or graphics is allowed. Specify <code>true</code> to allow copying</li><li><code>annotating</code> - whether annotating, form filling is allowed. Specify <code>true</code> to allow annotating and form filling</li><li><code>fillingForms</code> - whether form filling and signing is allowed. Specify <code>true</code> to allow filling in form fields and signing</li><li><code>contentAccessibility</code> - whether copying text for accessibility is allowed. Specify <code>true</code> to allow copying for accessibility</li><li><code>documentAssembly</code> - whether assembling document is allowed. Specify <code>true</code> to allow document assembly</li></ul>
|
|
|
|
<p>You can specify either user password, owner password or both passwords.
|
|
Behavior differs according to passwords you provides:</p>
|
|
|
|
<ul><li>When only user password is provided,
|
|
users with user password are able to decrypt the file and have full access to the document.</li><li>When only owner password is provided,
|
|
users are able to decrypt and open the document without providing any password,
|
|
but the access is limited to those operations explicitly permitted.
|
|
Users with owner password have full access to the document.</li><li>When both passwords are provided,
|
|
users with user password are able to decrypt the file
|
|
but only have limited access to the file according to permission settings.
|
|
Users with owner password have full access to the document.</li></ul>
|
|
|
|
<p>Note that PDF file itself cannot enforce access privileges.
|
|
When file is decrypted, PDF viewer applications have full access to the file content,
|
|
and it is up to viewer applications to respect permission settings.</p>
|
|
|
|
<p>To choose encryption method, you need to specify PDF version.
|
|
PDFKit will choose best encryption method available in the PDF version you specified.</p>
|
|
|
|
<ul><li><code>pdfVersion</code> - a string value specifying PDF file version</li></ul>
|
|
|
|
<p>Available options includes:</p>
|
|
|
|
<ul><li><code>1.3</code> - PDF version 1.3 (default), 40-bit RC4 is used</li><li><code>1.4</code> - PDF version 1.4, 128-bit RC4 is used</li><li><code>1.5</code> - PDF version 1.5, 128-bit RC4 is used</li><li><code>1.6</code> - PDF version 1.6, 128-bit AES is used</li><li><code>1.7</code> - PDF version 1.7, 128-bit AES is used</li><li><code>1.7ext3</code> - PDF version 1.7 ExtensionLevel 3, 256-bit AES is used</li></ul>
|
|
|
|
<p>When using PDF version 1.7 ExtensionLevel 3, password is truncated to 127 bytes of its UTF-8 representation.
|
|
In older versions, password is truncated to 32 bytes, and only Latin-1 characters are allowed.</p>
|
|
|
|
<h2 id="adding_content">Adding content</h2>
|
|
|
|
<p>Once you've created a <code>PDFDocument</code> instance, you can add content to the
|
|
document. Check out the other sections described in this document to
|
|
learn about each type of content you can add.</p>
|
|
|
|
<p>That's the basics! Now let's move on to PDFKit's powerful vector graphics
|
|
abilities.</p><nav><a href="/docs/../index.html" class="previous">Previous</a><a href="/docs/vector.html" class="next">Next</a></nav></div><script src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script><script src="/docs/js/scroll.js"></script><script src="/docs/js/highlight.pack.js"></script><script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
ga('create', 'UA-48340245-1', 'pdfkit.org');
|
|
ga('send', 'pageview');</script></body></html> |