Создание веб-части SharePoint с помощью Microsoft Graph Toolkit

  • Статья

В этой статье описывается использование компонентов Microsoft Graph Toolkit в клиентской веб-части SharePoint. Начало работы с включает следующие действия:

  1. Настройка среды разработки.
  2. Создайте проект веб-части.
  3. Добавьте пакеты Microsoft Graph Toolkit.
  4. Добавление поставщика SharePoint.
  5. Добавление компонентов.
  6. Настройка разрешений.
  7. Настройка webpack
  8. Создание и развертывание веб-части.
  9. Проверка веб-части.

Настройка среды разработки SharePoint Framework и создание новой веб-части

Выполните действия, описанные в разделе Настройка среды разработки SharePoint Framework.

Создание проекта веб-части

Следуйте инструкциям, чтобы создать новую веб-часть. При ответе на вопрос о том, какой шаблон вы хотите использовать, выберите React.

Важно!

При выборе платформы при использовании yo @microsoft/sharepointнеобходимо выбрать React .

Добавление пакетов Microsoft Graph Toolkit

Набор средств Microsoft Graph публикует несколько пакетов, необходимых для создания веб-части SharePoint Framework. @microsoft/mgt-elementПри установке пакетов , @microsoft/mgt-react, @microsoft/mgt-sharepoint-providerи @microsoft/mgt-spfx-utils устанавливаются необходимые зависимости.

npm install @microsoft/mgt-element @microsoft/mgt-react @microsoft/mgt-sharepoint-provider @microsoft/mgt-spfx-utils

Добавление поставщика SharePoint

Поставщики Microsoft Graph Toolkit обеспечивают проверку подлинности и доступ к Microsoft Graph для компонентов. Дополнительные сведения см. в статье Использование поставщиков. Веб-части SharePoint всегда существуют в контексте, прошедшем проверку подлинности, так как пользователь проходит проверку подлинности, чтобы попасть на страницу, на которую размещена веб-часть. Используйте этот контекст для инициализации поставщика SharePoint.

Сначала добавьте поставщика в веб-часть. Найдите файл src\webparts\<your-project>\<your-web-part>.ts в папке проекта и добавьте следующую строку в верхнюю часть файла прямо под существующими операторами import :

import { Providers } from '@microsoft/mgt-element';
import { SharePointProvider } from "@microsoft/mgt-sharepoint-provider";

Затем инициализируйте поставщика с использованием контекста проверки подлинности в onInit() методе веб-части. В том же файле добавьте следующий код прямо перед строкой public render(): void {:

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

Настройка дизамбига

Чтобы убедиться, что веб-часть работает при наличии нескольких решений веб-частей с помощью Microsoft Graph Toolkit на одной странице, необходимо использовать дизамбиг. Дополнительные сведения см. в разделе дизамбиг.

Сначала обновите импорт из @microsoft/mgt-element и добавьте его для вспомогательного lazyLoadComponent средства.

import { Providers, customElementHelper } from "@microsoft/mgt-element";
import { lazyLoadComponent } from "@microsoft/mgt-spfx-utils";

Затем обновите onInit() метод корневой веб-части, чтобы настроить дизамбиг. Строка, используемая для дизамбига, должна быть уникальной для решения SharePoint Framework:

protected async onInit(): Promise<void> {
  if (!Providers.globalProvider) {
    Providers.globalProvider = new SharePointProvider(this.context);
  }
  customElementHelper.withDisambiguation('contoso-hr-solution');
  return super.onInit();
}

Обновление импорта и отрисовки компонента React

Сначала преобразуйте импорт компонента для использования React.lazy. Найдите инструкцию import <WebPartName> from './components/<WebPartName>; и обновите ее следующим образом:

const MgtComponent = React.lazy(
  () =>
    import(/* webpackChunkName: 'mgt-react-component' */ "./components/<WebPartName>")
);

Затем измените метод render для использования вспомогательного lazyLoadComponent средства:

  public render(): void {
    const element = lazyLoadComponent<IHelloWorldProps>(MgtComponent, {
      description: this.properties.description,
      isDarkTheme: this._isDarkTheme,
      environmentMessage: this._environmentMessage,
      hasTeamsContext: !!this.context.sdks.microsoftTeams,
      userDisplayName: this.context.pageContext.user.displayName
    });

    ReactDom.render(element, this.domElement);
  }

Теперь веб-часть должна выглядеть следующим образом:

import * as React from "react";
import * as ReactDom from "react-dom";
import { Version } from "@microsoft/sp-core-library";
import {
  type IPropertyPaneConfiguration,
  PropertyPaneTextField,
} from "@microsoft/sp-property-pane";
import { BaseClientSideWebPart } from "@microsoft/sp-webpart-base";
import { IReadonlyTheme } from "@microsoft/sp-component-base";
import { Providers, customElementHelper } from "@microsoft/mgt-element";
import { lazyLoadComponent } from "@microsoft/mgt-spfx-utils";
import { SharePointProvider } from "@microsoft/mgt-sharepoint-provider";

import * as strings from "HelloWorldWebPartStrings";
const HelloWorld = React.lazy(
  () =>
    import(
      /* webpackChunkName: 'mgt-react-component' */ "./components/HelloWorld"
    )
);
import { IHelloWorldProps } from "./components/IHelloWorldProps";

export interface IHelloWorldWebPartProps {
  description: string;
}

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  private _isDarkTheme: boolean = false;
  private _environmentMessage: string = "";

  public render(): void {
    const element = lazyLoadComponent<IHelloWorldProps>(HelloWorld, {
      description: this.properties.description,
      isDarkTheme: this._isDarkTheme,
      environmentMessage: this._environmentMessage,
      hasTeamsContext: !!this.context.sdks.microsoftTeams,
      userDisplayName: this.context.pageContext.user.displayName,
    });

    ReactDom.render(element, this.domElement);
  }

  protected async onInit(): Promise<void> {
    if (!Providers.globalProvider) {
      Providers.globalProvider = new SharePointProvider(this.context);
    }
    customElementHelper.withDisambiguation("contoso-hr-solution");
    return super.onInit();
  }
  // [...] trimmed for brevity
}

Добавление компонентов

Добавьте компоненты в компонент React. Найдите и откройте src\webparts\<your-project>\components\<your-component>.tsx файл, добавьте импорт для компонента, который вы хотите использовать (в данном случае компонент), Person а затем обновите render() метод для использования компонента Person. Теперь компонент должен выглядеть следующим образом:

import * as React from 'react';
import type { IHelloWorldProps } from './IHelloWorldProps';
import { Person } from '@microsoft/mgt-react';

export default class HelloWorld extends React.Component<IHelloWorldProps, {}> {
  public render(): React.ReactElement<IHelloWorldProps> {
    return (<Person personQuery="me" view="twolines" />);
  }
}

Или если вы предпочитаете использовать React функциональные компоненты:

import * as React from 'react';
import type { IHelloWorldProps } from './IHelloWorldProps';
import { Person, ViewType } from '@microsoft/mgt-react';

const HelloWorld = (props: IHelloWorldProps): React.ReactElement => <Person personQuery="me" view={ViewType.twolines} />;

export default HelloWorld;

Настройка разрешений

Чтобы вызвать Microsoft Graph из приложения SharePoint Framework, необходимо запросить необходимые разрешения в пакете решения, а администратор клиента Microsoft 365 должен утвердить запрошенные разрешения.

Чтобы добавить разрешения в пакет решения, найдите и откройте файл config\package-solution.json, а также настройте:

"isDomainIsolated": false,

Сразу под этой строкой добавьте следующую строку:

"webApiPermissionRequests":[],

Определите, какие разрешения Microsoft API Graph вам нужны, чтобы зависеть от компонентов, которые вы используете. На странице документации каждого компонента содержится список разрешений, требуемых компоненту. Необходимо добавить каждое необходимое разрешение в webApiPermissionRequests. Например, если вы используете компонент "Человек" и компонент "Повестка дня", webApiPermissionRequests может выглядеть следующим образом:

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

Настройка webpack

Чтобы создать веб-часть, необходимо обновить конфигурацию SharePoint Framework webpack, чтобы правильно обрабатывать современный JavaScript с необязательным связыванием и объединением nullish с помощью дополнительных преобразований Babel.

Установка пакетов Babel

Для правильной обработки зависимостей, которые выдают код на основе ES2021, в проект необходимо добавить загрузчик babel и некоторые преобразования в качестве зависимостей разработки.

npm i --save-dev babel-loader@8.3.0 @babel/plugin-transform-optional-chaining @babel/plugin-transform-nullish-coalescing-operator @babel/plugin-transform-logical-assignment-operators

Изменение конфигурации webpack

SharePoint Framework предоставляет модель расширяемости для изменения конфигурации webpack, используемой для упаковки веб-частей. Найдите и откройте gulpfile.js. Добавьте следующий код над строкой, содержащей build.initialize(require('gulp'));

const path = require("path");
const litFolders = [
  `node_modules${path.sep}lit${path.sep}`,
  `node_modules${path.sep}@lit${path.sep}`,
  `node_modules${path.sep}lit-html${path.sep}`
];
build.configureWebpack.mergeConfig({
  additionalConfiguration: generatedConfiguration => {
    generatedConfiguration.module.rules.push({
      test: /\.js$/,
      // only run on lit packages
      include: resourcePath => 
        litFolders.some(litFolder => resourcePath.includes(litFolder)),
      use: {
        loader: 'babel-loader',
        options: {
          plugins: [
            '@babel/plugin-transform-optional-chaining',
            '@babel/plugin-transform-nullish-coalescing-operator',
            '@babel/plugin-transform-logical-assignment-operators'
          ]
        }
      }
    });
    return generatedConfiguration;
  }
});

Это гарантирует, что код из библиотеки lit правильно обрабатывается цепочкой сборки SharePoint Framework.

Создание и развертывание веб-части

Теперь вы создадите приложение и развернете его в SharePoint. Создайте приложение с помощью следующих команд:

gulp build
gulp bundle
gulp package-solution

В папке sharepoint/solution есть новый .sppkg файл. Этот файл необходимо отправить в каталог приложений SharePoint Online. Перейдите на страницу дополнительных функций Центра администрирования SharePoint. Выберите Открыть в разделе Приложения, а затем выберите Каталог приложений и Распространение приложений для SharePoint. .sppkg Отправьте файл и выберите Развернуть.

Затем необходимо утвердить разрешения как администратор.

Перейдите в Центр администрирования SharePoint. В области навигации слева выберите Дополнительно, а затем Доступ через API. Вы должны увидеть ожидающие запросы для каждого из разрешений, которые были добавлены в файл config\package-solution.json. Выберите и утвердите каждое разрешение.

Проверка веб-части

Теперь вы можете добавить веб-часть на страницу SharePoint и протестировать ее. Для тестирования веб-частей, использующих Microsoft Graph Toolkit, необходимо использовать размещенную рабочую область, так как для вызова Microsoft Graph компоненты нуждаются в контексте проверки подлинности. Размещенную рабочую среду можно найти по адресу https://< YOUR_TENANT.sharepoint.com/_layouts/15/workbench.aspx>.

config\serve.json Откройте файл в проекте и замените значение initialPage URL-адресом размещенной рабочей среды:

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

Сохраните файл и запустите следующую команду на консоли, чтобы создать и предварительно просмотреть веб-часть:

gulp serve

Размещенная workbench автоматически откроется в браузере. Добавьте веб-часть на страницу, и вы увидите ее вместе с компонентами Microsoft Graph Toolkit! Пока команда gulp serve все еще работает на консоли, можно продолжать вносить изменения в код, а затем просто обновлять браузер, чтобы увидеть изменения.

Дальнейшие действия