Excel.SettingCollection class

ブックの一部であるキーと値のペア設定オブジェクトのコレクションを表します。スコープは、ファイルとアドイン (作業ウィンドウまたはコンテンツ) の組み合わせごとに制限されます。

注釈

使用元

プロパティ

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()	API オブジェクトが`JSON.stringify()`に渡されたときにより便利な出力を提供するために、JavaScript `toJSON()` メソッドをオーバーライドします。 (`JSON.stringify`、それに渡されるオブジェクトの `toJSON` メソッドを呼び出します)。元の `Excel.SettingCollection` オブジェクトは API オブジェクトですが、 `toJSON` メソッドは、コレクションの項目から読み込まれたプロパティの浅いコピーを含む "items" 配列を含むプレーンな JavaScript オブジェクト ( `Excel.Interfaces.SettingCollectionData`として型指定) を返します。

イベント

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

API オブジェクトがJSON.stringify()に渡されたときにより便利な出力を提供するために、JavaScript toJSON() メソッドをオーバーライドします。 (JSON.stringify、それに渡されるオブジェクトの toJSON メソッドを呼び出します)。元の Excel.SettingCollection オブジェクトは API オブジェクトですが、 toJSON メソッドは、コレクションの項目から読み込まれたプロパティの浅いコピーを含む "items" 配列を含むプレーンな JavaScript オブジェクト ( Excel.Interfaces.SettingCollectionDataとして型指定) を返します。

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

注釈

使用元

プロパティ

メソッド

イベント

プロパティの詳細

context

プロパティ値

items

プロパティ値

メソッドの詳細

add(key, value)

パラメーター

返品

注釈

例

getCount()

返品

注釈

getItem(key)

パラメーター

返品

注釈

getItemOrNullObject(key)

パラメーター

返品

注釈

例

load(options)

パラメーター

返品

load(propertyNames)

パラメーター

返品

load(propertyNamesAndPaths)

パラメーター

返品

toJSON()

返品

イベントの詳細

onSettingsChanged

イベントの種類

注釈

例

フィードバック