Excel.WorksheetProtection class
Represents the protection of a worksheet object.
- Extends
Remarks
Properties
| allow |
Specifies the |
| can |
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. |
| is |
Specifies if the sheet is password protected. |
| is |
Specifies if worksheet protection is paused. |
| options | Specifies the protection options for the worksheet. |
| protected | Specifies if the worksheet is protected. |
| saved |
Specifies the protection options saved in the worksheet. This will return the same |
Methods
| check |
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 |
| 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 |
| pause |
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 |
| protect(options, password) | Protects a worksheet. Fails if the worksheet has already been protected. |
| resume |
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. |
| set |
Changes the password associated with the |
| toJSON() | Overrides the JavaScript |
| unprotect(password) | Unprotects a worksheet. |
| update |
Change the worksheet protection options associated with the |
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
canPauseProtection
Specifies if protection can be paused for this worksheet.
readonly canPauseProtection: boolean;Property Value
boolean
Remarks
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
isPaused
Specifies if worksheet protection is paused.
readonly isPaused: boolean;Property Value
boolean
Remarks
options
Specifies the protection options for the worksheet.
readonly options: Excel.WorksheetProtectionOptions;Property Value
Remarks
protected
Specifies if the worksheet is protected.
readonly protected: boolean;Property Value
boolean
Remarks
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
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
OfficeExtension.ClientResult<boolean>
Returns true if the password can be used to unlock worksheet protection. Otherwise, returns false.
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.WorksheetProtectionLoadOptions): Excel.WorksheetProtection;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.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
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
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
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
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