Office.Settings interface

包:

office

表示作为名称/值对存储在主机文档中的任务窗格或内容外接程序的自定义设置。

注解

应用程序：Excel、PowerPoint、Word

使用对象方法 Settings 创建的设置按加载项和文档保存。 即，这些设置仅供创建它们的外接程序使用，并且仅来自保存它们的文档。

设置的名称为字符串，而值可以为字符串、数字、布尔值、null、对象或数组。

Settings对象作为对象的一部分Document自动加载，并且在加载项激活时可通过调用该对象的设置属性来使用。

开发人员负责在添加或删除设置后调用 saveAsync 该方法，以将设置保存在文档中。

使用方

• Office.Document： 设置
• Office.SettingsChangedEventArgs： settings

方法

addHandlerAsync(eventType, handler, options, callback)	为 settingsChanged 事件添加事件处理程序。 重要提示： 当加载项使用任何 Excel 客户端运行时，加载项的代码可以注册事件的settingsChanged处理程序，但是仅当加载项包含以 Excel web 版 打开的电子表格，并且多个用户正在编辑电子表格 (共同创作) 时，才会触发该事件。 因此，实际上，只有在共同创作方案中的 Excel web 版中才支持该settingsChanged事件。
addHandlerAsync(eventType, handler, callback)	为 settingsChanged 事件添加事件处理程序。 重要提示： 当加载项使用任何 Excel 客户端运行时，加载项的代码可以注册事件的settingsChanged处理程序，但是仅当加载项包含以 Excel web 版 打开的电子表格，并且多个用户正在编辑电子表格 (共同创作) 时，才会触发该事件。 因此，实际上，只有在共同创作方案中的 Excel web 版中才支持该settingsChanged事件。
get(name)	检索指定设置。
refreshAsync(callback)	读取文档中保存的所有设置并刷新内容或任务窗格外接程序在内存中保留的这些设置的副本。
remove(name)	移除指定设置。 重要提示： 请注意，该 Settings.remove 方法仅影响 settings 属性包的内存中副本。 若要在文档中保留删除指定设置，在调用 Settings.remove 该方法之后的某个时间点和关闭加载项之前，您必须调用 Settings.saveAsync 该方法。
removeHandlerAsync(eventType, options, callback)	删除事件的 settingsChanged 事件处理程序。
removeHandlerAsync(eventType, callback)	删除事件的 settingsChanged 事件处理程序。
saveAsync(options, callback)	将设置属性包的内存副本保留到文档中。
saveAsync(callback)	将设置属性包的内存副本保留到文档中。
set(name, value)	设置或创建指定设置。 重要提示： 请注意，该 Settings.set 方法仅影响 settings 属性包的内存中副本。 要确保在下次打开文档时、在调用 Settings.set 该方法之后和关闭该加载项之前的某个时间点，加载项可以对设置进行添加或更改，您必须调用该 Settings.saveAsync 方法以将设置保留在文档中。

方法详细信息

addHandlerAsync(eventType, handler, options, callback)

为 settingsChanged 事件添加事件处理程序。

重要提示： 当加载项使用任何 Excel 客户端运行时，加载项的代码可以注册事件的settingsChanged处理程序，但是仅当加载项包含以 Excel web 版 打开的电子表格，并且多个用户正在编辑电子表格 (共同创作) 时，才会触发该事件。 因此，实际上，只有在共同创作方案中的 Excel web 版中才支持该settingsChanged事件。

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

参数

eventType

Office.EventType

指定要添加事件的类型。 必填。

handler

any

要添加的事件处理程序函数，其唯一参数的类型为 Office.SettingsChangedEventArgs。 必填。

options

Office.AsyncContextOptions

提供用于保留任何类型的上下文数据（不变）以供回调使用的选项。

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。

属性	用途
AsyncResult.value	总是返回 undefined ，因为添加事件处理程序时没有要检索的数据或对象。
AsyncResult.status	确定操作是成功还是失败。
AsyncResult.error	访问一个 Error 在操作失败时提供错误信息的对象。
AsyncResult.asyncContext	定义在对象中 AsyncResult 返回而不进行更改的任何类型的项目。

返回

void

注解

要求集： 不在集合中

只要每个事件处理程序函数的名称唯一，就可以为指定的 eventType 事件处理程序添加多个事件处理程序。

addHandlerAsync(eventType, handler, callback)

为 settingsChanged 事件添加事件处理程序。

重要提示： 当加载项使用任何 Excel 客户端运行时，加载项的代码可以注册事件的settingsChanged处理程序，但是仅当加载项包含以 Excel web 版 打开的电子表格，并且多个用户正在编辑电子表格 (共同创作) 时，才会触发该事件。 因此，实际上，只有在共同创作方案中的 Excel web 版中才支持该settingsChanged事件。

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): void;

参数

eventType

Office.EventType

指定要添加事件的类型。 必填。

handler

any

要添加的事件处理程序函数，其唯一参数的类型为 Office.SettingsChangedEventArgs。 必填。

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。

属性	用途
AsyncResult.value	总是返回 undefined ，因为添加事件处理程序时没有要检索的数据或对象。
AsyncResult.status	确定操作是成功还是失败。
AsyncResult.error	访问一个 Error 在操作失败时提供错误信息的对象。
AsyncResult.asyncContext	定义在对象中 AsyncResult 返回而不进行更改的任何类型的项目。

返回

void

注解

要求集： 不在集合中

只要每个事件处理程序函数的名称唯一，就可以为指定的 eventType 事件处理程序添加多个事件处理程序。

示例

function addSelectionChangedEventHandler() {
    Office.context.document.settings.addHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs: Office.SettingsChangedEventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

get(name)

检索指定设置。

get(name: string): any;

参数

name

string

返回

any

具有映射到 JSON 序列化值的属性名称的对象。

注解

要求集： 设置

示例

function displayMySetting() {
    write('Current value for mySetting: ' + Office.context.document.settings.get('mySetting'));
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

refreshAsync(callback)

读取文档中保存的所有设置并刷新内容或任务窗格外接程序在内存中保留的这些设置的副本。

refreshAsync(callback?: (result: AsyncResult<Office.Settings>) => void): void;

参数

callback

(result: Office.AsyncResult<Office.Settings>) => void

可选。 回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是具有已刷新值的 Office.Settings 对象。

返回

void

注解

要求集： 不在集合中

在 Excel、Word 和 PowerPoint 共同创作方案中，同一加载项的多个实例正在处理同一文档时，此方法非常有用。 因为每个加载项在用户打开文档时都对从文档加载的设置的内存内副本运行，所以每个用户使用的设置值可能会不同步。每当加载项的实例调用该 Settings.saveAsync 方法来将该用户的所有设置保存到文档时，就会发生这种情况。 refreshAsync从加载项事件的settingsChanged事件处理程序调用该方法将刷新所有用户的设置值。

在传递给该方法的 refreshAsync 回调函数中，您可以使用对象的 AsyncResult 属性返回以下信息。

属性	用途
AsyncResult.value	使用刷新的值访问 Settings 对象。
AsyncResult.status	确定操作是成功还是失败。
AsyncResult.error	访问一个 Error 在操作失败时提供错误信息的对象。
AsyncResult.asyncContext	定义在对象中 AsyncResult 返回而不进行更改的任何类型的项目。

示例

function refreshSettings() {
    Office.context.document.settings.refreshAsync(function (asyncResult) {
        write('Settings refreshed with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

remove(name)

移除指定设置。

重要提示： 请注意，该 Settings.remove 方法仅影响 settings 属性包的内存中副本。 若要在文档中保留删除指定设置，在调用 Settings.remove 该方法之后的某个时间点和关闭加载项之前，您必须调用 Settings.saveAsync 该方法。

remove(name: string): void;

参数

name

string

返回

void

注解

要求集： 设置

null 是设置的有效值。 因此，分配给 null 设置不会将其从设置属性包中删除。

示例

function removeMySetting() {
    Office.context.document.settings.remove('mySetting');
}

removeHandlerAsync(eventType, options, callback)

删除事件的 settingsChanged 事件处理程序。

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

参数

eventType

Office.EventType

指定要移除事件的类型。 必填。

options

Office.RemoveHandlerOptions

提供用于确定删除哪些事件处理程序或处理程序的选项。

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。

返回

void

注解

要求集： 不在集合中

如果在调用 removeHandlerAsync 方法时省略了可选处理程序参数，则将删除指定的 eventType 所有事件处理程序。

当您传递给回调参数的函数执行时，它会收到一个 AsyncResult 对象，您可以从回调函数的唯一参数访问该对象。

在传递给该方法的 removeHandlerAsync 回调函数中，您可以使用对象的 AsyncResult 属性返回以下信息。

属性	用途
AsyncResult.value	始终返回 undefined ，因为设置格式时没有要检索的数据或对象。
AsyncResult.status	确定操作是成功还是失败。
AsyncResult.error	访问一个 Error 在操作失败时提供错误信息的对象。
AsyncResult.asyncContext	定义在对象中 AsyncResult 返回而不进行更改的任何类型的项目。

removeHandlerAsync(eventType, callback)

删除事件的 settingsChanged 事件处理程序。

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

参数

eventType

Office.EventType

指定要移除事件的类型。 必填。

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。

返回

void

注解

要求集： 不在集合中

如果在调用 removeHandlerAsync 方法时省略了可选处理程序参数，则将删除指定的 eventType 所有事件处理程序。

当您传递给回调参数的函数执行时，它会收到一个 AsyncResult 对象，您可以从回调函数的唯一参数访问该对象。

在传递给该方法的 removeHandlerAsync 回调函数中，您可以使用对象的 AsyncResult 属性返回以下信息。

属性	用途
AsyncResult.value	始终返回 undefined ，因为设置格式时没有要检索的数据或对象。
AsyncResult.status	确定操作是成功还是失败。
AsyncResult.error	访问一个 Error 在操作失败时提供错误信息的对象。
AsyncResult.asyncContext	定义在对象中 AsyncResult 返回而不进行更改的任何类型的项目。

示例

function removeSettingsChangedEventHandler() {
    Office.context.document.settings.removeHandlerAsync(Office.EventType.SettingsChanged);
}

saveAsync(options, callback)

将设置属性包的内存副本保留到文档中。

saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;

参数

options

Office.SaveSettingsOptions

提供保存设置的选项。

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。

返回

void

注解

要求集： 设置

外接程序初始化时会加载之前保存的所有设置，因此，在会话的生存期内，只能通过 set 和 get 方法使用设置属性包的内存副本。 如果希望保留这些设置以便可在下次使用外接程序时使用，请使用 saveAsync 方法。

注意：该 saveAsync 方法会将内存中设置属性包保存到文档文件中。 但是，仅当用户 (或“自动恢复”设置) 将文档保存到文件系统时，才保存对文档文件本身的更改。 仅当 refreshAsync 同一加载项的其他实例可能更改设置，并且这些更改应适用于所有实例时，该方法才在共同创作方案中有用。

属性	用途
AsyncResult.value	始终返回 undefined ，因为没有要检索的对象或数据。
AsyncResult.status	确定操作是成功还是失败。
AsyncResult.error	访问一个 Error 在操作失败时提供错误信息的对象。
AsyncResult.asyncContext	定义在对象中 AsyncResult 返回而不进行更改的任何类型的项目。

saveAsync(callback)

将设置属性包的内存副本保留到文档中。

saveAsync(callback?: (result: AsyncResult<void>) => void): void;

参数

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。

返回

void

注解

要求集： 设置

外接程序初始化时会加载之前保存的所有设置，因此，在会话的生存期内，只能通过 set 和 get 方法使用设置属性包的内存副本。 如果希望保留这些设置以便可在下次使用外接程序时使用，请使用 saveAsync 方法。

注意：该 saveAsync 方法会将内存中设置属性包保存到文档文件中。 但是，仅当用户 (或“自动恢复”设置) 将文档保存到文件系统时，才保存对文档文件本身的更改。 仅当 refreshAsync 同一加载项的其他实例可能更改设置，并且这些更改应适用于所有实例时，该方法才在共同创作方案中有用。

属性	用途
AsyncResult.value	始终返回 undefined ，因为没有要检索的对象或数据。
AsyncResult.status	确定操作是成功还是失败。
AsyncResult.error	访问一个 Error 在操作失败时提供错误信息的对象。
AsyncResult.asyncContext	定义在对象中 AsyncResult 返回而不进行更改的任何类型的项目。

示例

function persistSettings() {
    Office.context.document.settings.saveAsync(function (asyncResult) {
        write('Settings saved with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

set(name, value)

设置或创建指定设置。

重要提示： 请注意，该 Settings.set 方法仅影响 settings 属性包的内存中副本。 要确保在下次打开文档时、在调用 Settings.set 该方法之后和关闭该加载项之前的某个时间点，加载项可以对设置进行添加或更改，您必须调用该 Settings.saveAsync 方法以将设置保留在文档中。

set(name: string, value: any): void;

参数

name

string

value

any

Specifies the value to be stored.

返回

void

注解

要求集： 设置

如果 set 指定名称尚不存在，则该方法会创建一个新设置，或者在设置属性包的内存中副本中设置指定名称的现有设置。 调用该 Settings.saveAsync 方法后，该值将作为其数据类型的序列化 JSON 表示形式存储在文档中。

示例

function setMySetting() {
    Office.context.document.settings.set('mySetting', 'mySetting value');
}