Compartilhar via

Criar sua primeira extensão de Conjunto de Comandos ListView

  • Artigo

As extensões são componentes do lado do cliente que são executados dentro do contexto de uma página do SharePoint. As extensões podem ser implantadas no SharePoint Online e você pode usar ferramentas e bibliotecas JavaScript modernas para construí-las.

Você pode seguir estas etapas assistindo ao vídeo no Canal do YouTube do Microsoft 365 Platform Communtiy (PnP):

Criar um projeto de extensão

  1. Crie um novo diretório de projeto em seu local favorito.

    md command-extension

  2. Vá para o diretório do projeto.

    cd command-extension

  3. Crie uma nova extensão HelloWorld executando o gerador Yeoman do SharePoint.

    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?: extensão de comando
    • 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? HelloWorld

    Neste ponto, o Yeoman instala as dependências necessárias e manterá a estrutura dos arquivos da solução juntamente com a extensão HelloWorld. Isso geralmente leva de 1 a 3 minutos.

  5. Em seguida, digite o seguinte no console para iniciar o Visual Studio Code.

    code .

  6. Abra o arquivo ./src/extensions/helloWorld/HelloWorldCommandSet.manifest.json .

    Este arquivo define seu tipo de extensão e um identificador id exclusivo para sua extensão. Você precisa desse identificador exclusivo mais tarde ao depurar e implantar sua extensão no SharePoint.

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

  "id": "95688e19-faea-4ef1-8394-489bed1de2b4",
  "alias": "HelloWorldCommandSet",
  "componentType": "Extension",
  "extensionType": "ListViewCommandSet",

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

  "requiresCustomScript": false,

  "items": {
    "COMMAND_1": {
      "title": { "default": "Command One" },
      "iconImageUrl": "icons/request.png",
      "type": "command"
    },
    "COMMAND_2": {
      "title": { "default": "Command Two" },
      "iconImageUrl": "icons/cancel.png",
      "type": "command"
    }
  }
}

    Observe as definições de comando reais no arquivo de manifesto. Estes são os botões reais que são expostos com base no destino de registro. No modelo padrão, você encontra dois botões diferentes: Comando Um e Comando Dois.

Observação

As imagens não são referenciadas corretamente, a menos que você esteja se referindo a elas de locais absolutos em uma CDN dentro de seu manifesto.

Codificar seu Conjunto de Comandos ListView

Abra o arquivo ./src/extensions/helloWorld/HelloWorldCommandSet.ts.

Observe que a classe base do Conjunto de Comandos ListView é importada do pacote @microsoft/sp-listview-extensibility, que contém Estrutura do SharePoint código (SPFx) exigido pelo Conjunto de Comandos ListView.

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

O comportamento dos botões personalizados está contido nos onListViewUpdated() métodos e OnExecute() .

O onListViewUpdated() evento ocorre separadamente para cada comando (por exemplo, um item de menu) sempre que uma alteração acontece no ListView e a interface do usuário precisa ser renderizada novamente. O event parâmetro de função representa informações sobre o comando que está sendo renderizado. O manipulador pode usar essas informações para personalizar o título ou ajustar a visibilidade, por exemplo, se um comando só deve ser mostrado quando um determinado número de itens for selecionado na exibição de lista. Essa é a implementação padrão.

Ao usar o método tryGetCommand(), você obtém um objeto Command, que é uma representação do comando que aparece na interface do usuário. Você pode modificar seus valores, como title, ou visible, para modificar o elemento da interface do usuário. O SPFx usa essas informações ao renderizar novamente os comandos. Esses objetos mantêm o estado da última renderização, portanto, se um comando estiver definido como visible = false, ele permanecerá invisível até que ele seja definido como visible = true.

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

O onExecute() método define o que acontece quando um comando é executado (por exemplo, o item de menu é selecionado). Na implementação padrão, diferentes mensagens são mostradas com base em qual botão foi selecionado.

@override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
  switch (event.itemId) {
    case 'COMMAND_1':
      Dialog.alert(`${this.properties.sampleTextOne}`);
      break;
    case 'COMMAND_2':
      Dialog.alert(`${this.properties.sampleTextTwo}`);
      break;
    default:
      throw new Error('Unknown command');
  }
}

Depurar seu Conjunto de Comandos ListView

Não é possível usar o Workbench local para testar as Extensões da Estrutura do SharePoint. Você precisará testá-los e desenvolvê-los diretamente em um site do SharePoint Online ao vivo. Não é preciso implantar sua personalização no catálogo de aplicativos para fazer isso, o que torna a experiência de depuração simples e eficiente.

  1. Vá até qualquer lista do SharePoint no site do SharePoint Online usando a experiência moderna ou crie uma lista. Copie a URL da lista para área de transferência, pois precisaremos dela na etapa seguinte.

    Como nosso Conjunto de Comandos ListView está hospedado no localhost e está em execução, podemos usar parâmetros da consulta de depuração específicos para executar o código no modo de exibição em lista.

  2. Abra o arquivo ./config/serve.json . Atualize os pageUrl atributos para corresponder a uma URL da lista em que você deseja testar a solução. Depois de editar seu serve.json deve ser um pouco parecido:

    {
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "customActions": {
        "bf232d1d-279c-465e-a6e4-359cb4957377": {
          "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
          "properties": {
            "sampleTextOne": "One item is selected in the list",
            "sampleTextTwo": "This command is always visible."
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "customActions": {
        "bf232d1d-279c-465e-a6e4-359cb4957377": {
          "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
          "properties": {
            "sampleTextOne": "One item is selected in the list",
            "sampleTextTwo": "This command is always visible."
          }
        }
      }
    }
  }
}

  3. Compile o código e hospede os arquivos compilados do computador local executando este comando:

    gulp serve

    Quando o código for compilado sem erros, ele atenderá ao manifesto resultante de https://localhost:4321.

    Isso também iniciará seu navegador padrão dentro da URL definida no arquivo ./config/serve.json . Observe que, pelo menos no Windows, você pode controlar qual janela do navegador é usada ativando a preferida antes de executar este comando.

  4. Aceite o carregamento de manifestos de depuração clicando em Carregar scripts de depuração quando solicitado.

    Aceitar o carregamento de debugripts

  5. Observe que o novo botão Comando Dois disponível na barra de ferramentas. Selecione esse botão para ver o texto fornecido como propriedade para a propriedade sampleTextTwo.

    Botão Comando Dois visível na barra de ferramentas de biblioteca de documentos

  6. O botão Comando Um não fica visível com base no código, até que uma linha seja selecionada na biblioteca de documentos. Carregue ou crie um documento para a biblioteca e confirme se o segundo botão está visível.

    Captura de tela do Comando Um que está sendo selecionado com a ordem Item A sendo realçada.

  7. Selecione Comando Dois para ver como funciona o controle de diálogo, usado na saída padrão do scaffolding da solução quando o Conjunto de Comandos ListView é selecionado como o tipo de extensão.

    Captura de tela de uma mensagem de alerta lendo Este comando está sempre visível com a opção O K sendo realçada.

Mais detalhes sobre as opções serve.json

  • customActions: simula uma ação personalizada. Você pode definir muitas propriedades sobre este objeto CustomAction e que afetam a aparência e o local do seu botão; vamos abordá-las mais tarde.
    • GUID: GUID da extensão.
    • Location: onde os comandos são exibidos. Os valores possíveis são:
      • ClientSideExtension.ListViewCommandSet.ContextMenu: o menu de contexto dos itens(s).
      • ClientSideExtension.ListViewCommandSet.CommandBarO 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").
    • Properties: um objeto JSON opcional que contém propriedades disponíveis por meio do this.properties membro.

Aprimorar a renderização do Conjunto de Comandos ListView

Vamos aproveitar uma nova API Diálogo, que pode ser usada para mostrar caixas de diálogo modais com facilidade desde o código. Nas etapas a seguir, modificaremos um pouco a experiência padrão para demonstrar casos de uso da API de Diálogo.

  1. Volte para Visual Studio Code (ou seu editor preferencial).

  2. Abra o arquivo ./src/extensions/helloWorld/HelloWorldCommandSet.ts .

  3. Atualize o método da onExecute() seguinte maneira:

    @override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
  switch (event.itemId) {
    case 'COMMAND_1':
      Dialog.alert(`Clicked ${strings.Command1}`);
      break;
    case 'COMMAND_2':
      Dialog.prompt(`Clicked ${strings.Command2}. Enter something to alert:`).then((value: string) => {
        Dialog.alert(value);
      });
      break;
    default:
      throw new Error('Unknown command');
  }
}

  4. Na janela do console, verifique se não há exceções. Se você ainda não tiver a solução em execução no localhost, execute o seguinte comando:

    gulp serve

  5. Aceite o carregamento de manifestos de depuração clicando em Carregar scripts de depuração quando solicitado.

    Aceitar o carregamento de scripts de depuração

    Ainda temos os mesmos botões na barra de ferramentas, mas você perceberá que eles se comportarão de maneira diferente se você selecioná-los um por um. Agora estamos usando a API de Diálogo nova, que pode ser facilmente usada com suas soluções, mesmo para cenários complexos.

    Aceitar o carregamento de scripts de depuração do botão OK

Adição de um Conjunto de Comandos ListView a um pacote de solução para implantação

  1. Retorne à sua solução no Visual Studio Code (ou em seu editor preferencial).
  2. Abra o arquivo ./sharepoint/assets/elements.xml.

Copie a estrutura XML a seguir para elements.xml. A ClientSideComponentId propriedade foi atualizada para a ID exclusiva do conjunto de comandos ListView disponível no arquivo ./src/extensions/helloWorld/HelloWorldCommandSet.manifest.json .

Observe que usamos um valor de local específico ClientSideExtension.ListViewCommandSet.CommandBar para definir que esse é um Conjunto de Comandos ListView e deve ser exibido na barra de comandos. Também definimos o RegistrationId para 100 e o RegistrationType como List associar essa ação personalizada automaticamente a listas genéricas. ClientSideComponentProperties pode ser usada para fornecer configurações específicas da instância. Nesse caso, estamos usando propriedades padrão chamadas sampleTextOne e sampleTextTwo.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="100"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
</Elements>

Observação

Durante a execução de localhost, a ação personalizada funcionará em listas e bibliotecas de documentos, mas não será implantada uma vez, a menos que o elements.xml seja atualizado. RegistrationId=100 só associará a ação personalizada com listas e NÃO com bibliotecas de documentos.

Para associar a ação personalizada a bibliotecas de documentos, o RegistrationId deve ser definido como 101. Se você quiser que a ação funcione em listas e bibliotecas de documentos, outra CustomAction deve ser adicionada ao arquivo elements.xml

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="100"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
    <CustomAction
        Title="SPFxListViewCommandSet"
        RegistrationId="101"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
        ClientSideComponentProperties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}">
    </CustomAction>
</Elements>

Os valores de local possíveis que podem ser usados com um Conjunto de Comandos ListView:

  • ClientSideExtension.ListViewCommandSet.CommandBar: Barra de ferramentas da lista ou biblioteca
  • ClientSideExtension.ListViewCommandSet.ContextMenu: menu de contexto para itens de lista ou biblioteca
  • ClientSideExtension.ListViewCommandSet: registrar comandos na barra de ferramentas e no menu de contexto

As definições devem ser usadas na conta dentro do pipeline de build

Abra o arquivo ./config/package-solution.json.

O arquivo package-solution.json define os metadados do pacote, conforme mostrado no código a seguir. Para garantir que o arquivo element.xml seja levado em conta enquanto o pacote de solução é criado, o scaffolding padrão deste arquivo é atualizado para incluir detalhes adicionais para uma definição de recurso. Essa definição de recurso é usada para provisionar e executar o arquivo elements.xml .

Observação

Você pode usar ClientSideInstance.xml para implantar automaticamente suas extensões em todos os sites no locatário. Mais detalhes sobre essa opção são encontrados no artigo Implantação de extensões da Estrutura do SharePoint para todos os locatários. Como essa solução destina-se a ser configurada para não usar a opção de escopo de locatário, esse arquivo xml é ignorado quando a solução é ativada no catálogo de aplicativos.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "command-extension-client-side-solution",
    "id": "0abe5c73-1655-49d3-922b-7a47dd70e151",
    "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": "25f8df47-61f2-4d75-bfe2-8d614f775219",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml",
            "clientsideinstance.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/command-extension.sppkg"
  }
}

Implantar a extensão no SharePoint Online

Agora, você está pronto para implantar a solução em um site do SharePoint e para ter a CustomAction associada automaticamente no nível do site.

Já que, por padrão, as soluções usarão a funcionalidade de empacotamento de ativos, os arquivos de JavaScript e outros ativos serão automaticamente empacotados no arquivo sppkg e então hospedados automaticamente do Office 365 CDN ou do conjunto de sites de catálogo de aplicativos.

  1. Na janela do console, insira o seguinte comando para empacotar sua solução do lado do cliente que contém a extensão, para que possamos preparar a estrutura básica para o empacotamento:

    gulp bundle --ship

  2. Em seguida, execute o comando a seguir para que o pacote da solução seja criado:

    gulp package-solution --ship

    O comando cria o seguinte pacote: pasta ./sharepoint/solution/command-extension.sppkg :

  3. Implante o pacote que foi gerado no catálogo de aplicativos. Para fazer isso, vá até o catálogo de aplicativos do seu locatário e abra a biblioteca Aplicativos do SharePoint.

  4. Carregue a pasta ./sharepoint/solution/command-extension.sppkg no catálogo do aplicativo. O SharePoint exibe uma caixa de diálogo e solicita que você confie na solução do lado do cliente.

  5. Escolha o botão Implantar.

    Confiar na operação no upload para o catálogo de aplicativos

  6. Vá para o site onde você deseja testar o provisionamento de ativos do SharePoint. Pode ser qualquer conjunto de sites no locatário em que você implantou o pacote de solução.

  7. Selecione o ícone de engrenagens na barra de navegação superior à direita e selecione Adicionar um aplicativo para acessar sua página Aplicativos.

  8. Na caixa Pesquisa, digite extensão e selecione Enter para filtrar os aplicativos.

    instalação do conjunto de comandos listview em um site

  9. Selecione o aplicativo command-extension-client-side-solution para instalar a solução no site. Quando a instalação estiver concluída.

  10. Após a instalação do aplicativo, selecione Nova na barra de ferramentas da página Conteúdo do Site e então escolha Lista

    Criação de uma nova lista

  11. Forneça o nome como Amostra e selecione Criar.

    Observe como o Comando Um e o Comando Dois estão sendo processados na barra de ferramentas com base em suas personalizações do Conjunto de Comandos ListView. Observe que a extensão também é reproduzida automaticamente para qualquer lista existente, não apenas para as novas.

    Botões adicionais visíveis na barra de ferramentas

Confira também