Excel.PageBreakCollection class

Package:: excel

Extends: OfficeExtension.ClientObject

Remarks

Used by

Excel.Worksheet: horizontalPageBreaks, verticalPageBreaks

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/manage-page-breaks.yaml

// Load and inspect the page breaks in both worksheet collections.
await Excel.run(async (context) => {
    const sheet: Excel.Worksheet = context.workbook.worksheets.getItem("Sample");
    const horizontalBreaks: Excel.PageBreakCollection = sheet.horizontalPageBreaks;
    const verticalBreaks: Excel.PageBreakCollection = sheet.verticalPageBreaks;
    horizontalBreaks.load("items/rowIndex, items/columnIndex");
    verticalBreaks.load("items/rowIndex, items/columnIndex");

    await context.sync();
    console.log(`Horizontal page breaks: ${horizontalBreaks.items.length}`);
    horizontalBreaks.items.forEach((pageBreak: Excel.PageBreak) => {
        console.log("Horizontal break (zero-based indexes):", {
            rowIndex: pageBreak.rowIndex,
            columnIndex: pageBreak.columnIndex
        });
    });
    console.log(`Vertical page breaks: ${verticalBreaks.items.length}`);
    verticalBreaks.items.forEach((pageBreak: Excel.PageBreak) => {
        console.log("Vertical break (zero-based indexes):", {
            rowIndex: pageBreak.rowIndex,
            columnIndex: pageBreak.columnIndex
        });
    });
});

Properties

context	The request context associated with the object. This connects the add-in's process to the Office host application's process.
items	Gets the loaded child items in this collection.

Methods

add(pageBreakRange)	Adds a page break before the top-left cell of the range specified.
getCount()	Gets the number of page breaks in the collection.
getItem(index)	Gets a page break object via the index.
load(options)	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.
removePageBreaks()	Resets all manual page breaks in the collection.
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's passed to it.) Whereas the original `Excel.PageBreakCollection` object is an API object, the `toJSON` method returns a plain JavaScript object (typed as `Excel.Interfaces.PageBreakCollectionData`) that contains an "items" array with shallow copies of any loaded properties from the collection's items.

Property Details

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

Excel.RequestContext

items

Gets the loaded child items in this collection.

readonly items: Excel.PageBreak[];

Property Value

Excel.PageBreak[]

Method Details

add(pageBreakRange)

Adds a page break before the top-left cell of the range specified.

add(pageBreakRange: Range | string): Excel.PageBreak;

Parameters

pageBreakRange: Excel.Range | string

The range immediately after the page break to be added.

Returns

Excel.PageBreak

Remarks

API set: ExcelApi 1.9

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-page-layout.yaml

// Add a horizontal page break before the next group of farm sales.
await Excel.run(async (context) => {
    const farmSheet: Excel.Worksheet = context.workbook.worksheets.getItem("Print");
    const horizontalBreaks: Excel.PageBreakCollection = farmSheet.horizontalPageBreaks;
    horizontalBreaks.add("A21:E21");
    await context.sync();
    console.log("Added a horizontal page break before row 21.");
});

getCount()

Gets the number of page breaks in the collection.

getCount(): OfficeExtension.ClientResult<number>;

Returns

OfficeExtension.ClientResult<number>

Remarks

API set: ExcelApi 1.9

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/manage-page-breaks.yaml

// Count page breaks without loading the collection's items.
await Excel.run(async (context) => {
    const sheet: Excel.Worksheet = context.workbook.worksheets.getItem("Sample");
    const horizontalBreaks: Excel.PageBreakCollection = sheet.horizontalPageBreaks;
    const verticalBreaks: Excel.PageBreakCollection = sheet.verticalPageBreaks;
    const horizontalCount: OfficeExtension.ClientResult<number> = horizontalBreaks.getCount();
    const verticalCount: OfficeExtension.ClientResult<number> = verticalBreaks.getCount();

    await context.sync();
    console.log(`Horizontal page breaks: ${horizontalCount.value}`);
    console.log(`Vertical page breaks: ${verticalCount.value}`);
});

getItem(index)

Gets a page break object via the index.

getItem(index: number): Excel.PageBreak;

Parameters

index: number

Index of the page break.

Returns

Excel.PageBreak

Remarks

API set: ExcelApi 1.9

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/manage-page-breaks.yaml

// Inspect the first horizontal break and locate the cell immediately after it.
await Excel.run(async (context) => {
    const sheet: Excel.Worksheet = context.workbook.worksheets.getItem("Sample");
    const horizontalBreaks: Excel.PageBreakCollection = sheet.horizontalPageBreaks;
    const horizontalCount: OfficeExtension.ClientResult<number> = horizontalBreaks.getCount();
    await context.sync();

    if (horizontalCount.value === 0) {
        console.warn("No horizontal page breaks. Choose Add page breaks first.");
        return;
    }

    const firstBreak: Excel.PageBreak = horizontalBreaks.getItem(0);
    const cellAfterBreak: Excel.Range = firstBreak.getCellAfterBreak();
    firstBreak.load("rowIndex, columnIndex");
    cellAfterBreak.load("address");

    await context.sync();
    console.log("First horizontal page break (zero-based indexes):", {
        rowIndex: firstBreak.rowIndex,
        columnIndex: firstBreak.columnIndex,
        cellAfterBreak: cellAfterBreak.address
    });
});

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.PageBreakCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.PageBreakCollection;

Parameters

options: Excel.Interfaces.PageBreakCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

Provides options for which properties of the object to load.

Returns

Excel.PageBreakCollection

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.PageBreakCollection;

Parameters

propertyNames: string | string[]

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

Returns

Excel.PageBreakCollection

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?: OfficeExtension.LoadOption): Excel.PageBreakCollection;

Parameters

propertyNamesAndPaths: OfficeExtension.LoadOption

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

Excel.PageBreakCollection

removePageBreaks()

Resets all manual page breaks in the collection.

removePageBreaks(): void;

Returns

void

Remarks

API set: ExcelApi 1.9

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/manage-page-breaks.yaml

// Reset all manual page breaks in both worksheet collections.
await Excel.run(async (context) => {
    const sheet: Excel.Worksheet = context.workbook.worksheets.getItem("Sample");
    const horizontalBreaks: Excel.PageBreakCollection = sheet.horizontalPageBreaks;
    const verticalBreaks: Excel.PageBreakCollection = sheet.verticalPageBreaks;
    horizontalBreaks.removePageBreaks();
    verticalBreaks.removePageBreaks();

    await context.sync();
    console.log("Removed all manual page breaks. Choose Count page breaks to verify the collections.");
});

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's passed to it.) Whereas the original Excel.PageBreakCollection object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.PageBreakCollectionData) that contains an "items" array with shallow copies of any loaded properties from the collection's items.

toJSON(): Excel.Interfaces.PageBreakCollectionData;

Returns

Excel.Interfaces.PageBreakCollectionData

Feedback

Was this page helpful?