Office.Settings interface

ホストドキュメントに名前/値のペアとして格納される、作業ウィンドウアドインまたはコンテンツアドインのカスタム設定を表します。

注釈

アプリケーション: Excel、PowerPoint、Word

Settings オブジェクトのメソッドを使用して作成された設定は、アドインごとおよびドキュメントごとに保存されます。つまり、これらの設定は、それを作成したアドインでのみ、かつ設定が保存されているドキュメントからのみ使用できます。

設定の名前は文字列ですが、値には文字列、数値、ブール値、null、オブジェクト、または配列を指定できます。

Settings オブジェクトは Document オブジェクトの一部として自動的に読み込まれ、アドインがアクティブ化されたときにそのオブジェクトの設定プロパティを呼び出すことによって使用可能になります。

設定を追加または削除した後、開発者は saveAsync メソッドを呼び出して、ドキュメント内の設定を保存する必要があります。

使用元

メソッド

addHandlerAsync(eventType, handler, options, callback)	`settingsChanged` イベントのイベントハンドラーを追加します。重要: アドインが任意の Excel クライアントで実行されているときに `settingsChanged` イベントのハンドラーをアドインのコードで登録できますが、イベントが発生するのは、アドインが Excel on the web で開かれたスプレッドシートでアドインが読み込まれ、複数のユーザーがスプレッドシートを編集 (共同編集) しているときにのみです。したがって、`settingsChanged` イベントは事実上、共同編集シナリオのExcel on the webでのみサポートされます。
addHandlerAsync(eventType, handler, callback)	`settingsChanged` イベントのイベントハンドラーを追加します。重要: アドインが任意の Excel クライアントで実行されているときに `settingsChanged` イベントのハンドラーをアドインのコードで登録できますが、イベントが発生するのは、アドインが Excel on the web で開かれたスプレッドシートでアドインが読み込まれ、複数のユーザーがスプレッドシートを編集 (共同編集) しているときにのみです。したがって、`settingsChanged` イベントは事実上、共同編集シナリオのExcel on the webでのみサポートされます。
get(name)	指定された設定を取得します。
refreshAsync(callback)	ドキュメントに保持されている設定をすべて読み取って、メモリ内に保持されているこれらの設定のコンテンツまたは作業ウィンドウアドインのコピーを更新します。
remove(name)	指定された設定を削除します。重要: `Settings.remove` メソッドは、設定プロパティバッグのメモリ内コピーにのみ影響することに注意してください。ドキュメントで指定された設定を削除し続けるには、 `Settings.remove` メソッドを呼び出した後、アドインを閉じる前に、 `Settings.saveAsync` メソッドを呼び出す必要があります。
removeHandlerAsync(eventType, options, callback)	`settingsChanged` イベントのイベントハンドラーを削除します。
removeHandlerAsync(eventType, callback)	`settingsChanged` イベントのイベントハンドラーを削除します。
saveAsync(options, callback)	設定プロパティバッグのメモリ内コピーをドキュメントに保持します。
saveAsync(callback)	設定プロパティバッグのメモリ内コピーをドキュメントに保持します。
set(name, value)	指定された設定を行うかまたは作成します。重要: `Settings.set` メソッドは、設定プロパティバッグのメモリ内コピーにのみ影響することに注意してください。次にドキュメントを開いたときに、 `Settings.set` メソッドを呼び出した後、アドインを閉じる前に、設定の追加や変更をアドインで確実に利用できるようにするには、 `Settings.saveAsync` メソッドを呼び出してドキュメント内の設定を保持する必要があります。

addHandlerAsync(eventType, handler, options, callback)

settingsChanged イベントのイベントハンドラーを追加します。

重要: アドインが任意の Excel クライアントで実行されているときに settingsChanged イベントのハンドラーをアドインのコードで登録できますが、イベントが発生するのは、アドインが Excel on the web で開かれたスプレッドシートでアドインが読み込まれ、複数のユーザーがスプレッドシートを編集 (共同編集) しているときにのみです。したがって、settingsChanged イベントは事実上、共同編集シナリオのExcel on the webでのみサポートされます。

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

パラメーター

eventType: Office.EventType

追加するイベントの種類を指定します。必須です。

handler: any

追加するイベントハンドラー関数。その唯一のパラメーターは Office.SettingsChangedEventArgs 型です。必須です。

options: Office.AsyncContextOptions

コールバックで使用するために、任意の種類のコンテキストデータを変更されないまま保持するためのオプションを提供します。

callback: (result: Office.AsyncResult<void>) => void

省略可能。コールバックが返されたときに呼び出される関数。その唯一のパラメーターは Office.AsyncResult 型です。

プロパティ	使用
`AsyncResult.value`	イベントハンドラーを追加するときに取得するデータまたはオブジェクトがないため、常に `undefined` を返します。
`AsyncResult.status`	操作の成功または失敗を判断します。
`AsyncResult.error`	操作が失敗した場合にエラー情報を提供する `Error` オブジェクトにアクセスします。
`AsyncResult.asyncContext`	変更せずに `AsyncResult` オブジェクトで返される任意の型の項目を定義します。

返品

void

注釈

要件セット: セットにない

指定した eventType に複数のイベントハンドラーを追加できるのは、各イベントハンドラー関数の名前が一意である限りです。

addHandlerAsync(eventType, handler, callback)

settingsChanged イベントのイベントハンドラーを追加します。

重要: アドインが任意の Excel クライアントで実行されているときに settingsChanged イベントのハンドラーをアドインのコードで登録できますが、イベントが発生するのは、アドインが Excel on the web で開かれたスプレッドシートでアドインが読み込まれ、複数のユーザーがスプレッドシートを編集 (共同編集) しているときにのみです。したがって、settingsChanged イベントは事実上、共同編集シナリオのExcel on the webでのみサポートされます。

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): void;

パラメーター

eventType: Office.EventType

追加するイベントの種類を指定します。必須です。

handler: any

追加するイベントハンドラー関数。その唯一のパラメーターは Office.SettingsChangedEventArgs 型です。必須です。

callback: (result: Office.AsyncResult<void>) => void

省略可能。コールバックが返されたときに呼び出される関数。その唯一のパラメーターは Office.AsyncResult 型です。

プロパティ	使用
`AsyncResult.value`	イベントハンドラーを追加するときに取得するデータまたはオブジェクトがないため、常に `undefined` を返します。
`AsyncResult.status`	操作の成功または失敗を判断します。
`AsyncResult.error`	操作が失敗した場合にエラー情報を提供する `Error` オブジェクトにアクセスします。
`AsyncResult.asyncContext`	変更せずに `AsyncResult` オブジェクトで返される任意の型の項目を定義します。

返品

void

注釈

要件セット: セットにない

指定した eventType に複数のイベントハンドラーを追加できるのは、各イベントハンドラー関数の名前が一意である限りです。

例

function addSelectionChangedEventHandler() {
    Office.context.document.settings.addHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs: Office.SettingsChangedEventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

get(name)

指定された設定を取得します。

get(name: string): any;

パラメーター

name: string

返品

any

JSON シリアル化された値にマップされたプロパティ名を持つオブジェクト。

注釈

要件セット: 設定

例

function displayMySetting() {
    write('Current value for mySetting: ' + Office.context.document.settings.get('mySetting'));
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

refreshAsync(callback)

ドキュメントに保持されている設定をすべて読み取って、メモリ内に保持されているこれらの設定のコンテンツまたは作業ウィンドウアドインのコピーを更新します。

refreshAsync(callback?: (result: AsyncResult<Office.Settings>) => void): void;

パラメーター

callback: (result: Office.AsyncResult<Office.Settings>) => void

省略可能。コールバックが返されたときに呼び出される関数。その唯一のパラメーターは Office.AsyncResult 型です。結果の value プロパティは、更新された値を持つ Office.Settings オブジェクトです。

返品

void

注釈

要件セット: セットにない

この方法は、同じアドインの複数のインスタンスが同じドキュメントを操作している場合に、Excel、Word、PowerPoint の共同編集シナリオで役立ちます。各アドインは、ユーザーがドキュメントを開いた時点でドキュメントから読み込まれた設定のメモリ内コピーに対して動作するため、各ユーザーが使用する設定値が同期しない可能性があります。これは、アドインのインスタンスが Settings.saveAsync メソッドを呼び出して、ユーザーのすべての設定をドキュメントに保持するたびに発生する可能性があります。アドインの settingsChanged イベントのイベントハンドラーから refreshAsync メソッドを呼び出すと、すべてのユーザーの設定値が更新されます。

refreshAsync メソッドに渡されるコールバック関数では、AsyncResult オブジェクトのプロパティを使用して次の情報を返すことができます。

プロパティ	使用
`AsyncResult.value`	更新された値を使用して `Settings` オブジェクトにアクセスします。
`AsyncResult.status`	操作の成功または失敗を判断します。
`AsyncResult.error`	操作が失敗した場合にエラー情報を提供する `Error` オブジェクトにアクセスします。
`AsyncResult.asyncContext`	変更せずに `AsyncResult` オブジェクトで返される任意の型の項目を定義します。

例

function refreshSettings() {
    Office.context.document.settings.refreshAsync(function (asyncResult) {
        write('Settings refreshed with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

remove(name)

指定された設定を削除します。

重要: Settings.remove メソッドは、設定プロパティバッグのメモリ内コピーにのみ影響することに注意してください。ドキュメントで指定された設定を削除し続けるには、 Settings.remove メソッドを呼び出した後、アドインを閉じる前に、 Settings.saveAsync メソッドを呼び出す必要があります。

remove(name: string): void;

パラメーター

name: string

返品

void

注釈

要件セット: 設定

null は、設定の有効な値です。そのため、設定に null を割り当てても、設定プロパティバッグから削除されることはありません。

例

function removeMySetting() {
    Office.context.document.settings.remove('mySetting');
}

removeHandlerAsync(eventType, options, callback)

settingsChanged イベントのイベントハンドラーを削除します。

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

パラメーター

eventType: Office.EventType

削除するイベントの型を指定します。必須です。

options: Office.RemoveHandlerOptions

削除されるイベントハンドラーを決定するオプションを提供します。

callback: (result: Office.AsyncResult<void>) => void

省略可能。コールバックが返されたときに呼び出される関数。その唯一のパラメーターは Office.AsyncResult 型です。

返品

void

注釈

要件セット: セットにない

removeHandlerAsync メソッドの呼び出し時にオプションのハンドラーパラメーターを省略すると、指定したeventTypeのすべてのイベントハンドラーが削除されます。

コールバックパラメーターに渡した関数が実行されると、コールバック関数の唯一のパラメーターからアクセスできる AsyncResult オブジェクトを受け取ります。

removeHandlerAsync メソッドに渡されるコールバック関数では、AsyncResult オブジェクトのプロパティを使用して次の情報を返すことができます。

プロパティ	使用
`AsyncResult.value`	書式設定時に取得するデータまたはオブジェクトがないため、常に `undefined` を返します。
`AsyncResult.status`	操作の成功または失敗を判断します。
`AsyncResult.error`	操作が失敗した場合にエラー情報を提供する `Error` オブジェクトにアクセスします。
`AsyncResult.asyncContext`	変更せずに `AsyncResult` オブジェクトで返される任意の型の項目を定義します。

removeHandlerAsync(eventType, callback)

settingsChanged イベントのイベントハンドラーを削除します。

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

パラメーター

eventType: Office.EventType

削除するイベントの型を指定します。必須です。

callback: (result: Office.AsyncResult<void>) => void

省略可能。コールバックが返されたときに呼び出される関数。その唯一のパラメーターは Office.AsyncResult 型です。

返品

void

注釈

要件セット: セットにない

removeHandlerAsync メソッドの呼び出し時にオプションのハンドラーパラメーターを省略すると、指定したeventTypeのすべてのイベントハンドラーが削除されます。

コールバックパラメーターに渡した関数が実行されると、コールバック関数の唯一のパラメーターからアクセスできる AsyncResult オブジェクトを受け取ります。

removeHandlerAsync メソッドに渡されるコールバック関数では、AsyncResult オブジェクトのプロパティを使用して次の情報を返すことができます。

プロパティ	使用
`AsyncResult.value`	書式設定時に取得するデータまたはオブジェクトがないため、常に `undefined` を返します。
`AsyncResult.status`	操作の成功または失敗を判断します。
`AsyncResult.error`	操作が失敗した場合にエラー情報を提供する `Error` オブジェクトにアクセスします。
`AsyncResult.asyncContext`	変更せずに `AsyncResult` オブジェクトで返される任意の型の項目を定義します。

例

function removeSettingsChangedEventHandler() {
    Office.context.document.settings.removeHandlerAsync(Office.EventType.SettingsChanged);
}

saveAsync(options, callback)

設定プロパティバッグのメモリ内コピーをドキュメントに保持します。

saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;

パラメーター

options: Office.SaveSettingsOptions

設定を保存するためのオプションを提供します。

callback: (result: Office.AsyncResult<void>) => void

省略可能。コールバックが返されたときに呼び出される関数。その唯一のパラメーターは Office.AsyncResult 型です。

返品

void

注釈

要件セット: 設定

アドインによって以前に保存された設定は、アドインが初期化されるときに読み込まれるため、セッションの有効期間中は、 set メソッドと get メソッドを使用して、設定プロパティバッグのメモリ内コピーを操作できます。次回アドインを使用するときに使用できるように設定を保持する場合は、 saveAsync メソッドを使用します。

注: saveAsync メソッドは、メモリ内設定プロパティバッグをドキュメントファイルに保持します。ただし、ドキュメントファイル自体に対する変更は、ユーザー (または自動バックアップ設定) がドキュメントをファイルシステムに保存した場合にのみ保存されます。 refreshAsync メソッドは、共同編集シナリオでのみ役に立ちます。同じアドインの他のインスタンスが設定を変更し、それらの変更をすべてのインスタンスで使用できるようにする必要がある場合のみです。

プロパティ	使用
`AsyncResult.value`	取得するオブジェクトまたはデータがないため、常に `undefined` を返します。
`AsyncResult.status`	操作の成功または失敗を判断します。
`AsyncResult.error`	操作が失敗した場合にエラー情報を提供する `Error` オブジェクトにアクセスします。
`AsyncResult.asyncContext`	変更せずに `AsyncResult` オブジェクトで返される任意の型の項目を定義します。

saveAsync(callback)

設定プロパティバッグのメモリ内コピーをドキュメントに保持します。

saveAsync(callback?: (result: AsyncResult<void>) => void): void;

パラメーター

callback: (result: Office.AsyncResult<void>) => void

省略可能。コールバックが返されたときに呼び出される関数。その唯一のパラメーターは Office.AsyncResult 型です。

返品

void

注釈

要件セット: 設定

アドインによって以前に保存された設定は、アドインが初期化されるときに読み込まれるため、セッションの有効期間中は、 set メソッドと get メソッドを使用して、設定プロパティバッグのメモリ内コピーを操作できます。次回アドインを使用するときに使用できるように設定を保持する場合は、 saveAsync メソッドを使用します。

注: saveAsync メソッドは、メモリ内設定プロパティバッグをドキュメントファイルに保持します。ただし、ドキュメントファイル自体に対する変更は、ユーザー (または自動バックアップ設定) がドキュメントをファイルシステムに保存した場合にのみ保存されます。 refreshAsync メソッドは、共同編集シナリオでのみ役に立ちます。同じアドインの他のインスタンスが設定を変更し、それらの変更をすべてのインスタンスで使用できるようにする必要がある場合のみです。

プロパティ	使用
`AsyncResult.value`	取得するオブジェクトまたはデータがないため、常に `undefined` を返します。
`AsyncResult.status`	操作の成功または失敗を判断します。
`AsyncResult.error`	操作が失敗した場合にエラー情報を提供する `Error` オブジェクトにアクセスします。
`AsyncResult.asyncContext`	変更せずに `AsyncResult` オブジェクトで返される任意の型の項目を定義します。

例

function persistSettings() {
    Office.context.document.settings.saveAsync(function (asyncResult) {
        write('Settings saved with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

set(name, value)

指定された設定を行うかまたは作成します。

重要: Settings.set メソッドは、設定プロパティバッグのメモリ内コピーにのみ影響することに注意してください。次にドキュメントを開いたときに、 Settings.set メソッドを呼び出した後、アドインを閉じる前に、設定の追加や変更をアドインで確実に利用できるようにするには、 Settings.saveAsync メソッドを呼び出してドキュメント内の設定を保持する必要があります。

set(name: string, value: any): void;

パラメーター

name: string

value: any

Specifies the value to be stored.

返品

void

注釈

要件セット: 設定

set メソッドは、指定した名前の新しい設定を作成します (まだ存在しない場合)。または、設定プロパティバッグのメモリ内コピーに指定した名前の既存の設定を設定します。 Settings.saveAsync メソッドを呼び出すと、値はデータ型のシリアル化された JSON 表現としてドキュメントに格納されます。

例

function setMySetting() {
    Office.context.document.settings.set('mySetting', 'mySetting value');
}

注釈

使用元

メソッド

メソッドの詳細

addHandlerAsync(eventType, handler, options, callback)

パラメーター

返品

注釈

addHandlerAsync(eventType, handler, callback)

パラメーター

返品

注釈

例

get(name)

パラメーター

返品

注釈

例

refreshAsync(callback)

パラメーター

返品

注釈

例

remove(name)

パラメーター

返品

注釈

例

removeHandlerAsync(eventType, options, callback)

パラメーター

返品

注釈

removeHandlerAsync(eventType, callback)

パラメーター

返品

注釈

例

saveAsync(options, callback)

パラメーター

返品

注釈

saveAsync(callback)

パラメーター

返品

注釈

例

set(name, value)

パラメーター

返品

注釈

例

フィードバック