Excel.Setting class

Setting represents a key-value pair of a setting persisted to the document (per file per add-in). These custom key-value pair can be used to store state or lifecycle information needed by the content or task-pane add-in. Note that settings are persisted in the document and hence it is not a place to store any sensitive or protected information such as user information and password.

[ API set: ExcelApi 1.4 ]

Extends
OfficeExtension.ClientObject

Properties

key

Returns the key that represents the id of the Setting. Read-only.

[ API set: ExcelApi 1.4 ]

value

Represents the value stored for this setting.

[ API set: ExcelApi 1.4 ]

Methods

delete()

Deletes the setting.

[ API set: ExcelApi 1.4 ]

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

toJSON()

Property Details

key

Returns the key that represents the id of the Setting. Read-only.

[ API set: ExcelApi 1.4 ]

readonly key: string;
Property Value
string

value

Represents the value stored for this setting.

[ API set: ExcelApi 1.4 ]

value: any;
Property Value
any

Method Details

delete()

Deletes the setting.

[ API set: ExcelApi 1.4 ]

delete(): void;
Returns
void

Examples

await Excel.run(async (context) => {
    const settings = context.workbook.settings;
    let needsReview = settings.getItem("NeedsReview");
    needsReview.delete();
    needsReview = settings.getItemOrNullObject("NeedsReview");

    await context.sync();

    if (needsReview.isNullObject) {
        OfficeHelpers.UI.notify("The setting has been deleted");
    } else {
        OfficeHelpers.UI.notify("The setting was not deleted");
    }

    await context.sync();
});

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(option?: string | string[]): Excel.Setting;
Parameters
option
string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns
Remarks

In addition to this signature, this method has the following signatures:

load(option?: { select?: string; expand?: string; }): Excel.Setting - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Excel.Setting - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

toJSON()

toJSON(): Excel.Interfaces.SettingData;
Returns