Word.SettingCollection class
Wordのコレクションを格納します。オブジェクトの設定。
- Extends
注釈
例
// 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) | 新しい設定を作成するか、既存の設定を設定します。 |
delete |
このアドインのすべての設定を削除します。 |
get |
設定の数を取得します。 |
get |
キーによって設定オブジェクトを取得します。これは大文字と小文字が区別されます。 設定が |
get |
キーによって設定オブジェクトを取得します。これは大文字と小文字が区別されます。 設定が存在しない場合、このメソッドは プロパティが に設定されたオブジェクトを |
load(options) | オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
load(property |
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
load(property |
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、 |
toJSON() | API オブジェクトが に渡されたときにより便利な出力を提供するために、JavaScript |
track() | ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを呼び出しで |
untrack() | 前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に を呼び出す |
プロパティの詳細
context
オブジェクトに関連付けられている要求コンテキスト。 これにより、アドインのプロセスが Office ホスト アプリケーションのプロセスに接続されます。
context: RequestContext;
プロパティ値
items
このコレクション内に読み込まれた子アイテムを取得します。
readonly items: 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
必須です。 設定の値。
戻り値
注釈
例
// 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
注釈
例
// 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>
注釈
例
// 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
設定オブジェクトを識別するキー。
戻り値
注釈
例
// 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
必須です。 設定オブジェクトを識別するキー。
戻り値
注釈
例
// 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;
パラメーター
読み込むオブジェクトのプロパティのオプションを提供します。
戻り値
load(propertyNames)
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync()
を呼び出す必要があります。
load(propertyNames?: string | string[]): Word.SettingCollection;
パラメーター
- propertyNames
-
string | string[]
読み込むプロパティを指定するコンマ区切り文字列または文字列の配列。
戻り値
load(propertyNamesAndPaths)
オブジェクトの指定されたプロパティを読み込むコマンドを待ち行列に入れます。 プロパティを読み取る前に、context.sync()
を呼び出す必要があります。
load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.SettingCollection;
パラメーター
- propertyNamesAndPaths
- OfficeExtension.LoadOption
propertyNamesAndPaths.select
は、読み込むプロパティを指定するコンマ区切り文字列で propertyNamesAndPaths.expand
、読み込むナビゲーション プロパティを指定するコンマ区切りの文字列です。
戻り値
toJSON()
API オブジェクトが に渡されたときにより便利な出力を提供するために、JavaScript toJSON()
メソッドを JSON.stringify()
オーバーライドします。 (JSON.stringify
さらに、渡される オブジェクトの メソッドを呼び出 toJSON
します)。元 Word.SettingCollection
のオブジェクトは API オブジェクトですが、 toJSON
メソッドは、コレクションの項目から読み込まれたプロパティの浅いコピーを含む "items" 配列を含むプレーンな JavaScript オブジェクト (として Word.Interfaces.SettingCollectionData
型指定) を返します。
toJSON(): Word.Interfaces.SettingCollectionData;
戻り値
track()
ドキュメントの環境変更に基づいて自動的に調整する目的でオブジェクトを追跡します。 この呼び出しは、context.trackedObjects.add(thisObject)の短縮形です。 このオブジェクトを呼び出しで .sync
使用していて、".run" バッチのシーケンシャル実行の外部で使用していて、プロパティを設定するとき、またはオブジェクトのメソッドを呼び出すときに "InvalidObjectPath" エラーが発生する場合は、オブジェクトが最初に作成されたときに追跡対象のオブジェクト コレクションにオブジェクトを追加する必要があります。 このオブジェクトがコレクションの一部である場合は、親コレクションも追跡する必要があります。
track(): Word.SettingCollection;
戻り値
untrack()
前に追跡されていた場合、このオブジェクトに関連付けられているメモリを解放します。 この呼び出しは、context.trackedObjects.remove(thisObject)の短縮形です。 追跡対象オブジェクトが多いとホスト アプリケーションの動作が遅くなります。追加したオブジェクトが不要になったら、必ずそれを解放してください。 メモリ解放が有効になる前に を呼び出す context.sync()
必要があります。
untrack(): Word.SettingCollection;
戻り値
Office Add-ins