S’abonner aux notifications de liste

Article
03/21/2023

Introduit dans SharePoint Framework v1.7.0, vous pouvez vous abonner aux modifications apportées aux fichiers stockés dans une bibliothèque de documents SharePoint. Vous pouvez ainsi répondre aux modifications le cas échéant, sans avoir besoin d’interroger régulièrement le contenu de la bibliothèque.

Configuration requise

Pour utiliser la fonctionnalité d’abonnement de liste SharePoint Framework, vous devez d’abord installer le package npm @microsoft/sp-list-subscription. Pour ce faire, utilisez l’extrait de code suivant :

npm install @microsoft/sp-list-subscription --save --save-exact

Recevoir des notifications sur les modifications apportées aux documents stockés dans une bibliothèque de documents SharePoint

Pour vous abonner aux modifications apportées aux fichiers stockés dans une bibliothèque de documents SharePoint, créez une instance de la classe ListSubscriptionFactory. Ensuite, appelez la méthode createSubscription() en transmettant l’ID de la bibliothèque de documents à laquelle vous voulez vous abonner. Si la bibliothèque de documents se trouve dans le site actuel, il suffit de spécifier l’ID de bibliothèque. S’il se trouve dans un autre site ou collection de sites, vous devez également spécifier leurs ID.

Voici un exemple d’abonnement aux listes pour une bibliothèque de documents qui se trouve dans le site actuel :

import { ListSubscriptionFactory, IListSubscription } from '@microsoft/sp-list-subscription';
import { Guid } from '@microsoft/sp-core-library';

export default class LatestDocumentsWebPart extends BaseClientSideWebPart<ILatestDocumentsWebPartProps> {
  private _listSubscriptionFactory: ListSubscriptionFactory;
  private _listSubscription: IListSubscription;

  private async createListSubscription(): Promise<void> {
    this._listSubscriptionFactory = new ListSubscriptionFactory(this);
    this._listSubscription = await this._listSubscriptionFactory.createSubscription({
      listId: Guid.parse(this.properties.listId),
      callbacks: {
        notification: this._loadDocuments.bind(this)
      }
    });
  }

  private _loadDocuments(): void {
    // load documents here
  }

  // omitted for brevity
}

Lorsque vous créez un abonnement aux listes à l’aide de la propriété callbacks.notification, vous devez spécifier la méthode à appeler lorsqu’une modification est détectée. La méthode n’accepte aucun argument. Pour des raisons de sécurité, vous ne recevez pas de notification indiquant exactement ce qui a été modifié. Pour obtenir le contenu le plus récent de la bibliothèque de documents, conformément aux autorisations configurées, vous pouvez utiliser les API REST de SharePoint ou Microsoft Graph.

Configuration supplémentaire

En fonction de votre solution, vous devrez peut-être procéder à une configuration supplémentaire lorsque vous vous abonnez aux notifications de liste.

Se connecter à une collection de sites dans un client Multi-Géo

Si vous utilisez SharePoint dans un client Multi-Géo, vous devez fournir le domaine dans lequel se trouve la collection de sites particulière. Pour ce faire, utilisez la propriété domain. Par exemple :

this._listSubscriptionFactory.createSubscription({
  domain: this.properties.siteDomain,
  siteId: Guid.parse(this.properties.siteId),
  webId: Guid.parse(this.properties.webId),
  listId: Guid.parse(this.properties.listId),
  callbacks: {
    notification: this._loadDocuments.bind(this)
  }
});

Recevoir une notification lorsque l’abonnement a été établi ou annulé

Dans certains cas, vous souhaiterez être averti si le composant que vous créez s’est abonné correctement aux notifications de liste ou si la connexion a été interrompue. Cela vous permet de communiquer la connexion à l’utilisateur via l’interface utilisateur.

L’API d’abonnement de liste expose deux rappels supplémentaires que vous pouvez implémenter pour répondre à l’état de l’abonnement. Le code suivant illustre le cas où le composant est averti lorsque de l’abonnement est établi et lorsqu’il est déconnecté.

private createListSubscription(): void {
  this._listSubscriptionFactory.createSubscription({
    domain: this.properties.siteDomain,
    siteId: Guid.parse(this.properties.siteId),
    webId: Guid.parse(this.properties.webId),
    listId: Guid.parse(this.properties.listId),
    callbacks: {
      notification: this._loadDocuments.bind(this),
      connect: this._subscriptionConnected.bind(this),
      disconnect: this._subscriptionDisconnected.bind(this)
    }
  });
}

private _subscriptionConnected(): void {
  // code to execute when the subscription to the list has been established
}

private _subscriptionDisconnected(reason: string): void {
  // code to execute when the connection to the list has been disconnected
}

La méthode relative au rappel callbacks.disconnect transmet la raison pour laquelle la connexion a été déconnectée en tant qu’argument. Les valeurs possibles sont io server disconnect, lorsque la connexion a été interrompue par le client, ou io client disconnect lorsque le serveur a fermé la connexion.

Considérations

tous les composants SharePoint Framework peuvent utiliser les fonctionnalités d’abonnement de liste
vous pouvez vous abonner à des événements à partir de bibliothèques et de listes
il y a quelques secondes de retard entre la modification et la réception de la notification par le composant
les composants peuvent s’abonner aux modifications dans plusieurs bibliothèques de documents
La notification de modification ne transmet pas d’informations sur le document ajouté ou modifié. Pour afficher ce qui a été modifié, utilisez l’API REST SharePoint ou Microsoft Graph.

Voir aussi

Exemple de code d’abonnement aux listes

Partager via