Compartir a través de

Compilar la primera extensión Field Customizer

  • Artículo

Las extensiones son componentes del lado cliente que se ejecutan dentro del contexto de una página de SharePoint. Las extensiones se pueden implementar en SharePoint Online y puede usar herramientas y bibliotecas modernas de JavaScript para compilarlas.

Para seguir estos pasos, vea el vídeo en el canal de YouTube de Microsoft 365 Platform Communtiy (PnP):

Crear un proyecto de extensión

  1. Cree un nuevo directorio del proyecto en su ubicación favorita.

    md field-extension

  2. Vaya al directorio del proyecto.

    cd field-extension

  3. Para crear una extensión HelloWorld, ejecute el generador de SharePoint de Yeoman.

    yo @microsoft/sharepoint

  4. En el momento en que se le solicite, introduzca los siguientes valores (seleccione la opción predeterminada para todas las solicitudes que se omitan a continuación):

    • ¿Cuál es el nombre de la solución?: field-extension
    • ¿Cuál es el tipo de componente del lado cliente que se va a crear?: Extensión
    • ¿Qué tipo de extensión del lado cliente se va a crear? Personalizador de campo
    • ¿Cuál es el nombre del personalizador de campo? HolaMundo
    • ¿Qué plantilla le gustaría usar?: Sin JavaScript Framework

    En este momento, Yeoman instalará las dependencias necesarias y aplicará scaffolding a los archivos de la solución con la extensión HelloWorld. Esta operación puede tardar unos minutos.

  5. Luego, escriba lo siguiente en la consola para iniciar Visual Studio Code.

    code .

    Nota:

    Como la solución del lado cliente de SharePoint se basa en HTML/TypeScript, puede usar cualquier editor de código que admita el desarrollo del lado cliente para compilar la extensión.

  6. Abra el archivo ./src/extensions/helloWorld/HelloWorldFieldCustomizer.manifest.json .

    Este archivo define el tipo de extensión y un identificador id único para la extensión. Necesitará este identificador único más adelante al depurar e implementar la extensión en SharePoint.

Programar el personalizador de campo

Abra el archivo ./src/extensions/helloWorld/HelloWorldFieldCustomizer.ts .

Observe que la clase base del personalizador de campo se importa del paquete sp-application-base, que contiene el código de SharePoint Framework que requiere el personalizador de campo.

import { Log } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
  BaseFieldCustomizer,
  IFieldCustomizerCellEventParameters
} from '@microsoft/sp-listview-extensibility';

La lógica del personalizador de campo está contenida en los onInit()métodos , onRenderCell()y onDisposeCell() .

  • onInit() es donde ejecutará la configuración necesaria para la extensión. Este evento se produce después this.context de y this.properties se asignan, pero antes de que la página DOM esté lista. Al igual que con los elementos web, onInit() devuelve una promesa que puede usar para realizar operaciones asincrónicas; onRenderCell() no se llama a hasta que la promesa se haya resuelto. Si no lo necesita, simplemente devuelva Promise.resolve<void>();.
  • onRenderCell() se produce cuando se representa cada celda. Proporciona un event.domElement elemento HTML donde el código puede escribir su contenido.
  • onDisposeCell() se produce inmediatamente antes de event.cellDiv que se elimine. Se puede usar para liberar todos los recursos asignados durante la representación de campos. Por ejemplo, si onRenderCell() se monta un elemento React, onDisposeCell() se debe usar para liberarlo; de lo contrario, se produciría una fuga de recursos.

A continuación se muestra el contenido de onRenderCell() y onDisposeCell() en la solución predeterminada:

@override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  // Use this method to perform your custom cell rendering.
  const text: string = `${this.properties.sampleText}: ${event.fieldValue}`;

  event.domElement.innerText = text;

  event.domElement.classList.add(styles.cell);
}

@override
public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
  super.onDisposeCell(event);
}

Depurar el personalizador de campo

No se puede usar el área de trabajo local para probar Extensiones de SharePoint Framework. Debe probarlos y desarrollarlos directamente en un sitio de SharePoint Online en directo. No es necesario implementar la personalización en el catálogo de aplicaciones para ello, lo que hace que la experiencia de depuración sea sencilla y eficaz.

  1. Para probar la extensión, primero debe crear el campo en el que probar el personalizador. Por lo tanto, vaya al sitio en su inquilino de SharePoint Online en el que desea probar el personalizador de campo.

  2. Vaya a la página Contenido del sitio.

  3. En la barra de herramientas, seleccione Nuevo y luego Lista.

    Crear una lista

  4. Cree una lista denominada Pedidos y haga clic en Crear.

    Crear una lista con el nombre Pedidos

  5. Seleccione el + signo y, a continuación, seleccione Número para crear un nuevo campo Número para la lista.

    Crear un campo de número

  6. Establezca el nombre del campo en Porcentaje y seleccione Guardar.

    Crear un campo denominado Porcentaje

  7. Agregue algunos elementos con números diferentes en el campo de porcentaje. Modificaremos la representación más adelante en este tutorial, por lo que los distintos números se presentarán de forma diferente en función de la implementación personalizada.

    Crear elementos en la lista recién creada con distintos valores en el campo de porcentaje

  8. En Visual Studio Code, abra el archivo ./config/serve.json.

    Establezca el InternalFieldName atributo Percent en para el nombre del campo que hemos creado. Actualice los pageUrl atributos para que coincidan con una dirección URL de la lista que hemos creado en los pasos de vista previa. Después de los cambios, el archivo serve.json debe tener un aspecto similar al código siguiente:

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "fieldCustomizers": {
        "Percent": {
          "id": "b909e395-f714-421f-94e0-d638dafeb210",
            "properties": {
            "sampleText": "Value"
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "fieldCustomizers": {
        "Percent": {
          "id": "b909e395-f714-421f-94e0-d638dafeb210",
          "properties": {
            "sampleText": "Value"
          }
        }
      }
    }
  }
}

    Nota:

    El GUID del fragmento de JSON anterior es el ID. único del componente de extensión de SPFx. Se define en el manifiesto del componente. El GUID de la solución será diferente, ya que todos los ID. de componente son únicos.

  9. Compile el código y hospede los archivos compilados en la máquina local ejecutando este comando:

    gulp serve

    Después de compilar el código sin errores, el manifiesto resultante se entrega desde https://localhost:4321.

    gulp serve

    Esto iniciará el explorador predeterminado y cargará la página definida en el archivo serve.json .

  10. Para aceptar la carga de los manifiestos de depuración, seleccione Cargar scripts de depuración cuando se le pida.

    Aceptar la carga de scripts de depuración

    Observe cómo los valores de la columna Porcentaje ahora se presentan con una cadena de prefijo adicional como Value:, que se proporciona como una propiedad para el personalizador de campo.

    Vista de lista con el personalizador de campo que se representa para el campo de porcentaje

Mejorar la representación del personalizador de campo

Ahora que hemos probado correctamente el punto inicial de fábrica del personalizador de campos, vamos a modificar ligeramente la lógica para tener una representación más pulida del valor del campo.

  1. Abra el archivo ./src/extensions/helloWorld/HelloWorldFieldCustomizer.module.scss y actualice la definición de estilo de la siguiente manera.

    .HelloWorld {
  .cell {
    display: inline-block;
  }
  .full {
    background-color: #e5e5e5;
    width: 100px;
  }
}

  2. Abra el archivo ./src/extensions/helloWorld/HelloWorldFieldCustomizer.ts y actualice el método de la onRenderCell() siguiente manera.

    @override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  event.domElement.classList.add(styles.cell);
  event.domElement.innerHTML = `
    <div class='${styles.HelloWorld}'>
        <div class='${styles.full}'>
        <div style='width: ${event.fieldValue}px; background:#0094ff; color:#c0c0c0'>
            &nbsp; ${event.fieldValue}
        </div>
        </div>
    </div>`;
}

  3. En la ventana de la consola, asegúrese de que no tiene ningún error. Si la solución no se está ejecutando, ejecute la tarea siguiente:

    gulp serve

  4. En la lista creada anteriormente, actualice la ventana del explorador con los parámetros de consulta de depuración o reinicie el explorador con gulp serve.

  5. Para aceptar la carga de los manifiestos de depuración, seleccione Cargar scripts de depuración cuando se le pida.

    Aceptar la carga de scripts de depuración

    Observe cómo hemos cambiado por completo el estilo de representación del campo. El valor del campo se indica mediante una representación gráfica del valor.

    Representación gráfica de porcentajes

Agregar la definición de campo al paquete de solución para su implementación

Ahora que hemos probado la solución correctamente en modo de depuración, podemos empaquetarla para que se implemente automáticamente como parte del paquete de solución implementado en los sitios.

  1. Instale el paquete de solución en el sitio donde debe instalarse, de modo que el manifiesto de extensión se incluya para su ejecución.

  2. Asociar el personalizador de campo a un campo existente en el sitio. Puede hacerlo mediante programación mediante rest de SharePoint o la API de CSOM, o bien mediante Feature Framework en del paquete de solución de SharePoint Framework. En este tutorial, usaremos los archivos xml de Feature Framework. Tendrá que asociar las siguientes propiedades del objeto SPField en el nivel de sitio o de lista.

    • ClientSideComponentId: este es el identificador (GUID) del personalizador de campo que se ha instalado en el catálogo de aplicaciones.
    • ClientSideComponentProperties: se trata de un parámetro opcional que se puede usar para proporcionar propiedades para la instancia de Field Customizer.

    Puede controlar el requisito de agregar una solución que contenga la extensión al sitio con la propiedad en el skipFeatureDeployment archivo ./config/package-solution.json . Aunque no requeriría que la solución se instalara en el sitio, tendría que asociarse ClientSideComponentId a objetos específicos para que la extensión sea visible.

    Por ejemplo, puede usar el cmdlet Set-PnPField de los cmdlets de PowerShell de PnP para asociar mediante programación una extensión a campos existentes en los sitios.

    Nota:

    PnP PowerShell es una solución de código abierto con una comunidad activa que ofrece su soporte. No hay ningún contrato de nivel de servicio para el soporte de la herramienta de código abierto de Microsoft.

Revisar el archivo elements.xml

En los pasos siguientes, se revisa la definición de campo predeterminada, que se ha creado automáticamente y luego se usará para implementar automáticamente las configuraciones necesarias cuando el paquete de solución se instale en un sitio.

  1. Vuelva a la solución en Visual Studio Code (o el editor que prefiera).

  2. Abra el archivo ./sharepoint/assets/elements.xml.

    carpeta

Examine el XML de este archivo. La ClientSideComponentId propiedad se ha actualizado automáticamente al identificador único del personalizador de campo disponible en el archivo ./src/extensions/helloWorld/HelloWorldFieldCustomizer.manifest.json . Tendrá que ajustar la coincidencia de este archivo en el tipo de campo y los detalles.

Nota:

Para obtener más información sobre el esquema XML de Feature Framework, vea: Referencia de esquema de SharePoint.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field ID="{060E50AC-E9C1-3D3C-B1F9-DE0BCAC200F6}"
          Name="SPFxPercentage"
          DisplayName="Percentage"
          Type="Number"
          Min="0"
          Required="FALSE"
          Group="SPFx Columns"
          ClientSideComponentId="7e7a4262-d02b-49bf-bfcb-e6ef1716aaef">
  </Field>
</Elements>

Comprobar que las definiciones se usan en la canalización de compilación

Abra el archivo./config/package-solution.json.

El archivo package-solution.json define los metadatos del paquete como se muestra en el siguiente código. Para asegurarse de que el archivo elements.xml se tiene en cuenta mientras se crea el paquete de solución, se actualiza el scaffolding predeterminado de este archivo para incluir detalles adicionales para una definición de características. Esta definición de característica se usa para aprovisionar y ejecutar el archivo elements.xml .

Observe también que el includeClientSideAssets atributo está establecido en true. Esto significa que los recursos de JavaScript se incluirán en el archivo *.sppkg :

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "field-extension-client-side-solution",
    "id": "80c04d1b-dca7-4d0a-86c0-9aedf904704f",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    "features": [
      {
        "title": "Application Extension - Deployment of custom action.",
        "description": "Deploys a custom action with ClientSideComponentId association",
        "id": "b27507b9-7c2a-4398-8946-7438571f16f6",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/field-extension.sppkg"
  }
}

Implementar el campo en SharePoint Online y hospedar JavaScript desde un host local

Ahora está listo para implementar la solución en un sitio de SharePoint y obtener la asociación de campo que se incluye automáticamente en un campo. Usaremos la opción --ship con este empaquetado para que todos los recursos se empaquetan automáticamente en el paquete de la solución.

  1. En la ventana de la consola, escriba el comando siguiente para crear un paquete de la solución del lado cliente que contenga la extensión, y así tener preparada la estructura básica necesaria para el paquete:

    gulp bundle --ship

  2. Ejecute el comando siguiente para crear el paquete de solución:

    gulp package-solution --ship

    El comando crea el paquete: ./sharepoint/solution/field-extension.sppkg:

  3. Ahora, tiene que implementar el paquete que se generó en el Catálogo de aplicaciones. Para hacerlo, vaya al Catálogo de aplicaciones del espacio empresarial y abra la biblioteca de Aplicaciones para SharePoint.

  4. Cargue el archivo ./sharepoint/solution/field-extension.sppkg en el catálogo de aplicaciones.

    Observe que SharePoint muestra el cuadro de diálogo de confianza y le pide que confíe en la solución del lado cliente con SharePoint Online como dominio. Los recursos se hospedarán automáticamente desde la dirección URL del catálogo de aplicaciones o desde Microsoft red CDN pública 365, en función de la configuración del inquilino.

  5. Seleccione el botón Implementar.

    Cuadro de diálogo Implementar

  6. Vaya al sitio donde quiere probar el aprovisionamiento de activos de SharePoint. Puede ser cualquier colección de sitios del espacio empresarial donde ha implementado este paquete de solución.

  7. Seleccione el icono de engranaje en la barra de navegación superior de la derecha y, a continuación, seleccione Agregar una aplicación.

  8. En el cuadro Buscar , escriba el campo y, a continuación, seleccione ENTRAR para filtrar las aplicaciones.

    instalar el personalizador de campo en el sitio

  9. Seleccione la aplicación field-extension-client-side-solution para instalar la solución en el sitio. Una vez completada la instalación, actualice la página.

  10. Cuando la aplicación se haya instalado, seleccione Nuevo en la barra de herramientas de la página Contenidos del sitio y elija Lista.

    Crear una lista

  11. Cree una lista denominada Facturas.

  12. Cuando la nueva lista se haya creado, en la página Contenidos del sitio, seleccione Configuración en el menú de la lista recién creada.

    Configuración de lista de la nueva lista

  13. Seleccione Columnas>Agregar desde columnas de sitio existentes.

  14. Seleccione el campoPorcentaje de columnas> de SPFx que se aprovisionó desde el paquete de solución y, a continuación, seleccione Aceptar.

    Agregar el campo de porcentaje a la lista

  15. Vaya a la lista Facturas recién creada. Agregue algunos elementos a la lista con distintos valores en la columna de porcentaje para determinar cómo se representa el campo sin los parámetros de consulta de depuración.

Representación de campo sin parámetros de consulta de depuración

El proceso de publicación de la aplicación es idéntico entre los distintos tipos de extensión.

Nota:

Se trata de un personalizador de campos relativamente sencillo con funcionalidad que también podría haberse logrado con Usar formato de columna para personalizar SharePoint. Sin embargo, el formato de columna no admite código personalizado real. Tenga en cuenta que los usuarios finales no pueden modificar los personalizadores de campos desde la interfaz de usuario, lo que permite casos de uso adicionales.

Vea también