Compartilhar via

Migrar itens de menu editar bloco de controle (BCE) para extensões de Estrutura do SharePoint

  • Artigo

Nos últimos anos, a maioria das soluções corporativas criadas em cima do Microsoft 365 e do SharePoint Online aproveitou a funcionalidade do site CustomAction da Estrutura de Recursos do SharePoint para estender a interface do usuário das páginas. Com a interface do usuário "moderna" do SharePoint, a maioria dessas personalizações não está mais disponível. Com Estrutura do SharePoint extensões, você pode fornecer funcionalidades semelhantes na interface do usuário "moderna".

Neste tutorial, você aprenderá a migrar uma personalização "clássica" herdada para o modelo atual: Estrutura do SharePoint extensões.

Primeiro, vamos apresentar as opções disponíveis ao desenvolver Extensões da Estrutura do SharePoint:

  • Personalizador de Aplicativos: estende a interface do usuário nativa "moderna" do SharePoint Online adicionando o código do cliente e elementos HTML personalizados a espaços reservados predefinidos das páginas "modernas". Para obter mais informações sobre personalizadores de aplicativos, consulte Compilar sua primeira Extensão da Estrutura do SharePoint (Olá, Mundo parte um).
  • Conjunto de Comandos: permite adicionar itens de menu ECB personalizados ou botões personalizados à barra de comandos do modo de exibição de lista de uma lista ou uma biblioteca. Você pode associar qualquer ação do lado do cliente a esses comandos. Para obter mais informações sobre conjuntos de comandos, consulte Construir sua primeira extensão do Conjunto de Comandos ListView.
  • Personalizador de Campos: personaliza a renderização de um campo em um modo de exibição de lista usando elementos HTML personalizados e o código do cliente. Para obter mais informações sobre personalizadores de campo, consulte Compilar sua primeira extensão do Personalizador de Campos.

A opção mais útil no nosso contexto é a extensão de Conjunto de Comando.

Suponha que você tenha um CustomAction no SharePoint Online para ter um item de menu do BCE personalizado para documentos em uma biblioteca. Cabe ao item de menu ECB abrir uma página personalizada e fornecer a ID da lista e a ID do item de lista do item atualmente selecionado na sequência de consulta da página de destino.

No snippet de código a seguir, você pode ver o código XML definindo um CustomAction usando a Estrutura de Recursos do SharePoint.

<?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 você pode ver, o arquivo de elementos de recurso define um elemento do tipo CustomAction para adicionar um novo item no EditControlBlock local (ou seja, BCE) para qualquer documento em qualquer biblioteca (RegistrationType é List e RegistrationId é 101).

Na figura a seguir, observe a saída da ação personalizada anterior no modo de exibição de lista de uma biblioteca.

O rodapé personalizado em uma página clássica

O item personalizado ECB da Estrutura de Recursos do SharePoint atua em uma lista "moderna". Na verdade, desde que você não use o código do JavaScript, uma ação personalizada da lista ainda atuará nas listas "modernas".

Para migrar a solução anterior para a Estrutura do SharePoint, confira as etapas a seguir.

Criar uma nova solução da Estrutura do SharePoint

  1. No console, crie uma nova pasta para o seu projeto:

    md spfx-ecb-extension

  2. Vá até a pasta do projeto:

    cd spfx-ecb-extension

  3. Crie uma nova web part de solução Estrutura do SharePoint executando o Gerador do SharePoint do Yeoman.

    yo @microsoft/sharepoint

  4. Quando solicitado, insira os seguintes valores (selecione a opção padrão para todos os avisos omitidos abaixo):

    • Qual é o nome da solução?: spfx-bce-extension
    • Quais pacotes de linha de base que você deseja segmentar para o(s) seu(s) componente(s)?: somente SharePoint Online (mais recente)
    • Que tipo de componente do lado do cliente deve ser criado?: Extensão
    • Que tipo de extensão do lado do cliente criar? Conjunto de comandos ListView
    • Qual é o nome do seu Conjunto de Comandos? CustomECB

    Neste ponto, o Yeoman instala as dependências necessárias e mantém a estruturação dos arquivos e pastas da solução juntamente com a extensão CustomFooter. Isso pode levar alguns minutos.

  5. Inicie o Visual Studio Code (ou o editor de código de sua preferência) e comece a desenvolver a solução. Para iniciar o Visual Studio Code, execute a seguinte instrução.

    code .

Definir o novo item ECB

Para reproduzir o mesmo comportamento do item de menu ECB compilado com a Estrutura de Recursos do SharePoint, você precisa implementar a mesma lógica usando o código de cliente na nova solução da Estrutura do SharePoint. Para realizar essa tarefa, conclua as etapas a seguir.

  1. Abra o arquivo ./src/extensions/customEcb/CustomEcbCommandSet.manifest.json. Copie o valor da propriedade id e armazene-o em um local seguro, pois você precisará dele mais tarde.

  2. No mesmo arquivo, edite a matriz de items na parte inferior do arquivo para definir um único comando para o Conjunto de Comandos. Chame o comando ShowDetails e, em seguida, forneça um título e um tipo de comando. Na captura de tela a seguir, é possível ver como deve ser a aparência do arquivo de manifesto.

    {
  "$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 o arquivo ./src/extensions/customEcb/CustomEcbCommandSet.ts e edite o conteúdo de acordo com o seguinte snippet 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 a instrução import bem no início do arquivo que faz referência ao tipo Guid que é usado para manter a ID da lista atual.

    A interface ICustomEcbCommandSetProperties declara uma única propriedade chamada targetUrl que pode ser usada para fornecer a URL da página de destino a ser aberta ao selecionar o item de menu DO BCE.

    Além disso, a substituição do método onExecute() lida com a execução da ação personalizada. Observe o trecho de código que lê a ID do item atualmente selecionado, o argumento event e a ID da lista de origem do objeto pageContext.

    Por fim, observe a substituição do método onListViewUpdated(), que habilitou o comando ShowDetails por padrão, apenas se um único item estiver selecionado.

    O redirecionamento para a URL de destino é tratado usando o código do JavaScript clássico e a função window.location.replace(). Você pode escrever qualquer código TypeScript que quiser dentro do onExecute() método. Para criar um exemplo, aproveite a Estrutura da Caixa de Diálogo da Estrutura do SharePoint para abrir uma nova janela de diálogo e interagir com os usuários.

    Observação

    Para obter mais informações sobre a Estrutura de Diálogo Estrutura do SharePoint, consulte Usar caixas de diálogo personalizadas com extensões Estrutura do SharePoint.

    Na figura a seguir, é possível ver a saída resultante.

    O Conjunto de Comandos do ECB renderizado na lista

Testar a solução no modo de depuração

  1. Retorne à janela do console e execute o seguinte comando para criar a solução e executar o servidor Node.js local para hospedá-lo.

    gulp serve --nobrowser

  2. Abra seu navegador favorito e vá para uma biblioteca "moderna" de qualquer site de equipe "moderno". Acrescente os seguintes parâmetros de sequência de consulta para a URL da 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"}}}

    Na sequência de consulta anterior, substitua o GUID pelo id valor salvo no arquivo CustomEcbCommandSet.manifest.json.

    Além disso, há uma location propriedade que assume o valor de ClientSideExtension.ListViewCommandSet.ContextMenu, que instrui o SPFx a renderizar o Conjunto de Comandos como um item de menu BCE. A seguir estão todas as opções para a propriedade location:

    • ClientSideExtension.ListViewCommandSet.ContextMenu: o menu de contexto dos itens(s).
    • ClientSideExtension.ListViewCommandSet.CommandBar: o menu do conjunto de comandos superior em uma lista ou biblioteca.
    • ClientSideExtension.ListViewCommandSet: o menu de contexto e a barra de comandos (corresponde a SPUserCustomAction.Location="CommandUI.Ribbon").

    Ainda na cadeia de caracteres de consulta, há uma propriedade chamada properties que representa a serialização JSON de um objeto do tipo ICustomEcbCommandSetProperties que é o tipo das propriedades personalizadas solicitadas pelo Conjunto de Comandos personalizado para renderização.

    Durante a execução de solicitação da página, uma caixa de mensagem de aviso é exibida com o título "Permitir scripts de depuração?", que solicita o consentimento para executar códigos de um host local por motivos de segurança. Se você quiser depurar localmente e testar a solução, é necessário permitir "Carregar scripts de depuração".

    Observação

    Como alternativa, você pode criar entradas de configuração de atendimento no arquivo config/serve.json em seu projeto para automatizar a criação dos parâmetros da cadeia de caracteres de consulta de depuração, conforme descrito neste documento: Depurar soluções da Estrutura do SharePoint em páginas modernas do SharePoint

Empacotar e hospedar a solução

Se você estiver satisfeito com o resultado, já pode empacotar a solução hospedá-la em uma infraestrutura de hospedagem real.

Antes de compilar o pacote, você precisa declarar um arquivo de Estrutura de Recursos XML para provisionar a extensão.

Revisar elementos da Estrutura de Recursos

  1. No editor de código, abra a subpasta /sharepoint/assets da pasta de solução e edite o arquivo elements.xml . No trecho de código a seguir, é possível ver como deve ser a aparência do arquivo.

    <?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 é possível ver, isso nos lembra o arquivo da Estrutura de Recursos do SharePoint que vimos no modelo "clássico", mas usa o atributo ClientSideComponentId para fazer referência à id da extensão personalizada e o atributo ClientSideComponentProperties para configurar as propriedades personalizadas de configuração necessárias para a extensão.

  2. Abra o arquivo ./config/package-solution.json na solução. No arquivo, você pode ver que há uma referência ao arquivo elements.xml na assets seção.

    {
  "$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"
  }
}

Empacotar, empacotar e implantar o componente Estrutura do SharePoint

Prepare e implante a solução para o locatário do SharePoint Online:

  1. Execute a seguinte tarefa para reunir a solução. Isso executa uma versão de lançamento do seu projeto:

    gulp bundle --ship

  2. Execute a seguinte tarefa para criar um pacote para a solução. Esse comando cria um pacote *.sppkg na pasta sharepoint/solution .

    gulp package-solution --ship

  3. Carregue ou arraste e solte o pacote de solução recém-criado do lado do cliente no catálogo de aplicativos de seu locatário e então selecione o botão Implantar.

Instalar e executar a solução

  1. Abra o navegador e acesse qualquer site de destino "moderno".

  2. Vá até a página Conteúdo do Site e selecione adicionar um novo Aplicativo.

  3. Escolha a opção para instalar um novo aplicativo De Sua Organização para procurar as soluções disponíveis no catálogo de aplicativos.

  4. Escolha a solução chamada spfx-ecb-extension-client-side-solution e instale-a no site de destino.

    Adicionar uma Interface do Usuário do Aplicativo para adicionar a solução a um site

  5. Após a conclusão da instalação do aplicativo, abra a biblioteca Documents e selecione um único documento do site para ver o item de menu ECB personalizado em ação.

Aproveite seu novo item de menu do BCE personalizado criado usando as extensões de Estrutura do SharePoint!

Confira também