Migrar itens do menu do ECB e ações personalizadas de usuário para as Extensões da Estrutura do SharePoint
O Estrutura do SharePoint (SPFx) é o modelo de desenvolvimento recomendado para estender e criar personalizações do SharePoint. Se você personalizou o SharePoint com ações personalizadas do usuário e itens de menu ECB (Bloco de Controle de Edição) personalizados usando a Estrutura de Recursos do SharePoint, você pode se perguntar qual é a vantagem de migrá-los para o SPFx?
Primeiro, vamos apresentar as opções disponíveis ao desenvolver extensões Estrutura do SharePoint (SPFx):
- 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: adicione itens de menu ECB personalizados ou botões personalizados à barra de comandos de um modo de exibição de lista para uma lista ou 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 do alvo da sua personalização, é possível aproveitar qualquer um dos modelos acima. Por exemplo, os Personalizadores de Aplicativos são um excelente substituto para as ações personalizadas do usuário. Os Conjuntos de Comandos são uma substituição apropriada para os itens de menu ECB. Por fim, os Personalizadores de Campo destinam-se a substituir personalizações de JSLink/CSR (Client-Side-Rendering).
Benefícios de migrar as personalizações da Estrutura de Recursos do SharePoint para a Estrutura do SharePoint
A Estrutura do SharePoint foi desenvolvida pensando na nova experiência "moderna" do SharePoint, que está disponível nos sites de equipe "modernos" e em sites de comunicação "modernos", e se destina a todos os dispositivos e plataformas.
Só há suporte para a maneira de personalizar sites "modernos" sem script
Um dos principais benefícios da migração de personalizações herdadas da Estrutura de Recursos do SharePoint para o Estrutura do SharePoint é que essa é a única técnica com suporte que você tem em sites modernos para personalizar a interface do usuário.
Na verdade, os sites "modernos" têm o sinalizador sem script habilitado, o que evita a execução de qualquer script inserido na página e qualquer ação personalizada do usuário, que se refere ao JavaScript externo ou ao JavaScript inserido.
As ações personalizadas do usuário herdado simplesmente não funcionam na interface do usuário "moderna". As personalizações de ECB criadas usando o Feature Framework são limitadas. Você só pode definir itens ECB que não se referem a arquivos JavaScript externos ou que não usam chamadas JavaScript inseridas. Se você realmente quiser estender a interface do usuário "moderna", precisará atualizar para o Estrutura do SharePoint.
Acesso mais fácil a informações no SharePoint e no Microsoft 365
Outro ponto fundamental a ser considerado é que, no modelo herdado de ações personalizadas do usuário e personalizações de ECB, não era fácil consumir conteúdo e dados do SharePoint. A única maneira de fazer isso era usando as APIs REST de nível inferior ou JSOM (o modelo de objeto do lado do cliente do JavaScript do SharePoint). Além disso, era quase impossível consumir o conjunto completo de serviços do Microsoft 365, a menos que você tenha aproveitado o ADAL.JS (Biblioteca de Autenticação do Azure Active Directory para JavaScript) e o 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 ações personalizadas do usuário da Estrutura de Recursos do SharePoint e os itens do ECB e as personalizações da Estrutura de Recursos do SharePoint compartilham algumas semelhanças.
Modelo de provisionamento
As extensões Estrutura do SharePoint e as ações personalizadas do usuário ou as soluções de item de menu ECB aproveitam um arquivo de manifesto XML, que é escrito com a sintaxe da Estrutura de Recursos do SharePoint; a implantação é baseada nas mesmas técnicas.
Executar como parte da página
Assim como em ações personalizadas de usuários e ECB da Estrutura de Recursos do SharePoint, as Extensões de Estrutura do SharePoint são 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 as Extensões da Estrutura do SharePoint são executadas como parte da página, sejam quais forem os recursos aos quais uma personalização tem acesso, os demais elementos na página também poderão acessá-los. É 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. Uma vez que as Extensões da Estrutura do SharePoint são executadas como parte da página, outros elementos na página também podem acessar todos esses recursos.
Usar qualquer biblioteca para criar suas extensões
Ao criar personalizações de página usando ações personalizadas do usuário, você pode ter usado bibliotecas como jQuery ou Knockout para implementar personalizações dinâmicas e responder melhor à interação do usuário. Ao criar as Extensões da Estrutura do SharePoint, é possível usar qualquer biblioteca do lado do cliente para aprimorar sua solução, da mesma maneira que teria feito no passado.
Um benefício adicional que o Estrutura do SharePoint oferece é o isolamento do script. Embora a Web Part seja executada como parte da página, seu script é empacotado como um módulo, permitindo que extensões diferentes na mesma página usem uma versão diferente do jQuery sem colidir entre si. 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 ações personalizadas do usuário e itens do menu do ECB, 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 soluções de Extensões de Estrutura do SharePoint e ações personalizadas do usuário ou item do menu do ECB são executadas no navegador e podem conter somente o código JavaScript no 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 a ação personalizada do usuário ou as soluções de item de menu ECB podem ser hospedadas 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. Os pacotes da Estrutura do SharePoint (arquivos *.sppkg) implantados no catálogo de aplicativos especificam a URL na qual a 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.
Diferenças entre soluções da Estrutura do SharePoint e personalizações da Estrutura de Recursos do SharePoint
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
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 de sem script e funcionam em todos os sites "modernos".
Conjunto predefinido de pontos de extensibilidade
Embora uma ação personalizada do usuário possa inserir código JavaScript que possa atualizar ou alterar o DOM de qualquer parte da página, uma extensão Estrutura do SharePoint só pode personalizar áreas com suporte de páginas "modernas".
Teoricamente, é possível criar um Personalizador de Aplicativos que usa o DOM para alterar completamente a estrutura de uma página, como com as ações personalizadas do usuário. A Estrutura do SharePoint estimula uma abordagem mais estruturada e confiável para a personalização do SharePoint. Em vez de usar elementos DOM específicos para personalizar o SharePoint, a Estrutura do SharePoint oferece aos desenvolvedores ganchos e espaços reservados para personalizações, e você deve usar somente eles.
Use TypeScript para compilar de maneira mais robusta e manter as soluções com mais facilidade
Ao criar personalizações usando as ações personalizadas do usuário ou os itens de menu ECB, os desenvolvedores geralmente usaram JavaScript. 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, muitos erros são capturados durante o desenvolvimento, em vez de em runtime. 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 do usuário clássica do SharePoint, muitos desenvolvedores usavam o modelo de objeto do JavaScript (JSOM) para se comunicar com o SharePoint. O JSOM oferecia a eles IntelliSense e acesso fácil à API do SharePoint de forma semelhante ao modelo de objeto do lado do cliente (CSOM). Nas páginas clássicas do SharePoint, a principal parte do JSOM estava presente por padrão na página e os desenvolvedores poderiam carregar partes adicionais para, por exemplo, se comunicarem com a Pesquisa do SharePoint.
A experiência moderna do usuário do SharePoint não inclui o SharePoint JSOM por padrão. Embora os desenvolvedores possam carregá-la por conta própria, a recomendação é usar a API REST em vez disso, ou a Biblioteca Principal do JavaScript de Padrões e Práticas do SharePoint (Biblioteca PnP JS), 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á mais investindo ativamente em JSOM. Se preferir trabalhar com uma API, você poderá usar a Biblioteca PnP JS, que oferece uma API fluente e tipificações typeScript.
Migrar personalização existente para as Extensões de Estrutura do SharePoint
Migrar personalizações de Extensões de Estrutura do SharePoint oferece aos usuários finais e aos desenvolvedores vários benefícios. 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 Extensões da Estrutura do SharePoint, é possível optar por reutilizar seus 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 JavaScript, não há uma maneira fácil de determinar se os scripts existentes podem ser reutilizados em uma solução Estrutura do SharePoint ou se você precisa reescrevê-los. 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 do que reutilização de scripts existentes, ele oferece melhores resultados em um período mais longo: uma solução que é melhor e mais fácil de manter.
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.