使用 Microsoft Graph 部件生成 SharePoint ToolkitBuild a SharePoint web part with the Microsoft Graph Toolkit

本主题介绍如何使用 Microsoft Graph Toolkit SharePoint 客户端 Web 部件中的组件This topic covers how to use Microsoft Graph Toolkit components in a SharePoint client-side web part. 入门包括以下步骤:Getting started involves the following steps:

  1. 设置开发环境并创建 Web 部件。Set up your development environment and create a web part.
  2. 更新项目中的 TypeScript。Update TypeScript in your project.
  3. 添加 Microsoft Graph Toolkit。Add the Microsoft Graph Toolkit.
  4. 添加 SharePoint 提供程序。Add the SharePoint Provider.
  5. 添加组件。Add components.
  6. 配置权限。Configure permissions.
  7. 生成和部署 Web 部件。Build and deploy your web part.
  8. 测试 Web 部件。Test your web part.

设置 SharePoint 框架开发环境并创建新的 Web 部件Set up your SharePoint Framework development environment and create a new web part

按照步骤设置SharePoint 框架开发环境,然后创建新的 Web 部件Follow the steps to Set up your SharePoint Framework development environment and then create a new web part.

更新项目中的 TypeScriptUpdate TypeScript in your project

Microsoft Graph Toolkit Typescript 3.x。The Microsoft Graph Toolkit requires Typescript 3.x. 在将Toolkit项目之前,请确保你使用的是支持的 Typescript 版本Before adding the Toolkit to your project, make sure you're using a supported version of Typescript. 例如,若要添加 Typescript 3.7,请使用以下命令:For example, to add Typescript 3.7, use the following command:

npm install @microsoft/rush-stack-compiler-3.7 --save-dev

然后,在 tsconfig.json 项目文件夹中找到该文件,打开该文件,然后查找以下行:Then, locate the tsconfig.json file in your project folder, open the file, and look for this line:

"extends": "./node_modules/@microsoft/rush-stack-compiler-3.3/includes/tsconfig-web.json",

将该行替换为:Replace the line with:

"extends": "./node_modules/@microsoft/rush-stack-compiler-3.7/includes/tsconfig-web.json",

添加 Microsoft Graph ToolkitAdd the Microsoft Graph Toolkit

通过以下Toolkit安装 Microsoft Graph Toolkit npm 包和填充:Install the Microsoft Graph Toolkit npm package and polyfills with the following command:

npm install @microsoft/mgt

如果计划在 Web 部件中支持 IE11,则需要执行其他步骤以确保跨浏览器兼容性:If you plan to support IE11 in your web parts, you'll need to follow additional steps to ensure cross-browser compatibility:

  1. 安装以下程序包:Install the following packages:
npm install -D babel-loader @babel/core @babel/preset-env webpack
npm install -D @webcomponents/webcomponentsjs regenerator-runtime core-js
  1. 将以下代码添加到 gulpfile.js 正上方 build.initialize(gulp)Add the following code to gulpfile.js, right above build.initialize(gulp):
build.configureWebpack.mergeConfig({
  additionalConfiguration: (generatedConfiguration) => {
    generatedConfiguration.module.rules.push(
      {
        test: /\.m?js$/, use:
        {
          loader: "babel-loader",
          options:
          {
            presets: [["@babel/preset-env",
              {
                targets: {
                  "ie": "11"
                }
              }]]
          }
        }
      }
    );

    return generatedConfiguration;
  }
});
  1. 在文件中,在 SharePoint 提供程序下一步 src\webparts\<your-project>\<your-web-part>.ts 中导入以下填充。In your src\webparts\<your-project>\<your-web-part>.ts file, import the following polyfills before the SharePoint provider in the next step.
import 'regenerator-runtime/runtime';
import 'core-js/es/number';
import 'core-js/es/math';
import 'core-js/es/string';
import 'core-js/es/date';
import 'core-js/es/array';
import 'core-js/es/regexp';
import '@webcomponents/webcomponentsjs/webcomponents-bundle.js';

添加 SharePoint 提供程序Add the SharePoint Provider

Microsoft Graph Toolkit提供程序为组件启用身份验证并访问 Microsoft Graph。The Microsoft Graph Toolkit providers enable authentication and access to Microsoft Graph for the components. 若要了解更多信息,请参阅"使用提供程序"。To learn more, see Using the providers. SharePoint Web 部件始终存在于经过身份验证的上下文中,因为用户已经必须登录才能访问承载 Web 部件的页面。SharePoint web parts always exist in an authenticated context because the user has already had to sign in in order to get to the page that hosts your web part. 使用此上下文初始化 SharePoint 提供程序Use this context to initialize the SharePoint provider.

首先,将提供程序添加到 Web 部件。First, add the provider to your web part. 在项目文件夹中找到该文件,将以下行添加到文件顶部,位于现有语句 src\webparts\<your-project>\<your-web-part>.ts import 的正下方:Locate the src\webparts\<your-project>\<your-web-part>.ts file in your project folder, and add the following line to the top of your file, right below the existing import statements:

import { Providers, SharePointProvider } from '@microsoft/mgt';

接下来,您需要在 Web 部件的方法内使用经过身份验证的上下文初始化 onInit() 提供程序。Next, you need to initialize the provider with the authenticated context inside the onInit() method of your web part. 在同一文件中,将以下代码添加到该行 public render(): void { 的正前:In the same file, add the following code right before the public render(): void { line:

protected async onInit() {
    Providers.globalProvider = new SharePointProvider(this.context)
}

添加组件Add components

现在,你可以开始向 Web 部件添加组件。Now, you can start adding components to your web part. 只需将组件添加到方法内的 HTML,组件将使用 render() SharePoint 上下文访问 Microsoft Graph。Simply add the components to the HTML inside of the render() method, and the components will use the SharePoint context to access Microsoft Graph. 例如,若要添加 Person 组件,代码将如下所示:For example, to add the Person component, your code will look like:

public render(): void {
    this.domElement.innerHTML = `
      <mgt-person person-query="me" view="twolines"><mgt-person>
    `;
}

配置权限Configure permissions

若要从 SharePoint 框架应用程序调用 Microsoft Graph,需要在解决方案包中请求所需的权限,并且 Microsoft 365 租户管理员需要批准请求的权限。To call Microsoft Graph from your SharePoint Framework application, you need to request the needed permissions in your solution package and a Microsoft 365 tenant administrator needs to approve the requested permissions.

若要将权限添加到解决方案包,请找到并打开 config\package-solution.json 该文件并设置:To add the permissions to your solution package, locate and open the config\package-solution.json file and set:

"isDomainIsolated": false,

在该行正下方,添加以下内容:Just below that line, add the following:

"webApiPermissionRequests":[],

根据你使用的组件确定你需要哪些 Microsoft Graph API 权限。Determine which Microsoft Graph API permissions you need depending on the components you're using. 每个组件的文档页都提供组件所需的权限列表。Each component's documentation page provides a list of the permissions that component requires. 您需要将所需的每个权限添加到 webApiPermissionRequestsYou will need to add each permission required to webApiPermissionRequests. 例如,如果你使用的是"人员"组件和"议程"组件,可能 webApiPermissionRequests 如下所示:For example, if you're using the Person component and the Agenda component, your webApiPermissionRequests might look like:

"webApiPermissionRequests": [
  {
    "resource": "Microsoft Graph",
    "scope": "User.Read"
  },
  {
    "resource": "Microsoft Graph",
    "scope": "Calendars.Read"
  }
]

生成和部署 Web 部件Build and deploy your web part

现在,将生成应用程序,并部署到 SharePoint。Now, you will build your application and deploy it to SharePoint. 通过运行以下命令生成应用程序:Build your application by running the following commands:

gulp build
gulp bundle
gulp package-solution

sharepoint/solution 文件夹中有一个新 .sppkg 文件。In the sharepoint/solution folder, there will be a new .sppkg file. 您需要将此文件上载到 SharePoint Online 应用程序目录。You will need to upload this file to your SharePoint Online App Catalog. 转到 SharePoint 管理中心的"更多功能"页Go to the More features page of your SharePoint admin center. 选择 "应用程序****"下的"打开", 然后单击 "应用程序目录****",然后分发 SharePoint 应用程序Select Open under Apps, then click App Catalog, and Distribute apps for SharePoint. 上载文件 .sppkg ,然后单击"部署 "。Upload your .sppkg file, and click Deploy.

接下来,您需要以管理员角色批准权限。Next, you need to approve the permissions as an administrator.

转到 SharePoint 管理中心Go to your SharePoint Admin center. 在左侧导航栏中,选择 "高级",然后选择 "API Access"。In the left-hand navigation, select Advanced and then API Access. 应看到针对在文件中添加的每个权限的挂起 config\package-solution.json 请求。You should see pending requests for each of the permissions you added in your config\package-solution.json file. 选择并批准每个权限。Select and approve each permission.

测试 Web 部件Test your web part

现在可以将 Web 部件添加到 SharePoint 页面并进行测试。你将需要使用托管的工作台来测试使用 Microsoft Graph Toolkit因为组件需要经过身份验证的上下文才能调用 Microsoft Graph。You're now ready to add your web part to a SharePoint page and test it out. You will need to use the hosted workbench to test web parts that use the Microsoft Graph Toolkit because the components need the authenticated context in order to call Microsoft Graph. 您可以在 https://<YOUR_TENANT>.sharepoint.com/_layouts/15/workbench.aspx 找到托管的工作台。You can find your hosted workbench at https://<YOUR_TENANT>.sharepoint.com/_layouts/15/workbench.aspx.

打开项目中的文件,将值替换为托管工作台的 config\serve.json initialPage URL:Open the config\serve.json file in your project and replace the value of initialPage with the url for your hosted workbench:

"initialPage": "https://<YOUR_TENANT>.sharepoint.com/_layouts/15/workbench.aspx",

保存该文件,然后在控制台中运行以下命令以生成和预览 Web 部件:Save the file and then run the following command in the console to build and preview your web part:

gulp serve

托管的工作台将自动在浏览器中打开。Your hosted workbench will automatically open in your browser. 将 Web 部件添加到页面,你应该会看到你的 Web 部件与 Microsoft Graph Toolkit组件在操作!Add your web part to the page and you should see your web part with the Microsoft Graph Toolkit components in action! 只要 gulp serve 命令仍在控制台中运行,就可以继续编辑代码,然后刷新浏览器以查看更改。As long as the gulp serve command is still running in your console, you can continue to make edits to your code and then just refresh your browser to see your changes.

后续步骤Next Steps