タブでダイアログを使用する

タブにモーダル ダイアログ (TeamsJS v1.x のタスク モジュールと呼ばれます) を追加して、データ入力を必要とするワークフローのユーザー エクスペリエンスを簡略化します。 ダイアログを使用すると、Planner カードの編集など、Microsoft Teams-Aware モーダル ウィンドウでユーザー入力を収集できます。 ダイアログを使用して、同様のエクスペリエンスを作成できます。

ダイアログの 2 つのメイン操作には、ダイアログの開閉 (送信) が含まれます。 TeamsJS ライブラリの以前のバージョン (v2.x.x より前) では、関数が若干異なります。

TeamsJs v2

// Open HTML dialog
microsoftTeams.dialog.url.open(
    urlDialogInfo: UrlDialogInfo, 
       submitHandler?: DialogSubmitHandler, 
       messageFromChildHandler?: PostMessageChannel
): void;

// Open Adaptive Card dialog
microsoftTeams.dialog.adaptiveCard.open(
    adaptiveCardDialogInfo: AdaptiveCardDialogInfo,
    submitHandler?: DialogSubmitHandler
): void;

// Submit HTML dialog (AC dialogs send result from Action.Submit)
   microsoftTeams.dialog.url.submit(
    result?: string | any,
    appIds?: string | string[]
): void;

注:

プロパティは dialog.submit ダイアログ内でのみ呼び出すことができます。

TeamsJs v1

// Same function is used for both HTML and Adaptive Card dialogs.
microsoftTeams.tasks.startTask(
    taskInfo: TaskInfo,
    submitHandler?: (err: string, result: string | any) => void
): void;

// Only works for HTML dialogs (AC dialogs send result from Action.Submit)
microsoftTeams.tasks.submitTask(
    result?: string | any,
    appIds?: string | string[]
): void;

次のセクションでは、タブからダイアログを呼び出し、結果を送信するプロセスについて説明します。

タブからダイアログを呼び出す

注:

TeamsJS v2.8.x 以降、名前空間では dialog アダプティブ カード ベースのダイアログがサポートされています。 名前空間はtasks下位互換性のために引き続きサポートされていますが、ベスト プラクティスは、HTML とdialog.adaptiveCard.openアダプティブ カードベースのダイアログの呼び出しdialog.url.openをそれぞれ更新tasks.startTask()することです。 詳細については、 ダイアログ名前空間に関するページを参照してください。

タブから HTML またはアダプティブ カードダイアログを呼び出すことができます。

HTML ダイアログ

 microsoftTeams.dialog.url.open(urlDialogInfo, submitHandler);

の UrlDialogInfo.url 値は、ダイアログのコンテンツの場所に設定されます。 ダイアログ ウィンドウが開き、 UrlDialogInfo.url その中に として <iframe> 読み込まれます。 ダイアログ ページの JavaScript は を呼び出します microsoftTeams.app.initialize()。 ページに関数があり submitHandler 、 を呼び出 microsoftTeams.dialog.url.open()すときにエラーが発生した場合は、 を submitHandler 同じを示すエラー文字列に設定して呼び出されます err 。

警告

Web バージョンの Teams (teams.microsoft.com)、Outlook (outlook.com)、Microsoft 365 (microsoft365.com) ドメインを含む Microsoft のクラウド サービスは、cloud.microsoft ドメインに移行しています。 2024 年 6 月より前に次の手順を実行して、アプリが Teams Web クライアントで引き続きレンダリングされるようにします。

1. TeamsJS SDK を v.2.19.0 以降に更新します。 TeamsJS SDK の最新リリースの詳細については、「 Microsoft Teams JavaScript クライアント ライブラリ」を参照してください。

2. Teams アプリの コンテンツ セキュリティ ポリシー ヘッダーを更新して、アプリが teams.cloud.microsoft ドメインにアクセスできるようにします。 Teams アプリが Outlook と Microsoft 365 に拡張されている場合は、アプリが teams.cloud.microsoft、outlook.cloud.microsoft、m365.cloud.microsoft ドメインにアクセスできることを確認します。

[アダプティブ カード] ダイアログ

 microsoftTeams.dialog.adaptiveCard.open(adaptiveCardDialogInfo, submitHandler);

adaptiveCardDialogInfo.card の値は、アダプティブ カードの JSON です。 を呼び出すときにエラーが発生した場合、またはユーザーが X (Exit) ボタンをopen()使用してダイアログを閉じる場合は、err 文字列を使用して呼び出す を指定submitHandlerできます。

次のセクションでは、ダイアログを呼び出す例を示します。

ダイアログの呼び出しの例

次の図は、ダイアログを表示します。

次のコードは、 ダイアログ サンプルから調整されています。

TeamsJs v2

let urlDialogInfo = {
    title: null,
    height: null,
    width: null,
    url: null,
    fallbackUrl: null,
};

urlDialogInfo.url = "https://contoso.com/teamsapp/customform";
urlDialogInfo.title = "Custom Form";
urlDialogInfo.height = 510;
urlDialogInfo.width = 430;
submitHandler = (submitHandler) => {
        console.log(`Submit handler - err: ${submitHandler.err}`);
        alert("Result = " + JSON.stringify(submitHandler.result) + "\nError = " + JSON.stringify(submitHandler.err));
    };

 microsoftTeams.dialog.url.open(urlDialogInfo, submitHandler);

TeamsJs v1

let taskInfo = {
    title: null,
    height: null,
    width: null,
    url: null,
    card: null,
    fallbackUrl: null,
    completionBotId: null,
};

taskInfo.url = "https://contoso.com/teamsapp/customform";
taskInfo.title = "Custom Form";
taskInfo.height = 510;
taskInfo.width = 430;
submitHandler = (err, result) => {
    console.log(`Submit handler - err: ${err}`);
    console.log(`Submit handler - result\rName: ${result.name}\rEmail: ${result.email}\rFavorite book: ${result.favoriteBook}`);
};
microsoftTeams.tasks.startTask(taskInfo, submitHandler);

はsubmitHandler、 または result のerr値をコンソールにエコーします。

ダイアログの結果を送信する

ダイアログの呼び出し中にエラーが発生した場合は、発生したエラーをsubmitHandler示す文字列をerr使用して関数がすぐに呼び出されます。 submitHandlerユーザーがダイアログで X をerr選択して終了すると、関数も文字列で呼び出されます。

呼び出しエラーがなく、ユーザーが [X ] を選択してダイアログを閉じなかった場合、ユーザーは完了時に送信ボタンを選択します。 次のセクションでは、HTML とアダプティブ カードのダイアログの種類の次の動作について説明します。

HTML または JavaScript ダイアログ

ユーザー入力を検証したら、 を呼び出します microsoftTeams.dialog.url.submit()。 Teams でダイアログを閉じる場合は、パラメーターなしでを呼び出 submit() すことができます。または、オブジェクトまたは文字列 result を最初のパラメーターとしてアプリに渡し、ダイアログを開いたアプリの を appId 2 番目のパラメーターとして渡すことができます。 パラメーターをresult指定して を呼び出すsubmit()場合は、 (またはダイアログのappId結果を受け取るために承認されたアプリの文字列の配列) を渡すappId必要があります。 このアクションにより、Teams は、結果を送信するアプリが呼び出されたダイアログと同じであることを検証できます。

その後、Teams は、 が null で、 result に渡したsubmit()オブジェクトまたは文字列を呼び出しますsubmitHandlererr。

アダプティブ カード ダイアログ

を使用submitHandlerしてダイアログを呼び出し、ユーザーがボタンをAction.Submit選択すると、カード内の値がそのdataオブジェクトとして返されます。 ユーザーが Esc キーを押すか 、X を選択してダイアログを終了すると、 submitHandler が文字列で err 呼び出されます。 アプリにタブに加えてボットが含まれている場合は、ボットの を appId の値completionBotIdとして (BotAdaptiveCardDialogInfo) オブジェクトにTaskInfo含めることができます。

ユーザーが入力したアダプティブ カードの本文は、ユーザーが Action.Submit ボタンを選択すると、task/submit invoke メッセージを使用してボットに送信されます。 受信するオブジェクトのスキーマは、 タスク/フェッチメッセージとタスク/送信メッセージに対して受け取るスキーマに似ています。 唯一の違いは、JSON オブジェクトのスキーマが Adaptive Card オブジェクトであるのに対し、アダプティブ カードがボットで使用される場合としてアダプティブ カード オブジェクトを含むオブジェクトであるということです。

ペイロードの例を次に示します。

{
  "task": {
    "type": "continue",
    "value": {
      "title": "Title",
      "height": "height",
      "width": "width",
      "url": null,
      "card": "Adaptive Card or Adaptive Card bot card attachment",
      "fallbackUrl": null,
      "completionBotID": "bot App ID"
    }
  }
}

次のコードは、Invoke 要求の例です。

let adaptiveCardDialogInfo = {
    title: "Dialog Demo",
    height: "medium",
    width: "medium",
    card: null,
    fallbackUrl: null,
    completionBotId: null,
};

adaptiveCardDialogInfo.card = {
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
        {
            "type": "TextBlock",
            "text": "This is a sample adaptive card.",
            "wrap": true
        }
    ]
}

submitHandler = (err, result) => {
    console.log(`Submit handler - err: ${err}`);
    alert(
        "Result = " + JSON.stringify(result) + "\nError = " + JSON.stringify(err)
    );
};

microsoftTeams.dialog.adaptiveCard.open(adaptiveCardDialogInfo, submitHandler);

次のセクションでは、ダイアログの結果を送信する例を示します (TeamsJS v1.x ではタスク モジュールと呼ばれます)。

ダイアログの結果を送信する例

HTML ダイアログを呼び出す前の例を取り上げて、ダイアログに埋め込まれた HTML フォームの例を次に示します。

<form method="POST" id="customerForm" action="/register" onSubmit="return validateForm()">

このフォームには 5 つのフィールドがありますが、この例では、、email、および namefavoriteBookの 3 つの値のみが必要です。

次のコードは、submit() を呼び出す validateForm() 関数の例を示しています。

function validateForm() {
    var customerInfo = {
        name: document.forms["customerForm"]["name"].value,
        email: document.forms["customerForm"]["email"].value,
        favoriteBook: document.forms["customerForm"]["favoriteBook"].value
    }
    microsoftTeams.dialog.url.submit(customerInfo, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
    return true;
}

ダイアログ呼び出しエラー

注:

名前空間は tasks 名前空間に dialog 置き換えられます。 dialog名前空間には、HTML ()、アダプティブ カード ()、ボットベースのadaptiveCardurl ( および ) 機能のサブ名前空間がdialog.url.botdialog.adaptiveCard.bot含まれています。

次の表に、受け取る可能性のある値 err を submitHandler 示します。

問題	err の値であるエラー メッセージ
TaskInfo.url と TaskInfo.card の両方の値が指定されました。	カードと URL の両方の値が指定されました。 どちらか一方が許可されますが、両方は許可されません。
TaskInfo.url と TaskInfo.card を指定します。	カードまたは URL の値を指定する必要があります。
無効な appId	アプリ ID が無効です。
ユーザーが選択した [X] ボタンを閉じます。	ユーザーがダイアログを取り消したか閉じました。

コード サンプル

サンプルの名前	説明	.NET	Node.js	マニフェスト
ダイアログ サンプル bots-V4	このサンプルでは、ボット フレームワーク v4 タブと Teams タブを使用してダイアログを作成する方法を示します。	表示	表示	表示

次の手順

ボットからのダイアログの使用

関連項目

• カードとダイアログ
• ダイアログの呼び出しと閉じる