Compartilhar via

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

  • Artigo

Este artigo aborda como utilizar componentes do Microsoft Graph Toolkit numa peça Web do lado do cliente do SharePoint. Os primeiros passos envolvem as seguintes etapas:

  1. Defina seu ambiente de desenvolvimento.
  2. Crie o seu projeto de peça Web.
  3. Adicione os pacotes do Microsoft Graph Toolkit.
  4. Adicione o provedor do Microsoft Office SharePoint Online.
  5. Adicione os componentes.
  6. Configure as permissões.
  7. Configurar o 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 os passos para Configurar o ambiente de desenvolvimento Estrutura do SharePoint.

Criar o seu projeto de peça Web

Siga as instruções para criar uma nova peça Web. Quando lhe for perguntado qual o modelo que pretende utilizar, selecione React.

Importante

Tem de escolher React ao selecionar a arquitetura quando utilizar yo @microsoft/sharepoint.

Adicionar os pacotes do Microsoft Graph Toolkit

O Microsoft Graph Toolkit publica vários pacotes necessários para criar uma peça Web Estrutura do SharePoint. Instalar os @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 peças Web do SharePoint existem sempre num contexto autenticado porque o utilizador é autenticado para aceder à página que aloja a peça Web. 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 fornecedor com o contexto autenticado dentro do onInit() método da peça Web. 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 desambiguação

Para garantir que a peça Web funciona se existirem várias soluções de peças Web com o Microsoft Graph Toolkit numa única página, tem de utilizar a desambiguação. Para obter mais informações, veja a desambiguação.

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

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

Em seguida, atualize o onInit() método da peça Web raiz para configurar a desambiguação. A cadeia utilizada para a desambiguação tem de ser exclusiva da sua solução de 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 composição do componente React

Primeiro, converta a importação do componente para utilizar 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 de composição para utilizar o lazyLoadComponent programa 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, a peça Web deverá ter o seguinte aspeto:

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 ficheiro, adicione a importação para o componente que pretende utilizar - neste caso, o Person componente - e, em seguida, atualize o render() método para utilizar o componente Pessoa. Agora, o componente deverá ter o seguinte aspeto:

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

Em alternativa, se preferir utilizar 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,

Imediatamente abaixo dessa linha, adicione a seguinte linha:

"webApiPermissionRequests":[],

Determine quais as permissões do Microsoft API do Graph de que precisa para depender dos componentes que está a utilizar. A página de documentação de cada componente fornece uma lista das permissões que o componente requer. Terá de 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 o webpack

Para criar a sua peça Web, a configuração do webpack Estrutura do SharePoint tem de ser atualizada para processar corretamente o JavaScript moderno com encadeamento opcional e agrupamento nulo através de transformações adicionais do Babel.

Instalar pacotes Babel

Para processar corretamente as dependências que emitem código baseado em ES2021, é necessário adicionar um carregador babel e algumas transformações 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

Versão <do Webpack =4

Estrutura do SharePoint fornece um modelo de extensibilidade para modificar a configuração do webpack utilizada para agrupar as peças Web. Localize e abra gulpfile.js. Adicione o seguinte código 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;
  }
});

Isto garante que o código da lit biblioteca é processado corretamente pela cadeia de compilação Estrutura do SharePoint. Isto é necessário para as versões <=v1.18do fornecedor do SharePoint.

Webpack versão 5+

Não é necessária qualquer configuração adicional quando utiliza a versão 5 ou superior do webpack. Isto é suportado com a versão v1.19+do fornecedor do SharePoint .

Construir e implantar sua web part

Agora, vai criar a sua aplicação e implementá-la no SharePoint. Crie seu aplicativo executando os seguintes comandos:

gulp build
gulp bundle
gulp package-solution

sharepoint/solution Na pasta, existe um novo .sppkg ficheiro. Tem de carregar este ficheiro para o Catálogo de Aplicações do SharePoint Online. Vá para a página Mais recursos do Centro de Administração do SharePoint Online. Selecione Abrir em Aplicações e, em seguida, selecione Catálogo de Aplicações e Distribuir aplicações para o SharePoint. Carregue o ficheiro .sppkg e selecione Implementar.

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, está pronto para adicionar a peça Web a uma página do SharePoint e testá-la. Terá de utilizar o workbench alojado para testar peças Web que utilizam o Microsoft Graph Toolkit porque os componentes precisam do contexto autenticado para chamar o Microsoft Graph. Pode encontrar o workbench alojado em https://< YOUR_TENANT.sharepoint.com/_layouts/15/workbench.aspx>.

Abra o config\serve.json ficheiro no seu projeto e substitua o valor de initialPage pelo URL do workbench alojado:

"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 seu workbench alojado abre automaticamente no browser. 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