Publier une web part SPFx en onglet et app Teams

1Étape 1 : Déclarer les hôtes Teams dans le manifeste

Ouvrez le fichier src/webparts/<nom>/<Nom>WebPart.manifest.json. La propriété supportedHosts liste les endroits où la web part peut être utilisée.

TeamsTab l'expose comme onglet dans un canal ou une conversation de groupe. TeamsPersonalApp l'expose comme application personnelle. Gardez SharePointWebPart pour continuer à l'utiliser sur les pages SharePoint.

Sans supportedHosts, l'hôte par défaut est SharePointWebPart seul. Un tableau vide retire la web part de SharePoint et du manifeste Teams généré.

Le nom et la description de l'application Teams générée viennent de preconfiguredEntries[0].title et preconfiguredEntries[0].description. Soignez-les.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/client-side-web-part-manifest.schema.json",
  "id": "<GUID du composant>",
  "alias": "MonWebPart",
  "componentType": "WebPart",
  "supportedHosts": ["SharePointWebPart", "TeamsTab", "TeamsPersonalApp"],
  "preconfiguredEntries": [
    {
      "title": { "default": "Suivi des demandes" },
      "description": { "default": "Liste des demandes de l'équipe" }
    }
  ]
}

Vérification : supportedHosts contient TeamsTab, TeamsPersonalApp ou les deux.

2Étape 2 : Détecter le contexte Teams dans le code

Quand la web part tourne dans Teams, Outlook ou l'application Microsoft 365, this.context.sdks.microsoftTeams est renseigné. Sur une page SharePoint, il est vide.

Pour lire le contexte, appelez this.context.sdks.microsoftTeams.teamsJs.app.getContext(). La propriété this.context.sdks.microsoftTeams.context est dépréciée depuis SPFx 1.16.

Le contexte TeamsJS v2 donne par exemple team.displayName, channel.displayName, app.host.name et app.theme.

N'installez pas votre propre version de @microsoft/teams-js : Microsoft ne la prend pas en charge dans un composant SPFx. Utilisez l'instance fournie par le contexte.

protected async onInit(): Promise<void> {
  await super.onInit();

  const teams = this.context.sdks.microsoftTeams;
  if (teams) {
    const ctx = await teams.teamsJs.app.getContext();
    this._hostName = ctx.app.host.name;        // "Teams", "Outlook", "Office"…
    this._teamName = ctx.team?.displayName;    // vide en application personnelle
    this._theme = ctx.app.theme;               // default | dark | contrast…
  } else {
    this._hostName = "SharePoint";
  }
}

Vérification : La web part affiche un contenu différent sur une page SharePoint et dans un onglet Teams.

3Étape 3 : Adapter le thème et la configuration

Par défaut, le thème de la web part vient du site SharePoint sous-jacent, pas de Teams. En mode sombre, le rendu peut donc détonner.

Lisez app.theme dans le contexte (default, dark, contrast, ou glass sur Apple Vision Pro) et abonnez-vous aux changements avec app.registerOnThemeChangeHandler.

En onglet de canal, le volet de propriétés de la web part sert de page de configuration. SPFx stocke les réglages pour vous. Mettez canUpdateConfiguration à false dans le manifeste pour masquer cette configuration.

Une application personnelle n'a pas de volet de propriétés. Prévoyez la configuration dans l'interface de la web part, ou dans une web part de réglages séparée.

const teams = this.context.sdks.microsoftTeams;
if (teams) {
  teams.teamsJs.app.registerOnThemeChangeHandler((theme: string) => {
    this.domElement.dataset.theme = theme; // vos styles CSS s'appuient sur cet attribut
    this.render();
  });
}

Vérification : Passer Teams en thème sombre change l'apparence de la web part sans recharger l'onglet.

4Étape 4 : Préparer le dossier teams du projet

Le dossier teams à la racine du projet contient deux icônes par composant : <componentId>_color.png et <componentId>_outline.png. Remplacez-les en gardant exactement ces noms, sinon elles ne sont pas empaquetées.

Teams attend une icône couleur de 192 × 192 pixels et une icône de contour de 32 × 32 pixels.

Pour contrôler le manifeste Teams vous-même (plusieurs onglets dans une application personnelle, identifiant et nom choisis), placez un paquet TeamsSPFxApp.zip dans ce dossier. Compressez le contenu du dossier, pas le dossier lui-même.

Dans ce manifeste, ajoutez l'entrée webApplicationInfo ci-dessous. Elle est nécessaire pour que les appels d'API réussissent depuis les clients Teams.

"webApplicationInfo": {
  "resource": "https://{teamSiteDomain}",
  "id": "00000003-0000-0ff1-ce00-000000000000"
}

Vérification : Le dossier teams contient les deux icônes au bon nom, et TeamsSPFxApp.zip si vous fournissez votre manifeste.

5Étape 5 : Construire et déployer le paquet SharePoint

Construisez le .sppkg comme d'habitude avec Heft. Le paquet embarque le dossier teams, y compris TeamsSPFxApp.zip s'il existe.

Déposez-le dans le catalogue d'applications du tenant et cochez « Make this solution available to all sites in the organization » (« Rendre cette solution disponible pour tous les sites »). Le détail du dépôt est dans notre guide sur le déploiement d'une solution SPFx dans le catalogue d'applications.

Un déploiement limité au site est possible, mais la solution doit alors être installée sur le site SharePoint de chaque équipe avant usage.

heft build --production
heft package-solution --production

ls sharepoint/solution/*.sppkg

Vérification : La colonne « App Package Error Message » du catalogue est vide pour la solution.

6Étape 6 : Publier l'application dans Teams

Dans le catalogue d'applications, sélectionnez la solution puis le bouton « Sync to Teams » du ruban (onglet Fichiers). Selon la version de l'interface, Microsoft le nomme aussi « Add to Teams ».

Sans TeamsSPFxApp.zip, SharePoint génère le manifeste et le paquet Teams, puis les publie dans le catalogue Teams de l'organisation. Avec ce fichier, il publie votre paquet tel quel.

Autre voie : chargez le paquet Teams dans le centre d'administration Teams, sous Teams apps > Manage apps > Upload new app. Le paquet généré se télécharge via _api/web/tenantappcatalog/downloadteamssolution(id)/$value, où id est l'identifiant numérique de la solution dans le catalogue.

Les stratégies d'autorisation d'applications du centre d'administration Teams décident ensuite qui peut utiliser l'application.

https://contoso.sharepoint.com/sites/appcatalog/_api/web/tenantappcatalog/downloadteamssolution(12)/$value

Vérification : Un message de synchronisation réussie s'affiche en haut à droite du catalogue.

7Étape 7 : Tester dans Teams

Dans Teams, ouvrez Applications. L'application apparaît dans la section « Built for your org ». Comptez quelques minutes à cause du cache.

Pour un onglet : dans un canal, sélectionnez +, cherchez l'application, puis Ajouter et Enregistrer. Le volet de propriétés s'ouvre pour la configuration initiale.

Pour une application personnelle : ajoutez-la depuis le magasin. Elle s'ouvre sans contexte d'équipe, donc team est vide.

Vérifiez les droits : un onglet de canal s'exécute dans le contexte du site SharePoint de l'équipe. Les données lues et les appels d'API suivent les permissions de l'utilisateur sur ce site et les autorisations d'API approuvées pour SPFx.

Vérification : L'onglet affiche le nom de l'équipe et l'application personnelle s'ouvre sans erreur.

8Étape 8 : Publier une mise à jour

Incrémentez solution.version, reconstruisez, redéposez le .sppkg puis relancez « Sync to Teams ».

Si le message « Failed to sync solution to teams » apparaît, supprimez l'ancienne version de l'application dans Teams, puis synchronisez à nouveau. La synchronisation n'écrase pas une application existante.

Si vous gérez le paquet dans le centre d'administration Teams, chargez la nouvelle version depuis la page de détails de l'application avec « Upload file ».

Vérification : Teams charge la nouvelle version de la web part dans l'onglet existant.