Excel.WorksheetProtection class

Represents the protection of a worksheet object.

Extends

Remarks

[ API set: ExcelApi 1.2 ]

Properties

allowEditRanges

Specifies the AllowEditRangeCollection object found in this worksheet. This is a collection of AllowEditRange objects, which work with worksheet protection properties. When worksheet protection is enabled, an AllowEditRange object can be used to allow editing of a specific range, while maintaining protection on the rest of the worksheet.

canPauseProtection

Specifies if protection can be paused for this worksheet.

context

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

isPasswordProtected

Specifies if the sheet is password protected.

isPaused

Specifies if worksheet protection is paused.

options

Specifies the protection options for the worksheet.

protected

Specifies if the worksheet is protected.

savedOptions

Specifies the protection options saved in the worksheet. This will return the same WorksheetProtectionOptions object regardless of the worksheet protection state.

Methods

checkPassword(password)

Specifies if the password can be used to unlock worksheet protection. This method doesn't change the worksheet protection state. If a password is entered but no password is required to unlock worksheet protection, this method will return false.

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.

pauseProtection(password)

Pauses worksheet protection for the given worksheet object for the user in the current session. This method does nothing if worksheet protection isn't enabled or is already paused. If the password is incorrect, then this method throws an InvalidArgument error and fails to pause protection. This method does not change the protection state if worksheet protection is not enabled or already paused.

protect(options, password)

Protects a worksheet. Fails if the worksheet has already been protected.

resumeProtection()

Resumes worksheet protection for the given worksheet object for the user in a given session. Worksheet protection must be paused for this method to work. If worksheet protection is not paused, then this method will not change the protection state of the worksheet.

setPassword(password)

Changes the password associated with the WorksheetProtection object. Setting the password as an empty string ("") or as null will remove password protection from the WorksheetProtection object. Worksheet protection must be enabled and paused for this method to work properly. If worksheet protection is disabled, this method throws an InvalidOperation error and fails to change the password. If worksheet protection is enabled and not paused, this method throws an AccessDenied error and fails to change the password.

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.WorksheetProtection object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.WorksheetProtectionData) that contains shallow copies of any loaded child properties from the original object.

unprotect(password)

Unprotects a worksheet.

updateOptions(options)

Change the worksheet protection options associated with the WorksheetProtection object. Worksheet protection must be disabled or paused for this method to work properly. If worksheet protection is enabled and not paused, this method throws an AccessDenied error and fails to change the worksheet protection options.

Property Details

allowEditRanges

Specifies the AllowEditRangeCollection object found in this worksheet. This is a collection of AllowEditRange objects, which work with worksheet protection properties. When worksheet protection is enabled, an AllowEditRange object can be used to allow editing of a specific range, while maintaining protection on the rest of the worksheet.

readonly allowEditRanges: Excel.AllowEditRangeCollection;

Property Value

Remarks

[ API set: ExcelApiOnline 1.1 ]

canPauseProtection

Specifies if protection can be paused for this worksheet.

readonly canPauseProtection: boolean;

Property Value

boolean

Remarks

[ API set: ExcelApiOnline 1.1 ]

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

isPasswordProtected

Specifies if the sheet is password protected.

readonly isPasswordProtected: boolean;

Property Value

boolean

Remarks

[ API set: ExcelApiOnline 1.1 ]

isPaused

Specifies if worksheet protection is paused.

readonly isPaused: boolean;

Property Value

boolean

Remarks

[ API set: ExcelApiOnline 1.1 ]

options

Specifies the protection options for the worksheet.

readonly options: Excel.WorksheetProtectionOptions;

Property Value

Remarks

[ API set: ExcelApi 1.2 ]

protected

Specifies if the worksheet is protected.

readonly protected: boolean;

Property Value

boolean

Remarks

[ API set: ExcelApi 1.2 ]

savedOptions

Specifies the protection options saved in the worksheet. This will return the same WorksheetProtectionOptions object regardless of the worksheet protection state.

readonly savedOptions: Excel.WorksheetProtectionOptions;

Property Value

Remarks

[ API set: ExcelApiOnline 1.1 ]

Method Details

checkPassword(password)

Specifies if the password can be used to unlock worksheet protection. This method doesn't change the worksheet protection state. If a password is entered but no password is required to unlock worksheet protection, this method will return false.

checkPassword(password?: string): OfficeExtension.ClientResult<boolean>;

Parameters

password

string

The password to check against the protected worksheet.

Returns

Returns true if the password can be used to unlock worksheet protection. Otherwise, returns false.

Remarks

[ API set: ExcelApiOnline 1.1 ]

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.WorksheetProtectionLoadOptions): Excel.WorksheetProtection;

Parameters

options
Excel.Interfaces.WorksheetProtectionLoadOptions

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

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

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

pauseProtection(password)

Pauses worksheet protection for the given worksheet object for the user in the current session. This method does nothing if worksheet protection isn't enabled or is already paused. If the password is incorrect, then this method throws an InvalidArgument error and fails to pause protection. This method does not change the protection state if worksheet protection is not enabled or already paused.

pauseProtection(password?: string): void;

Parameters

password

string

The password associated with the protected worksheet.

Returns

void

Remarks

[ API set: ExcelApiOnline 1.1 ]

protect(options, password)

Protects a worksheet. Fails if the worksheet has already been protected.

protect(options?: Excel.WorksheetProtectionOptions, password?: string): void;

Parameters

options
Excel.WorksheetProtectionOptions

Optional. Sheet protection options.

password

string

Optional. Sheet protection password.

Returns

void

Remarks

[ API set: ExcelApi 1.2 for options; 1.7 for password ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/data-protection.yaml

let password = await passwordHandler();
passwordHelper(password);
await Excel.run(async (context) => {
    let activeSheet = context.workbook.worksheets.getActiveWorksheet();
    activeSheet.load("protection/protected");

    await context.sync();

    if (!activeSheet.protection.protected) {
        activeSheet.protection.protect(null, password);
    }
});

resumeProtection()

Resumes worksheet protection for the given worksheet object for the user in a given session. Worksheet protection must be paused for this method to work. If worksheet protection is not paused, then this method will not change the protection state of the worksheet.

resumeProtection(): void;

Returns

void

Remarks

[ API set: ExcelApiOnline 1.1 ]

setPassword(password)

Changes the password associated with the WorksheetProtection object. Setting the password as an empty string ("") or as null will remove password protection from the WorksheetProtection object. Worksheet protection must be enabled and paused for this method to work properly. If worksheet protection is disabled, this method throws an InvalidOperation error and fails to change the password. If worksheet protection is enabled and not paused, this method throws an AccessDenied error and fails to change the password.

setPassword(password?: string): void;

Parameters

password

string

The password associated with the WorksheetProtection object.

Returns

void

Remarks

[ API set: ExcelApiOnline 1.1 ]

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.WorksheetProtection object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.WorksheetProtectionData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.WorksheetProtectionData;

Returns

unprotect(password)

Unprotects a worksheet.

unprotect(password?: string): void;

Parameters

password

string

Sheet protection password.

Returns

void

Remarks

[ API set: ExcelApi 1.7 for password ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/data-protection.yaml

let password = await passwordHandler();
passwordHelper(password);
await Excel.run(async (context) => {
    let activeSheet = context.workbook.worksheets.getActiveWorksheet();
    activeSheet.protection.unprotect(password);
});

updateOptions(options)

Change the worksheet protection options associated with the WorksheetProtection object. Worksheet protection must be disabled or paused for this method to work properly. If worksheet protection is enabled and not paused, this method throws an AccessDenied error and fails to change the worksheet protection options.

updateOptions(options: Excel.WorksheetProtectionOptions): void;

Parameters

options
Excel.WorksheetProtectionOptions

The options interface associated with the WorksheetProtection object.

Returns

void

Remarks

[ API set: ExcelApiOnline 1.1 ]