次の方法で共有

Word.SettingCollection class

  • リファレンス
パッケージ:
word

Wordのコレクションを格納します。オブジェクトの設定。

Extends
OfficeExtension.ClientObject

注釈

[ API セット: WordApi 1.4 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-settings.yaml

// Deletes all custom settings this add-in had set on this document.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  settings.deleteAll();
  await context.sync();
  console.log("All settings deleted.");
});

プロパティ

context

オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。
items

このコレクション内に読み込まれた子アイテムを取得します。

メソッド

add(key, value)

新しい設定を作成するか、既存の設定を設定します。
deleteAll()

このアドインのすべての設定を削除します。
getCount()

設定の数を取得します。
getItem(key)

キーによって設定オブジェクトを取得します。これは大文字と小文字が区別されます。 設定が存在しない場合は、 ItemNotFound エラーをスローします。
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 メソッドを呼び出します)。元の Word.SettingCollection オブジェクトは API オブジェクトですが、 toJSON メソッドは、コレクションの項目から読み込まれたプロパティの浅いコピーを含む "items" 配列を含むプレーンな JavaScript オブジェクト ( Word.Interfaces.SettingCollectionDataとして型指定) を返します。
track()

ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを .sync 呼び出しで使用し、".run" バッチのシーケンシャル実行の外部でプロパティを設定するとき、またはオブジェクトに対してメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクト コレクションにオブジェクトを追加する必要があります。 このオブジェクトがコレクションの一部である場合は、親コレクションも追跡する必要があります。
untrack()

前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは 、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に、 context.sync() を呼び出す必要があります。

プロパティの詳細

context

オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。

context: RequestContext;

プロパティ値

Word.RequestContext

items

このコレクション内に読み込まれた子アイテムを取得します。

readonly items: Word.Setting[];

プロパティ値

Word.Setting[]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-settings.yaml

// Gets all custom settings this add-in set on this document.
await Word.run(async (context) => {
  const settings: Word.SettingCollection = context.document.settings;
  settings.load("items");
  await context.sync();

  if (settings.items.length == 0) {
    console.log("There are no settings.");
  } else {
    console.log("All settings:");
    for (let i = 0; i < settings.items.length; i++) {
      console.log(settings.items[i]);
    }
  }
});

メソッドの詳細

add(key, value)

新しい設定を作成するか、既存の設定を設定します。

add(key: string, value: any): Word.Setting;

パラメーター

key

string

必須。 設定のキー。大文字と小文字が区別されます。

value

any

必須。 設定の値。

戻り値

Word.Setting

注釈

[ API セット: WordApi 1.4 ]

例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-settings.yaml

// Adds a new custom setting or
// edits the value of an existing one.
await Word.run(async (context) => {
  const key = $("#key")
    .val()
    .toString();

  if (key == "") {
    console.error("Key shouldn't be empty.");
    return;
  }

  const value = $("#value")
    .val()
    .toString();

  const settings: Word.SettingCollection = context.document.settings;
  const setting: Word.Setting = settings.add(key, value);
  setting.load();
  await context.sync();

  console.log("Setting added or edited:", setting);
});

deleteAll()

このアドインのすべての設定を削除します。

deleteAll(): void;

戻り値

void

注釈

[ API セット: WordApi 1.4 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Queue commands add a setting.
    const settings = context.document.settings;
    settings.add('startMonth', { month: 'March', year: 1998 });

    // Queue a command to get the count of settings.
    const count = settings.getCount();

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    console.log(count.value);

    // Queue a command to delete all settings.
    settings.deleteAll();

    // Queue a command to get the new count of settings.
    count = settings.getCount();

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    console.log(count.value);
});

getCount()

設定の数を取得します。

getCount(): OfficeExtension.ClientResult<number>;

戻り値

OfficeExtension.ClientResult<number>

注釈

[ API セット: WordApi 1.4 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Queue commands add a setting.
    const settings = context.document.settings;
    settings.add('startMonth', { month: 'March', year: 1998 });

    // Queue a command to get the count of settings.
    const count = settings.getCount();

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    console.log(count.value);

    // Queue a command to delete all settings.
    settings.deleteAll();

    // Queue a command to get the new count of settings.
    count = settings.getCount();

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    console.log(count.value);
});

getItem(key)

キーによって設定オブジェクトを取得します。これは大文字と小文字が区別されます。 設定が存在しない場合は、 ItemNotFound エラーをスローします。

getItem(key: string): Word.Setting;

パラメーター

key

string

設定オブジェクトを識別するキー。

戻り値

Word.Setting

注釈

[ API セット: WordApi 1.4 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Queue commands add a setting.
    const settings = context.document.settings;
    settings.add('startMonth', { month: 'March', year: 1998 });

    // Queue a command to retrieve a setting.
    const startMonth = settings.getItem('startMonth');

    // Queue a command to load the setting.
    startMonth.load();

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
    console.log(JSON.stringify(startMonth.value));
});

getItemOrNullObject(key)

キーによって設定オブジェクトを取得します。これは大文字と小文字が区別されます。 設定が存在しない場合、このメソッドは isNullObject プロパティを true に設定したオブジェクトを返します。 詳細については、「 *OrNullObject メソッドとプロパティ」を参照してください。

getItemOrNullObject(key: string): Word.Setting;

パラメーター

key

string

必須。 設定オブジェクトを識別するキー。

戻り値

Word.Setting

注釈

[ API セット: WordApi 1.4 ]

例

// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Queue commands add a setting.
    const settings = context.document.settings;
    settings.add('startMonth', { month: 'March', year: 1998 });
    
    // Queue commands to retrieve settings.
    const startMonth = settings.getItemOrNullObject('startMonth');
    const endMonth = settings.getItemOrNullObject('endMonth');

    // Queue commands to load settings.
    startMonth.load();
    endMonth.load();

    // Synchronize the document state by executing the queued commands, 
    // and return a promise to indicate task completion.
    await context.sync();
        if (startMonth.isNullObject) {
            console.log("No such setting.");
        }
        else {
            console.log(JSON.stringify(startMonth.value));
        }
        if (endMonth.isNullObject) {
            console.log("No such setting.");
        }
        else {
            console.log(JSON.stringify(endMonth.value));
        }
});

load(options)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

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

パラメーター

options

Word.Interfaces.SettingCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions

読み込むオブジェクトのプロパティのオプションを提供します。

戻り値

Word.SettingCollection

load(propertyNames)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

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

パラメーター

propertyNames

string | string[]

読み込むプロパティを指定するコンマ区切り文字列または文字列の配列。

戻り値

Word.SettingCollection

load(propertyNamesAndPaths)

オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync() を呼び出す必要があります。

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

パラメーター

propertyNamesAndPaths
OfficeExtension.LoadOption

propertyNamesAndPaths.select は読み込むプロパティを指定するコンマ区切りの文字列で、 propertyNamesAndPaths.expand は読み込むナビゲーション プロパティを指定するコンマ区切りの文字列です。

戻り値

Word.SettingCollection

toJSON()

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

toJSON(): Word.Interfaces.SettingCollectionData;

戻り値

Word.Interfaces.SettingCollectionData

track()

ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、 context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを .sync 呼び出しで使用し、".run" バッチのシーケンシャル実行の外部でプロパティを設定するとき、またはオブジェクトに対してメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに、追跡対象のオブジェクト コレクションにオブジェクトを追加する必要があります。 このオブジェクトがコレクションの一部である場合は、親コレクションも追跡する必要があります。

track(): Word.SettingCollection;

戻り値

Word.SettingCollection

untrack()

前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは 、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に、 context.sync() を呼び出す必要があります。

untrack(): Word.SettingCollection;

戻り値

Word.SettingCollection