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

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

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()を呼び出すと、Office はマニフェストで指定したファイルを作業ウィンドウに表示します。 構成は、使用しているマニフェストの種類によって異なります。

• Microsoft 365 の統合マニフェスト: ファイルの URL は、"openPage" 型のアクション オブジェクトを持つランタイム オブジェクトの "runtimes.code.page" プロパティの値として割り当てられます。

  注:

  Microsoft 365 の統合マニフェストは、運用環境の Outlook アドインで使用できます。Excel、PowerPoint、Word アドインのプレビューとしてのみ使用できます。

• アドインのみのマニフェスト: ファイルの URL は、作業ウィンドウのリソース ID (resid) 値として割り当てられます。 このresid値は、マニフェスト ファイルを開き、<Action xsi:type="ShowTaskpane">要素内で<SourceLocation>を見つけることで割り当てまたは変更できます。

(詳細については、「 共有ランタイムを使用するように Office アドインを構成 する」を参照してください)。

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

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

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

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

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

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

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

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

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

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

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

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

関連項目

• 共有ランタイムを使用するように Office アドインを構成する
• ドキュメントが開いたら、Office アドインでコードを実行する