订阅列表通知

项目
03/21/2023

SharePoint 框架 v1.7.0 中引入，您可以订阅对存储在 SharePoint 文档库中的文件所做的更改。这样当发生更改时就可以作出响应，而无需定期轮询库的内容。

先决条件

若要使用SharePoint 框架列表订阅功能，首先需要安装 @microsoft/sp-list-subscription npm 包。可以使用以下代码片段进行安装：

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

SharePoint 文档库中存储的文档发生更改时收到相关通知。

若要订阅对 SharePoint 文档库中存储的文件的更改，先创建 ListSubscriptionFactory 类的实例。然后调用 createSubscription() 方法来传递想要订阅的文档库的 ID。如果文档库位于当前网站，则仅指定库 ID 即可。如果它位于其他网站或网站集中，则还需要指定其 ID。

下面提供了位于当前网站的文档库的列表订阅示例：

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
}

使用 callbacks.notification 属性创建列表订阅时，必须指定检测到更改后应调用的方法。此方法不包含任何参数，并且出于安全原因不会通知你更改的具体内容。可以按照配置的权限使用 SharePoint REST API 或 Microsoft Graph 获取文档库的最新内容。

其他配置

订阅列表通知时可能需要提供其他配置，具体取决于解决方案。

连接到多位置租户中的网站集

若使用多位置租户中的 SharePoint，需要提供特定网站集所在的域。可以使用 domain 属性提供，例如：

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)
  }
});

在订阅已建立或取消时收到通知

有时可能想要在所构建的部件成功订阅列表通知或在连接断开时收到通知。这样则可以通过 UI 通知用户连接状况。

列表订阅 API 公开了两个附加回调，你可以实现这些回调来响应订阅状态。以下代码说明了这种情况，即当订阅创建或断开时通知部件。

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
}

callbacks.disconnect 回调的方法以参数的形式传递连接断开的原因。可能的值有 io server disconnect（客户端断开了连接时）或 io client disconnect（服务器关闭了连接时）。

注意事项

所有SharePoint 框架组件都可以使用列表订阅功能
可以从库和列表订阅事件
更改与组件接收的通知之间有几秒钟的延迟
组件可以订阅多个文档库中的更改
更改通知不会传递所添加或更改的文档的任何相关信息。若要查看更改的内容，请使用 SharePoint REST API 或 Microsoft Graph

另请参阅

列表订阅示例代码

通过