refactor: printToPDF should be headless (#33654)
This commit is contained in:
Shelley Vohr
GitHub
parent
0d69067dee
commit
93b39b92b5
17 changed files with 648 additions and 414 deletions
|
|
@ -1428,7 +1428,7 @@ Returns `Promise<PrinterInfo[]>` - Resolves with a [`PrinterInfo[]`](structures/
|
|||
* `header` string (optional) - string to be printed as page header.
|
||||
* `footer` string (optional) - string to be printed as page footer.
|
||||
* `pageSize` string | Size (optional) - Specify page size of the printed document. Can be `A3`,
|
||||
`A4`, `A5`, `Legal`, `Letter`, `Tabloid` or an Object containing `height`.
|
||||
`A4`, `A5`, `Legal`, `Letter`, `Tabloid` or an Object containing `height` and `width`.
|
||||
* `callback` Function (optional)
|
||||
* `success` boolean - Indicates success of the print call.
|
||||
* `failureReason` string - Error description called back if the print fails.
|
||||
|
|
@ -1459,43 +1459,28 @@ win.webContents.print(options, (success, errorType) => {
|
|||
#### `contents.printToPDF(options)`
|
||||
|
||||
* `options` Object
|
||||
* `headerFooter` Record<string, string> (optional) - the header and footer for the PDF.
|
||||
* `title` string - The title for the PDF header.
|
||||
* `url` string - the url for the PDF footer.
|
||||
* `landscape` boolean (optional) - `true` for landscape, `false` for portrait.
|
||||
* `marginsType` Integer (optional) - Specifies the type of margins to use. Uses 0 for
|
||||
default margin, 1 for no margin, and 2 for minimum margin.
|
||||
* `scaleFactor` number (optional) - The scale factor of the web page. Can range from 0 to 100.
|
||||
* `pageRanges` Record<string, number> (optional) - The page range to print.
|
||||
* `from` number - Index of the first page to print (0-based).
|
||||
* `to` number - Index of the last page to print (inclusive) (0-based).
|
||||
* `pageSize` string | Size (optional) - Specify page size of the generated PDF. Can be `A3`,
|
||||
`A4`, `A5`, `Legal`, `Letter`, `Tabloid` or an Object containing `height` and `width` in microns.
|
||||
* `printBackground` boolean (optional) - Whether to print CSS backgrounds.
|
||||
* `printSelectionOnly` boolean (optional) - Whether to print selection only.
|
||||
* `landscape` boolean (optional) - Paper orientation.`true` for landscape, `false` for portrait. Defaults to false.
|
||||
* `displayHeaderFooter` boolean (optional) - Whether to display header and footer. Defaults to false.
|
||||
* `printBackground` boolean (optional) - Whether to print background graphics. Defaults to false.
|
||||
* `scale` number(optional) - Scale of the webpage rendering. Defaults to 1.
|
||||
* `pageSize` string | Size (optional) - Specify page size of the generated PDF. Can be `A0`, `A1`, `A2`, `A3`,
|
||||
`A4`, `A5`, `A6`, `Legal`, `Letter`, `Tabloid`, `Ledger`, or an Object containing `height` and `width` in inches. Defaults to `Letter`.
|
||||
* `margins` Object (optional)
|
||||
* `top` number (optional) - Top margin in inches. Defaults to 1cm (~0.4 inches).
|
||||
* `bottom` number (optional) - Bottom margin in inches. Defaults to 1cm (~0.4 inches).
|
||||
* `left` number (optional) - Left margin in inches. Defaults to 1cm (~0.4 inches).
|
||||
* `right` number (optional) - Right margin in inches. Defaults to 1cm (~0.4 inches).
|
||||
* `pageRanges` string (optional) - Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
|
||||
* `headerTemplate` string (optional) - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: `date` (formatted print date), `title` (document title), `url` (document location), `pageNumber` (current page number) and `totalPages` (total pages in the document). For example, `<span class=title></span>` would generate span containing the title.
|
||||
* `footerTemplate` string (optional) - HTML template for the print footer. Should use the same format as the `headerTemplate`.
|
||||
* `preferCSSPageSize` boolean (optional) - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size.
|
||||
|
||||
Returns `Promise<Buffer>` - Resolves with the generated PDF data.
|
||||
|
||||
Prints window's web page as PDF with Chromium's preview printing custom
|
||||
settings.
|
||||
Prints the window's web page as PDF.
|
||||
|
||||
The `landscape` will be ignored if `@page` CSS at-rule is used in the web page.
|
||||
|
||||
By default, an empty `options` will be regarded as:
|
||||
|
||||
```javascript
|
||||
{
|
||||
marginsType: 0,
|
||||
printBackground: false,
|
||||
printSelectionOnly: false,
|
||||
landscape: false,
|
||||
pageSize: 'A4',
|
||||
scaleFactor: 100
|
||||
}
|
||||
```
|
||||
|
||||
Use `page-break-before: always;` CSS style to force to print to a new page.
|
||||
|
||||
An example of `webContents.printToPDF`:
|
||||
|
||||
```javascript
|
||||
|
|
@ -1504,7 +1489,7 @@ const fs = require('fs')
|
|||
const path = require('path')
|
||||
const os = require('os')
|
||||
|
||||
const win = new BrowserWindow({ width: 800, height: 600 })
|
||||
const win = new BrowserWindow()
|
||||
win.loadURL('http://github.com')
|
||||
|
||||
win.webContents.on('did-finish-load', () => {
|
||||
|
|
@ -1521,6 +1506,8 @@ win.webContents.on('did-finish-load', () => {
|
|||
})
|
||||
```
|
||||
|
||||
See [Page.printToPdf](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF) for more information.
|
||||
|
||||
#### `contents.addWorkSpace(path)`
|
||||
|
||||
* `path` string
|
||||
|
|
|
|||
|
|
@ -565,21 +565,21 @@ Prints `webview`'s web page. Same as `webContents.print([options])`.
|
|||
### `<webview>.printToPDF(options)`
|
||||
|
||||
* `options` Object
|
||||
* `headerFooter` Record<string, string> (optional) - the header and footer for the PDF.
|
||||
* `title` string - The title for the PDF header.
|
||||
* `url` string - the url for the PDF footer.
|
||||
* `landscape` boolean (optional) - `true` for landscape, `false` for portrait.
|
||||
* `marginsType` Integer (optional) - Specifies the type of margins to use. Uses 0 for
|
||||
default margin, 1 for no margin, and 2 for minimum margin.
|
||||
and `width` in microns.
|
||||
* `scaleFactor` number (optional) - The scale factor of the web page. Can range from 0 to 100.
|
||||
* `pageRanges` Record<string, number> (optional) - The page range to print. On macOS, only the first range is honored.
|
||||
* `from` number - Index of the first page to print (0-based).
|
||||
* `to` number - Index of the last page to print (inclusive) (0-based).
|
||||
* `pageSize` string | Size (optional) - Specify page size of the generated PDF. Can be `A3`,
|
||||
`A4`, `A5`, `Legal`, `Letter`, `Tabloid` or an Object containing `height`
|
||||
* `printBackground` boolean (optional) - Whether to print CSS backgrounds.
|
||||
* `printSelectionOnly` boolean (optional) - Whether to print selection only.
|
||||
* `landscape` boolean (optional) - Paper orientation.`true` for landscape, `false` for portrait. Defaults to false.
|
||||
* `displayHeaderFooter` boolean (optional) - Whether to display header and footer. Defaults to false.
|
||||
* `printBackground` boolean (optional) - Whether to print background graphics. Defaults to false.
|
||||
* `scale` number(optional) - Scale of the webpage rendering. Defaults to 1.
|
||||
* `pageSize` string | Size (optional) - Specify page size of the generated PDF. Can be `A0`, `A1`, `A2`, `A3`,
|
||||
`A4`, `A5`, `A6`, `Legal`, `Letter`, `Tabloid`, `Ledger`, or an Object containing `height` and `width` in inches. Defaults to `Letter`.
|
||||
* `margins` Object (optional)
|
||||
* `top` number (optional) - Top margin in inches. Defaults to 1cm (~0.4 inches).
|
||||
* `bottom` number (optional) - Bottom margin in inches. Defaults to 1cm (~0.4 inches).
|
||||
* `left` number (optional) - Left margin in inches. Defaults to 1cm (~0.4 inches).
|
||||
* `right` number (optional) - Right margin in inches. Defaults to 1cm (~0.4 inches).
|
||||
* `pageRanges` string (optional) - Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
|
||||
* `headerTemplate` string (optional) - HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: `date` (formatted print date), `title` (document title), `url` (document location), `pageNumber` (current page number) and `totalPages` (total pages in the document). For example, `<span class=title></span>` would generate span containing the title.
|
||||
* `footerTemplate` string (optional) - HTML template for the print footer. Should use the same format as the `headerTemplate`.
|
||||
* `preferCSSPageSize` boolean (optional) - Whether or not to prefer page size as defined by css. Defaults to false, in which case the content will be scaled to fit the paper size.
|
||||
|
||||
Returns `Promise<Uint8Array>` - Resolves with the generated PDF data.
|
||||
|
||||
|
|
|
|||
|
|
@ -14,6 +14,61 @@ This document uses the following convention to categorize breaking changes:
|
|||
|
||||
## Planned Breaking API Changes (20.0)
|
||||
|
||||
### API Changed: `webContents.printToPDF()`
|
||||
|
||||
`webContents.printToPDF()` has been modified to conform to [`Page.printToPDF`](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF) in the Chrome DevTools Protocol. This has been changes in order to
|
||||
address changes upstream that made our previous implementation untenable and rife with bugs.
|
||||
|
||||
**Arguments Changed**
|
||||
|
||||
* `pageRanges`
|
||||
|
||||
**Arguments Removed**
|
||||
|
||||
* `printSelectionOnly`
|
||||
* `marginsType`
|
||||
* `headerFooter`
|
||||
* `scaleFactor`
|
||||
|
||||
**Arguments Added**
|
||||
|
||||
* `headerTemplate`
|
||||
* `footerTemplate`
|
||||
* `displayHeaderFooter`
|
||||
* `margins`
|
||||
* `scale`
|
||||
* `preferCSSPageSize`
|
||||
|
||||
```js
|
||||
// Main process
|
||||
const { webContents } = require('electron')
|
||||
|
||||
webContents.printToPDF({
|
||||
landscape: true,
|
||||
displayHeaderFooter: true,
|
||||
printBackground: true,
|
||||
scale: 2,
|
||||
pageSize: 'Ledger',
|
||||
margins: {
|
||||
top: 2,
|
||||
bottom: 2,
|
||||
left: 2,
|
||||
right: 2
|
||||
},
|
||||
pageRanges: '1-5, 8, 11-13',
|
||||
headerTemplate: '<h1>Title</h1>',
|
||||
footerTemplate: '<div><span class="pageNumber"></span></div>',
|
||||
preferCSSPageSize: true
|
||||
}).then(data => {
|
||||
fs.writeFile(pdfPath, data, (error) => {
|
||||
if (error) throw error
|
||||
console.log(`Wrote PDF successfully to ${pdfPath}`)
|
||||
})
|
||||
}).catch(error => {
|
||||
console.log(`Failed to write PDF to ${pdfPath}: `, error)
|
||||
})
|
||||
```
|
||||
|
||||
### Default Changed: renderers without `nodeIntegration: true` are sandboxed by default
|
||||
|
||||
Previously, renderers that specified a preload script defaulted to being
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue