Compartir a través de

Migración de elementos de menú editar bloque de control (ECB) a extensiones de SharePoint Framework

  • Artículo

Durante los últimos años, la mayoría de las soluciones empresariales basadas en Microsoft 365 y SharePoint Online aprovecharon la capacidad del sitio CustomAction de SharePoint Feature Framework para ampliar la interfaz de usuario de las páginas. Con la interfaz de usuario "moderna" de SharePoint, la mayoría de esas personalizaciones ya no están disponibles. Con las extensiones de SharePoint Framework, puede proporcionar una funcionalidad similar en la interfaz de usuario "moderna".

En este tutorial, aprenderá a migrar las personalizaciones "clásicas" heredadas al modelo actual: extensiones de SharePoint Framework.

En primer lugar, se presentan las opciones disponibles al desarrollar extensiones de SharePoint Framework:

La opción más útil en nuestro contexto es la extensión del conjunto de comandos.

Supongamos que tiene un CustomAction elemento en SharePoint Online para tener un elemento de menú BCE personalizado para los documentos de una biblioteca. El ámbito del elemento de menú ECB es abrir una página personalizada, proporcionando el identificador de lista y el identificador de elemento de lista del elemento seleccionado actualmente en la cadena de consulta de la página de destino.

En el siguiente fragmento de código, puede ver el código XML que define mediante CustomAction SharePoint Feature Framework.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction
      Id="OpenDetailsPageWithItemReference"
      Title="Show Details"
      Description="Opens a new page with further details about the currently selected item"
      Sequence="1001"
      RegistrationType="List"
      RegistrationId="101"
      Location="EditControlBlock">
    <UrlAction Url="ShowDetails.aspx?ID={ItemId}&amp;List={ListId}" />
  </CustomAction>
</Elements>

Como puede ver, el archivo de elementos de características define un elemento de tipo CustomAction para agregar un nuevo elemento en la EditControlBlock ubicación (es decir, ECB) para cualquier documento de cualquier biblioteca (RegistrationType es List y RegistrationId es 101).

En la siguiente ilustración, puede ver el resultado de la acción personalizada anterior en la vista de lista de una biblioteca.

Pie de página personalizado en una página clásica

Observe que el elemento personalizado ECB de SharePoint Feature Framework funciona en una lista "moderna". De hecho, mientras no use código JavaScript, una acción personalizada de lista seguirá funcionando en listas "modernas".

Para migrar la solución anterior a SharePoint Framework, vea los siguientes pasos.

Crear una solución nueva de SharePoint Framework

  1. Desde la consola, cree una carpeta para el proyecto:

    md spfx-ecb-extension

  2. Vaya a la carpeta del proyecto:

    cd spfx-ecb-extension

  3. Cree un nuevo elemento web de solución de SharePoint Framework mediante la ejecución del 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?: spfx-ecb-extension
    • ¿Qué paquetes de línea base quiere usar como destino para el componente o los componentes?: solo SharePoint Online (versión más reciente)
    • ¿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? Conjunto de comandos de ListView
    • ¿Cuál es el nombre del conjunto de comandos? CustomECB

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

  5. Inicie Visual Studio Code (o el editor de código que prefiera) y empiece a desarrollar la solución. Para iniciar Visual Studio Code, puede ejecutar la siguiente instrucción.

    code .

Definir el nuevo elemento ECB

Para reproducir el mismo comportamiento del elemento de menú ECB creado mediante SharePoint Feature Framework, debe implementar la misma lógica mediante código del lado cliente dentro de la nueva solución de SharePoint Framework. Para realizar esta tarea, complete los pasos siguientes.

  1. Abra el archivo ./src/extensions/customEcb/CustomEcbCommandSet.manifest.json. Copie el valor de la propiedad id y guárdelo en un lugar seguro, ya que lo necesitará más adelante.

  2. En el mismo archivo, edite la matriz de items en la parte inferior del archivo para definir un único comando para el conjunto de comandos. Llame al comando ShowDetails y proporcione un título y un tipo de comando. En la captura de pantalla siguiente, puede ver el aspecto que debe tener el archivo de manifiesto.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/command-set-extension-manifest.schema.json",

  "id": "5d3bac4c-e040-44ed-ab43-464490d22762",
  "alias": "CustomEcbCommandSet",
  "componentType": "Extension",
  "extensionType": "ListViewCommandSet",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,

  "items": {
    "ShowDetails": {
      "title": {
        "default": "Show Details"
      },
      "type": "command"
    }
  }
}

  3. Abra el archivo ./src/extensions/customEcb/CustomEcbCommandSet.ts y edite el contenido según el siguiente fragmento de código:

    import { Guid } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
  BaseListViewCommandSet,
  Command,
  IListViewCommandSetListViewUpdatedParameters,
  IListViewCommandSetExecuteEventParameters
} from '@microsoft/sp-listview-extensibility';
import { Dialog } from '@microsoft/sp-dialog';

import * as strings from 'CustomEcbCommandSetStrings';

export interface ICustomEcbCommandSetProperties {
  targetUrl: string;
}

export default class CustomEcbCommandSet extends BaseListViewCommandSet<ICustomEcbCommandSetProperties> {

  @override
  public onInit(): Promise<void> {
    return Promise.resolve();
  }

  @override
  public onListViewUpdated(event: IListViewCommandSetListViewUpdatedParameters): void {
    const compareOneCommand: Command = this.tryGetCommand('ShowDetails');
    if (compareOneCommand) {
      // This command should be hidden unless exactly one row is selected.
      compareOneCommand.visible = event.selectedRows.length === 1;
    }
  }

  @override
  public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
    switch (event.itemId) {
      case 'ShowDetails':

        const itemId: number = event.selectedRows[0].getValueByName("ID");
        const listId: Guid = this.context.pageContext.list.id;

        window.location.replace(`${this.properties.targetUrl}?ID=${itemId}&List=${listId}`);

        break;
      default:
        throw new Error('Unknown command');
    }
  }
}

    Observe la instrucción import del principio del archivo que hace referencia al tipo Guid, que se usa para almacenar el id. de la lista actual.

    La interfaz ICustomEcbCommandSetProperties declara una única propiedad denominada targetUrl que se puede usar para proporcionar la dirección URL de la página de destino que se va a abrir al seleccionar el elemento de menú ECB.

    Además, la invalidación del onExecute() método controla la ejecución de la acción personalizada. Observe el extracto de código que lee el identificador del elemento seleccionado actualmente, del event argumento y el identificador de la lista de origen del pageContext objeto.

    Por último, observe la invalidación del método onListViewUpdated(), que solo habilita de forma predeterminada el comando ShowDetails si se selecciona un único elemento.

    El redireccionamiento a la dirección URL de destino se controla mediante el código JavaScript clásico y la window.location.replace() función . Puede escribir el código TypeScript que quiera dentro del onExecute() método . Solo para dar un ejemplo, puede aprovechar SharePoint Framework Dialog Framework para abrir una nueva ventana de diálogo e interactuar con los usuarios.

    Nota:

    Para obtener más información sobre SharePoint Framework Dialog Framework, vea Usar cuadros de diálogo personalizados con extensiones de SharePoint Framework.

    Puede ver el resultado en la siguiente ilustración.

    Conjunto de comandos ECB representado en la lista

Probar la solución en modo de depuración

  1. Volver a la ventana de la consola y ejecutar el siguiente comando para compilar la solución y ejecutar el servidor local Node.js para hospedarlo.

    gulp serve --nobrowser

  2. Abra su explorador favorito y vaya a una biblioteca "moderna" de cualquier sitio de equipo "moderno". Anexe los siguientes parámetros de cadena de consulta a la dirección URL de la página AllItems.aspx .

    ?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"6c5b8ee9-43ba-4cdf-a106-04857c8307be":{"location":"ClientSideExtension.ListViewCommandSet.ContextMenu","properties":{"targetUrl":"ShowDetail.aspx"}}}

    En la cadena de consulta anterior, reemplace el GUID por el valor de id que ha guardado en el archivo CustomEcbCommandSet.manifest.json.

    Además, hay una location propiedad que asume el valor de ClientSideExtension.ListViewCommandSet.ContextMenu, que indica a SPFx que represente el conjunto de comandos como un elemento de menú ECB. A continuación se muestran todas las opciones de la location propiedad :

    • ClientSideExtension.ListViewCommandSet.ContextMenu: el menú contextual de los elementos.
    • ClientSideExtension.ListViewCommandSet.CommandBar: menú principal de conjunto de comandos en una lista o biblioteca.
    • ClientSideExtension.ListViewCommandSet: tanto el menú contextual como la barra de comandos (corresponde a SPUserCustomAction.Location="CommandUI.Ribbon").

    Todavía en la cadena de consulta, hay una propiedad llamada properties que representa la serialización JSON de un objeto de tipo ICustomEcbCommandSetProperties que es el tipo de las propiedades personalizadas solicitadas por el conjunto de comandos personalizado para la representación.

    Tenga en cuenta que al ejecutar la solicitud de página, se le pedirá un cuadro de mensaje de advertencia con el título "Permitir scripts de depuración?", que le pide su consentimiento para ejecutar código desde localhost por motivos de seguridad. Si desea depurar y probar localmente la solución, tiene que permitir que "Cargar scripts de depuración".

    Nota:

    Como alternativa, puede crear entradas de configuración de servidor en el archivo config/serve.json del proyecto para automatizar la creación de los parámetros de cadena de consulta de depuración como se describe en este documento: Depurar soluciones de SharePoint Framework en páginas modernas de SharePoint

Empaquetar y hospedar la solución

Si le gusta el resultado, ya puede empaquetar la solución y hospedarla en una infraestructura de hospedaje real.

Antes de crear la agrupación y el paquete, deberá declarar un archivo XML de Feature Framework para aprovisionar la extensión.

Revisar los elementos de Feature Framework

  1. En el editor de código, abra la subcarpeta /sharepoint/assets de la carpeta de la solución y edite el archivo elements.xml . Puede ver el aspecto que debe tener el archivo en el siguiente fragmento de código.

    <?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <CustomAction
        Title="CustomEcb"
        RegistrationId="101"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.ContextMenu"
        ClientSideComponentId="6c5b8ee9-43ba-4cdf-a106-04857c8307be"
        ClientSideComponentProperties="{&quot;targetUrl&quot;:&quot;ShowDetails.aspx&quot;}">
    </CustomAction>
</Elements>

    Como puede ver, recuerda al archivo del marco de características de SharePoint que se ha visto en el modelo "clásico", pero usa el atributo ClientSideComponentId para hacer referencia a id de la extensión personalizada y el atributo ClientSideComponentProperties para definir las propiedades de configuración personalizadas necesarias en la extensión.

  2. Abra el archivo ./config/package-solution.json en la solución. Dentro del archivo, puede ver que hay una referencia al archivo elements.xml dentro de la assets sección .

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-ecb-extension-client-side-solution",
    "id": "b8ff6fdf-16e9-4434-9fdb-eac6c5f948ee",
    "version": "1.0.2.0",
    "features": [
      {
        "title": "Custom ECB Menu Item.",
        "description": "Deploys a custom ECB menu item sample extension",
        "id": "f30a744c-6f30-4ccc-a428-125a290b5233",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-ecb-extension.sppkg"
  }
}

Agrupación, empaquetado e implementación del componente de SharePoint Framework

Prepare e implemente la solución para el espacio empresarial de SharePoint Online:

  1. Ejecute la tarea siguiente para agrupar la solución. Esto crea una compilación de versión del proyecto:

    gulp bundle --ship

  2. Ejecute la siguiente tarea para empaquetar la solución. Este comando crea un paquete *.sppkg en la carpeta sharepoint/solution .

    gulp package-solution --ship

  3. En el Catálogo de aplicaciones del espacio empresarial, cargue (o arrastre y coloque) el nuevo paquete de solución del lado cliente y, después, seleccione el botón Implementar.

Instalar y ejecutar la solución

  1. Abra el explorador y navegue a cualquier sitio de destino "moderno".

  2. Vaya a la página Contenidos del sitio y seleccione agregar una nueva Aplicación.

  3. Seleccione esta opción para instalar una nueva aplicación De su organización para examinar las soluciones disponibles en el Catálogo de aplicaciones.

  4. Seleccione la solución denominada spfx-ecb-extension-client-side-solution e instálela en el sitio de destino.

    Agregar una interfaz de usuario de aplicación para agregar la solución a un sitio

  5. Cuando se haya completado la instalación de la aplicación, abra la biblioteca Documentos del sitio y vea el elemento de menú ECB personalizado en acción al seleccionar un solo documento.

¡Disfruta de tu nuevo elemento de menú ecb personalizado creado con las extensiones de SharePoint Framework!

Vea también