Office.Settings interface

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

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

注釈

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

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

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

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

設定を追加または削除した後、開発者は 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 プロパティ バッグのメモリ内コピーにのみ影響します。 To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.
removeHandlerAsync(eventType, options, callback)

settingsChanged イベントのイベント ハンドラーを削除します。
removeHandlerAsync(eventType, callback)

settingsChanged イベントのイベント ハンドラーを削除します。
saveAsync(options, callback)

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

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

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

重要: Settings.set メソッドは、settings プロパティ バッグのメモリ内コピーにのみ影響します。 To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

メソッドの詳細

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) {
    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 プロパティ バッグのメモリ内コピーにのみ影響します。 To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.

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 メソッドを呼び出すときに省略可能な handler パラメーターを省略すると、指定した 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 メソッドを呼び出すときに省略可能な handler パラメーターを省略すると、指定した 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, MyHandler);
}

function MyHandler(eventArgs) {
    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; 
}

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 メソッドを使用して、settings プロパティ バッグのメモリ内コピーを操作できます。 次回アドインを使用するときに使用できるように設定を保持する場合は、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 メソッドを使用して、settings プロパティ バッグのメモリ内コピーを操作できます。 次回アドインを使用するときに使用できるように設定を保持する場合は、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 プロパティ バッグのメモリ内コピーにのみ影響します。 To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

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');
}