Office.Settings interface

包:

office

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

注解

应用程序：Excel、PowerPoint Word

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

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

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

开发者负责在添加或删除设置后调用 saveAsync 方法，从而将设置保存到文档中。

方法

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.remove 方法之后的某个时间点以及在关闭外接程序之前保留文档中指定设置的删除状态，你必须调用 Settings.saveAsync 方法。
removeHandlerAsync(eventType, options, callback)	删除 settingsChanged 事件的事件处理程序。
removeHandlerAsync(eventType, callback)	删除 settingsChanged 事件的事件处理程序。
saveAsync(options, callback)	将设置属性包的内存副本保留到文档中。
saveAsync(callback)	将设置属性包的内存副本保留到文档中。
set(name, value)	设置或创建指定设置。 重要提示：请注意，Settings.set 方法仅影响设置属性包的内存中副本。 为了确保对设置所做的增补或更改在文档下次打开时、在调用 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) {
    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 方法以将该用户的所有设置保存到文档时，都可能会发生这种情况。 从外接程序的 settingsChanged 事件的事件处理程序调用 refreshAsync 方法将刷新所有用户的设置值。

在传递给 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.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 方法时省略可选的 handler 参数，则将删除指定 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 方法时省略可选的 handler 参数，则将删除指定 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, MyHandler);
}

function MyHandler(eventArgs) {
    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; 
}

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.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');
}