Compartilhar via

Migrar personalizações de JSLink para Personalizadores de Campo da Estrutura do SharePoint

  • Artigo

O Estrutura do SharePoint (SPFx) é o modelo recomendado para estender e criar personalizações do SharePoint. Se você personalizou campos e exibições de lista do SharePoint com JSLink, você pode se perguntar qual é a vantagem de migrar essas personalizações para o SPFx.

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.

Dependendo de qual é o alvo da sua personalização, é possível aproveitar qualquer um dos modelos acima. Por exemplo, os Personalizadores de Campo são uma boa substituição para as personalizações de campos de JSLink.

Dica

Embora os personalizadores de campo sejam o caminho de migração natural do JSLink, você também deve avaliar o uso da formatação de lista e coluna para personalizar o modo de exibição de lista. Ambas as tecnologias têm suas vantagens e desvantagens individuais e uma pode ser mais simples de implementar e manter do que a outra, dependendo do seu cenário.

Saiba mais aqui: usar a formatação de coluna para personalizar o SharePoint

O Estrutura do SharePoint foi criado para estender a experiência "moderna" do SharePoint. A experiência "moderna" está disponível nos sites de equipe "modernos" e nos sites de comunicação "modernos", e tem como alvo qualquer dispositivo e qualquer plataforma.

A única maneira compatível de personalizar listas e bibliotecas "modernas"

Um dos principais benefícios da migração de personalizações de JSLink herdadas para o Estrutura do SharePoint é que essa é a única opção com suporte disponível. Na verdade, as listas e bibliotecas "modernas", devido à sua infraestrutura de renderização e devido ao sinalizador sem script habilitado nos sites "modernos", não podem depender de personalizações de JSLink herdados. Se você realmente quiser estender a interface do usuário "moderna", precisará migrar a solução JSLink para um Estrutura do SharePoint personalizador de campo.

Acesso mais fácil a informações no SharePoint e no Microsoft 365

Outro tópico fundamental a ser considerado é que, nas personalizações de JSLink herdados, não era fácil consumir conteúdo e dados do SharePoint. A única maneira de fazer isso era usando o JSOM (modelo de objeto do lado do cliente) javaScript ou APIs REST de baixo nível. Era quase impossível consumir o conjunto completo de serviços do Microsoft 365, a menos que você tenha usado ADAL.JS (Biblioteca de Autenticação do Azure Active Directory para JavaScript) e código JavaScript personalizado.

Agora, com o Estrutura do SharePoint e as extensões Estrutura do SharePoint, é fácil e simples consumir a API REST do SharePoint e o Microsoft Graph. Agora você pode criar soluções mais poderosas, que podem consumir e interagir com todo o ecossistema de serviços fornecidos pelo Microsoft 365.

Similaridades entre soluções da Estrutura do SharePoint e personalizações da Estrutura de Recursos do SharePoint

As personalizações do JSLink e as personalizações da Estrutura de Recursos do SharePoint compartilham algumas semelhanças.

Modelo de provisionamento

As Estrutura do SharePoint e as ações personalizadas do usuário ou as soluções de item de menu ECB usam um arquivo de manifesto XML, que é escrito com a sintaxe da Estrutura de Recursos do SharePoint. Portanto, a implantação se baseia nas mesmas técnicas. No entanto, com novos Personalizadores de Campo, é possível personalizar a renderização de um campo e não a renderização de um único modo de exibição de uma lista ou biblioteca. O campo personalizado pode ser usado em quantas listas e bibliotecas desejar.

Executar como parte da página

Semelhante às ações personalizadas do usuário e ao ECB da Estrutura de Recursos do SharePoint, Estrutura do SharePoint extensões fazem parte da página. Isso fornece a essas soluções acesso ao DOM da página e permite que elas se comuniquem com outros componentes na mesma página. Além disso, ele permite que os desenvolvedores deixem suas soluções mais responsivas para se adaptarem aos diferentes fatores de forma nos quais uma página do SharePoint pode ser exibida, incluindo o aplicativo móvel do SharePoint.

Como Estrutura do SharePoint extensões são executadas como parte da página, quaisquer recursos aos que a personalização tenha acesso, outros elementos na página também podem acessar. É importante ter isso em mente ao criar soluções que dependem de fluxo implícito de OAuth com tokens de acesso do portador ou usam cookies ou armazenamento do navegador para armazenar informações confidenciais. Como Estrutura do SharePoint extensões são executadas como parte da página, outros elementos nessa página também podem acessar todos esses recursos.

Usar qualquer biblioteca para criar suas extensões

Ao criar personalizações de páginas usando ações personalizadas do usuário, você talvez tenha usado bibliotecas como jQuery ou Knockout para tornar sua personalização dinâmica e responder melhor à interação do usuário. Ao criar Estrutura do SharePoint extensões, você pode usar qualquer biblioteca do lado do cliente para enriquecer sua solução, da mesma maneira que faria no passado.

Um benefício adicional que a Estrutura do SharePoint oferece é o isolamento de script. Embora a web part seja executada como parte da página, seu script é fornecido como um módulo, permitindo, por exemplo, diferentes extensões na mesma página para usar uma versão diferente do jQuery sem entrar em conflito. Este é um poderoso recurso que permite que você se concentre em fornecer o valor de negócios em vez de migração técnica e comprometer a funcionalidade.

Executar como o usuário atual

Em personalizações criadas usando JSLink, sempre que você precisava se comunicar com o SharePoint, bastava chamar sua API. A solução do lado do cliente estava sendo executada no navegador no contexto do usuário atual e ao enviar automaticamente o cookie de autenticação junto com a solicitação, sua solução podia se conectar diretamente ao SharePoint. Nenhuma autenticação adicional, como ao usar os Suplementos do SharePoint, era necessária para se comunicar com o SharePoint.

O mesmo mecanismo se aplica a personalizações criadas na Estrutura do SharePoint, que também é executado no contexto do usuário autenticado atualmente e não requer outras etapas de autenticação para se comunicar com o SharePoint. O contexto de segurança é o do usuário conectado no momento, o que implica que, de uma perspectiva de segurança, você precisa ter cuidado ao instalar qualquer extensão Estrutura do SharePoint em qualquer conjunto de sites de destino.

Usar somente o código do lado do cliente

As Estrutura do SharePoint e as personalizações JSLink são executadas no navegador e podem conter apenas o código JavaScript do lado do cliente. As soluções do lado do cliente têm várias limitações, como não poder elevar permissões no SharePoint ou utilizar APIs externas que não dão suporte à comunicação entre origens (CORS) ou autenticação usando fluxo implícito de OAuth. Nesses casos, a solução do lado do cliente pode aproveitar uma API remota do lado do servidor para executar a operação necessária e retornar os resultados para o cliente.

Modelo de hospedagem auto-consistente e baseado no Microsoft 365

As extensões Estrutura do SharePoint e os arquivos JavaScript para personalizações JSLink podem ser hospedados no SharePoint Online e, eventualmente, no serviço CDN do Microsoft 365, evitando qualquer necessidade de serviços externos ou ambientes de hospedagem.

Embora a hospedagem Estrutura do SharePoint soluções em uma CDN ofereça muitas vantagens, ela não é necessária e você pode optar por hospedar o código em uma biblioteca de documentos do SharePoint. Estrutura do SharePoint pacotes (*arquivos .sppkg) implantados no Catálogo de Aplicativos especificam a URL na qual Estrutura do SharePoint pode encontrar o código da solução. Se o usuário que navega na página com a extensão puder baixar o script do local especificado, não haverá restrições em relação a qual deve ser a URL.

O Microsoft 365 oferece a funcionalidade de CDN pública que permite que você publique arquivos de uma biblioteca de documentos específica do SharePoint em uma CDN. A CDN pública do Microsoft 365 tem um bom equilíbrio entre os benefícios de usar uma CDN e a simplicidade de hospedar arquivos de código em uma biblioteca de documentos do SharePoint. Se sua organização não se importar que seus arquivos de código estão disponíveis publicamente, usar a CDN pública do Microsoft 365 é uma opção que vale a pena considerar.

No entanto, entre os dois modelos de desenvolvimento há algumas diferenças significativas, que você deve considerar ao desenvolver a arquitetura das suas soluções.

Executar em sites sem script, em listas e bibliotecas "modernas"

Como Estrutura do SharePoint soluções, incluindo extensões, são implantadas por meio do Catálogo de Aplicativos com uma aprovação anterior, elas não estão sujeitas às restrições sem script e funcionam em todos os sites "modernos". Como já vimos, os personalizadores de campo Estrutura do SharePoint funcionam em listas e bibliotecas "modernas", enquanto o JSLink herdado não funciona.

Os Personalizadores de Campo oferecem suporte somente a cenário de exibição

Uma personalização JSLink pode ser usada para personalizar não apenas o modo de exibição de um campo em uma lista ou biblioteca, mas também a exibição, e editar os modos de exibição de um campo ao mostrar um único item.

No momento da redação deste artigo, um Personalizador de Campos do Estrutura do SharePoint pode personalizar a renderização de um campo somente no modo de renderização do modo de exibição de lista, enquanto nas exibições de exibição e edição de um único item você não pode aproveitar a personalização.

Use TypeScript para compilar de maneira mais robusta e manter as soluções com mais facilidade

Durante a criação de personalizações usando o JSLink, os desenvolvedores geralmente usavam JavaScript simples. Muitas vezes, essas soluções não continham testes automatizados e refatorar o código poderia gerar erros.

A Estrutura do SharePoint permite que os desenvolvedores se beneficiem do sistema de tipos TypeScript ao criar soluções. Graças ao sistema de tipos, os erros são detectados durante o desenvolvimento e não no tempo de execução. Além disso, a refatoração de código pode ser feita com mais facilidade porque as alterações no código são protegidas pelo TypeScript. Como todo JavaScript é um TypeScript válido, a barreira de entrada é baixa, e é possível migrar seu JavaScript simples para TypeScript gradualmente ao longo do tempo aumentando a capacidade de manutenção de suas soluções.

Sem acesso ao modelo de objeto do SharePoint JavaScript por padrão

Ao criar personalizações do lado do cliente para a experiência clássica do usuário do SharePoint, muitos desenvolvedores usaram o JSOM para se comunicar com o SharePoint. O JSOM ofereceu a eles o IntelliSense e acesso fácil à API do SharePoint de maneira semelhante ao CSOM (modelo de objeto Client-Side). Nas páginas clássicas do SharePoint, a parte principal do JSOM estava presente por padrão na página, e os desenvolvedores podiam carregar partes adicionais para se comunicar com a Pesquisa do SharePoint, por exemplo.

A experiência moderna do usuário do SharePoint não inclui o SharePoint JSOM por padrão. Embora os desenvolvedores possam carregá-lo por conta própria, a recomendação é usar a API REST ou a PnPJS (Biblioteca Principal de Padrões e Práticas do SharePoint), que usa internamente a API REST do SharePoint. Usar REST é mais universal e intercambiável entre as diferentes bibliotecas do lado do cliente, como jQuery, Angular ou React.

A Microsoft não está investindo ativamente no JSOM. Se preferir trabalhar com uma API, você poderá usar a Biblioteca PnP JS, que oferece uma API fluente e declarações de tipo TypeScript.

Migrar a personalização existente para as extensões Estrutura do SharePoint configuração

A migração de personalizações existentes para as extensões Estrutura do SharePoint oferece muitos benefícios aos usuários finais e aos desenvolvedores. Ao considerar a migração de personalizações existentes para o Estrutura do SharePoint, você pode optar por reutilizar o máximo possível de scripts JavaScript existentes ou reescrever completamente a personalização usando o TypeScript.

Reutilizar scripts existentes

Ao migrar as personalizações existentes para as Estrutura do SharePoint, você pode optar por reutilizar os scripts existentes. Embora a Estrutura do SharePoint incentive o uso de TypeScript, é possível usar o JavaScript simples e gradualmente transformá-lo em TypeScript. Se você precisar de suporte para uma solução por um período limitado ou se tiver um orçamento limitado, essa abordagem poderá ser boa para você.

Reutilizar scripts existentes em uma solução da Estrutura do SharePoint nem sempre é possível. Por exemplo, considerando a variedade de bibliotecas do JavaScript, não há maneira fácil de saber antecipadamente se seus scripts podem ser reutilizados em uma solução da Estrutura do SharePoint ou se você precisará reescrevê-los no final das contas. A única maneira de determinar isto é tentar mover as diferentes partes de uma solução da Estrutura do SharePoint e ver se elas funcionam conforme o esperado.

Reescrever a personalização

Se você precisar dar suporte à sua solução por um período mais longo ou quiser fazer melhor uso do Estrutura do SharePoint ou se descobrir que os scripts existentes não podem ser reutilizados com o Estrutura do SharePoint, talvez seja necessário reescrever completamente sua personalização. Embora seja mais caro que reutilizar scripts, isso proporciona melhores resultados no longo prazo: uma solução de melhor desempenho e mais fácil de manter e de usar.

Ao reescrever uma personalização existente para uma Estrutura do SharePoint, você deve começar com a funcionalidade desejada em mente. Para implementar a experiência do usuário, você deverá usar o Office UI Fabric para que sua solução pareça fazer parte do SharePoint.

Confira também