Excel.PageLayout class

Extends
OfficeExtension.ClientObject

Properties

blackAndWhite

Gets or sets the worksheet's black and white print option.

[ API set: ExcelApi 1.9 ]

bottomMargin

Gets or sets the worksheet's bottom page margin to use for printing in points.

[ API set: ExcelApi 1.9 ]

centerHorizontally

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

[ API set: ExcelApi 1.9 ]

centerVertically

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

[ API set: ExcelApi 1.9 ]

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

draftMode

Gets or sets the worksheet's draft mode option. If true the sheet will be printed without graphics.

[ API set: ExcelApi 1.9 ]

firstPageNumber

Gets or sets the worksheet's first page number to print. Null value represents "auto" page numbering.

[ API set: ExcelApi 1.9 ]

footerMargin

Gets or sets the worksheet's footer margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

headerMargin

Gets or sets the worksheet's header margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

headersFooters

Header and footer configuration for the worksheet.

[ API set: ExcelApi 1.9 ]

leftMargin

Gets or sets the worksheet's left margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

orientation

Gets or sets the worksheet's orientation of the page.

[ API set: ExcelApi 1.9 ]

paperSize

Gets or sets the worksheet's paper size of the page.

[ API set: ExcelApi 1.9 ]

printComments

Gets or sets whether the worksheet's comments should be displayed when printing.

[ API set: ExcelApi 1.9 ]

printErrors

Gets or sets the worksheet's print errors option.

[ API set: ExcelApi 1.9 ]

printGridlines

Gets or sets the worksheet's print gridlines flag. This flag determines whether gridlines will be printed or not.

[ API set: ExcelApi 1.9 ]

printHeadings

Gets or sets the worksheet's print headings flag. This flag determines whether headings will be printed or not.

[ API set: ExcelApi 1.9 ]

printOrder

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

[ API set: ExcelApi 1.9 ]

rightMargin

Gets or sets the worksheet's right margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

topMargin

Gets or sets the worksheet's top margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

zoom

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

[ API set: ExcelApi 1.9 ]

Methods

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, an ItemNotFound error will be thrown.

[ API set: ExcelApi 1.9 ]

getPrintAreaOrNullObject()

Gets the RangeAreas object, comprising one or more rectangular ranges, that represents the print area for the worksheet. If there is no print area, a null object will be returned.

[ API set: ExcelApi 1.9 ]

getPrintTitleColumns()

Gets the range object representing the title columns.

[ API set: ExcelApi 1.9 ]

getPrintTitleColumnsOrNullObject()

Gets the range object representing the title columns. If not set, this will return a null object.

[ API set: ExcelApi 1.9 ]

getPrintTitleRows()

Gets the range object representing the title rows.

[ API set: ExcelApi 1.9 ]

getPrintTitleRowsOrNullObject()

Gets the range object representing the title rows. If not set, this will return a null object.

[ API set: ExcelApi 1.9 ]

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

setPrintArea(printArea)

Sets the worksheet's print area.

[ API set: ExcelApi 1.9 ]

setPrintMargins(unit, marginOptions)

Sets the worksheet's page margins with units.

[ API set: ExcelApi 1.9 ]

setPrintMargins(unitString, marginOptions)

Sets the worksheet's page margins with units.

[ API set: ExcelApi 1.9 ]

setPrintTitleColumns(printTitleColumns)

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

[ API set: ExcelApi 1.9 ]

setPrintTitleRows(printTitleRows)

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

[ API set: ExcelApi 1.9 ]

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.PageLayout object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.PageLayoutData) that contains shallow copies of any loaded child properties from the original object.

Property Details

blackAndWhite

Gets or sets the worksheet's black and white print option.

[ API set: ExcelApi 1.9 ]

blackAndWhite: boolean;

Property Value

boolean

bottomMargin

Gets or sets the worksheet's bottom page margin to use for printing in points.

[ API set: ExcelApi 1.9 ]

bottomMargin: number;

Property Value

number

centerHorizontally

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

[ API set: ExcelApi 1.9 ]

centerHorizontally: boolean;

Property Value

boolean

Examples

await Excel.run(async (context) => {
    const farmSheet = context.workbook.worksheets.getItem("Print");
    farmSheet.pageLayout.centerHorizontally = true;
    farmSheet.pageLayout.centerVertically = true;
    await context.sync();
});

centerVertically

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

[ API set: ExcelApi 1.9 ]

centerVertically: boolean;

Property Value

boolean

Examples

await Excel.run(async (context) => {
    const farmSheet = context.workbook.worksheets.getItem("Print");
    farmSheet.pageLayout.centerHorizontally = true;
    farmSheet.pageLayout.centerVertically = true;
    await context.sync();
});

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

draftMode

Gets or sets the worksheet's draft mode option. If true the sheet will be printed without graphics.

[ API set: ExcelApi 1.9 ]

draftMode: boolean;

Property Value

boolean

firstPageNumber

Gets or sets the worksheet's first page number to print. Null value represents "auto" page numbering.

[ API set: ExcelApi 1.9 ]

firstPageNumber: number | "";

Property Value

number | ""

footerMargin

Gets or sets the worksheet's footer margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

footerMargin: number;

Property Value

number

headerMargin

Gets or sets the worksheet's header margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

headerMargin: number;

Property Value

number

headersFooters

Header and footer configuration for the worksheet.

[ API set: ExcelApi 1.9 ]

readonly headersFooters: Excel.HeaderFooterGroup;

Property Value

leftMargin

Gets or sets the worksheet's left margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

leftMargin: number;

Property Value

number

orientation

Gets or sets the worksheet's orientation of the page.

[ API set: ExcelApi 1.9 ]

orientation: Excel.PageOrientation | "Portrait" | "Landscape";

Property Value

Excel.PageOrientation | "Portrait" | "Landscape"

Examples

await Excel.run(async (context) => {
    const farmSheet = context.workbook.worksheets.getItem("Print");
    farmSheet.pageLayout.orientation = Excel.PageOrientation.landscape;
    await context.sync();
});

paperSize

Gets or sets the worksheet's paper size of the page.

[ API set: ExcelApi 1.9 ]

paperSize: Excel.PaperType | "Letter" | "LetterSmall" | "Tabloid" | "Ledger" | "Legal" | "Statement" | "Executive" | "A3" | "A4" | "A4Small" | "A5" | "B4" | "B5" | "Folio" | "Quatro" | "Paper10x14" | "Paper11x17" | "Note" | "Envelope9" | "Envelope10" | "Envelope11" | "Envelope12" | "Envelope14" | "Csheet" | "Dsheet" | "Esheet" | "EnvelopeDL" | "EnvelopeC5" | "EnvelopeC3" | "EnvelopeC4" | "EnvelopeC6" | "EnvelopeC65" | "EnvelopeB4" | "EnvelopeB5" | "EnvelopeB6" | "EnvelopeItaly" | "EnvelopeMonarch" | "EnvelopePersonal" | "FanfoldUS" | "FanfoldStdGerman" | "FanfoldLegalGerman";

Property Value

Excel.PaperType | "Letter" | "LetterSmall" | "Tabloid" | "Ledger" | "Legal" | "Statement" | "Executive" | "A3" | "A4" | "A4Small" | "A5" | "B4" | "B5" | "Folio" | "Quatro" | "Paper10x14" | "Paper11x17" | "Note" | "Envelope9" | "Envelope10" | "Envelope11" | "Envelope12" | "Envelope14" | "Csheet" | "Dsheet" | "Esheet" | "EnvelopeDL" | "EnvelopeC5" | "EnvelopeC3" | "EnvelopeC4" | "EnvelopeC6" | "EnvelopeC65" | "EnvelopeB4" | "EnvelopeB5" | "EnvelopeB6" | "EnvelopeItaly" | "EnvelopeMonarch" | "EnvelopePersonal" | "FanfoldUS" | "FanfoldStdGerman" | "FanfoldLegalGerman"

printComments

Gets or sets whether the worksheet's comments should be displayed when printing.

[ API set: ExcelApi 1.9 ]

printComments: Excel.PrintComments | "NoComments" | "EndSheet" | "InPlace";

Property Value

Excel.PrintComments | "NoComments" | "EndSheet" | "InPlace"

printErrors

Gets or sets the worksheet's print errors option.

[ API set: ExcelApi 1.9 ]

printErrors: Excel.PrintErrorType | "AsDisplayed" | "Blank" | "Dash" | "NotAvailable";

Property Value

Excel.PrintErrorType | "AsDisplayed" | "Blank" | "Dash" | "NotAvailable"

printGridlines

Gets or sets the worksheet's print gridlines flag. This flag determines whether gridlines will be printed or not.

[ API set: ExcelApi 1.9 ]

printGridlines: boolean;

Property Value

boolean

printHeadings

Gets or sets the worksheet's print headings flag. This flag determines whether headings will be printed or not.

[ API set: ExcelApi 1.9 ]

printHeadings: boolean;

Property Value

boolean

printOrder

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

[ API set: ExcelApi 1.9 ]

printOrder: Excel.PrintOrder | "DownThenOver" | "OverThenDown";

Property Value

Excel.PrintOrder | "DownThenOver" | "OverThenDown"

rightMargin

Gets or sets the worksheet's right margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

rightMargin: number;

Property Value

number

topMargin

Gets or sets the worksheet's top margin, in points, for use when printing.

[ API set: ExcelApi 1.9 ]

topMargin: number;

Property Value

number

zoom

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

[ API set: ExcelApi 1.9 ]

zoom: Excel.PageLayoutZoomOptions;

Property Value

Examples

await Excel.run(async (context) => {
    const farmSheet = context.workbook.worksheets.getItem("Print");
    farmSheet.pageLayout.zoom = { scale: 200 };
    await context.sync();
});

Method Details

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, an ItemNotFound error will be thrown.

[ API set: ExcelApi 1.9 ]

getPrintArea(): Excel.RangeAreas;

Returns

getPrintAreaOrNullObject()

Gets the RangeAreas object, comprising one or more rectangular ranges, that represents the print area for the worksheet. If there is no print area, a null object will be returned.

[ API set: ExcelApi 1.9 ]

getPrintAreaOrNullObject(): Excel.RangeAreas;

Returns

getPrintTitleColumns()

Gets the range object representing the title columns.

[ API set: ExcelApi 1.9 ]

getPrintTitleColumns(): Excel.Range;

Returns

getPrintTitleColumnsOrNullObject()

Gets the range object representing the title columns. If not set, this will return a null object.

[ API set: ExcelApi 1.9 ]

getPrintTitleColumnsOrNullObject(): Excel.Range;

Returns

getPrintTitleRows()

Gets the range object representing the title rows.

[ API set: ExcelApi 1.9 ]

getPrintTitleRows(): Excel.Range;

Returns

getPrintTitleRowsOrNullObject()

Gets the range object representing the title rows. If not set, this will return a null object.

[ API set: ExcelApi 1.9 ]

getPrintTitleRowsOrNullObject(): Excel.Range;

Returns

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(option?: Excel.Interfaces.PageLayoutLoadOptions): Excel.PageLayout;

Parameters

Returns

Remarks

In addition to this signature, this method has the following signatures:

load(option?: string | string[]): Excel.PageLayout - Where option is a comma-delimited string or an array of strings that specify the properties to load.

load(option?: { select?: string; expand?: string; }): Excel.PageLayout - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Excel.PageLayout - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Excel.PageLayout;

Parameters

propertyNames
string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: { select?: string; expand?: string; }): Excel.PageLayout;

Parameters

propertyNamesAndPaths
{ select?: string; expand?: string; }

Where propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.PageLayoutUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

properties
Interfaces.PageLayoutUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options
OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

Remarks

This method has the following additional signature:

set(properties: Excel.PageLayout): void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Excel.PageLayout): void;

Parameters

properties
Excel.PageLayout

Returns

void

setPrintArea(printArea)

Sets the worksheet's print area.

[ API set: ExcelApi 1.9 ]

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

Parameters

printArea
Range | RangeAreas | string

The range, or RangeAreas of the content to print.

Returns

void

Examples

await Excel.run(async (context) => {
    const farmSheet = context.workbook.worksheets.getItem("Print");
    farmSheet.pageLayout.setPrintArea("A1:D41");
    await context.sync();
});

setPrintMargins(unit, marginOptions)

Sets the worksheet's page margins with units.

[ API set: ExcelApi 1.9 ]

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

Parameters

unit
Excel.PrintMarginUnit

Measurement unit for the margins provided.

marginOptions
Excel.PageLayoutMarginOptions

Margin values to set, margins not provided will remain unchanged.

Returns

void

setPrintMargins(unitString, marginOptions)

Sets the worksheet's page margins with units.

[ API set: ExcelApi 1.9 ]

setPrintMargins(unitString: "Points" | "Inches" | "Centimeters", marginOptions: Excel.PageLayoutMarginOptions): void;

Parameters

unitString
"Points" | "Inches" | "Centimeters"

Measurement unit for the margins provided.

marginOptions
Excel.PageLayoutMarginOptions

Margin values to set, margins not provided will remain unchanged.

Returns

void

setPrintTitleColumns(printTitleColumns)

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

[ API set: ExcelApi 1.9 ]

setPrintTitleColumns(printTitleColumns: Range | string): void;

Parameters

printTitleColumns
Range | string

The columns to be repeated to the left of each page, 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.

[ API set: ExcelApi 1.9 ]

setPrintTitleRows(printTitleRows: Range | string): void;

Parameters

printTitleRows
Range | string

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

Returns

void

Examples

await Excel.run(async (context) => {
    const farmSheet = context.workbook.worksheets.getItem("Print");
    farmSheet.pageLayout.setPrintTitleRows("$1:$1");
    await context.sync();
});

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.PageLayout object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.PageLayoutData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.PageLayoutData;

Returns