From b2d2bf822a83f866d9c53eb869c118eb06aab9c2 Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Mon, 17 Jul 2017 02:06:52 -0700 Subject: [PATCH] Rename Page.printToPDF into page.pdf This patch: - renames Page.printToPDF into page.pdf - adds a 'path' option to the page.pdf options instead of a separate `filePath` parameter - improves on the documentation for the `page.pdf` References #39. --- README.md | 2 +- docs/api.md | 64 ++++++++++++++++++++++++++++++----------- lib/Page.js | 10 ++++--- phantom_shim/WebPage.js | 3 +- test/test.js | 4 +-- 5 files changed, 58 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 7476d683..25e636c6 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ However, if you're using Node 8 or higher, `async/await` make life easier: ```javascript browser.newPage().then(async page => { await page.setViewportSize({width: 1000, height: 1000}); - await page.printToPDF('blank.pdf'); + await page.pdf({path: 'blank.pdf'}); browser.close(); }); ``` diff --git a/docs/api.md b/docs/api.md index dc59e0e7..0ef47ecb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -35,8 +35,8 @@ * [page.injectFile(filePath)](#pageinjectfilefilepath) * [page.mainFrame()](#pagemainframe) * [page.navigate(url, options)](#pagenavigateurl-options) + * [page.pdf(options)](#pagepdfoptions) * [page.plainText()](#pageplaintext) - * [page.printToPDF(filePath[, options])](#pageprinttopdffilepath-options) * [page.screenshot([options])](#pagescreenshotoptions) * [page.setContent(html)](#pagesetcontenthtml) * [page.setHTTPHeaders(headers)](#pagesethttpheadersheaders) @@ -308,28 +308,58 @@ The `page.navigate` will throw an error if: - target URL is invalid. - the `maxTime` is exceeded during navigation. +#### page.pdf(options) +- `options` <[Object]> Options object which might have the following properties: + - `path` <[string]> The file path to save the PDF to. + - `scale` <[number]> Scale of the webpage rendering. Defaults to `1`. + - `displayHeaderFooter` <[boolean]> Display header and footer. Defaults to `false`. + - `printBackground` <[boolean]> Print background graphics. Defaults to `false`. + - `landscape` <[boolean]> Paper orientation. Defaults to `false`. + - `pageRanges` <[string]> Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages. + - `format` <[string]> Paper format. If set, takes priority over `width` or `height` options. Defaults to 'Letter'. + - `width` <[string]> Paper width, accepts values labeled with units. + - `height` <[string]> Paper height, accepts values labeled with units. + - `margin` <[Object]> Paper margins, defaults to none. + - `top` <[string]> Top margin, accepts values labeled with units. + - `right` <[string]> Right margin, accepts values labeled with units. + - `bottom` <[string]> Bottom margin, accepts values labeled with units. + - `left` <[string]> Left margin, accepts values labeled with units. +- returns: <[Promise]<[Buffer]>> Promise which resolves with PDF buffer. + +The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled values are treated as pixels. + +A few examples: +- `page.pdf({width: 100})` - prints with width set to 100 pixels +- `page.pdf({width: '100px'})` - prints with width set to 100 pixels +- `page.pdf({width: '10cm'})` - prints with width set to 10 centimeters. + +All possible units are: +- `px` - pixel +- `in` - inch +- `cm` - centimeter +- `mm` - millimeter + +The `format` options are: +- `Letter`: 8.5in x 11in +- `Legal`: 8.5in x 14in +- `Tabloid`: 11in x 17in +- `Ledger`: 17in x 11in +- `A0`: 33.1in x 46.8in +- `A1`: 23.4in x 33.1in +- `A2`: 16.5in x 23.4in +- `A3`: 11.7in x 16.5in +- `A4`: 8.27in x 11.7in +- `A5`: 5.83in x 8.27in + #### page.plainText() - returns: <[Promise]<[string]>> Returns page's inner text. -#### page.printToPDF(filePath[, options]) -- `filePath` <[string]> The file path to save the image to. The screenshot type will be inferred from file extension -- `options` <[Object]> Options object which might have the following properties: - - `scale` <[number]> - - `displayHeaderFooter` <[boolean]> - - `printBackground` <[boolean]> - - `landscape` <[boolean]> - - `pageRanges` <[string]> - - `format` <[string]> - - `width` <[number]> - - `height` <[number]> -- returns: <[Promise]> Promise which resolves when the PDF is saved. - #### page.screenshot([options]) - `options` <[Object]> Options object which might have the following properties: - `path` <[string]> The file path to save the image to. The screenshot type will be inferred from file extension. - - `type` <[string]> Specify screenshot type, could be either `jpeg` or `png`. - - `quality` <[number]> The quality of the image, between 0-100. Not applicable to `.png` images. - - `fullPage` <[boolean]> When true, takes a screenshot of the full scrollable page. + - `type` <[string]> Specify screenshot type, could be either `jpeg` or `png`. Defaults to 'png'. + - `quality` <[number]> The quality of the image, between 0-100. Not applicable to `png` images. + - `fullPage` <[boolean]> When true, takes a screenshot of the full scrollable page. Defaults to `false`. - `clip` <[Object]> An object which specifies clipping region of the page. Should have the following fields: - `x` <[number]> x-coordinate of top-left corner of clip area - `y` <[number]> y-coordinate of top-left corner of clip area diff --git a/lib/Page.js b/lib/Page.js index 9bedfe99..078168e8 100644 --- a/lib/Page.js +++ b/lib/Page.js @@ -422,9 +422,9 @@ class Page extends EventEmitter { /** * @param {string} filePath * @param {!Object=} options - * @return {!Promise} + * @return {!Promise} */ - async printToPDF(filePath, options) { + async pdf(options) { options = options || {}; let scale = options.scale || 1; @@ -465,7 +465,9 @@ class Page extends EventEmitter { pageRanges: pageRanges }); let buffer = new Buffer(result.data, 'base64'); - fs.writeFileSync(filePath, buffer); + if (options.path) + fs.writeFileSync(options.path, buffer); + return buffer; } /** @@ -652,7 +654,7 @@ function convertPrintParameterToInches(parameter) { console.assert(!isNaN(value), 'Failed to parse parameter value: ' + text); pixels = value * unitToPixels[unit]; } else { - throw new Error('printToPDF Cannot handle parameter type: ' + (typeof parameter)); + throw new Error('page.pdf() Cannot handle parameter type: ' + (typeof parameter)); } return pixels / 96; } diff --git a/phantom_shim/WebPage.js b/phantom_shim/WebPage.js index c72f7e04..c6c44f64 100644 --- a/phantom_shim/WebPage.js +++ b/phantom_shim/WebPage.js @@ -405,7 +405,8 @@ class WebPage { options.landscape = paperSize.orientation === 'landscape'; options.width = paperSize.width; options.height = paperSize.height; - await(this._page.printToPDF(fileName, options)); + options.path = fileName; + await(this._page.pdf(options)); } else { let options = {}; if (this.clipRect && (this.clipRect.left || this.clipRect.top || this.clipRect.width || this.clipRect.height)) { diff --git a/test/test.js b/test/test.js index 82e28cb6..ecb7e41f 100644 --- a/test/test.js +++ b/test/test.js @@ -829,7 +829,7 @@ describe('Puppeteer', function() { })); }); - describe('Page.printToPDF', function() { + describe('Page.pdf', function() { let outputFile = __dirname + '/assets/output.pdf'; afterEach(function() { fs.unlinkSync(outputFile); @@ -837,7 +837,7 @@ describe('Puppeteer', function() { it('should print to pdf', SX(async function() { await page.navigate(PREFIX + '/grid.html'); - await page.printToPDF(outputFile); + await page.pdf({path: outputFile}); expect(fs.readFileSync(outputFile).byteLength).toBeGreaterThan(0); })); });