次の方法で共有

Teams JavaScript クライアント ライブラリ

  • [アーティクル]

Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) は、Teams、Microsoft 365 アプリ、Outlook でホストされているエクスペリエンスを作成するのに役立ちます。このエクスペリエンスでは、アプリ コンテンツが iFrame でホストされます。 ライブラリは、次の Teams 機能を使用してアプリを開発するのに役立ちます。

バージョン 2.0.0以降、既存の TeamsJS ライブラリ (@microsoft/teams-js、または単に TeamsJS) がリファクタリングされ、 Teams アプリを Outlook と Microsoft 365 アプリで実行できるように、Microsoft Teamsに加えて有効になります。 機能的な観点から見ると、最新バージョンの TeamsJS では、既存のすべての (v.1.x.x) Teams アプリ機能がサポートされ、Outlook と Microsoft 365 アプリで Teams アプリをホストするオプションの機能が追加されています。

さまざまなアプリ シナリオのバージョン管理ガイダンスを次に示します。

アプリの種類 TeamsJS のバージョン アプリ マニフェストのバージョン 次の手順
Outlook と Microsoft 365 全体で拡張された Teams アプリ TeamsJS v.2.19.0 以降 v.1.13 以降 Teams アプリを拡張して Microsoft 365 全体で実行する、または新しい Microsoft 365 アプリを作成する
既存の Teams 専用アプリ 可能な場合は TeamsJS v.2.19.0 に更新します (v.1.12 はまだサポートされています*) 1.12 TeamsJS の下位互換性について理解し、TeamsJS v.2.0 に更新する
新しい Teams 専用アプリ TeamsJS v.2.19.0 以降 1.12 Teams Toolkit を使用して新しい Teams アプリを作成する

* Teams 専用アプリを含む最新の機能強化と新機能のサポートを利用するには、可能な限り最新の TeamsJS (v.2.19.0 以降) を使用します。TeamsJS v.1.12 は引き続きサポートされますが、新機能や機能強化は追加されません。1.12 スキーマと 1.13 スキーマは同じです。詳細については、「 TeamsJS ライブラリ」を参照してください。

この記事の残りの部分では、TeamsJS ライブラリの構造と最新の更新プログラムについて説明します。

Microsoft 365 のサポート (Microsoft 365 と Outlook での Teams アプリの実行)

TeamsJS v.2.0 では、特定の種類の Teams アプリをMicrosoft 365 エコシステム全体で実行する機能が導入されています。 Teams アプリ用の他の Microsoft 365 アプリケーション ホスト (Microsoft 365 アプリと Outlook を含む) では、Teams プラットフォーム用に構築できるアプリケーションの種類と機能のサブセットがサポートされています。 このサポートは時間の経過と同時に拡張されます。 Teams アプリのホスト サポートの概要については、「 Microsoft 365 全体での TeamsJS 機能のサポート」を参照してください。

JavaScript ツリーの揺れを使用して読み込み時間のパフォーマンスを向上させる

バージョン 2.31.0 以降では、TeamsJS ライブラリは完全にツリー シャク可能です。 ツリーの揺れ は、未使用のコードを排除する JavaScript 最適化です。 アプリがデプロイにバンドルされている場合にツリーシェイクを使用することで、パッケージのサイズを小さくすることができ、ダウンロードが高速化され、読み込み時間が短縮されます。

TeamsJS でツリー シェイクを使用する方法

アプリ パッケージをバンドルするときにツリーの揺れを利用するには、 Webpack や ロールアップなどのツリーの揺れをサポートするバンドルャーを使用します。 ツリーの揺れを有効にすると、未使用の TeamsJS コードはすべて、最終的なバンドルで自動的に削除されます。 たとえば、次のコードを考えてみましょう。

export function scanBarCode(barCodeConfig: BarCodeConfig): Promise<string> {
   //implementation omitted
}

export function hasPermission(): Promise<boolean>{
   //implementation omitted
}

export function requestPermission(): Promise<boolean>{
   //implementation omitted
}

export function isSupported(): boolean {
   //implementation omitted
}

TeamsJS の barCode モジュールに、 hasPermission()、 isSupported()、 requestPermission()、 scanBarCode(BarCodeConfig)の 4 つの関数が含まれているとします。 アプリが hasPermission() 関数のみを使用する場合、ツリーのシェイク後、他の 3 つの関数はアプリ バンドルから除外されます。 これにより、アプリはできるだけ軽量に保たれ、必要なコードのみが含まれます。

重要

ツリーの揺れを使用する場合は、次の考慮事項に注意してください。

  1. アプリで CDN を使用して TeamsJS ライブラリを使用する場合、使用されるライブラリバージョンはツリーシャック可能ではありません。
  2. ツリーの揺れをサポートするために、TeamsJS ライブラリの種類が UMD (ユニバーサル モジュール定義) から ESM (ECMAScript モジュール) に変更されました。 ただし、UMD バージョンは引き続き提供されます。 バンドルが ESM をサポートしている場合は、TeamsJS のツリーシャック可能な ESM パッケージが使用されます。それ以外の場合は UMD パッケージが使用されます。

TeamsJS バージョン 2.x.x の新機能

TeamsJS バージョン 1.x.x と v.2.0.0 以降には、2 つの大きな変更があります。

ヒント

Microsoft Visual Studio Code の Teams Toolkit 拡張機能を使用すると、既存の Teams アプリの TeamsJS v.2.0 更新プロセスを簡略化できます。

下位互換性

既存の Teams アプリから @microsoft/teams-js@2.0.0 (以降) の参照を開始すると、変更された API を呼び出すコードに対して非推奨の警告が表示されます。

API 翻訳レイヤー (v.1 から v.2 TeamsJS API 呼び出しへのマッピング) は、TeamsJS v.2 API パターンを使用するようにアプリケーション コードを更新できるようになるまで、既存の Teams アプリが Teams での作業を継続できるようにするために用意されています。

認証

バージョン 2.11.0 以降TeamsJSでは、認証が完了した後にユーザーを正しいクライアントにリダイレクトするには、認証 API で 3 つ目の url パラメーター (hostRedirectUrl) をアプリで指定する必要があります。 クライアントを Microsoft 365 ホスト アプリケーション全体でサポートできるようにするには、 hostRedirectUrl 認証パラメーターが必要です。 古いバージョンの TeamsJS に実装されたアプリでは、 oauthRedirectmethod と authId クエリ パラメーターがサード パーティのアプリ サーバーに渡されるため、この更新プログラムに続く Teams のみがサポートされます。

認証パラメーターの詳細については、「 外部 OAuth プロバイダーの使用」を参照してください。

Microsoft 365 全体で実行されている Teams アプリ

既存の Teams アプリを Outlook と Microsoft 365 で実行できるようにするための要件を次に示します。

  1. TeamsJS バージョン 2.x.x ( @microsoft/teams-js@2.0.0) 以降への依存関係。

  2. この記事で説明する必要な変更に従って、既存のアプリケーション コードを変更します。

  3. アプリ マニフェスト (以前は Teams アプリ マニフェストと呼ばれる) をバージョン 1.13 以降に更新します。

詳細については、「 Microsoft 365 全体で Teams アプリを拡張する」を参照してください。

コールバックの Promise への変換

注:

getTabInstances API は Teams モバイルには実装されていません。

以前にコールバック パラメーターを受け取った Teams API は、JavaScript Promise オブジェクトを返すように更新されます。 これには、以下の API が含まれます。

app.getContext, app.initialize, appInstallDialog.openAppInstallDialog, app.openLink, authentication.authenticate, authentication.getAuthToken, authentication.getUser, authentication.registerAuthenticationHandlers was removed to support using Promises, calendar.openCalendarItem, calendar.composeMeeting, call.startCall, chat.getChatMembers, conversations.openConversation, location.getLocation, location.showLocation, mail.openMailItem, mail.composeMail, pages.backStack.navigateBack, pages.navigateToTab, pages.tabs.getMruTabInstances, pages.tabs.getTabInstances, pages.getConfig, pages.config.setConfig, pages.backStack.navigateBack, people.selectPeople, teams.fullTrust.getConfigSetting, teams.fullTrust.joinedTeams.getUserJoinedTeams

Promises を使用するには、コードがこれらの API のいずれかを呼び出す方法を更新する必要があります。 たとえば、コードが次のような Teams API を呼び出しているとします。

コード:

import microsoftTeams from "@microsoft/teams-js";

microsoftTeams.getContext((context) => { /* ... */ });

これを次のように更新する必要があります:

import { app } from "@microsoft/teams-js";

app.getContext().then((context) => {
    /*...*/
});

...または同等の async/await パターン:

import { app } from "@microsoft/teams-js";

async function example() {
  const context = await app.getContext();
  /*...*/
}

ヒント

Teams Toolkit を使用して TeamsJS v.2.0 に更新すると、更新プログラムにフラグが付けられ、クライアント コードに TODO コメントが含まれます。

SDK を介したクラウド間通信は、セキュリティ上の理由から制限されています。そのため、21Vianet ドメインによって運営される Teams は validOriginsに含まれません。 アプリが 21Vianet によって運用される Teams で機能できるようにするには、アプリのデプロイで SDK の初期化中に、 validMessageOrigins パラメーターを使用して、21Vianet ドメインによって運用される Teams を指定します。

import { app } from '@microsoft/teams-js';
app.initialize(["https://teams.microsoftonline.cn"]);

API の機能への編成

機能は、同様の機能を提供する API の (名前空間を介した) 論理グループです。 Microsoft Teams、Outlook、Microsoft 365 アプリは、タブ アプリのホストと考えることができます。 ホストは、特定の機能内で定義されているすべての API をサポートしている場合、その機能をサポートします。 ホストが機能を部分的に実装することはできません。 機能は、認証やダイアログのように、機能ベースまたはコンテンツ ベースです。 ページなどのアプリケーションの種類や他のグループの機能もあります。

TeamsJS v.2.0 以降では、API は JavaScript 名前空間の関数として定義されます。この名前は、必要な機能と一致します。 たとえば、アプリがダイアログ機能をサポートするホストで実行されている場合、アプリは (名前空間で定義されている他のダイアログ関連の API に加えて) dialog.open などの API を安全に呼び出すことができます。 アプリがそのホストでサポートされていない API を呼び出そうとすると、API によって例外が生成されます。

ヒント

その機能 (名前空間) で isSupported() 関数を呼び出して、特定の機能の実行時にホスト サポートを確認します。

アプリ エクスペリエンスを差別化する

その機能 (名前空間) で isSupported() 関数を呼び出して、特定の機能の実行時にホスト サポートを確認できます。 サポートされている場合は true を返し、サポートされていない場合は false し、必要に応じてアプリの動作を調整できます。 これにより、アプリは、サポートするホストの UI と機能を明らかにしながら、サポートしないホストで引き続き実行できます。

アプリが動作するホスト名は、Context インターフェイス (app.Context.app.host.name) の HostName 列挙値として表示されます。 これを実行時にクエリするには、 getContextを呼び出します。 クラシック Teams クライアントの場合、この値は 不明 または 未定義として返される場合があります。 この場合、これらの値をクラシック Teams にマップします。

{hostName} URL プレースホルダー値も使用できます。 ただし、 hostName メカニズムは慎重に使用することをお勧めします。

  • hostName プロパティ値に基づいて、特定の機能がホストで使用できる、またはできないとは考えないでください。 代わりに、機能サポート (isSupported) を確認します。
  • hostName を使用して API 呼び出しをゲートしないでください。 代わりに、機能サポート (isSupported) を確認します。
  • hostName は、実行中のホストに基づいてアプリケーションのテーマを区別するために使用します。 たとえば、Teamsで実行する場合は Microsoft Teams の紫色を主なアクセント カラーとして使用し、Outlook で実行する場合は Outlook の青を使用できます。
  • hostName は、実行中のホストに基づいてユーザーに表示されるメッセージを区別するために使用します。 たとえば、Web 上の Microsoft 365 で実行する場合は Microsoft 365 でタスクを管理 し、Teams で実行する場合 は Teams でタスクを管理 するを示します。

ヒント

ベスト プラクティスは、アプリコードをホスト固有のロジックで特別に大文字と小文字を区別するのではなく、ホストに依存しない方法でアプリのランタイム要件と依存関係を指定することです。 詳細については、 アプリ マニフェストで Microsoft 365 ホスト ランタイム要件を指定する方法に関するページを参照してください。

名前空間

TeamsJS v.2.0 以降、API は名前空間として機能に編成されます。 特に重要な新しい名前空間には、app、pages、dialog、teamsCore があります。

app 名前空間

app名前空間には、Teams、Microsoft 365 アプリ、Outlook 全体で、アプリ全体の使用に必要なトップレベル API が含まれています。 他のさまざまな TeamsJS 名前空間のすべての API は、TeamsJS v.2.0 の時点で app 名前空間に移動されます。

元の名前空間 global (window) 新しい名前空間 app
executeDeepLink app.openLink (名前の変更)
initialize app.initialize
getContext app.getContext
registerOnThemeChangeHandler app.registerOnThemeChangeHandler
元の名前空間 appInitialization 新しい名前空間 app
appInitialization.notifyAppLoaded app.notifyAppLoaded
appInitialization.notifySuccess app.notifySuccess
appInitialization.notifyFailure app.notifyFailure
appInitialization.notifyExpectedFailure app.notifyExpectedFailure
appInitialization.FailedReason 列挙 app.FailedReason
appInitialization.ExpectedFailureReason 列挙 app.ExpectedFailureReason
appInitialization.IFailedRequest 列挙 app.IFailedRequest
appInitialization.IExpectedFailureRequest 列挙 app.IExpectedFailureRequest
pages 名前空間

pages名前空間には、Teams、Microsoft 365 アプリ、Outlook など、さまざまな Microsoft 365 ホスト内で Web ページを実行および移動するための機能が含まれています。 また、サブ名前空間として実装されるいくつかのサブ機能も含まれています。

元の名前空間 global (window) 新しい名前空間 pages
setFrameContext pages.setCurrentFrame (名前の変更)
initializeWithFrameContext pages.initializeWithFrameContext
registerFocusEnterHandler pages.registerFocusEnterHandler
registerFullScreenHandler pages.registerFullScreenHandler
returnFocus pages.returnFocus
shareDeepLink pages.shareDeepLink
元の名前空間 settings 新しい名前空間 pages
settings.getSettings pages.getConfig (名前の変更)
pages.tabs
元の名前空間 global (window) 新しい名前空間 pages.tabs
getTabInstances pages.tabs.getTabInstances
getMruTabInstances pages.tabs.getMruTabInstances
元の名前空間 navigation 新しい名前空間 pages.tabs
navigation.navigateToTab pages.tabs.navigateToTab
pages.config
元の名前空間 settings 新しい名前空間 pages.config
settings.setSettings pages.config.setConfig (名前の変更)
settings.setValidityState pages.config.setValidityState
settings.initialize pages.config.initialize
settings.registerOnSaveHandler pages.config.registerOnSaveHandler
settings.registerOnRemoveHandler pages.config.registerOnRemoveHandler
settings.Settings インターフェイス pages.config.Config (名前の変更)
settings.SaveEvent インターフェイス pages.config.SaveEvent (名前の変更)
settings.RemoveEvent インターフェイス pages.config.RemoveEvent (名前の変更)
settings.SaveParameters インターフェイス pages.config.SaveParameters (名前の変更)
settings.SaveEventImpl インターフェイス pages.config.SaveEventImpl (名前の変更)
元の名前空間 global (window) 新しい名前空間 pages.config
registerChangeConfigHandler pages.config.registerChangeConfigHandler (名前の変更)
pages.backStack
元の名前空間 navigation 新しい名前空間 pages.backStack
navigation.navigateBack pages.backStack.navigateBack
元の名前空間 global (window) 新しい名前空間 pages.backStack
registerBackButtonHandler pages.backStack.registerBackButtonHandler
pages.appButton
元の名前空間 global (window) 新しい名前空間 pages.appButton
registerAppButtonClickHandler pages.appButton.onClick (名前の変更)
registerAppButtonHoverEnterHandler pages.appButton.onHoverEnter (名前の変更)
registerAppButtonHoverLeaveEnter pages.appButton.onHoverLeave (名前の変更)
FrameContext インターフェイス pages.appButton.FrameInfo (名前の変更)
dialog 名前空間

注:

ダイアログの表示に使用する window.alert、 window.confirm、 window.prompt API は、新しい Teams クライアントではサポートされていません。 Fluent V9 ダイアログを使用する場合や、Microsoft Teams JavaScript クライアント ライブラリ (TeamsJS) を使用してアダプティブ カードや入れ子になった<iframe>を使用して Teams ダイアログを表示するなど、独自のフレーム内にダイアログをレンダリングすることをお勧めします。

TeamsJS タスク 名前空間の名前が ダイアログに変更され、次の API の名前が変更されます。

元の名前空間 tasks 新しい名前空間 dialog
tasks.startTask dialog.url.open, dialog.url.bot.open, dialog.adaptiveCard.open, dialog.adaptiveCard.bot.open
tasks.submitTask dialog.url.submit (名前の変更)
tasks.updateTask dialog.update (名前の変更)
tasks.TaskModuleDimension 列挙 dialog.DialogDimension (名前の変更)
tasks.TaskInfo インターフェイス dialog.DialogInfo (名前の変更)

さらに、この機能は 2 つのメインサブキャパビリティに分割されます。HTML ベースのダイアログの場合はdialog.url、アダプティブ カード ベースのダイアログの場合はdialog.adaptiveCard、ボットベースのダイアログにはさらにサブネームスペースがあります。

teamsCore 名前空間

Microsoft 365 アプリや Outlook などの他の Microsoft 365 ホストを実行するように TeamsJS ライブラリを一般化するために、Teams 固有の機能 (もともと はグローバル 名前空間) が teamsCore 名前空間に移動されます。

元の名前空間 global (window) 新しい名前空間 teamsCore
enablePrintCapability teamsCore.enablePrintCapability
print teamsCore.print
registerOnLoadHandler teamsCore.registerOnLoadHandler
registerBeforeUnloadHandler teamsCore.registerBeforeUnloadHandler

Context インターフェイスの更新

Context インターフェイスは、app名前空間に移動され、Teams に加えて Outlook と Microsoft 365 アプリで実行されるスケーラビリティを向上させるために同様のプロパティをグループ化するように更新されます。

ホスト アプリケーションに応じてユーザー エクスペリエンスを区別するためのタブを有効にするために、新しいプロパティ app.Context.app.host.name が追加されます。

TeamsJS バージョン 2.x.x ソース (app.ts ファイル) のtransformLegacyContextToAppContext関数を確認して、変更を視覚化することもできます。

Context インターフェイスでの元の名前 app.Context の新しい場所
appIconPosition app.Context.app.iconPositionVertical
appLaunchId NOT IN TeamsJS v.2.0
appSessionId app.Context.app.sessionId
channelId app.Context.channel.id
channelName app.Context.channel.displayName
channelRelativeUrl app.Context.channel.relativeUrl
channelType app.Context.channel.membershipType
chatId app.Context.chat.id
defaultOneNoteSectionId app.Context.channel.defaultOneNoteSectionId
entityId app.Context.page.id
frameContext app.Context.page.frameContext
groupId app.Context.team.groupId
hostClientType app.Context.app.host.clientType
hostTeamGroupId app.Context.channel.ownerGroupId
hostTeamTenantId app.Context.channel.ownerTenantId
isCallingAllowed app.Context.user.isCallingAllowed
isFullScreen app.Context.page.isFullScreen
isMultiWindow app.Context.page.isMultiWindow
isPSTNCallingAllowed app.Context.user.isPSTNCallingAllowed
isTeamArchived app.Context.team.isArchived
locale app.Context.app.locale
loginHint app.Context.user.loginHint
meetingId app.Context.meeting.id
osLocaleInfo app.Context.app.osLocaleInfo
parentMessageId app.Context.app.parentMessageId
ringId app.Context.app.host.ringId
sessionId app.Context.app.host.sessionId
sourceOrigin app.Context.page.sourceOrigin
subEntityId app.Context.page.subPageId
teamId app.Context.team.internalId
teamSiteDomain app.Context.sharepointSite.domain
teamSitePath app.Context.sharepointSite.path
teamSiteUrl app.Context.sharepointSite.url
teamTemplateId app.Context.team.templateId
teamType app.Context.team.type
tenantSKU app.Context.user.tenant.teamsSku
tid app.Context.user.tenant.id
upn app.Context.user.userPrincipalName
userClickTime app.Context.app.userClickTime
userFileOpenPreference app.Context.app.userFileOpenPreference
userLicenseType app.Context.user.licenseType
userObjectId app.Context.user.id
userTeamRole app.Context.team.userRole
該当なし app.Context.app.host.name

TeamsJS バージョン 2.0 への更新

TeamsJS バージョン 2.0.x で Teams アプリを更新する最も簡単な方法は、Visual Studio Code 用 の Teams Toolkit 拡張機能 を使用することです。 このセクションでは、その手順について説明します。 コードを手動で更新する場合は、必要な API の変更の詳細については、「Promise と APIに変換されたコールバック」セクションを参照してください。

1. 最新の Teams Toolkit Visual Studio Code 拡張機能をインストールする

Visual Studio Code Extensions Marketplace で、Teams Toolkit を検索し、最新バージョンをインストールします。

2. TeamsJS 参照を更新する

Outlook と Microsoft 365 アプリで実行するには、アプリが npm パッケージ@microsoft/teams-js@2.0.0 (以降) に依存している必要があります。 これらの手順を手動で実行する方法と、API の変更の詳細については、「コールバックの Promise への変換」と「API の機能への編成」に関する以下のセクションを参照してください。

  1. 最新の Teams Toolkit (バージョン 2.10.0 以降) があることを確認します
  2. コマンド パレットを開きます: Ctrl+Shift+P
  3. コマンド Teams: Upgrade Teams JS SDK references to support Outlook and Microsoft 365 apps を実行します。

完了すると、ユーティリティは TeamsJS バージョン 2.x.x (@microsoft/teams-js@2.0.0 以降) の依存関係を使用してpackage.json ファイルを更新し、*.js/.tsと*.jsx/.tsxは次のように更新されます。

重要

html ファイル内のコードはアップグレード ツールではサポートされていないため、手動で変更する必要があります。

3. アプリ マニフェストを更新する (省略可能)

Microsoft 365 アプリと Outlook で実行するように Teams アプリを更新する場合は、アプリ マニフェストをバージョン 1.13 以降に更新する必要もあります。 これは、Teams Toolkit で簡単に行うか、手動で行うことができます。

  1. コマンド パレットを開きます: Ctrl+Shift+P
  2. Teams を実行する: Outlook と Microsoft 365 apps コマンドをサポートするように Teams マニフェストをアップグレードし、アプリ マニフェスト ファイルを選択します。 変更が行われます。

Teams Toolkit を使用して個人用アプリを作成した場合は、それを使用してアプリ マニフェスト ファイルの変更を検証し、エラーを特定することもできます。 コマンド パレットを開いてTeams をCtrl+Shift+P見つけます。マニフェスト ファイルを検証するか、Teams ツールキットの [配置] メニューからオプションを選択します (Visual Studio Code の左側にある Teams アイコンを探します)。

Teams ツールキット [配置] メニューの [マニフェスト ファイルの検証] オプション

次の手順