Compartilhar via

Migrar do JSLink para Extensões da Estrutura do SharePoint

  • Artigo

Desde o Microsoft SharePoint 2013, a maioria das soluções corporativas compiladas sobre o Microsoft 365 e o SharePoint aproveitam a propriedade JSLink dos campos e modos de exibição de lista para personalizar a renderização dos campos.

Dentro da Interface do usuário "moderna" do SharePoint Online e do SharePoint Server 2019, a maioria dessas personalizações não está mais disponível. Felizmente, as extensões da Estrutura do SharePoint permitem que você forneça funcionalidade semelhante na IU "moderna".

Neste tutorial, você aprende a migrar das antigas personalizações "clássicas" para o novo modelo com base nas Extensões da Estrutura do SharePoint.

Observação

Confira mais informações sobre como criar as Extensões de Estrutura do SharePoint em Visão geral das Extensões de Estrutura do SharePoint.

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 em nosso contexto é a extensão do Personalizador de Campos.

Suponha que você esteja no SharePoint Online e tenha uma lista personalizada com um campo personalizado chamado "Cor" do tipo Escolha e que poderá assumir os seguintes valores: Vermelho, Verde, Azul e Amarelo. Suponha que você tenha um valor personalizado para a propriedade JSLink do modo de exibição de lista que renderiza a web part da lista personalizada.

No seguinte trecho de código, é possível ver o código do JavaScript referenciado pela propriedade JSLink (customColorRendering.js).

// Define a namespace for the custom rendering code
var customJSLinkRendering = customJSLinkRendering || {};

// Define a function that declare the custom rendering rules for the target list view
customJSLinkRendering.CustomizeFieldRendering = function () {

  // Define a custom object to configure the rendering template overrides
  var customRenderingOverride = {};
  customRenderingOverride.Templates = {};
  customRenderingOverride.Templates.Fields =
  {
    // Declare the custom rendering function for the 'View' of field 'Color'
    'Color':
    {
      'View': customJSLinkRendering.RenderColorField
    }
  };

  // Register the custom rendering template
  SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);
};

// Declare the custom rendering function for the 'View' of field 'Color'
customJSLinkRendering.RenderColorField = function (context)
{
  var colorField = context.CurrentItem.Color;

  // Declare a local variable to hold the output color
  var color = '';

  // Evaluate the values of the 'Color' field and render it accordingly
  switch (colorField)
  {
    case 'Red':
      color = 'red';
      break;
    case 'Green':
      color = 'green';
      break;
    case 'Blue':
      color = 'blue';
      break;
    case 'Yellow':
      color = 'yellow';
      break;
    default:
      color = 'white';
      break;
  }

  // Render the output for the 'Color' field
  return "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
};

// Invoke the custom rendering function
customJSLinkRendering.CustomizeFieldRendering();

Além disso, na captura de tela a seguir, é possível ver como a propriedade JSLink está configurada na web part do modo de exibição de lista.

A configuração da propriedade JSLink na web part do modo de exibição de lista

Se você tiver carregado o arquivo do JavaScript na biblioteca Site Assets, o valor da propriedade JSLink poderá ser "~site/SiteAssets/customColorRendering.js".

Você pode ver como funciona a renderização personalizada da lista.

A renderização personalizada do campo

Como é possível ver, os campos Cor renderizam uma caixa de cores preenchida com a cor selecionada no nível do item.

Observação

Para provisionar esse tipo de solução em um site "clássico", eventualmente, use um modelo de provisionamento PnP que pode provisionar a lista com o campo personalizado e a propriedade JSLink ao mesmo tempo.

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-custom-field-extension

  2. Vá até a pasta do projeto:

    cd spfx-custom-field-extension

  3. Na pasta do projeto, execute o gerador Yeoman da Estrutura do SharePoint para estruturar um novo projeto da Estrutura 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 sua solução?: spfx-custom-field-extension
    • Que tipo de componente do lado do cliente deve ser criado?: Extensão
    • Que tipo de extensão do lado do cliente criar? Personalizador de Campos
    • Qual o nome do Personalizador de Campos? CustomColorField
    • Qual é o modelo que você gostaria de usar?: nenhuma estrutura JavaScript

  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 Personalizador de Campos com o JavaScript

Para reproduzir o mesmo comportamento da renderização do campo personalizado JSLink, você só 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 a pasta de arquivo ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.manifest.json. Copie o valor da propriedade id e armazene-o em um local seguro, pois você precisará dele mais tarde.

  2. Abra o arquivo./src/extensions/customColorField/CustomColorFieldFieldCustomizer.ts e edite o conteúdo de acordo com o seguinte trecho de código:

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

import * as strings from 'CustomColorFieldFieldCustomizerStrings';
import styles from './CustomColorFieldFieldCustomizer.module.scss';

/**
* If your field customizer uses the ClientSideComponentProperties JSON input,
* it will be deserialized into the BaseExtension.properties object.
* You can define an interface to describe it.
*/
export interface ICustomColorFieldFieldCustomizerProperties {
  // This is an example; replace with your own property
  sampleText?: string;
}

const LOG_SOURCE: string = 'CustomColorFieldFieldCustomizer';

export default class CustomColorFieldFieldCustomizer
extends BaseFieldCustomizer<ICustomColorFieldFieldCustomizerProperties> {

  @override
  public onInit(): Promise<void> {
    // Add your custom initialization to this method.  The framework will wait
    // for the returned promise to resolve before firing any BaseFieldCustomizer events.
    Log.info(LOG_SOURCE, 'Activated CustomColorFieldFieldCustomizer with properties:');
    Log.info(LOG_SOURCE, JSON.stringify(this.properties, undefined, 2));
    Log.info(LOG_SOURCE, `The following string should be equal: "CustomColorFieldFieldCustomizer" and "${strings.Title}"`);
    return Promise.resolve();
  }

  @override
  public onRenderCell(event: IFieldCustomizerCellEventParameters): void {

    var colorField = event.fieldValue;

    // Declare a local variable to hold the output color
    var color = '';

    // Evaluate the values of the 'Color' field and render it accordingly
    switch (colorField)
    {
      case 'Red':
        color = 'red';
        break;
      case 'Green':
        color = 'green';
        break;
      case 'Blue':
        color = 'blue';
        break;
      case 'Yellow':
        color = 'yellow';
        break;
      default:
        color = 'white';
        break;
    }

    // Render the output for the 'Color' field
    event.domElement.innerHTML = "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
  }

  @override
  public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
    // This method should be used to free any resources that were allocated during rendering.
    // For example, if your onRenderCell() called ReactDOM.render(), then you should
    // call ReactDOM.unmountComponentAtNode() here.
    super.onDisposeCell(event);
  }
}

    Como é possível ver, o conteúdo do método onRenderCell() é quase igual ao método anterior RenderColorField() na implementação do JSLink. As únicas diferenças são:

    • Para recuperar o valor do campo atual, é necessário ler a propriedade event.fieldValue do argumento da entrada do método onRenderCell().
    • Para retornar o código HTML personalizado para renderizar o campo, você precisa atribuir um valor à propriedade innerHTML do objeto event.domElement que representa o contêiner HTML de saída da renderização do campo.

    Além dessas pequenas alterações, é possível reutilizar praticamente o mesmo código do JavaScript como antes.

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

    O Personalizador de Campos 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 lista de "moderna" que tem um campo personalizado com o nome Cor e digite Escolha com as mesmas opções de valor que antes (Vermelho, Verde, Azul, Amarelo). Eventualmente, é possível usar a lista criada no site "clássico". Para usá-la, basta exibi-la com a nova experiência "moderna". Agora, 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&fieldCustomizers={"Color":{"id":"c3070978-d85e-4298-8758-70b5b5933076"}}

    Na sequência de consulta, substitua o GUID pelo valor id salvo no arquivo CustomColorFieldFieldCustomizer.manifest.json e o nome do objeto Cor refere-se ao nome do campo a ser personalizado. Se quiser, você também pode fornecer um objeto de configuração personalizado, serializado em formato JSON, como um parâmetro adicional para a construção do personalizador de campos.

    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

Defina o novo Personalizador de Campos com o TypeScript

Agora você já está pronto para substituir o código do JavaScript pelo TypeScript para se beneficiar da abordagem totalmente digitada do TypeScript.

  1. Abra o arquivo ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.module.scss. Este arquivo, que é um Sass CSS, representa o estilo da interface do usuário do personalizador campos. Substitua o conteúdo do arquivo SCSS pelo conteúdo a seguir.

    .CustomColorField {
  .cell {
    float: left;
    width: 20px;
    height: 20px;
    margin: 5px;
    border: 1px solid rgba(0,0,0,.2);
  }

  .cellRed {
    background: red;
  }

  .cellGreen {
    background: green;
  }

  .cellBlue {
    background: blue;
  }

  .cellYellow {
    background: yellow;
  }

  .cellWhite {
    background: white;
  }
}

  2. Substitua a implementação do método onRenderCell() pelo seguinte trecho de código.

    @override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  // Read the current field value
  let colorField: String = event.fieldValue;

  // Add the main style to the field container element
  event.domElement.classList.add(styles.CustomColorField);

  // Get a reference to the output HTML
  let fieldHtml: HTMLDivElement = event.domElement.firstChild as HTMLDivElement;

  // Add the standard style
  fieldHtml.classList.add(styles.cell);

  // Add the colored style
  switch(colorField)
  {
    case "Red":
      fieldHtml.classList.add(styles.cellRed);
      break;
    case "Green":
      fieldHtml.classList.add(styles.cellGreen);
      break;
    case "Blue":
      fieldHtml.classList.add(styles.cellBlue);
      break;
    case "Yellow":
      fieldHtml.classList.add(styles.cellYellow);
      break;
    default:
      fieldHtml.classList.add(styles.cellWhite);
      break;
  }
}

    A implementação do novo método usa uma abordagem totalmente digitada e atribui a classe CSS cell ao elemento DIV filho do elemento de campo atual, além de outra classe CSS personalizada para definir a cor de destino do elemento DIV baseado no valor do campo selecionado no momento.

  3. Execute mais uma vez o Personalizador de Campos no modo de depuração e veja os resultados.

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 o arquivo /sharepoint/assets/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/">
    <Field ID="{40475661-efaf-447a-a220-c992b20ec1c3}"
           Name="SPFxColor"
           DisplayName="Color"
           Title="Color"
           Type="Choice"
           Required="FALSE"
           Group="SPFx Columns"
           ClientSideComponentId="c3070978-d85e-4298-8758-70b5b5933076">
    </Field>
</Elements>

    Como é possível ver, isso nos lembra o arquivo da Estrutura de Recursos do SharePoint, mas define um elemento Field personalizado com um tipo de campo Choice, que usa o atributo ClientSideComponentId para fazer referência à id do Personalizador de Campos, e pode haver um atributo ClientSideComponentProperties para configurar as propriedades personalizadas de configuração necessárias para o extensão.

  2. Abra o arquivo ./config/package-solution.json. No arquivo, é possível ver que há uma referência para o arquivo elements.xml na seção assets.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-custom-field-extension-client-side-solution",
    "id": "ab0fbbf8-01ba-4633-8498-46cfd5652619",
    "version": "1.0.0.0",
    "features": [{
      "title": "Application Extension - Deployment of custom action.",
      "description": "Deploys a custom action with ClientSideComponentId association",
      "id": "090dc976-878d-44fe-8f8e-ac603d094aa1",
      "version": "1.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml"
        ]
      }
    }]
  },
  "paths": {
    "zippedPackage": "solution/spfx-custom-field-extension.sppkg"
  }
}

Empacote e implante a solução

Em seguida, você precisa agrupar e empacotar o pacote de soluções para o catálogo de aplicativos. Para realizar essa tarefa, siga estas etapas.

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-custom-field-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, crie uma nova lista personalizada, edite as configurações da lista e adicione uma nova coluna a partir de colunas já existentes do site. Escolha o grupo de colunas chamado Colunas SPFx e adicione o campo Cor.

    Adicionar o campo à lista

  6. Edite apenas o campo adicionado, configure alguns valores de cor (como: Vermelho, Verde, Azul e Amarelo) e, em seguida, salve as configurações de campo.

  7. Adicione alguns itens à lista e veja o resultado no modo de exibição de lista. A exibição deve ser semelhante à captura de tela a seguir.

    O Personalizador de Campos em ação

Aproveite sua nova compilação do Personalizador de Campos usando as Extensões da Estrutura do SharePoint.

Confira também