JavaScript-Clientbibliothek für Teams

Die Microsoft Teams JavaScript-Clientbibliothek (TeamsJS) kann Ihnen helfen, gehostete Erfahrungen in Teams, der Microsoft 365-App und Outlook zu erstellen, in denen Ihre App-Inhalte in einem iFrame gehostet werden. Die Bibliothek ist hilfreich für die Entwicklung von Apps mit den folgenden Teams-Funktionen:

• Registerkarten
• Dialogfelder (in TeamsJS v1.x als Aufgabenmodule bezeichnet)

Ab Version 2.0.0wird die vorhandene TeamsJS-Bibliothek (@microsoft/teams-jsoder einfach TeamsJS) umgestaltet, damit Teams-Apps zusätzlich zu Microsoft Teams auch in Outlook und der Microsoft 365-App ausgeführt werden können. Aus funktionaler Sicht unterstützt die neueste Version von TeamsJS alle vorhandenen (v.1.x.x) Teams-App-Funktionen und fügt die optionale Möglichkeit hinzu, Teams-Apps in Outlook und der Microsoft 365-App zu hosten.

Hier finden Sie die Versionsanleitung für verschiedene App-Szenarien:

* Verwenden Sie das neueste TeamsJS, um von den neuesten Verbesserungen und neuer Featureunterstützung zu profitieren, einschließlich reiner Teams-Apps. TeamsJS v1.13.0 enthält keine neuen Features oder Verbesserungen. Neue App-Übermittlungen und -Updates erfordern jetzt TeamsJS v2.19.0 oder höher. Weitere Informationen finden Sie unter TeamsJS-Bibliothek.

** Wenn Sie Ihre persönliche Registerkarte oder Nachrichtenerweiterungs-App von Teams auf Manifestversion 1.13 oder höher aktualisieren, wird sie standardmäßig für alle Microsoft 365-Hosts verfügbar. Um ein teilweises Laden in nicht unterstützten Hosts zu vermeiden und eine konsistente Benutzererfahrung zu gewährleisten, definieren Sie Laufzeitanforderungen im Manifest, um zu steuern, wo und wie Ihre App angezeigt wird. Weitere Informationen finden Sie unter Angeben der Anforderungen an die Microsoft 365-Hostlaufzeit im App-Manifest.

Im restlichen Teil dieses Artikels werden Sie durch die Struktur und die neuesten Updates der TeamsJS-Bibliothek geführt.

Microsoft 365-Support (Ausführen von Teams-Apps in Microsoft 365 und Outlook)

TeamsJS v.2.0 führt die Möglichkeit ein, bestimmte Arten von Teams-Apps über das gesamte Microsoft 365-Ökosystem hinweg auszuführen. Die anderen Microsoft 365-Anwendungshosts (einschließlich Microsoft 365-App und Outlook) für Teams-Apps unterstützen eine Teilmenge der Anwendungstypen und Funktionen, die Sie für die Teams-Plattform erstellen können. Diese Unterstützung wird im Laufe der Zeit erweitert. Eine Zusammenfassung der Hostunterstützung für Teams-Apps finden Sie unter TeamsJS-Funktionsunterstützung in Microsoft 365.

Verbessern der Ladezeitleistung mit JavaScript Tree Shaking

Ab Version 2.31.0 und höher ist die TeamsJS-Bibliothek vollständig baumschüttelbar. Tree Shaking ist eine JavaScript-Optimierung, die nicht verwendeten Code eliminiert. Durch die Verwendung von Tree Shaking beim Bündeln einer App für die Bereitstellung können Sie die Paketgröße reduzieren, was zu einem schnelleren Download und einer verbesserten Ladezeit führt.

So verwenden Sie Baumschütteln mit TeamsJS

Um die Vorteile von Tree Shaking beim Bündeln Ihres App-Pakets zu nutzen, verwenden Sie einen Bundler, der Tree Shaking unterstützt, z. B. Webpack oder Rollup. Wenn Tree Shaking aktiviert ist, wird der gesamte nicht verwendete TeamsJS-Code automatisch im endgültigen Bundle entfernt. Betrachten Sie beispielsweise den folgenden Code:

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
}

Angenommen, das barCode-Modul in TeamsJS enthält die vier Funktionen hasPermission(), isSupported(), requestPermission(), und scanBarCode(BarCodeConfig). Wenn eine App nur die hasPermission() Funktion verwendet, werden nach dem Tree Shaking die anderen drei Funktionen aus dem App-Bundle ausgeschlossen. Dadurch wird sichergestellt, dass Apps so einfach wie möglich bleiben und nur den Code enthalten, den sie benötigen.

Neuigkeiten in TeamsJS Version 2.x.x

Es gibt zwei wesentliche Änderungen zwischen TeamsJS 1.x.x-Versionen und v.2.0.0 und höher:

• Rückruffunktionen geben jetzt Promise-Objekte zurück. Die meisten Funktionen mit Rückrufparametern in TeamsJS v.1.12 wurden modernisiert, um ein JavaScript Promise-Objekt zurückzugeben, um die Handhabung asynchroner Vorgänge und die Lesbarkeit des Codes zu verbessern.

• APIs sind jetzt in Funktionen organisiert. Sie können sich Funktionen als logische Gruppierungen von APIs vorstellen, die ähnliche Funktionen bereitstellen, z. B authentication. , dialog, chatund calendar. Jeder Namespace stellt eine separate Funktion dar.

Abwärtskompatibilität

Sobald Sie mit dem Verweisen @microsoft/teams-js@2.0.0 aus einer vorhandenen Teams-App beginnen (oder später), werden Veraltungswarnungen für alle Codeaufruf-APIs angezeigt, die geändert werden.

Eine API-Übersetzungsebene (Zuordnung von v.1 zu v.2 TeamsJS-API-Aufrufen) wird bereitgestellt, damit vorhandene Teams-Apps weiterhin in Teams arbeiten können, bis sie den Anwendungscode aktualisieren können, um die TeamsJS v.2-API-Muster zu verwenden.

Authentifizierung

In TeamsJS Version 2.11.0 oder höher müssen Apps einen dritten URL-Parameter hostRedirectUrl(, in der Authentifizierungs-API) bereitstellen, um Benutzer nach Abschluss der Authentifizierung zum richtigen Client umzuleiten. Der hostRedirectUrl Authentifizierungsparameter ist erforderlich, damit Ihr Client in allen Microsoft 365-Hostanwendungen unterstützt werden kann. Apps, die in älteren Versionen implementiert sind TeamsJS , unterstützen Teams nach diesem Update nur, da die oauthRedirectmethod Abfrageparameter und authId an den App-Server des Drittanbieters übergeben werden.

Weitere Informationen zum Authentifizierungsparameter finden Sie unter Verwenden externer OAuth-Anbieter.

Teams-Apps, die im gesamten Microsoft 365-Ölkosystem ausgeführt werden können

Im Folgenden finden Sie die Anforderungen, um die Ausführung einer vorhandenen Teams-App in Outlook und Microsoft 365 zu aktivieren:

1. Abhängigkeit von TeamsJS-Version 2.x.x ( @microsoft/teams-js@2.0.0) oder höher.

2. Ändern Sie den vorhandenen Anwendungscode entsprechend den in diesem Artikel beschriebenen erforderlichen Änderungen.

3. Aktualisieren Sie Ihr App-Manifest (früher als Teams-App-Manifest bezeichnet) auf Version 1.13 oder höher.

Weitere Informationen finden Sie unter Erweitern von Teams-Apps in Microsoft 365.

In Zusagen konvertierte Rückrufe

Teams-APIs, die zuvor einen Rückrufparameter akzeptiert haben, werden aktualisiert, um ein JavaScript Promise-Objekt zurückzugeben. Dazu gehören die folgenden APIs:

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

Sie müssen die Art und Weise aktualisieren, wie Ihr Code eine dieser APIs aufruft, um Zusagen zu verwenden. Wenn Ihr Code z. B. eine Teams-API wie folgt aufruft:

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

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

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

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

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

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

import * as microsoftTeams from "@microsoft/teams-js";
microsoftTeams.app.getContext().then((context:  microsoftTeams.app.Context) => { 
/* ... */ 
});

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

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

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

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

Die Cloudübergreifende Kommunikation über SDK ist aus Sicherheitsgründen eingeschränkt. Daher sind Teams, die von der Domäne 21Vianet betrieben werden, nicht in validOriginsenthalten. Um die Funktion einer App in Teams, die von 21Vianet betrieben werden, zu ermöglichen, geben Sie die von 21Vianet betriebene Teams-Domäne während der SDK-Initialisierung in Ihrer App-Bereitstellung mithilfe des validMessageOrigins-Parameters an.

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

In Funktionen unterteilte APIs

Eine Funktion ist eine logische Gruppierung (über Namespaces) von APIs, die ähnliche Funktionen bereitstellen. Sie können sich Microsoft Teams, Outlook und die Microsoft 365-App als Hosts für Ihre Registerkarten-App vorstellen. Ein Host unterstützt eine bestimmte Funktion, wenn er alle in dieser Funktion definierten APIs unterstützt. Ein Host kann eine Funktion nicht teilweise implementieren. Funktionen können feature- oder inhaltsbasiert sein, z. B. authentication (Authentifizierung) oder dialog (Dialogfeld). Es gibt auch Funktionen für Anwendungstypen wie Seiten und andere Gruppierungen.

Ab TeamsJS v.2.0 werden APIs als Funktionen in einem JavaScript-Namespace definiert, dessen Name der erforderlichen Funktion entspricht. Wenn eine App beispielsweise auf einem Host ausgeführt wird, der die dialog-Funktion (Dialogfeld) unterstützt, kann die App sicher APIs aufrufen, z. B. dialog.open (zusätzlich zu anderen dialogfeldbezogenen APIs, die im Namespace definiert sind). Wenn eine App versucht, eine API aufzurufen, die auf diesem Host nicht unterstützt wird, generiert die API eine Ausnahme.

Ableiten Ihrer App-Umgebung

Sie können die Hostunterstützung einer bestimmten Funktion zur Laufzeit überprüfen, indem Sie die Funktion isSupported() für diese Funktion (Namespace) aufrufen. Es wird zurückgegeben true , ob es unterstützt wird und false wenn nicht, und Sie können das App-Verhalten entsprechend anpassen. Auf diese Weise kann Ihre App Benutzeroberflächen und Funktionen in Hosts nutzen, die diese unterstützen, kann aber weiterhin auch für Hosts ausgeführt werden, die diese nicht unterstützen.

Der Hostname, auf dem Context Ihre App ausgeführt wird, wird als HostName-Enumerationswert der Schnittstelle () app.Context.app.host.nameangezeigt. Sie können dies zur Laufzeit abfragen, indem Sie getContext. Für den klassischen Teams-Client kann dieser Wert als unbekannt oder undefiniert zurückgegeben werden. Ordnen Sie in diesem Fall diese Werte klassischen Teams zu.

Der {hostName}URL-Platzhalterwert ist ebenfalls verfügbar. Es wird jedoch empfohlen, den hostName-Mechanismus mit Diskretion zu verwenden.

• Gehen Sie nicht basierend auf dem HostName-Eigenschaftswert davon aus, dass bestimmte Funktionen auf einem Host verfügbar sind oder nicht verfügbar sind. Überprüfen Sie stattdessen die Unterstützung der Funktion (isSupported).
• Sie sollten hostNamenicht verwenden, um API-Aufrufe Gates zuzuweisen. Überprüfen Sie stattdessen die Unterstützung der Funktion (isSupported).
• Sie sollten hostNameverwenden, um das Design Ihrer Anwendung basierend auf dem Host, auf dem sie ausgeführt wird, zu unterscheiden. Sie können das Lila von Microsoft Teams beispielsweise als Hauptakzentfarbe verwenden, wenn die App in Teams ausgeführt wird, und das Blau von Outlook, wenn sie in Outlook ausgeführt wird.
• Sie sollten hostNameverwenden, um Nachrichten, die dem Benutzer angezeigt werden, basierend auf dem Host, auf dem die App ausgeführt wird, zu unterscheiden. Zeigen Sie z. B. Verwalten Sie Ihre Aufgaben in Microsoft 365 , wenn Sie in Microsoft 365 im Web ausführen, und Verwalten Sie Ihre Aufgaben in Teams , wenn Sie in Teams ausführen.

Namespaces

Ab TeamsJS v.2.0 werden APIs mithilfe von Namespaces in Funktionen unterteilt. Einige neue Namespaces von besonderer Bedeutung sind app, pages, dialog und teamsCore.

Namespace app(App)

Der app Namespace enthält APIs der obersten Ebene, die für die allgemeine App-Nutzung in Teams, der Microsoft 365-App und Outlook erforderlich sind. Alle APIs aus verschiedenen anderen TeamsJS-Namespaces werden ab TeamsJS v.2.0 in den app Namespace verschoben:

Namespace pages (Seiten)

Der pages Namespace enthält Funktionen zum Ausführen und Navigieren von Webseiten in verschiedenen Microsoft 365-Hosts, einschließlich Teams, Microsoft 365 App und Outlook. Er enthält auch mehrere Unterfunktionen, die als Unternamespaces implementiert sind.

pages.tabs

pages.config

pages.backStack

pages.appButton

Namespace dialog (Dialogfeld)

Der TeamsJS-Aufgabennamespace wird in Dialog umbenannt, und die folgenden APIs werden umbenannt:

Darüber hinaus ist diese Funktion in zwei Hauptunterfunktionen unterteilt, dialog.url für HTML-basierte Dialoge und dialog.adaptiveCard für adaptive kartenbasierte Dialoge, mit weiteren Unternamespaces für Bot-basierte Dialoge.

Namespace teamsCore

Um die TeamsJS-Bibliothek auf die Ausführung anderer Microsoft 365-Hosts wie der Microsoft 365-App und Outlook zu generalisieren, werden teamsspezifische Funktionen (ursprünglich im globalen Namespace) in einen teamsCore-Namespace verschoben:

Aktualisierungen der Context-Schnittstelle

Die Context Schnittstelle wird in den app Namespace verschoben und aktualisiert, um ähnliche Eigenschaften zu gruppieren, um eine bessere Skalierbarkeit zu erzielen, da sie zusätzlich zu Teams in Outlook und der Microsoft 365-App ausgeführt wird.

Es wird eine neue Eigenschaft app.Context.app.host.name hinzugefügt, mit der Registerkarten je nach Hostanwendung unterschiedlicher Benutzererfahrung unterscheiden können.

Sie können die Änderungen auch visualisieren, indem Sie die transformLegacyContextToAppContext Funktion in der TeamsJS-Quelle (app.ts-Datei) Version 2.x.x überprüfen.

Aktualisieren auf TeamsJS Version 2.0

Die einfachste Möglichkeit, Ihre Teams-App mit TeamsJS Version 2.0.x zu aktualisieren, ist die Verwendung der Agents Toolkit-Erweiterung für Visual Studio Code. In diesem Abschnitt werden Sie durch die dazu erforderlichen Schritte geführt. Wenn Sie Ihren Code lieber manuell aktualisieren möchten, finden Sie in den Abschnitten "Rückrufe, die in Zusagen konvertiert wurden, und APIs, die in Funktionen organisiert sind ", weitere Informationen zu erforderlichen API-Änderungen.

1. Installieren Sie die neueste Agents Toolkit Visual Studio Code-Erweiterung

Suchen Sie im Visual Studio Code Extensions Marketplace nach Microsoft 365 Agents Toolkit und installieren Sie die neueste Version.

2. Aktualisieren von TeamsJS-Referenzen

Damit sie in Outlook und der Microsoft 365-App ausgeführt werden kann, muss Ihre App vom npm-Paket@microsoft/teams-js@2.0.0 (oder höher) abhängen. Wenn Sie diese Schritte manuell ausführen möchten und weitere Informationen zu den API-Änderungen benötigen, lesen Sie die Abschnitte In Zusagen konvertierte Rückrufe und APIs, die in Funktionen unterteilt sind.

1. Stellen Sie sicher, dass Sie über das neueste Agents-Toolkit (Version 2.10.0 oder höher) verfügen.
2. Öffnen Sie die Befehlspalette: Ctrl+Shift+P
3. Führen Sie den Befehl Teams: Upgrade Teams JS SDK references to support Outlook and Microsoft 365 apps aus.

Nach Abschluss aktualisiert das Hilfsprogramm Ihre package.json Datei mit der Abhängigkeit von TeamsJS Version 2.x.x (@microsoft/teams-js@2.0.0 oder höher), und Ihre *.js/.ts und *.jsx/.tsx werden aktualisiert mit:

3. Aktualisieren des App-Manifests (optional)

Wenn Sie eine Teams-App für die Ausführung in der Microsoft 365-App und Outlook aktualisieren, müssen Sie auch das App-Manifest auf Version 1.13 oder höher aktualisieren. Sie können dies ganz einfach mit dem Agents Toolkit oder manuell tun.

{
    "$schema" : "https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
    "manifestVersion" : "1.13"
}

Wenn Sie das Agents-Toolkit zum Erstellen Ihrer persönlichen App verwendet haben, können Sie es auch verwenden, um die Änderungen an Ihrer App-Manifestdatei zu überprüfen und Fehler zu identifizieren. Öffnen Sie die Befehlspalette Ctrl+Shift+P , und suchen Sie Teams: Manifestdatei validieren, oder wählen Sie die Option aus dem Menü "Bereitstellung" des Agents-Toolkits aus (suchen Sie nach dem Teams-Symbol auf der linken Seite von Visual Studio Code).

Nächste Schritte

• Verwenden Sie die TeamsJS-Bibliotheksreferenz , um mit der TeamsJS-Bibliothek zu beginnen.
• Überprüfen Sie das Änderungsprotokoll auf die neuesten Updates für TeamsJS.