Excel.PageLayout class
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.
- Extends
Remarks
Properties
| black |
The worksheet's black and white print option. |
| bottom |
The worksheet's bottom page margin to use for printing in points. |
| center |
The worksheet's center horizontally flag. This flag determines whether the worksheet will be centered horizontally when it's printed. |
| center |
The worksheet's center vertically flag. This flag determines whether the worksheet will be centered vertically when it's printed. |
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| draft |
The worksheet's draft mode option. If |
| first |
The worksheet's first page number to print. A |
| footer |
The worksheet's footer margin, in points, for use when printing. |
| header |
The worksheet's header margin, in points, for use when printing. |
| headers |
Header and footer configuration for the worksheet. |
| left |
The worksheet's left margin, in points, for use when printing. |
| orientation | The worksheet's orientation of the page. |
| paper |
The worksheet's paper size of the page. |
| print |
Specifies if the worksheet's comments should be displayed when printing. |
| print |
The worksheet's print errors option. |
| print |
Specifies if the worksheet's gridlines will be printed. |
| print |
Specifies if the worksheet's headings will be printed. |
| print |
The worksheet's page print order option. This specifies the order to use for processing the page number printed. |
| right |
The worksheet's right margin, in points, for use when printing. |
| top |
The worksheet's top margin, in points, for use when printing. |
| zoom | The worksheet's print zoom options. The |
Methods
| get |
Gets the |
| get |
Gets the |
| get |
Gets the range object representing the title columns. |
| get |
Gets the range object representing the title columns. If not set, then this method returns an object with its |
| get |
Gets the range object representing the title rows. |
| get |
Gets the range object representing the title rows. If not set, then this method returns an object with its |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| 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. |
| set |
Sets the worksheet's print area. |
| set |
Sets the worksheet's page margins with units. |
| set |
Sets the worksheet's page margins with units. |
| set |
Sets the columns that contain the cells to be repeated at the left of each page of the worksheet for printing. |
| set |
Sets the rows that contain the cells to be repeated at the top of each page of the worksheet for printing. |
| toJSON() | Overrides the JavaScript |
Property Details
blackAndWhite
The worksheet's black and white print option.
blackAndWhite: boolean;Property Value
boolean
Remarks
bottomMargin
The worksheet's bottom page margin to use for printing in points.
bottomMargin: number;Property Value
number
Remarks
centerHorizontally
The worksheet's center horizontally flag. This flag determines whether the worksheet will be centered horizontally when it's printed.
centerHorizontally: boolean;Property Value
boolean
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-page-layout.yaml
await Excel.run(async (context) => {
const farmSheet = context.workbook.worksheets.getItem("Print");
farmSheet.pageLayout.centerHorizontally = true;
farmSheet.pageLayout.centerVertically = true;
await context.sync();
});
centerVertically
The worksheet's center vertically flag. This flag determines whether the worksheet will be centered vertically when it's printed.
centerVertically: boolean;Property Value
boolean
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-page-layout.yaml
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
The worksheet's draft mode option. If true, the sheet will be printed without graphics.
draftMode: boolean;Property Value
boolean
Remarks
firstPageNumber
The worksheet's first page number to print. A null value represents "auto" page numbering.
firstPageNumber: number | "";Property Value
number | ""
Remarks
footerMargin
The worksheet's footer margin, in points, for use when printing.
footerMargin: number;Property Value
number
Remarks
headerMargin
The worksheet's header margin, in points, for use when printing.
headerMargin: number;Property Value
number
Remarks
headersFooters
Header and footer configuration for the worksheet.
readonly headersFooters: Excel.HeaderFooterGroup;Property Value
Remarks
leftMargin
The worksheet's left margin, in points, for use when printing.
leftMargin: number;Property Value
number
Remarks
orientation
The worksheet's orientation of the page.
orientation: Excel.PageOrientation | "Portrait" | "Landscape";Property Value
Excel.PageOrientation | "Portrait" | "Landscape"
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-page-layout.yaml
await Excel.run(async (context) => {
const farmSheet = context.workbook.worksheets.getItem("Print");
farmSheet.pageLayout.orientation = Excel.PageOrientation.landscape;
await context.sync();
});
paperSize
The worksheet's paper size of the page.
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"
Remarks
printComments
Specifies if the worksheet's comments should be displayed when printing.
printComments: Excel.PrintComments | "NoComments" | "EndSheet" | "InPlace";Property Value
Excel.PrintComments | "NoComments" | "EndSheet" | "InPlace"
Remarks
printErrors
The worksheet's print errors option.
printErrors: Excel.PrintErrorType | "AsDisplayed" | "Blank" | "Dash" | "NotAvailable";Property Value
Excel.PrintErrorType | "AsDisplayed" | "Blank" | "Dash" | "NotAvailable"
Remarks
printGridlines
Specifies if the worksheet's gridlines will be printed.
printGridlines: boolean;Property Value
boolean
Remarks
printHeadings
Specifies if the worksheet's headings will be printed.
printHeadings: boolean;Property Value
boolean
Remarks
printOrder
The worksheet's page print order option. This specifies the order to use for processing the page number printed.
printOrder: Excel.PrintOrder | "DownThenOver" | "OverThenDown";Property Value
Excel.PrintOrder | "DownThenOver" | "OverThenDown"
Remarks
rightMargin
The worksheet's right margin, in points, for use when printing.
rightMargin: number;Property Value
number
Remarks
topMargin
The worksheet's top margin, in points, for use when printing.
topMargin: number;Property Value
number
Remarks
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 = ...).
zoom: Excel.PageLayoutZoomOptions;Property Value
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-page-layout.yaml
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.
getPrintArea(): Excel.RangeAreas;Returns
Remarks
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, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getPrintAreaOrNullObject(): Excel.RangeAreas;Returns
Remarks
getPrintTitleColumns()
Gets the range object representing the title columns.
getPrintTitleColumns(): Excel.Range;Returns
Remarks
getPrintTitleColumnsOrNullObject()
Gets the range object representing the title columns. If not set, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getPrintTitleColumnsOrNullObject(): Excel.Range;Returns
Remarks
getPrintTitleRows()
Gets the range object representing the title rows.
getPrintTitleRows(): Excel.Range;Returns
Remarks
getPrintTitleRowsOrNullObject()
Gets the range object representing the title rows. If not set, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getPrintTitleRowsOrNullObject(): Excel.Range;Returns
Remarks
load(options)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(options?: Excel.Interfaces.PageLayoutLoadOptions): Excel.PageLayout;Parameters
Provides options for which properties of the object to load.
Returns
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; }
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
- Excel.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
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.
setPrintArea(printArea: Range | RangeAreas | string): void;Parameters
- printArea
-
Excel.Range | Excel.RangeAreas | string
The range or ranges of the content to print.
Returns
void
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-page-layout.yaml
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.
setPrintMargins(unit: Excel.PrintMarginUnit, marginOptions: Excel.PageLayoutMarginOptions): void;Parameters
Measurement unit for the margins provided.
- marginOptions
- Excel.PageLayoutMarginOptions
Margin values to set. Margins not provided remain unchanged.
Returns
void
Remarks
setPrintMargins(unitString, marginOptions)
Sets the worksheet's page margins with units.
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 remain unchanged.
Returns
void
Remarks
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
-
Excel.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
Remarks
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
-
Excel.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
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-page-layout.yaml
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
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for