From 9fdf2ba280fd59e4a41cfd7f7e1c3ef963ef3737 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Fri, 17 Jul 2020 13:58:56 +0100 Subject: [PATCH] chore(docs): migrate page.pdf() docs (#6228) Also took the opportunity to pull out the PDF types into their own file to clear up `Page.ts` slightly and give the PDF code a more natural place to live. --- new-docs/puppeteer.md | 3 + new-docs/puppeteer.page.md | 4 +- new-docs/puppeteer.page.pdf.md | 12 +- new-docs/puppeteer.page.queryobjects.md | 24 ++- new-docs/puppeteer.paperformat.md | 38 ++++ new-docs/puppeteer.pdfmargin.bottom.md | 11 ++ new-docs/puppeteer.pdfmargin.left.md | 11 ++ new-docs/puppeteer.pdfmargin.md | 22 +++ new-docs/puppeteer.pdfmargin.right.md | 11 ++ new-docs/puppeteer.pdfmargin.top.md | 11 ++ ...uppeteer.pdfoptions.displayheaderfooter.md | 13 ++ .../puppeteer.pdfoptions.footertemplate.md | 13 ++ new-docs/puppeteer.pdfoptions.format.md | 16 ++ .../puppeteer.pdfoptions.headertemplate.md | 21 ++ new-docs/puppeteer.pdfoptions.height.md | 13 ++ new-docs/puppeteer.pdfoptions.landscape.md | 13 ++ new-docs/puppeteer.pdfoptions.margin.md | 13 ++ new-docs/puppeteer.pdfoptions.md | 32 ++++ new-docs/puppeteer.pdfoptions.pageranges.md | 13 ++ new-docs/puppeteer.pdfoptions.path.md | 18 ++ .../puppeteer.pdfoptions.prefercsspagesize.md | 13 ++ .../puppeteer.pdfoptions.printbackground.md | 13 ++ new-docs/puppeteer.pdfoptions.scale.md | 13 ++ new-docs/puppeteer.pdfoptions.width.md | 13 ++ new-docs/puppeteer.puppeteer.md | 1 + src/api-docs-entry.ts | 1 + src/common/PDFOptions.ts | 179 ++++++++++++++++++ src/common/Page.ts | 83 ++++---- src/common/Puppeteer.ts | 6 +- 29 files changed, 587 insertions(+), 47 deletions(-) create mode 100644 new-docs/puppeteer.paperformat.md create mode 100644 new-docs/puppeteer.pdfmargin.bottom.md create mode 100644 new-docs/puppeteer.pdfmargin.left.md create mode 100644 new-docs/puppeteer.pdfmargin.md create mode 100644 new-docs/puppeteer.pdfmargin.right.md create mode 100644 new-docs/puppeteer.pdfmargin.top.md create mode 100644 new-docs/puppeteer.pdfoptions.displayheaderfooter.md create mode 100644 new-docs/puppeteer.pdfoptions.footertemplate.md create mode 100644 new-docs/puppeteer.pdfoptions.format.md create mode 100644 new-docs/puppeteer.pdfoptions.headertemplate.md create mode 100644 new-docs/puppeteer.pdfoptions.height.md create mode 100644 new-docs/puppeteer.pdfoptions.landscape.md create mode 100644 new-docs/puppeteer.pdfoptions.margin.md create mode 100644 new-docs/puppeteer.pdfoptions.md create mode 100644 new-docs/puppeteer.pdfoptions.pageranges.md create mode 100644 new-docs/puppeteer.pdfoptions.path.md create mode 100644 new-docs/puppeteer.pdfoptions.prefercsspagesize.md create mode 100644 new-docs/puppeteer.pdfoptions.printbackground.md create mode 100644 new-docs/puppeteer.pdfoptions.scale.md create mode 100644 new-docs/puppeteer.pdfoptions.width.md create mode 100644 src/common/PDFOptions.ts diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 5e64b8e168171..ba4744413d016 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -69,6 +69,8 @@ | [Metrics](./puppeteer.metrics.md) | | | [MouseOptions](./puppeteer.mouseoptions.md) | | | [MouseWheelOptions](./puppeteer.mousewheeloptions.md) | | +| [PDFMargin](./puppeteer.pdfmargin.md) | | +| [PDFOptions](./puppeteer.pdfoptions.md) | Valid options to configure PDF generation via [Page.pdf()](./puppeteer.page.pdf.md). | | [PressOptions](./puppeteer.pressoptions.md) | | | [ProductLauncher](./puppeteer.productlauncher.md) | Describes a launcher - a class that is able to create and launch a browser instance. | | [RemoteAddress](./puppeteer.remoteaddress.md) | | @@ -108,6 +110,7 @@ | [JSONArray](./puppeteer.jsonarray.md) | | | [KeyInput](./puppeteer.keyinput.md) | All the valid keys that can be passed to functions that take user input, such as [keyboard.press](./puppeteer.keyboard.press.md) | | [MouseButton](./puppeteer.mousebutton.md) | | +| [PaperFormat](./puppeteer.paperformat.md) | All the valid paper format types when printing a PDF. | | [Platform](./puppeteer.platform.md) | Supported platforms. | | [Product](./puppeteer.product.md) | Supported products. | | [PuppeteerErrors](./puppeteer.puppeteererrors.md) | | diff --git a/new-docs/puppeteer.page.md b/new-docs/puppeteer.page.md index 2e4705d0f21bc..de70a41ee5c32 100644 --- a/new-docs/puppeteer.page.md +++ b/new-docs/puppeteer.page.md @@ -107,8 +107,8 @@ page.off('request', logRequest); | [isJavaScriptEnabled()](./puppeteer.page.isjavascriptenabled.md) | | | | [mainFrame()](./puppeteer.page.mainframe.md) | | | | [metrics()](./puppeteer.page.metrics.md) | | | -| [pdf(options)](./puppeteer.page.pdf.md) | | | -| [queryObjects(prototypeHandle)](./puppeteer.page.queryobjects.md) | | | +| [pdf(options)](./puppeteer.page.pdf.md) | | Generatees a PDF of the page with the print CSS media type. | +| [queryObjects(prototypeHandle)](./puppeteer.page.queryobjects.md) | | This method iterates the JavaScript heap and finds all objects with the given prototype. | | [reload(options)](./puppeteer.page.reload.md) | | | | [screenshot(options)](./puppeteer.page.screenshot.md) | | | | [select(selector, values)](./puppeteer.page.select.md) | | | diff --git a/new-docs/puppeteer.page.pdf.md b/new-docs/puppeteer.page.pdf.md index 9e90436088e53..a7922f8978e09 100644 --- a/new-docs/puppeteer.page.pdf.md +++ b/new-docs/puppeteer.page.pdf.md @@ -4,6 +4,8 @@ ## Page.pdf() method +Generatees a PDF of the page with the `print` CSS media type. + Signature: ```typescript @@ -14,9 +16,17 @@ pdf(options?: PDFOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | -| options | PDFOptions | | +| options | [PDFOptions](./puppeteer.pdfoptions.md) | options for generating the PDF. | Returns: Promise<Buffer> +## Remarks + +IMPORTANT: PDF generation is only supported in Chrome headless mode. + +To generate a PDF with the `screen` media type, call [\`page.emulateMediaType('screen')\`](./puppeteer.page.emulatemediatype.md) before calling `page.pdf()`. + +By default, `page.pdf()` generates a pdf with modified colors for printing. Use the [\`-webkit-print-color-adjust\`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to force rendering of exact colors. + diff --git a/new-docs/puppeteer.page.queryobjects.md b/new-docs/puppeteer.page.queryobjects.md index 6a85584ae2313..7a4650ca3de9e 100644 --- a/new-docs/puppeteer.page.queryobjects.md +++ b/new-docs/puppeteer.page.queryobjects.md @@ -4,6 +4,8 @@ ## Page.queryObjects() method +This method iterates the JavaScript heap and finds all objects with the given prototype. + Signature: ```typescript @@ -14,9 +16,29 @@ queryObjects(prototypeHandle: JSHandle): Promise; | Parameter | Type | Description | | --- | --- | --- | -| prototypeHandle | [JSHandle](./puppeteer.jshandle.md) | | +| prototypeHandle | [JSHandle](./puppeteer.jshandle.md) | a handle to the object prototype. | Returns: Promise<[JSHandle](./puppeteer.jshandle.md)> +## Remarks + + +## Example + + +```js +// Create a Map object +await page.evaluate(() => window.map = new Map()); +// Get a handle to the Map object prototype +const mapPrototype = await page.evaluateHandle(() => Map.prototype); +// Query all map instances into an array +const mapInstances = await page.queryObjects(mapPrototype); +// Count amount of map objects in heap +const count = await page.evaluate(maps => maps.length, mapInstances); +await mapInstances.dispose(); +await mapPrototype.dispose(); + +``` + diff --git a/new-docs/puppeteer.paperformat.md b/new-docs/puppeteer.paperformat.md new file mode 100644 index 0000000000000..f0ef47e9caf23 --- /dev/null +++ b/new-docs/puppeteer.paperformat.md @@ -0,0 +1,38 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PaperFormat](./puppeteer.paperformat.md) + +## PaperFormat type + +All the valid paper format types when printing a PDF. + +Signature: + +```typescript +export declare type PaperFormat = 'letter' | 'legal' | 'tabloid' | 'ledger' | 'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6'; +``` + +## Remarks + +The sizes of each format are as follows: - `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.54in x 23.4in + +- `A3`: 11.7in x 16.54in + +- `A4`: 8.27in x 11.7in + +- `A5`: 5.83in x 8.27in + +- `A6`: 4.13in x 5.83in + diff --git a/new-docs/puppeteer.pdfmargin.bottom.md b/new-docs/puppeteer.pdfmargin.bottom.md new file mode 100644 index 0000000000000..1c5681cc4073f --- /dev/null +++ b/new-docs/puppeteer.pdfmargin.bottom.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFMargin](./puppeteer.pdfmargin.md) > [bottom](./puppeteer.pdfmargin.bottom.md) + +## PDFMargin.bottom property + +Signature: + +```typescript +bottom?: string | number; +``` diff --git a/new-docs/puppeteer.pdfmargin.left.md b/new-docs/puppeteer.pdfmargin.left.md new file mode 100644 index 0000000000000..d63d63a75c39f --- /dev/null +++ b/new-docs/puppeteer.pdfmargin.left.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFMargin](./puppeteer.pdfmargin.md) > [left](./puppeteer.pdfmargin.left.md) + +## PDFMargin.left property + +Signature: + +```typescript +left?: string | number; +``` diff --git a/new-docs/puppeteer.pdfmargin.md b/new-docs/puppeteer.pdfmargin.md new file mode 100644 index 0000000000000..a7b712f0d3227 --- /dev/null +++ b/new-docs/puppeteer.pdfmargin.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFMargin](./puppeteer.pdfmargin.md) + +## PDFMargin interface + + +Signature: + +```typescript +export interface PDFMargin +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [bottom](./puppeteer.pdfmargin.bottom.md) | string \| number | | +| [left](./puppeteer.pdfmargin.left.md) | string \| number | | +| [right](./puppeteer.pdfmargin.right.md) | string \| number | | +| [top](./puppeteer.pdfmargin.top.md) | string \| number | | + diff --git a/new-docs/puppeteer.pdfmargin.right.md b/new-docs/puppeteer.pdfmargin.right.md new file mode 100644 index 0000000000000..1ed32747c1fc9 --- /dev/null +++ b/new-docs/puppeteer.pdfmargin.right.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFMargin](./puppeteer.pdfmargin.md) > [right](./puppeteer.pdfmargin.right.md) + +## PDFMargin.right property + +Signature: + +```typescript +right?: string | number; +``` diff --git a/new-docs/puppeteer.pdfmargin.top.md b/new-docs/puppeteer.pdfmargin.top.md new file mode 100644 index 0000000000000..19dfcb5ce8903 --- /dev/null +++ b/new-docs/puppeteer.pdfmargin.top.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFMargin](./puppeteer.pdfmargin.md) > [top](./puppeteer.pdfmargin.top.md) + +## PDFMargin.top property + +Signature: + +```typescript +top?: string | number; +``` diff --git a/new-docs/puppeteer.pdfoptions.displayheaderfooter.md b/new-docs/puppeteer.pdfoptions.displayheaderfooter.md new file mode 100644 index 0000000000000..ef28923d99f04 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.displayheaderfooter.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [displayHeaderFooter](./puppeteer.pdfoptions.displayheaderfooter.md) + +## PDFOptions.displayHeaderFooter property + +Whether to show the header and footer. + +Signature: + +```typescript +displayHeaderFooter?: boolean; +``` diff --git a/new-docs/puppeteer.pdfoptions.footertemplate.md b/new-docs/puppeteer.pdfoptions.footertemplate.md new file mode 100644 index 0000000000000..ec6b0c371f5f4 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.footertemplate.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [footerTemplate](./puppeteer.pdfoptions.footertemplate.md) + +## PDFOptions.footerTemplate property + +HTML template for the print footer. Has the same constraints and support for special classes as [PDFOptions.headerTemplate](./puppeteer.pdfoptions.headertemplate.md). + +Signature: + +```typescript +footerTemplate?: string; +``` diff --git a/new-docs/puppeteer.pdfoptions.format.md b/new-docs/puppeteer.pdfoptions.format.md new file mode 100644 index 0000000000000..35fef3250b7fb --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.format.md @@ -0,0 +1,16 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [format](./puppeteer.pdfoptions.format.md) + +## PDFOptions.format property + +Signature: + +```typescript +format?: PaperFormat; +``` + +## Remarks + +If set, this takes priority over the `width` and `height` options. + diff --git a/new-docs/puppeteer.pdfoptions.headertemplate.md b/new-docs/puppeteer.pdfoptions.headertemplate.md new file mode 100644 index 0000000000000..8d9767f0cb6d0 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.headertemplate.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [headerTemplate](./puppeteer.pdfoptions.headertemplate.md) + +## PDFOptions.headerTemplate property + +HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - `date` formatted print date + +- `title` document title + +- `url` document location + +- `pageNumber` current page number + +- `totalPages` total pages in the document + +Signature: + +```typescript +headerTemplate?: string; +``` diff --git a/new-docs/puppeteer.pdfoptions.height.md b/new-docs/puppeteer.pdfoptions.height.md new file mode 100644 index 0000000000000..5172030eeb997 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.height.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [height](./puppeteer.pdfoptions.height.md) + +## PDFOptions.height property + +Sets the height of paper. You can pass in a number or a string with a unit. + +Signature: + +```typescript +height?: string | number; +``` diff --git a/new-docs/puppeteer.pdfoptions.landscape.md b/new-docs/puppeteer.pdfoptions.landscape.md new file mode 100644 index 0000000000000..f3e0c1d6bb79e --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.landscape.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [landscape](./puppeteer.pdfoptions.landscape.md) + +## PDFOptions.landscape property + +Whether to print in landscape orientation. + +Signature: + +```typescript +landscape?: boolean; +``` diff --git a/new-docs/puppeteer.pdfoptions.margin.md b/new-docs/puppeteer.pdfoptions.margin.md new file mode 100644 index 0000000000000..b1741e351faed --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.margin.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [margin](./puppeteer.pdfoptions.margin.md) + +## PDFOptions.margin property + +Set the PDF margins. + +Signature: + +```typescript +margin?: PDFMargin; +``` diff --git a/new-docs/puppeteer.pdfoptions.md b/new-docs/puppeteer.pdfoptions.md new file mode 100644 index 0000000000000..7950d17133cd6 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.md @@ -0,0 +1,32 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) + +## PDFOptions interface + +Valid options to configure PDF generation via [Page.pdf()](./puppeteer.page.pdf.md). + +Signature: + +```typescript +export interface PDFOptions +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [displayHeaderFooter](./puppeteer.pdfoptions.displayheaderfooter.md) | boolean | Whether to show the header and footer. | +| [footerTemplate](./puppeteer.pdfoptions.footertemplate.md) | string | HTML template for the print footer. Has the same constraints and support for special classes as [PDFOptions.headerTemplate](./puppeteer.pdfoptions.headertemplate.md). | +| [format](./puppeteer.pdfoptions.format.md) | [PaperFormat](./puppeteer.paperformat.md) | | +| [headerTemplate](./puppeteer.pdfoptions.headertemplate.md) | string | HTML template for the print header. Should be valid HTML with the following classes used to inject values into them: - date formatted print date- title document title- url document location- pageNumber current page number- totalPages total pages in the document | +| [height](./puppeteer.pdfoptions.height.md) | string \| number | Sets the height of paper. You can pass in a number or a string with a unit. | +| [landscape](./puppeteer.pdfoptions.landscape.md) | boolean | Whether to print in landscape orientation. | +| [margin](./puppeteer.pdfoptions.margin.md) | [PDFMargin](./puppeteer.pdfmargin.md) | Set the PDF margins. | +| [pageRanges](./puppeteer.pdfoptions.pageranges.md) | string | Paper ranges to print, e.g. 1-5, 8, 11-13. | +| [path](./puppeteer.pdfoptions.path.md) | string | The path to save the file to. | +| [preferCSSPageSize](./puppeteer.pdfoptions.prefercsspagesize.md) | boolean | Give any CSS @page size declared in the page priority over what is declared in the width or height or format option. | +| [printBackground](./puppeteer.pdfoptions.printbackground.md) | boolean | Set to true to print background graphics. | +| [scale](./puppeteer.pdfoptions.scale.md) | number | Scales the rendering of the web page. Amount must be between 0.1 and 2. | +| [width](./puppeteer.pdfoptions.width.md) | string \| number | Sets the width of paper. You can pass in a number or a string with a unit. | + diff --git a/new-docs/puppeteer.pdfoptions.pageranges.md b/new-docs/puppeteer.pdfoptions.pageranges.md new file mode 100644 index 0000000000000..c897276738ccd --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.pageranges.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [pageRanges](./puppeteer.pdfoptions.pageranges.md) + +## PDFOptions.pageRanges property + +Paper ranges to print, e.g. `1-5, 8, 11-13`. + +Signature: + +```typescript +pageRanges?: string; +``` diff --git a/new-docs/puppeteer.pdfoptions.path.md b/new-docs/puppeteer.pdfoptions.path.md new file mode 100644 index 0000000000000..30b952cd5cec5 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.path.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [path](./puppeteer.pdfoptions.path.md) + +## PDFOptions.path property + +The path to save the file to. + +Signature: + +```typescript +path?: string; +``` + +## Remarks + +If the path is relative, it's resolved relative to the current working directory. + diff --git a/new-docs/puppeteer.pdfoptions.prefercsspagesize.md b/new-docs/puppeteer.pdfoptions.prefercsspagesize.md new file mode 100644 index 0000000000000..0978d093164be --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.prefercsspagesize.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [preferCSSPageSize](./puppeteer.pdfoptions.prefercsspagesize.md) + +## PDFOptions.preferCSSPageSize property + +Give any CSS `@page` size declared in the page priority over what is declared in the `width` or `height` or `format` option. + +Signature: + +```typescript +preferCSSPageSize?: boolean; +``` diff --git a/new-docs/puppeteer.pdfoptions.printbackground.md b/new-docs/puppeteer.pdfoptions.printbackground.md new file mode 100644 index 0000000000000..d79d54144d6e4 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.printbackground.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [printBackground](./puppeteer.pdfoptions.printbackground.md) + +## PDFOptions.printBackground property + +Set to `true` to print background graphics. + +Signature: + +```typescript +printBackground?: boolean; +``` diff --git a/new-docs/puppeteer.pdfoptions.scale.md b/new-docs/puppeteer.pdfoptions.scale.md new file mode 100644 index 0000000000000..67b16df272319 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.scale.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [scale](./puppeteer.pdfoptions.scale.md) + +## PDFOptions.scale property + +Scales the rendering of the web page. Amount must be between `0.1` and `2`. + +Signature: + +```typescript +scale?: number; +``` diff --git a/new-docs/puppeteer.pdfoptions.width.md b/new-docs/puppeteer.pdfoptions.width.md new file mode 100644 index 0000000000000..3010f5cb27ae5 --- /dev/null +++ b/new-docs/puppeteer.pdfoptions.width.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PDFOptions](./puppeteer.pdfoptions.md) > [width](./puppeteer.pdfoptions.width.md) + +## PDFOptions.width property + +Sets the width of paper. You can pass in a number or a string with a unit. + +Signature: + +```typescript +width?: string | number; +``` diff --git a/new-docs/puppeteer.puppeteer.md b/new-docs/puppeteer.puppeteer.md index ca7e00cf0e128..f5245414fa812 100644 --- a/new-docs/puppeteer.puppeteer.md +++ b/new-docs/puppeteer.puppeteer.md @@ -34,6 +34,7 @@ const puppeteer = require('puppeteer'); })(); ``` +Once you have created a `page` you have access to a large API to interact with the page, navigate, or find certain elements in that page. The [\`page\` documentation](./puppeteer.page.md) lists all the available methods. ## Properties diff --git a/src/api-docs-entry.ts b/src/api-docs-entry.ts index 3e2f15aa7aa06..10c36e84326ab 100644 --- a/src/api-docs-entry.ts +++ b/src/api-docs-entry.ts @@ -54,6 +54,7 @@ export * from './common/NetworkManager.js'; export * from './common/WebWorker.js'; export * from './common/USKeyboardLayout.js'; export * from './common/EvalTypes.js'; +export * from './common/PDFOptions.js'; export * from './common/TimeoutSettings.js'; export * from './common/LifecycleWatcher.js'; export * from 'devtools-protocol/types/protocol'; diff --git a/src/common/PDFOptions.ts b/src/common/PDFOptions.ts new file mode 100644 index 0000000000000..743085904a476 --- /dev/null +++ b/src/common/PDFOptions.ts @@ -0,0 +1,179 @@ +/** + * Copyright 2020 Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @public + */ +export interface PDFMargin { + top?: string | number; + bottom?: string | number; + left?: string | number; + right?: string | number; +} + +/** + * All the valid paper format types when printing a PDF. + * + * @remarks + * + * The sizes of each format are as follows: + * - `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.54in x 23.4in + * + * - `A3`: 11.7in x 16.54in + * + * - `A4`: 8.27in x 11.7in + * + * - `A5`: 5.83in x 8.27in + * + * - `A6`: 4.13in x 5.83in + * + * @public + */ +export type PaperFormat = + | 'letter' + | 'legal' + | 'tabloid' + | 'ledger' + | 'a0' + | 'a1' + | 'a2' + | 'a3' + | 'a4' + | 'a5' + | 'a6'; + +/** + * Valid options to configure PDF generation via {@link Page.pdf}. + * @public + */ +export interface PDFOptions { + /** + * Scales the rendering of the web page. Amount must be between `0.1` and `2`. + * @defaultValue 1 + */ + scale?: number; + /** + * Whether to show the header and footer. + * @defaultValue false + */ + displayHeaderFooter?: boolean; + /** + * HTML template for the print header. Should be valid HTML with the following + * classes used to inject values into them: + * - `date` formatted print date + * + * - `title` document title + * + * - `url` document location + * + * - `pageNumber` current page number + * + * - `totalPages` total pages in the document + */ + headerTemplate?: string; + /** + * HTML template for the print footer. Has the same constraints and support + * for special classes as {@link PDFOptions.headerTemplate}. + */ + footerTemplate?: string; + /** + * Set to `true` to print background graphics. + * @defaultValue false + */ + printBackground?: boolean; + /** + * Whether to print in landscape orientation. + * @defaultValue = false + */ + landscape?: boolean; + /** + * Paper ranges to print, e.g. `1-5, 8, 11-13`. + * @defaultValue The empty string, which means all pages are printed. + */ + pageRanges?: string; + /** + * @remarks + * If set, this takes priority over the `width` and `height` options. + * @defaultValue `letter`. + */ + format?: PaperFormat; + /** + * Sets the width of paper. You can pass in a number or a string with a unit. + */ + width?: string | number; + /** + * Sets the height of paper. You can pass in a number or a string with a unit. + */ + height?: string | number; + /** + * Give any CSS `@page` size declared in the page priority over what is + * declared in the `width` or `height` or `format` option. + * @defaultValue `false`, which will scale the content to fit the paper size. + */ + preferCSSPageSize?: boolean; + /** + * Set the PDF margins. + * @defaultValue no margins are set. + */ + margin?: PDFMargin; + /** + * The path to save the file to. + * + * @remarks + * + * If the path is relative, it's resolved relative to the current working directory. + * + * @defaultValue the empty string, which means the PDF will not be written to disk. + */ + path?: string; +} + +/** + * @internal + */ +export interface PaperFormatDimensions { + width: number; + height: number; +} + +/** + * @internal + */ +export const paperFormats: Record = { + letter: { width: 8.5, height: 11 }, + legal: { width: 8.5, height: 14 }, + tabloid: { width: 11, height: 17 }, + ledger: { width: 17, height: 11 }, + a0: { width: 33.1, height: 46.8 }, + a1: { width: 23.4, height: 33.1 }, + a2: { width: 16.54, height: 23.4 }, + a3: { width: 11.7, height: 16.54 }, + a4: { width: 8.27, height: 11.7 }, + a5: { width: 5.83, height: 8.27 }, + a6: { width: 4.13, height: 5.83 }, +} as const; diff --git a/src/common/Page.ts b/src/common/Page.ts index 388ca610177ec..6370ab5ccddd5 100644 --- a/src/common/Page.ts +++ b/src/common/Page.ts @@ -57,6 +57,7 @@ import { EvaluateFnReturnType, UnwrapPromiseLike, } from './EvalTypes.js'; +import { PDFOptions, paperFormats } from './PDFOptions.js'; const writeFileAsync = promisify(fs.writeFile); @@ -151,48 +152,6 @@ interface ScreenshotOptions { encoding?: string; } -interface PDFMargin { - top?: string | number; - bottom?: string | number; - left?: string | number; - right?: string | number; -} - -interface PDFOptions { - scale?: number; - displayHeaderFooter?: boolean; - headerTemplate?: string; - footerTemplate?: string; - printBackground?: boolean; - landscape?: boolean; - pageRanges?: string; - format?: string; - width?: string | number; - height?: string | number; - preferCSSPageSize?: boolean; - margin?: PDFMargin; - path?: string; -} - -interface PaperFormat { - width: number; - height: number; -} - -const paperFormats: Record = { - letter: { width: 8.5, height: 11 }, - legal: { width: 8.5, height: 14 }, - tabloid: { width: 11, height: 17 }, - ledger: { width: 17, height: 11 }, - a0: { width: 33.1, height: 46.8 }, - a1: { width: 23.4, height: 33.1 }, - a2: { width: 16.54, height: 23.4 }, - a3: { width: 11.7, height: 16.54 }, - a4: { width: 8.27, height: 11.7 }, - a5: { width: 5.83, height: 8.27 }, - a6: { width: 4.13, height: 5.83 }, -} as const; - type VisionDeficiency = | 'none' | 'achromatopsia' @@ -832,6 +791,28 @@ export class Page extends EventEmitter { return context.evaluateHandle(pageFunction, ...args); } + /** + * This method iterates the JavaScript heap and finds all objects with the + * given prototype. + * + * @remarks + * + * @example + * + * ```js + * // Create a Map object + * await page.evaluate(() => window.map = new Map()); + * // Get a handle to the Map object prototype + * const mapPrototype = await page.evaluateHandle(() => Map.prototype); + * // Query all map instances into an array + * const mapInstances = await page.queryObjects(mapPrototype); + * // Count amount of map objects in heap + * const count = await page.evaluate(maps => maps.length, mapInstances); + * await mapInstances.dispose(); + * await mapPrototype.dispose(); + * ``` + * @param prototypeHandle - a handle to the object prototype. + */ async queryObjects(prototypeHandle: JSHandle): Promise { const context = await this.mainFrame().executionContext(); return context.queryObjects(prototypeHandle); @@ -1718,6 +1699,24 @@ export class Page extends EventEmitter { } } + /** + * Generatees a PDF of the page with the `print` CSS media type. + * @remarks + * + * IMPORTANT: PDF generation is only supported in Chrome headless mode. + * + * To generate a PDF with the `screen` media type, call + * {@link Page.emulateMediaType | `page.emulateMediaType('screen')`} before + * calling `page.pdf()`. + * + * By default, `page.pdf()` generates a pdf with modified colors for printing. + * Use the + * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust | `-webkit-print-color-adjust`} + * property to force rendering of exact colors. + * + * + * @param options - options for generating the PDF. + */ async pdf(options: PDFOptions = {}): Promise { const { scale = 1, diff --git a/src/common/Puppeteer.ts b/src/common/Puppeteer.ts index 310f7c209b46c..72f538d7dc5e9 100644 --- a/src/common/Puppeteer.ts +++ b/src/common/Puppeteer.ts @@ -59,6 +59,11 @@ import { PUPPETEER_REVISIONS } from '../revisions.js'; * await browser.close(); * })(); * ``` + * + * Once you have created a `page` you have access to a large API to interact + * with the page, navigate, or find certain elements in that page. + * The {@link Page | `page` documentation} lists all the available methods. + * * @public */ export class Puppeteer { @@ -270,7 +275,6 @@ export class Puppeteer { } /** - * * @param options - Set of configurable options to specify the settings * of the BrowserFetcher. * @returns A new BrowserFetcher instance.