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

Статья
11/07/2024

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

Настройка среды разработки.
Создайте проект веб-части.
Добавьте пакеты Microsoft Graph Toolkit.
Добавление поставщика SharePoint.
Добавление компонентов.
Настройка разрешений.
Настройка webpack
Создание и развертывание веб-части.
Проверка веб-части.

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

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

веб-части на основе React
Нет веб-частей платформы

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

Следуйте инструкциям, чтобы создать новую веб-часть. При ответе на вопрос о том, какой шаблон вы хотите использовать, выберите 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 Toolkit

Набор средств Microsoft Graph публикует несколько пакетов, необходимых для создания веб-части SharePoint Framework. Установите пакеты npm набора средств Microsoft Graph с помощью следующей команды:

npm install @microsoft/mgt-element @microsoft/mgt-components @microsoft/mgt-sharepoint-provider

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

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

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

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

Сначала обновите импорт из @microsoft/mgt-element

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

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

protected async onInit() {
  if (!Providers.globalProvider) {
    Providers.globalProvider = new SharePointProvider(this.context);
  }
  customElementsHelper.withDisambiguation('contoso-hr-solution');
}

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

Теперь можно приступить к добавлению компонентов в веб-часть. Сначала импортируйте соответствующие функции регистра:

import { registerMgtPersonComponent } from "@microsoft/mgt-components";

Примечание.

Функции регистрации используют соглашение об именовании registerMgt{Name}Component(). Для элемента управления "Выбор людей" эта функция будет иметь значение registerMgtPeoplePickerComponent().

Вызовите функции register после настройки дизамбига в методе onInit() :

protected async onInit() {
  if (!Providers.globalProvider) {
    Providers.globalProvider = new SharePointProvider(this.context);
  }
  customElementsHelper.withDisambiguation('contoso-hr-solution');
  registerMgtPersonComponent();
}

Добавьте компоненты в HTML-код внутри render() метода , и компоненты используют контекст SharePoint для доступа к Microsoft Graph. Например, чтобы добавить компонент Person, код выглядит следующим образом:

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

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

Чтобы вызвать 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

Версия <webpack =4

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. Это необходимо для версий <=v1.18поставщика SharePoint .

Webpack версии 5+

При использовании webpack версии 5+ дополнительная настройка не требуется. Это поддерживается в версии v1.19+поставщика SharePoint .

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

Теперь вы создадите приложение и развернете его в 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 все еще работает на консоли, можно продолжать вносить изменения в код, а затем просто обновлять браузер, чтобы увидеть изменения.

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

Изучите это пошаговое руководство по созданию веб-части SharePoint.
Воспользуйтесь компонентами в интерактивной среде.
Задавайте вопросы на сайте Stack Overflow.
Сообщайте об ошибках и оставляйте запросы на создание функций в GitHub.

Поделиться через

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Настройка webpack

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

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

Версия <webpack =4

Webpack версии 5+

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

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

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

Обратная связь

Дополнительные ресурсы