Office アドインの作業ウィンドウを表示または非表示にする

  • [アーティクル]

重要

共有ランタイムは、一部の Office アプリケーションでのみサポートされています。 詳細については、「共有ランタイム要件セット」を参照してください。

メソッドを呼び出すことで、Office アドインの作業ウィンドウを Office.addin.showAsTaskpane() 表示できます。

function onCurrentQuarter() {
    Office.addin.showAsTaskpane()
    .then(function() {
        // Code that enables task pane UI elements for
        // working with the current quarter.
    });
}

前のコードでは、 CurrentQuarterSales という名前の Excel ワークシートがあるシナリオを前提としています。 このワークシートがアクティブになると、アドインによって作業ウィンドウが表示されます。 メソッド onCurrentQuarter は、ワークシートに登録されている Office.Worksheet.onActivated イベントのハンドラーです。

メソッドを呼び出して作業ウィンドウを Office.addin.hide() 非表示にすることもできます。

function onCurrentQuarterDeactivated() {
    Office.addin.hide();
}

前のコードは、 Office.Worksheet.onDeactivated イベントに 登録されているハンドラーです。

作業ウィンドウの表示に関するその他の詳細

を呼び出 Office.addin.showAsTaskpane()すと、作業ウィンドウに、作業ウィンドウのリソース ID (resid) 値として割り当てたファイルが作業ウィンドウに表示されます。 このresid値は、manifest.xml ファイルを開き、要素内<Action xsi:type="ShowTaskpane">で SourceLocation> を<見つけることで割り当てまたは変更できます。 (詳細については、「 共有ランタイムを使用するように Office アドインを構成 する」を参照してください)。

は非同期メソッドであるため Office.addin.showAsTaskpane() 、メソッドが完了するまでコードは引き続き実行されます。 使用している JavaScript 構文に await 応じて、キーワードまたは then() メソッドでこの完了を待ちます。

共有ランタイムを使用するようにアドインを構成する

メソッドと hide() メソッドをshowAsTaskpane()使用するには、アドインで共有ランタイムを使用する必要があります。 詳細については、「 共有ランタイムを使用するように Office アドインを構成する」を参照してください。

状態リスナーとイベント リスナーの保持

hide()メソッドと showAsTaskpane() メソッドは、作業ウィンドウの可視性のみを変更します。 アンロードまたは再読み込み (または状態の再初期化) は行いません。

次のシナリオを考えてみましょう。作業ウィンドウはタブを使用して設計されています。 [ ホーム ] タブは、アドインが最初に起動されたときに開きます。 ユーザーが [設定] タブを開き、後で作業ウィンドウのコードが何らかのイベントに応答して呼び出 hide() されたとします。 さらに後のコードは、別のイベントに応答して呼び出します showAsTaskpane() 。 作業ウィンドウが再び表示され、[ 設定] タブが引き続き選択されています。

[ホーム]、[設定]、[お気に入り]、[アカウント] というラベルが付いた 4 つのタブがある作業ウィンドウ。

さらに、作業ウィンドウに登録されているイベント リスナーは、作業ウィンドウが非表示の場合でも引き続き実行されます。

次のシナリオを考えてみましょう。作業ウィンドウには、Excel Worksheet.onActivated の登録済みハンドラーと Worksheet.onDeactivatedSheet1 という名前のシートのイベントがあります。 アクティブ化されたハンドラーにより、作業ウィンドウに緑色のドットが表示されます。 非アクティブ化されたハンドラーは、ドットを赤に変えます (既定の状態)。 次に、Sheet1 がアクティブ化されておらず、ドットが赤の場合にコードが呼び出hide()されるとします。 作業ウィンドウが非表示になっている間、 Sheet1 がアクティブになります。 後のコードは、イベントに応答して呼び出します showAsTaskpane() 。 作業ウィンドウが開くと、作業ウィンドウが非表示であってもイベント リスナーとハンドラーが実行されたため、ドットは緑色になります。

可視性が変更されたイベントを処理する

または hide()を使用して作業ウィンドウshowAsTaskpane()の表示を変更すると、Office によってイベントがVisibilityModeChangedトリガーされます。 このイベントを処理すると便利です。 たとえば、作業ウィンドウにブック内のすべてのシートの一覧が表示されたとします。 作業ウィンドウが非表示になっているときに新しいワークシートが追加された場合、作業ウィンドウを表示しても、それ自体では、新しいワークシート名がリストに追加されません。 ただし、コードはVisibilityModeChangedイベントに応答して、以下のコード例に示すように、Workbook.worksheets コレクション内のすべてのワークシートの Worksheet.name プロパティを再読み込みできます。

イベントのハンドラーを登録するには、ほとんどの Office JavaScript コンテキストと同様に "ハンドラーの追加" メソッドを使用しません。 代わりに、ハンドラーを渡す特別な関数があります: Office.addin.onVisibilityModeChanged。 次に例を示します。 プロパティは args.visibilityModeVisibilityMode 型であることに注意してください。

Office.addin.onVisibilityModeChanged(function(args) {
    if (args.visibilityMode == "Taskpane") {
        // Code that runs whenever the task pane is made visible.
        // For example, an Excel.run() that loads the names of
        // all worksheets and passes them to the task pane UI.
    }
});

関数は、ハンドラーを 登録解除 する別の関数を返します。 ここでは単純ですが、堅牢ではありません。例を示します。

const removeVisibilityModeHandler =
    Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });


// In some later code path, deregister with:
removeVisibilityModeHandler();

メソッドは onVisibilityModeChanged 非同期であり、promise を返します。つまり、登録 解除 ハンドラーを呼び出す前に、コードで promise のフルフィルメントを待機する必要があります。

// await the promise from onVisibilityModeChanged and assign
// the returned deregister handler to removeVisibilityModeHandler.
const removeVisibilityModeHandler =
    await Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });

登録解除関数も非同期であり、promise を返します。 そのため、登録解除が完了するまで実行しないコードがある場合は、登録解除関数によって返される約束を待つ必要があります。

// await the promise from the deregister handler before continuing
await removeVisibilityModeHandler();
// subsequent code here

関連項目