mirror of
https://github.com/foliojs/pdfkit.git
synced 2026-01-25 16:06:44 +00:00
146 lines
8.8 KiB
HTML
146 lines
8.8 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="#setting_document_metadata">Setting document metadata</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 CoffeeScript or JavaScript source file and create an instance of the
|
|
<code>PDFDocument</code> class.</p>
|
|
|
|
<pre><code>PDFDocument = require 'pdfkit'
|
|
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
|
|
PDFDocument = require 'pdfkit'
|
|
blobStream = require 'blob-stream'
|
|
|
|
# create a document the same way as above
|
|
doc = new PDFDocument
|
|
|
|
# pipe the document to a blob
|
|
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', ->
|
|
# get a blob you can do whatever you like with
|
|
blob = stream.toBlob('application/pdf')
|
|
|
|
# or get a blob URL for display in the browser
|
|
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. Subsequent pages must be added by you. Luckily, it is
|
|
quite simple!</p>
|
|
|
|
<pre><code>doc.addPage()</code></pre>
|
|
|
|
<p>You can also set some options for the page, such as it's 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="http://pdfkit.org/docs/paper_sizes.html">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="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 it's 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="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> |