Excel.SettingCollection class

  • Ссылка
Пакет:
excel

Представляет коллекцию объектов параметров пары "ключ—значение", которые являются частью книги. Область ограничивается сочетанием файлов и надстроек (области задач или содержимого).

Extends
OfficeExtension.ClientObject

Комментарии

[ Набор API: ExcelApi 1.4 ]

Свойства

context

Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.
items

Получает загруженные дочерние элементы в этой коллекции.

Методы

add(key, value)

Задает или добавляет указанный параметр в книгу.
getCount()

Возвращает количество параметров в коллекции.
getItem(key)

Возвращает запись параметра с помощью ключа.
getItemOrNullObject(key)

Возвращает запись параметра с помощью ключа. Если параметр не существует, этот метод возвращает объект со свойством isNullObject .true Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
load(options)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
load(propertyNames)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
load(propertyNamesAndPaths)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
toJSON()

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringifyв свою очередь вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.SettingCollection объект является объектом API, toJSON метод возвращает обычный объект JavaScript (типизированный как Excel.Interfaces.SettingCollectionData), содержащий массив "items" с мелкими копиями всех загруженных свойств из элементов коллекции.

События

onSettingsChanged

Происходит при изменении параметров в документе.

Сведения о свойстве

context

Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.

context: RequestContext;

Значение свойства

Excel.RequestContext

items

Получает загруженные дочерние элементы в этой коллекции.

readonly items: Excel.Setting[];

Значение свойства

Excel.Setting[]

Сведения о методе

add(key, value)

Задает или добавляет указанный параметр в книгу.

add(key: string, value: string | number | boolean | Date | any[] | any): Excel.Setting;

Параметры

key

string

Ключ нового параметра.

value

string | number | boolean | Date | any[] | any

Значение нового параметра.

Возвращаемое значение

Excel.Setting

Комментарии

[ Набор API: ExcelApi 1.4 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    const settings = context.workbook.settings; 
    settings.onSettingsChanged.add(onChangedSetting);

    await context.sync();
    console.log("Settings changed handler registered.");
});

getCount()

Возвращает количество параметров в коллекции.

getCount(): OfficeExtension.ClientResult<number>;

Возвращаемое значение

OfficeExtension.ClientResult<number>

Комментарии

[ Набор API: ExcelApi 1.4 ]

getItem(key)

Возвращает запись параметра с помощью ключа.

getItem(key: string): Excel.Setting;

Параметры

key

string

Ключ параметра.

Возвращаемое значение

Excel.Setting

Комментарии

[ Набор API: ExcelApi 1.4 ]

getItemOrNullObject(key)

Возвращает запись параметра с помощью ключа. Если параметр не существует, этот метод возвращает объект со свойством isNullObject .true Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getItemOrNullObject(key: string): Excel.Setting;

Параметры

key

string

Ключ параметра.

Возвращаемое значение

Excel.Setting

Комментарии

[ Набор API: ExcelApi 1.4 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/create-get-change-delete-settings.yaml

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) {
        console.log("The setting has been deleted");
    } else {
        console.log("The setting was not deleted");
    }

    await context.sync();
});

load(options)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(options?: Excel.Interfaces.SettingCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.SettingCollection;

Параметры

options

Excel.Interfaces.SettingCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

Предоставляет параметры свойств объекта для загрузки.

Возвращаемое значение

Excel.SettingCollection

load(propertyNames)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

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

Параметры

propertyNames

string | string[]

Строка с разделителями-запятыми или массив строк, указывающих свойства для загрузки.

Возвращаемое значение

Excel.SettingCollection

load(propertyNamesAndPaths)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.SettingCollection;

Параметры

propertyNamesAndPaths
OfficeExtension.LoadOption

propertyNamesAndPaths.select — это строка с разделителями-запятыми, указывающая загружаемые свойства, и propertyNamesAndPaths.expand строка с разделителями-запятыми, указывающая загружаемые свойства навигации.

Возвращаемое значение

Excel.SettingCollection

toJSON()

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringifyв свою очередь вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.SettingCollection объект является объектом API, toJSON метод возвращает обычный объект JavaScript (типизированный как Excel.Interfaces.SettingCollectionData), содержащий массив "items" с мелкими копиями всех загруженных свойств из элементов коллекции.

toJSON(): Excel.Interfaces.SettingCollectionData;

Возвращаемое значение

Excel.Interfaces.SettingCollectionData

Сведения о событии

onSettingsChanged

Происходит при изменении параметров в документе.

readonly onSettingsChanged: OfficeExtension.EventHandlers<Excel.SettingsChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.SettingsChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.4 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    const settings = context.workbook.settings; 
    settings.onSettingsChanged.add(onChangedSetting);

    await context.sync();
    console.log("Settings changed handler registered.");
});