Crear un elemento web de SharePoint con el Kit de herramientas de Microsoft Graph

  • Artículo

En este artículo se explica cómo usar componentes de Microsoft Graph Toolkit en un elemento web del lado cliente de SharePoint. La introducción incluye los pasos siguientes:

  1. Configurar el entorno de desarrollo
  2. Cree el proyecto de elemento web.
  3. Agregue los paquetes del kit de herramientas de Microsoft Graph.
  4. Agregar el proveedor de SharePoint.
  5. Agregar componentes.
  6. Configurar permisos.
  7. Configuración de webpack
  8. Compilar e implementar el elemento web.
  9. Probar el elemento web.

Configurar el entorno de desarrollo de SharePoint Framework y crear un nuevo elemento web

Siga los pasos para configurar el entorno de desarrollo de SharePoint Framework.

Creación del proyecto de elemento web

Siga las instrucciones para crear un nuevo elemento web. Cuando se le pregunte qué plantilla desea usar, elija React.

Importante

Debe elegir React al seleccionar el marco cuando use yo @microsoft/sharepoint.

Adición de los paquetes del kit de herramientas de Microsoft Graph

Microsoft Graph Toolkit publica varios paquetes necesarios para crear un elemento web SharePoint Framework. Al instalar los @microsoft/mgt-elementpaquetes , @microsoft/mgt-react, @microsoft/mgt-sharepoint-providery @microsoft/mgt-spfx-utils se instalan las dependencias necesarias.

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

Agregar el proveedor de SharePoint

Los proveedores del Kit de herramientas de Microsoft Graph permiten la autenticación y el acceso a Microsoft Graph para los componentes. Para más información, vea Usar los proveedores. Los elementos web de SharePoint siempre existen en un contexto autenticado porque el usuario se autentica para llegar a la página que hospeda el elemento web. Use este contexto para inicializar el proveedor de SharePoint.

En primer lugar, agregue el proveedor al elemento web. Busque el archivo src\webparts\<your-project>\<your-web-part>.ts en la carpeta del proyecto y agregue la siguiente línea a la parte superior del archivo, justo debajo de las instrucciones import existentes:

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

A continuación, inicialice el proveedor con el contexto autenticado dentro del onInit() método del elemento web. En el mismo archivo, agregue el código siguiente justo antes de la línea public render(): void {:

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

Configuración de la desambiguación

Para asegurarse de que el elemento web funciona si hay varias soluciones de elementos web que usan Microsoft Graph Toolkit en una sola página, debe usar la desambiguación. Para obtener más información, vea la desambiguación.

En primer lugar, actualice las importaciones desde @microsoft/mgt-element y agregue una para el lazyLoadComponent asistente.

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

A continuación, actualice el onInit() método del elemento web raíz para configurar la desambiguación. La cadena usada para la desambiguación debe ser única para la solución de SharePoint Framework:

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

Actualización de la importación y representación del componente de React

En primer lugar, convierta la importación del componente para usar React.lazy. Busque la instrucción import <WebPartName> from './components/<WebPartName>; y actualícela a lo siguiente:

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

A continuación, modifique el método render para usar el lazyLoadComponent asistente:

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

Ahora el elemento web debería tener este aspecto:

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
}

Agregar componentes

Agregue los componentes al componente React. Busque y abra el src\webparts\<your-project>\components\<your-component>.tsx archivo y agregue la importación para el componente que desea usar (en este caso, el Person componente) y, a continuación, actualice el render() método para usar el componente Person. Ahora el componente debería tener este aspecto:

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

O bien, si prefiere usar React componentes funcionales:

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 permisos

Para llamar a Microsoft Graph desde la aplicación de SharePoint Framework, debe solicitar los permisos necesarios en el paquete de solución y un administrador de espacios empresariales de Microsoft 365 debe aprobar los permisos solicitados.

Para agregar los permisos al paquete de solución, busque y abra el archivo config\package-solution.json y establezca:

"isDomainIsolated": false,

Justo debajo de esa línea, agregue la siguiente línea:

"webApiPermissionRequests":[],

Determine qué permisos de Microsoft Graph API necesita para depender de los componentes que usa. La página de documentación de cada componente proporciona una lista de los permisos que requiere el componente. Tendrá que agregar cada permiso necesario a webApiPermissionRequests. Por ejemplo, si usa el componente Persona y el componente Agenda, webApiPermissionRequests podría tener el siguiente aspecto:

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

Configuración de webpack

Para compilar el elemento web, la configuración de webpack de SharePoint Framework debe actualizarse para controlar correctamente JavaScript moderno con encadenamiento opcional y fusión nula a través de transformaciones adicionales de Babel.

Instalación de paquetes de Babel

Para controlar correctamente las dependencias que emiten código basado en ES2021, es necesario agregar un cargador babel y algunas transformaciones como dependencias de desarrollo al proyecto.

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

Modificación de la configuración de webpack

SharePoint Framework proporciona un modelo de extensibilidad para modificar la configuración de webpack que se usa para agrupar los elementos web. Busque y abra gulpfile.js. Agregue el código siguiente encima de la línea que contiene 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;
  }
});

Esto garantiza que la cadena de compilación de SharePoint Framework procese correctamente el código de la lit biblioteca.

Compilar e implementar el elemento web

Ahora, compilará la aplicación e implementará en SharePoint. Compile la aplicación mediante la ejecución de los siguientes comandos:

gulp build
gulp bundle
gulp package-solution

En la sharepoint/solution carpeta, hay un nuevo .sppkg archivo. Debe cargar este archivo en el catálogo de aplicaciones de SharePoint Online. Vaya a la página Más características del Centro de administración de SharePoint. Seleccione Abrir en Aplicacionesy, después, Catálogo de aplicaciones y Distribuir aplicaciones para SharePoint. .sppkg Cargue el archivo y seleccione Implementar.

Después, debe aprobar los permisos como administrador.

Vaya al Centro de administración de SharePoint. En el panel de navegación izquierdo, seleccione Avanzado y Acceso de API. Debería ver solicitudes pendientes para cada uno de los permisos que agregó en el archivo config\package-solution.json. Seleccionar y aprobar cada permiso.

Probar el elemento web

Ya está listo para agregar el elemento web a una página de SharePoint y probarlo. Tendrá que usar el área de trabajo hospedada para probar los elementos web que usan microsoft Graph Toolkit porque los componentes necesitan el contexto autenticado para llamar a Microsoft Graph. Puede encontrar el área de trabajo hospedada en https://< YOUR_TENANT.sharepoint.com/_layouts/15/workbench.aspx>.

Abra el archivo en el config\serve.json proyecto y reemplace el valor de initialPage por la dirección URL del área de trabajo hospedada:

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

Guarde el archivo y ejecute el siguiente comando en la consola para compilar y obtener una vista previa del elemento web:

gulp serve

El área de trabajo hospedada se abre automáticamente en el explorador. Agregue el elemento web a la página y debería ver el elemento web con los componentes del Kit de herramientas de Microsoft Graph en acción. Siempre que el comando gulp serve siga ejecutándose en la consola, puede seguir realizando modificaciones en el código y, después, actualizar el explorador para ver los cambios.

Siguientes pasos