Criar uma web part do Microsoft Office SharePoint Online com o Kit de ferramentas do Microsoft Graph

  • Artigo

Este artigo aborda como usar componentes do Microsoft Graph Toolkit em uma Web Part do lado do cliente do SharePoint. Os primeiros passos envolvem as seguintes etapas:

  1. Defina seu ambiente de desenvolvimento.
  2. Crie seu projeto da Web Part.
  3. Adicione os pacotes do Kit de Ferramentas do Microsoft Graph.
  4. Adicione o provedor do Microsoft Office SharePoint Online.
  5. Adicione os componentes.
  6. Configure as permissões.
  7. Configurar webpack
  8. Crie e implante sua web part.
  9. Teste sua web part.

Configure seu ambiente de desenvolvimento da Estrutura do SharePoint e crie uma nova web part

Siga as etapas para configurar seu ambiente de desenvolvimento Estrutura do SharePoint.

Criar seu projeto da Web Part

Siga as instruções para criar uma web part. Quando perguntado qual modelo você gostaria de usar, escolha React.

Importante

Você deve escolher React ao selecionar sua estrutura ao usar yo @microsoft/sharepoint.

Adicionar os pacotes do Kit de Ferramentas do Microsoft Graph

O Microsoft Graph Toolkit publica vários pacotes necessários para criar uma web part Estrutura do SharePoint. A instalação dos @microsoft/mgt-elementpacotes , @microsoft/mgt-react, @microsoft/mgt-sharepoint-providere @microsoft/mgt-spfx-utils instala as dependências necessárias.

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

Adicionar o Provedor do Microsoft Office SharePoint Online

Os provedores do Kit de ferramentas do Microsoft Graph permitem autenticação e acesso ao Microsoft Graph para os componentes. Para saber mais, confira Usando os provedores. As web parts do SharePoint sempre existem em um contexto autenticado porque o usuário é autenticado para chegar à página que hospeda sua Web Part. Use este contexto para inicializar o provedor do Microsoft Office SharePoint Online.

Primeiro, adicione o provedor à sua web part. Localize o arquivo src\webparts\<your-project>\<your-web-part>.ts na pasta do projeto e adicione a seguinte linha no início do arquivo, logo abaixo das instruções import existentes:

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

Em seguida, inicialize o provedor com o contexto autenticado dentro do onInit() método de sua Web Part. No mesmo arquivo, adicione o seguinte código antes da linha public render(): void {:

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

Configurar a disambiguation

Para garantir que sua Web Part funcione se houver várias soluções de Web Part usando o Microsoft Graph Toolkit em uma única página, você deve usar a disambiguation. Para obter mais informações, consulte a disambiguation.

Primeiro, atualize suas importações @microsoft/mgt-element e adicione uma para o lazyLoadComponent auxiliar.

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

Em seguida, atualize o onInit() método da web part raiz para configurar a disambiguação. A cadeia de caracteres usada para disambiguation deve ser exclusiva para sua solução Estrutura do SharePoint:

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

Atualizar a importação e a renderização do componente React

Primeiro, converta a importação do componente para usar React.lazy. Localize a instrução import <WebPartName> from './components/<WebPartName>; e atualize-a para o seguinte:

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

Em seguida, modifique o método renderizador para usar o lazyLoadComponent auxiliar:

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

Agora, sua web part deve ser assim:

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
}

Adicionar os componentes

Adicione os componentes ao componente React. Localize e abra o src\webparts\<your-project>\components\<your-component>.tsx arquivo e adicione a importação para o componente que você deseja usar - nesse caso, o Person componente - e atualize o render() método para usar o componente Person. Agora seu componente deve ser assim:

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

Ou se preferir usar React Componentes Funcionais:

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;

Configurar as permissões

Para chamar o Microsoft Graph de seu aplicativo da Estrutura do SharePoint, você precisa solicitar as permissões necessárias em seu pacote de solução e um administrador de locatário do Microsoft 365 precisa aprovar as permissões solicitadas.

Para adicionar as permissões ao seu pacote de solução, localize e abra o arquivo config\package-solution.json e defina:

"isDomainIsolated": false,

Logo abaixo dessa linha, adicione a seguinte linha:

"webApiPermissionRequests":[],

Determine quais permissões do Microsoft API do Graph que você precisa depender dos componentes que você está usando. A página de documentação de cada componente fornece uma lista das permissões que o componente requer. Você precisará adicionar cada permissão necessária a webApiPermissionRequests. Por exemplo, se você estiver usando o componente Person e o componente Agenda, seu webApiPermissionRequests pode ser parecido com:

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

Configurar webpack

Para criar sua Web Part, a configuração do webpack Estrutura do SharePoint deve ser atualizada para lidar corretamente com JavaScript moderno com encadeamento opcional e agrupamento nullish por meio de transformações adicionais do Babel.

Instalar pacotes Babel

Para lidar corretamente com dependências que emitem código baseado em ES2021, um carregador babel e algumas transformações precisam ser adicionados como dependências de desenvolvimento ao projeto.

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

Modificar a configuração do webpack

Estrutura do SharePoint fornece um modelo de extensibilidade para modificar a configuração do webpack usada para empacotar as web parts. Localize e abra gulpfile.js. Adicionar o código a seguir acima da linha que contém 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;
  }
});

Isso garante que o código da lit biblioteca seja processado corretamente pela cadeia de build Estrutura do SharePoint.

Construir e implantar sua web part

Agora, você criará seu aplicativo e o implantará no SharePoint. Crie seu aplicativo executando os seguintes comandos:

gulp build
gulp bundle
gulp package-solution

sharepoint/solution Na pasta, há um novo .sppkg arquivo. Você precisa carregar esse arquivo no catálogo de aplicativos do SharePoint Online. Vá para a página Mais recursos do Centro de Administração do SharePoint Online. Selecione Abrirem Aplicativos e, em seguida, selecione Catálogo de Aplicativos e Distribuir aplicativos para o SharePoint. Carregue seu .sppkg arquivo e selecione Implantar.

Em seguida, você precisa aprovar as permissões como um administrador.

Vá para o seu Centro de administração do SharePoint Online. Na navegação à esquerda, selecione Avançado e depois Acesso à API. Você deve ver as solicitações pendentes para cada uma das permissões adicionadas ao seu arquivoconfig\package-solution.json. Selecione e aprove cada permissão.

Testar sua web part

Agora você está pronto para adicionar sua Web Part a uma página do SharePoint e testá-la. Você precisará usar o workbench hospedado para testar web parts que usam o Kit de Ferramentas do Microsoft Graph porque os componentes precisam do contexto autenticado para chamar o Microsoft Graph. Você pode encontrar seu workbench hospedado em https://< YOUR_TENANT.sharepoint.com/_layouts/15/workbench.aspx>.

Abra o config\serve.json arquivo em seu projeto e substitua o valor de initialPage pela URL do seu workbench hospedado:

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

Salve o arquivo e execute o seguinte comando no console para criar e visualizar sua web part:

gulp serve

O workbench hospedado é aberto automaticamente no navegador. Adicione sua web part à página e você deverá vê-la com os componentes do Kit de ferramentas do Microsoft Graph em ação! Contanto que o comando gulp serve ainda esteja em execução em seu console, você pode continuar a fazer edições em seu código e, em seguida, apenas atualizar seu navegador para ver as alterações.

Próximos passos