ExcelScript.PageLayout interface

Package:

ExcelScript

Represents layout and print settings that are not dependent on any printer-specific implementation. These settings include margins, orientation, page numbering, title rows, and print area.

Remarks

Examples

/**
 * This script sets some basic page layout settings for printing.
 */
function main(workbook: ExcelScript.Workbook) {
  // Go to each worksheet so the print settings are consistent.
  workbook.getWorksheets().forEach((sheet) => {
    const pageLayout : ExcelScript.PageLayout = sheet.getPageLayout();

    // Turn off draft mode so images are printed.
    pageLayout.setDraftMode(false);
    
    // Print on 8.5"x11" paper.
    pageLayout.setPaperSize(ExcelScript.PaperType.letter);

    // Print every page with a landscape orientation.
    pageLayout.setOrientation(ExcelScript.PageOrientation.landscape);
  });
}

Methods

getBlackAndWhite()	The worksheet's black and white print option.
getBottomMargin()	The worksheet's bottom page margin to use for printing in points.
getCenterHorizontally()	The worksheet's center horizontally flag. This flag determines whether the worksheet will be centered horizontally when it's printed.
getCenterVertically()	The worksheet's center vertically flag. This flag determines whether the worksheet will be centered vertically when it's printed.
getDraftMode()	The worksheet's draft mode option. If true, the sheet will be printed without graphics.
getFirstPageNumber()	The worksheet's first page number to print. A null value represents "auto" page numbering.
getFooterMargin()	The worksheet's footer margin, in points, for use when printing.
getHeaderMargin()	The worksheet's header margin, in points, for use when printing.
getHeadersFooters()	Header and footer configuration for the worksheet.
getLeftMargin()	The worksheet's left margin, in points, for use when printing.
getOrientation()	The worksheet's orientation of the page.
getPaperSize()	The worksheet's paper size of the page.
getPrintArea()	Gets the RangeAreas object, comprising one or more rectangular ranges, that represents the print area for the worksheet. If there is no print area, then this method returns undefined.
getPrintComments()	Specifies if the worksheet's comments should be displayed when printing.
getPrintErrors()	The worksheet's print errors option.
getPrintGridlines()	Specifies if the worksheet's gridlines will be printed.
getPrintHeadings()	Specifies if the worksheet's headings will be printed.
getPrintOrder()	The worksheet's page print order option. This specifies the order to use for processing the page number printed.
getPrintTitleColumns()	Gets the range object representing the title columns. If not set, then this method returns undefined.
getPrintTitleRows()	Gets the range object representing the title rows. If not set, then this method returns undefined.
getRightMargin()	The worksheet's right margin, in points, for use when printing.
getTopMargin()	The worksheet's top margin, in points, for use when printing.
getZoom()	The worksheet's print zoom options. The PageLayoutZoomOptions object must be set as a JSON object (use x.zoom = {...} instead of x.zoom.scale = ...).
setBlackAndWhite(blackAndWhite)	The worksheet's black and white print option.
setBottomMargin(bottomMargin)	The worksheet's bottom page margin to use for printing in points.
setCenterHorizontally(centerHorizontally)	The worksheet's center horizontally flag. This flag determines whether the worksheet will be centered horizontally when it's printed.
setCenterVertically(centerVertically)	The worksheet's center vertically flag. This flag determines whether the worksheet will be centered vertically when it's printed.
setDraftMode(draftMode)	The worksheet's draft mode option. If true, the sheet will be printed without graphics.
setFirstPageNumber(firstPageNumber)	The worksheet's first page number to print. A null value represents "auto" page numbering.
setFooterMargin(footerMargin)	The worksheet's footer margin, in points, for use when printing.
setHeaderMargin(headerMargin)	The worksheet's header margin, in points, for use when printing.
setLeftMargin(leftMargin)	The worksheet's left margin, in points, for use when printing.
setOrientation(orientation)	The worksheet's orientation of the page.
setPaperSize(paperSize)	The worksheet's paper size of the page.
setPrintArea(printArea)	Sets the worksheet's print area.
setPrintComments(printComments)	Specifies if the worksheet's comments should be displayed when printing.
setPrintErrors(printErrors)	The worksheet's print errors option.
setPrintGridlines(printGridlines)	Specifies if the worksheet's gridlines will be printed.
setPrintHeadings(printHeadings)	Specifies if the worksheet's headings will be printed.
setPrintMargins(unit, marginOptions)	Sets the worksheet's page margins with units.
setPrintOrder(printOrder)	The worksheet's page print order option. This specifies the order to use for processing the page number printed.
setPrintTitleColumns(printTitleColumns)	Sets the columns that contain the cells to be repeated at the left of each page of the worksheet for printing.
setPrintTitleRows(printTitleRows)	Sets the rows that contain the cells to be repeated at the top of each page of the worksheet for printing.
setRightMargin(rightMargin)	The worksheet's right margin, in points, for use when printing.
setTopMargin(topMargin)	The worksheet's top margin, in points, for use when printing.
setZoom(zoom)	The worksheet's print zoom options. The PageLayoutZoomOptions object must be set as a JSON object (use x.zoom = {...} instead of x.zoom.scale = ...).

Method Details

getBlackAndWhite()

The worksheet's black and white print option.

getBlackAndWhite(): boolean;

Returns

boolean

getBottomMargin()

The worksheet's bottom page margin to use for printing in points.

getBottomMargin(): number;

Returns

number

getCenterHorizontally()

The worksheet's center horizontally flag. This flag determines whether the worksheet will be centered horizontally when it's printed.

getCenterHorizontally(): boolean;

Returns

boolean

getCenterVertically()

The worksheet's center vertically flag. This flag determines whether the worksheet will be centered vertically when it's printed.

getCenterVertically(): boolean;

Returns

boolean

getDraftMode()

The worksheet's draft mode option. If true, the sheet will be printed without graphics.

getDraftMode(): boolean;

Returns

boolean

getFirstPageNumber()

The worksheet's first page number to print. A null value represents "auto" page numbering.

getFirstPageNumber(): number | "";

Returns

number | ""

getFooterMargin()

The worksheet's footer margin, in points, for use when printing.

getFooterMargin(): number;

Returns

number

getHeaderMargin()

The worksheet's header margin, in points, for use when printing.

getHeaderMargin(): number;

Returns

number

getHeadersFooters()

Header and footer configuration for the worksheet.

getHeadersFooters(): HeaderFooterGroup;

Returns

ExcelScript.HeaderFooterGroup

getLeftMargin()

The worksheet's left margin, in points, for use when printing.

getLeftMargin(): number;

Returns

number

getOrientation()

The worksheet's orientation of the page.

getOrientation(): PageOrientation;

Returns

ExcelScript.PageOrientation

getPaperSize()

The worksheet's paper size of the page.

getPaperSize(): PaperType;

Returns

ExcelScript.PaperType

getPrintArea()

Gets the RangeAreas object, comprising one or more rectangular ranges, that represents the print area for the worksheet. If there is no print area, then this method returns undefined.

getPrintArea(): RangeAreas;

Returns

ExcelScript.RangeAreas

getPrintComments()

Specifies if the worksheet's comments should be displayed when printing.

getPrintComments(): PrintComments;

Returns

ExcelScript.PrintComments

getPrintErrors()

The worksheet's print errors option.

getPrintErrors(): PrintErrorType;

Returns

ExcelScript.PrintErrorType

getPrintGridlines()

Specifies if the worksheet's gridlines will be printed.

getPrintGridlines(): boolean;

Returns

boolean

getPrintHeadings()

Specifies if the worksheet's headings will be printed.

getPrintHeadings(): boolean;

Returns

boolean

getPrintOrder()

The worksheet's page print order option. This specifies the order to use for processing the page number printed.

getPrintOrder(): PrintOrder;

Returns

ExcelScript.PrintOrder

getPrintTitleColumns()

Gets the range object representing the title columns. If not set, then this method returns undefined.

getPrintTitleColumns(): Range;

Returns

ExcelScript.Range

getPrintTitleRows()

Gets the range object representing the title rows. If not set, then this method returns undefined.

getPrintTitleRows(): Range;

Returns

ExcelScript.Range

getRightMargin()

The worksheet's right margin, in points, for use when printing.

getRightMargin(): number;

Returns

number

getTopMargin()

The worksheet's top margin, in points, for use when printing.

getTopMargin(): number;

Returns

number

getZoom()

The worksheet's print zoom options. The PageLayoutZoomOptions object must be set as a JSON object (use x.zoom = {...} instead of x.zoom.scale = ...).

getZoom(): PageLayoutZoomOptions;

Returns

ExcelScript.PageLayoutZoomOptions

setBlackAndWhite(blackAndWhite)

The worksheet's black and white print option.

setBlackAndWhite(blackAndWhite: boolean): void;

Parameters

blackAndWhite

boolean

Returns

void

setBottomMargin(bottomMargin)

The worksheet's bottom page margin to use for printing in points.

setBottomMargin(bottomMargin: number): void;

Parameters

bottomMargin

number

Returns

void

setCenterHorizontally(centerHorizontally)

The worksheet's center horizontally flag. This flag determines whether the worksheet will be centered horizontally when it's printed.

setCenterHorizontally(centerHorizontally: boolean): void;

Parameters

centerHorizontally

boolean

Returns

void

setCenterVertically(centerVertically)

The worksheet's center vertically flag. This flag determines whether the worksheet will be centered vertically when it's printed.

setCenterVertically(centerVertically: boolean): void;

Parameters

centerVertically

boolean

Returns

void

setDraftMode(draftMode)

The worksheet's draft mode option. If true, the sheet will be printed without graphics.

setDraftMode(draftMode: boolean): void;

Parameters

draftMode

boolean

Returns

void

Examples

/**
 * This script turns off the print setting for draft mode.
 */
function main(workbook: ExcelScript.Workbook) {
  // Go to each worksheet so the print settings are consistent.
  workbook.getWorksheets().forEach((sheet) => {
    const pageLayout = sheet.getPageLayout();

    // Turn off draft mode so images are printed.
    pageLayout.setDraftMode(false);
  });
}

setFirstPageNumber(firstPageNumber)

The worksheet's first page number to print. A null value represents "auto" page numbering.

setFirstPageNumber(firstPageNumber: number | ""): void;

Parameters

firstPageNumber

number | ""

Returns

void

setFooterMargin(footerMargin)

The worksheet's footer margin, in points, for use when printing.

setFooterMargin(footerMargin: number): void;

Parameters

footerMargin

number

Returns

void

setHeaderMargin(headerMargin)

The worksheet's header margin, in points, for use when printing.

setHeaderMargin(headerMargin: number): void;

Parameters

headerMargin

number

Returns

void

setLeftMargin(leftMargin)

The worksheet's left margin, in points, for use when printing.

setLeftMargin(leftMargin: number): void;

Parameters

leftMargin

number

Returns

void

setOrientation(orientation)

The worksheet's orientation of the page.

setOrientation(orientation: PageOrientation): void;

Parameters

orientation

ExcelScript.PageOrientation

Returns

void

Examples

/**
 * This script sets the printing orientation for the entire workbook.
 */
function main(workbook: ExcelScript.Workbook) {
  // Go to each worksheet so the print settings are consistent.
  workbook.getWorksheets().forEach((sheet) => {
    const pageLayout = sheet.getPageLayout();

    // Print every page with a landscape orientation.
    pageLayout.setOrientation(ExcelScript.PageOrientation.landscape);
  });
}

setPaperSize(paperSize)

The worksheet's paper size of the page.

setPaperSize(paperSize: PaperType): void;

Parameters

paperSize

ExcelScript.PaperType

Returns

void

Examples

/**
 * This script sets the page size for printing.
 */
function main(workbook: ExcelScript.Workbook) {
  // Go to each worksheet so the print settings are consistent.
  workbook.getWorksheets().forEach((sheet) => {
    const pageLayout = sheet.getPageLayout();
    // Print on 8.5"x11" paper.
    pageLayout.setPaperSize(ExcelScript.PaperType.letter);
  });
}

setPrintArea(printArea)

Sets the worksheet's print area.

setPrintArea(printArea: Range | RangeAreas | string): void;

Parameters

printArea

ExcelScript.Range | ExcelScript.RangeAreas | string

The range or ranges of the content to print.

Returns

void

setPrintComments(printComments)

Specifies if the worksheet's comments should be displayed when printing.

setPrintComments(printComments: PrintComments): void;

Parameters

printComments

ExcelScript.PrintComments

Returns

void

Examples

/**
 * This script makes the comments print at the end of the worksheet
 * when the workbook is printed.
 */
function main(workbook: ExcelScript.Workbook) {
  // Access every worksheet in the workbook.
  workbook.getWorksheets().forEach(worksheet => {
    // Get the page layout for each sheet.
    const layout = worksheet.getPageLayout();

    // Change the comment printing settings to print them at the end of the sheet.
    layout.setPrintComments(ExcelScript.PrintComments.endSheet);
  });
}

setPrintErrors(printErrors)

The worksheet's print errors option.

setPrintErrors(printErrors: PrintErrorType): void;

Parameters

printErrors

ExcelScript.PrintErrorType

Returns

void

setPrintGridlines(printGridlines)

Specifies if the worksheet's gridlines will be printed.

setPrintGridlines(printGridlines: boolean): void;

Parameters

printGridlines

boolean

Returns

void

setPrintHeadings(printHeadings)

Specifies if the worksheet's headings will be printed.

setPrintHeadings(printHeadings: boolean): void;

Parameters

printHeadings

boolean

Returns

void

setPrintMargins(unit, marginOptions)

Sets the worksheet's page margins with units.

setPrintMargins(
            unit: PrintMarginUnit,
            marginOptions: PageLayoutMarginOptions
        ): void;

Parameters

unit

ExcelScript.PrintMarginUnit

Measurement unit for the margins provided.

marginOptions

ExcelScript.PageLayoutMarginOptions

Margin values to set. Margins not provided remain unchanged.

Returns

void

setPrintOrder(printOrder)

The worksheet's page print order option. This specifies the order to use for processing the page number printed.

setPrintOrder(printOrder: PrintOrder): void;

Parameters

printOrder

ExcelScript.PrintOrder

Returns

void

Examples

/**
 * This script sets the print order for every worksheet in the workbook.
 * The order of printed content will go over (e.g., left-to-right) 
 * then down (i.e., top-to-bottom).
 */
function main(workbook: ExcelScript.Workbook) {
  // Access every worksheet in the workbook.
  workbook.getWorksheets().forEach(worksheet => {
    // Get the page layout for each sheet.
    const layout: ExcelScript.PageLayout = worksheet.getPageLayout();

    // Set the print order to over-then-down.
    layout.setPrintOrder(ExcelScript.PrintOrder.overThenDown);
  });
}

setPrintTitleColumns(printTitleColumns)

Sets the columns that contain the cells to be repeated at the left of each page of the worksheet for printing.

setPrintTitleColumns(printTitleColumns: Range | string): void;

Parameters

printTitleColumns

ExcelScript.Range | string

The columns to be repeated to the left of each page. The range must span the entire column to be valid.

Returns

void

setPrintTitleRows(printTitleRows)

Sets the rows that contain the cells to be repeated at the top of each page of the worksheet for printing.

setPrintTitleRows(printTitleRows: Range | string): void;

Parameters

printTitleRows

ExcelScript.Range | string

The rows to be repeated at the top of each page. The range must span the entire row to be valid.

Returns

void

setRightMargin(rightMargin)

The worksheet's right margin, in points, for use when printing.

setRightMargin(rightMargin: number): void;

Parameters

rightMargin

number

Returns

void

setTopMargin(topMargin)

The worksheet's top margin, in points, for use when printing.

setTopMargin(topMargin: number): void;

Parameters

topMargin

number

Returns

void

setZoom(zoom)

The worksheet's print zoom options. The PageLayoutZoomOptions object must be set as a JSON object (use x.zoom = {...} instead of x.zoom.scale = ...).

setZoom(zoom: PageLayoutZoomOptions): void;

Parameters

zoom

ExcelScript.PageLayoutZoomOptions

Returns

void

Examples

/**
 * This script changes the scale-to-fit of the page layout.
 */
function main(workbook: ExcelScript.Workbook) {
    // Get the current worksheet.
    const sheet = workbook.getActiveWorksheet();

    // Scale the layout to half size for printing.
    const layout = sheet.getPageLayout();
    const zoomOptions: ExcelScript.PageLayoutZoomOptions = {
        scale: 50
    }
    layout.setZoom(zoomOptions)
}