Office.Settings interface

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

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

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

パラメーター

戻り値

注釈

要件セット: セットに含まれていない

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

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

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

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): 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: 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?: (result: AsyncResult<Office.Settings>) => void): void;

パラメーター

戻り値

注釈

要件セット: セットに含まれていない

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

refreshAsync メソッドに渡されるコールバック関数では、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; 
}

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

重要: 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;

パラメーター

戻り値

注釈

要件セット: 設定

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

例

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

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

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

パラメーター

戻り値

注釈

要件セット: セットに含まれていない

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

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

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

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

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

パラメーター

戻り値

注釈

要件セット: セットに含まれていない

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

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

removeHandlerAsync メソッドに渡されるコールバック関数では、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?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;

パラメーター

戻り値

注釈

要件セット: 設定

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

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

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

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

パラメーター

戻り値

注釈

要件セット: 設定

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

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

例

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

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

重要: 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;

パラメーター

戻り値

注釈

要件セット: 設定

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

例

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