SharePoint Framework (SPFx): crea tu primer web part personalizado

Los web parts de serie cubren la mayoría de las necesidades, pero tarde o temprano aparece una que no: mostrar datos de un sistema interno, un panel con lógica propia, un formulario especial. Para eso existe SharePoint Framework (SPFx), el modelo de desarrollo oficial de Microsoft para personalizar SharePoint, Teams y Viva Connections. En el libro de SharePoint le dedicamos un capítulo; aquí tienes un recorrido práctico por tu primer web part.

Qué es SPFx y cuándo usarlo

SPFx es un conjunto de herramientas para crear componentes con TypeScript y tecnologías web estándar (puedes usar React u otro framework). Sus características clave:

• Se ejecuta en el navegador, dentro de la página, con el contexto y los permisos del usuario que la está viendo.
• Es compatible con las páginas modernas y se integra con el editor como cualquier web part de serie, incluido el panel de propiedades.
• Se despliega como un paquete (.sppkg) en el catálogo de aplicaciones.

Crear el proyecto

Necesitas Node.js en una versión compatible con tu versión de SPFx (Microsoft publica una tabla de compatibilidad) y el generador de proyectos:

$ npm install -g yo @microsoft/generator-sharepoint
$ mkdir aviso-webpart && cd aviso-webpart
$ yo @microsoft/sharepoint
  ? What is your solution name? aviso-webpart
  ? Which type of client-side component to create? WebPart
  ? What is your Web part name? Aviso
  ? Which template would you like to use? No framework

El generador crea la estructura del proyecto, instala las dependencias y deja un README con los comandos para probar el web part en el workbench (un entorno de pruebas dentro de tu sitio) y para empaquetarlo. Esos comandos han cambiado entre versiones de SPFx, así que sigue los del README de tu proyecto.

El código de un web part

Este web part muestra un aviso configurable y saluda al usuario por su nombre:

import { Version } from '@microsoft/sp-core-library';
import { IPropertyPaneConfiguration, PropertyPaneTextField } from '@microsoft/sp-property-pane';
import { BaseClientSideWebPart } from '@microsoft/sp-webpart-base';
import { escape } from '@microsoft/sp-lodash-subset';

export interface IAvisoWebPartProps {
  titulo: string;
  mensaje: string;
}

export default class AvisoWebPart extends BaseClientSideWebPart<IAvisoWebPartProps> {
  public render(): void {
    const usuario = this.context.pageContext.user.displayName;

    // escape() evita que un texto con HTML rompa la página o inyecte código
    this.domElement.innerHTML = `
      <section>
        <h2>${escape(this.properties.titulo)}</h2>
        <p>Hola, ${escape(usuario)}. ${escape(this.properties.mensaje)}</p>
      </section>`;
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }

  protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [{
        header: { description: 'Configura el aviso' },
        groups: [{
          groupName: 'Contenido',
          groupFields: [
            PropertyPaneTextField('titulo', { label: 'Título' }),
            PropertyPaneTextField('mensaje', { label: 'Mensaje', multiline: true }),
          ],
        }],
      }],
    };
  }
}

Propiedades configurables

El método getPropertyPaneConfiguration() define el panel lateral que ve el editor de la página al configurar el web part. Cada campo se guarda en this.properties, de modo que el mismo web part sirve para distintos avisos en distintas páginas sin tocar el código.

Leer datos de una lista

SPFx incluye un cliente HTTP ya autenticado con el usuario actual. Así se leerían las últimas solicitudes de la lista del artículo sobre Power Automate:

import { SPHttpClient } from '@microsoft/sp-http';

const web = this.context.pageContext.web.absoluteUrl;
const url = `${web}/_api/web/lists/getbytitle('Solicitudes de compra')/items`
          + `?$select=Title,Estado&$orderby=Created desc&$top=5`;

const respuesta = await this.context.spHttpClient.get(url, SPHttpClient.configurations.v1);
const datos = await respuesta.json();   // datos.value es el array de elementos

Como la petición se hace con los permisos del usuario, cada persona solo ve los elementos a los que ya tiene acceso. Para datos fuera de SharePoint, SPFx también ofrece clientes para Microsoft Graph y para APIs propias protegidas con Microsoft Entra ID.

Empaquetar y desplegar

1. Genera el paquete de producción con los comandos del README (el resultado es un archivo .sppkg en la carpeta sharepoint/solution).
2. Súbelo al catálogo de aplicaciones del tenant (o al catálogo de un sitio concreto, si solo lo necesita ese sitio).
3. Agrega la aplicación al sitio y el web part aparecerá en el editor de páginas, junto a los de serie.

Personaliza SharePoint con código

El libro de SharePoint dedica un capítulo a la personalización con SharePoint Framework para cuando las opciones de serie no son suficientes.

Comprar en Amazon