Excel.WorksheetProtection class

参考

包:: excel

表示工作表对象的保护。

Extends: OfficeExtension.ClientObject

注解

属性

allowEditRanges	指定 `AllowEditRangeCollection` 在此工作表中找到的对象。这是对象的集合 `AllowEditRange` ，这些对象使用工作表保护属性。启用工作表保护后， `AllowEditRange` 可以使用对象来允许编辑特定区域，同时对工作表的其余部分保持保护。
canPauseProtection	指定是否可以暂停此工作表的保护。
context	与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。
isPasswordProtected	指定工作表是否受密码保护。
isPaused	指定工作表保护是否暂停。
options	指定工作表的保护选项。
protected	指定工作表是否受保护。
savedOptions	指定工作表中保存的保护选项。无论工作表保护状态如何，都将返回相同的 `WorksheetProtectionOptions` 对象。

方法

checkPassword(password)	指定密码是否可用于解锁工作表保护。此方法不会更改工作表保护状态。如果输入了密码，但无需密码即可解锁工作表保护，则此方法将返回 false。
load(options)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNames)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
load(propertyNamesAndPaths)	将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 `context.sync()`。
pauseProtection(password)	暂停当前会话中用户的给定工作表对象的工作表保护。如果未启用工作表保护或已暂停，则此方法不执行任何操作。如果密码不正确，则此方法将引发错误 `InvalidArgument` ，无法暂停保护。如果未启用工作表保护或已暂停，则此方法不会更改保护状态。
protect(options, password)	保护 worksheet。如果工作表已受保护，则失败。
resumeProtection()	为给定会话中的用户恢复给定 worksheet 对象的工作表保护。必须暂停工作表保护才能使此方法正常工作。如果未暂停工作表保护，则此方法不会更改工作表的保护状态。
setPassword(password)	更改与 `WorksheetProtection` 对象关联的密码。将密码设置为空字符串 (“”) 或将 `null` 删除对象中的 `WorksheetProtection` 密码保护。必须启用和暂停工作表保护才能使此方法正常工作。如果禁用工作表保护，此方法将引发错误 `InvalidOperation` ，无法更改密码。如果启用了工作表保护但未暂停，此方法将 `AccessDenied` 引发错误，无法更改密码。
toJSON()	重写 JavaScript `toJSON()` 方法，以便在将 API 对象传递给 `JSON.stringify()`时提供更有用的输出。 `JSON.stringify` (，反过来，调用`toJSON`传递给它的对象的方法。) 虽然原始 Excel.WorksheetProtection 对象是 API 对象，但`toJSON`该方法返回一个纯 JavaScript 对象， (类型为 `Excel.Interfaces.WorksheetProtectionData`) ，该对象包含从原始对象加载的任何子属性的浅表副本。
unprotect(password)	解除对 worksheet 的保护。
updateOptions(options)	更改与对象关联的 `WorksheetProtection` 工作表保护选项。必须禁用或暂停工作表保护才能使此方法正常工作。如果工作表保护已启用且未暂停，此方法将引发错误 `AccessDenied` ，无法更改工作表保护选项。

属性详细信息

allowEditRanges

指定 AllowEditRangeCollection 在此工作表中找到的对象。这是对象的集合 AllowEditRange ，这些对象使用工作表保护属性。启用工作表保护后， AllowEditRange 可以使用对象来允许编辑特定区域，同时对工作表的其余部分保持保护。

readonly allowEditRanges: Excel.AllowEditRangeCollection;

属性值

Excel.AllowEditRangeCollection

注解

[ API 集：ExcelApiOnline 1.1 ]

canPauseProtection

指定是否可以暂停此工作表的保护。

readonly canPauseProtection: boolean;

属性值

boolean

注解

[ API 集：ExcelApiOnline 1.1 ]

context

与对象关联的请求上下文。这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

Excel.RequestContext

isPasswordProtected

指定工作表是否受密码保护。

readonly isPasswordProtected: boolean;

属性值

boolean

注解

[ API 集：ExcelApiOnline 1.1 ]

isPaused

指定工作表保护是否暂停。

readonly isPaused: boolean;

属性值

boolean

注解

[ API 集：ExcelApiOnline 1.1 ]

options

指定工作表的保护选项。

readonly options: Excel.WorksheetProtectionOptions;

属性值

Excel.WorksheetProtectionOptions

注解

[ API 集：ExcelApi 1.2 ]

protected

指定工作表是否受保护。

readonly protected: boolean;

属性值

boolean

注解

[ API 集：ExcelApi 1.2 ]

savedOptions

指定工作表中保存的保护选项。无论工作表保护状态如何，都将返回相同的 WorksheetProtectionOptions 对象。

readonly savedOptions: Excel.WorksheetProtectionOptions;

属性值

Excel.WorksheetProtectionOptions

注解

[ API 集：ExcelApiOnline 1.1 ]

方法详细信息

checkPassword(password)

指定密码是否可用于解锁工作表保护。此方法不会更改工作表保护状态。如果输入了密码，但无需密码即可解锁工作表保护，则此方法将返回 false。

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

参数

password: string

针对受保护的工作表检查的密码。

OfficeExtension.ClientResult<boolean>

true如果密码可用于解锁工作表保护，则返回。否则，返回 false。

注解

[ API 集：ExcelApiOnline 1.1 ]

load(options)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

load(options?: Excel.Interfaces.WorksheetProtectionLoadOptions): Excel.WorksheetProtection;

参数

options: Excel.Interfaces.WorksheetProtectionLoadOptions

提供要加载对象的属性的选项。

Excel.WorksheetProtection

load(propertyNames)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

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

参数

propertyNames: string | string[]

逗号分隔的字符串或指定要加载的属性的字符串数组。

Excel.WorksheetProtection

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。阅读属性前必须先调用 context.sync()。

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

参数

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

propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。

Excel.WorksheetProtection

pauseProtection(password)

暂停当前会话中用户的给定工作表对象的工作表保护。如果未启用工作表保护或已暂停，则此方法不执行任何操作。如果密码不正确，则此方法将引发错误 InvalidArgument ，无法暂停保护。如果未启用工作表保护或已暂停，则此方法不会更改保护状态。

pauseProtection(password?: string): void;

参数

password: string

与受保护的工作表关联的密码。

void

注解

[ API 集：ExcelApiOnline 1.1 ]

protect(options, password)

保护 worksheet。如果工作表已受保护，则失败。

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

参数

options: Excel.WorksheetProtectionOptions

可选。工作表保护选项。

password: string

可选。工作表保护密码。

void

注解

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

示例

// 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()

为给定会话中的用户恢复给定 worksheet 对象的工作表保护。必须暂停工作表保护才能使此方法正常工作。如果未暂停工作表保护，则此方法不会更改工作表的保护状态。

resumeProtection(): void;

void

注解

[ API 集：ExcelApiOnline 1.1 ]

setPassword(password)

更改与 WorksheetProtection 对象关联的密码。将密码设置为空字符串 (“”) 或将 null 删除对象中的 WorksheetProtection 密码保护。必须启用和暂停工作表保护才能使此方法正常工作。如果禁用工作表保护，此方法将引发错误 InvalidOperation ，无法更改密码。如果启用了工作表保护但未暂停，此方法将 AccessDenied 引发错误，无法更改密码。

setPassword(password?: string): void;

参数

password: string

与 WorksheetProtection 对象关联的密码。

void

注解

[ API 集：ExcelApiOnline 1.1 ]

toJSON()

重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来，调用toJSON传递给它的对象的方法。) 虽然原始 Excel.WorksheetProtection 对象是 API 对象，但toJSON该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.WorksheetProtectionData) ，该对象包含从原始对象加载的任何子属性的浅表副本。

toJSON(): Excel.Interfaces.WorksheetProtectionData;

Excel.Interfaces.WorksheetProtectionData

unprotect(password)

解除对 worksheet 的保护。

unprotect(password?: string): void;

参数

password: string

工作表保护密码。

void

注解

[ API set： ExcelApi 1.7 for password ]

示例

// 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)

更改与对象关联的 WorksheetProtection 工作表保护选项。必须禁用或暂停工作表保护才能使此方法正常工作。如果工作表保护已启用且未暂停，此方法将引发错误 AccessDenied ，无法更改工作表保护选项。

updateOptions(options: Excel.WorksheetProtectionOptions): void;

参数

options: Excel.WorksheetProtectionOptions

与对象关联的 WorksheetProtection 选项接口。

void

注解

[ API 集：ExcelApiOnline 1.1 ]

Excel.WorksheetProtection class

注解

属性

方法

属性详细信息

allowEditRanges

属性值

注解

canPauseProtection

属性值

注解

context

属性值

isPasswordProtected

属性值

注解

isPaused

属性值

注解

options

属性值

注解

protected

属性值

注解

savedOptions

属性值

注解

方法详细信息

checkPassword(password)

参数

返回

注解

load(options)

参数

返回

load(propertyNames)

参数

返回

load(propertyNamesAndPaths)

参数

返回

pauseProtection(password)

参数

返回

注解

protect(options, password)

参数

返回

注解

示例

resumeProtection()

返回

注解

setPassword(password)

参数

返回

注解

toJSON()

返回

unprotect(password)

参数

返回

注解

示例

updateOptions(options)

参数

返回

注解

反馈

其他资源