Migrar as personalizações de Web Part do Editor de Scripts existentes para a Estrutura do SharePoint
A Estrutura do SharePoint é um modelo para a criação de personalizações do SharePoint. Se você criou soluções do SharePoint do lado do cliente usando a Web Part do Editor de Scripts, deverá estar se perguntando quais são as possíveis vantagens de migrá-los para a Estrutura do SharePoint.
Este artigo destaca os benefícios de migrar personalizações existentes do lado do cliente para a Estrutura do SharePoint e ressalta várias informações que você deve levar em consideração ao planejar a migração.
Observação
As informações neste artigo aplicam-se a personalizações criadas usando o conteúdo e a Web Part do Editor de Scripts. Sempre que houver uma referência à Web Part do Editor de Scripts, você deverá ler Web Part do Editor de Conteúdo e Web Part do Editor de Scripts.
Benefícios de migrar as personalizações do lado do cliente existentes para a Estrutura do SharePoint
A Estrutura do SharePoint foi desenvolvida desde o início como um modelo de desenvolvimento do SharePoint concentrando-se no desenvolvimento do lado do cliente. Embora ele principalmente ofereça recursos de extensibilidade para sites de equipe modernos, as personalizações criadas na Estrutura do SharePoint também funcionam com a experiência clássica do SharePoint. Construir suas personalizações usando a Estrutura do SharePoint oferece muitos benefícios em relação a qualquer outro modelo de desenvolvimento do SharePoint disponível até o momento.
Construir uma vez, reutilizar em todos os dispositivos
A experiência do usuário do SharePoint moderna foi projetada para dar suporte nativo ao acesso às informações armazenadas no SharePoint em qualquer dispositivo. Além disso, a experiência moderna dá suporte ao aplicativo móvel do SharePoint. As soluções criadas usando a Estrutura do SharePoint integram-se perfeitamente com a experiência moderna do SharePoint e podem ser usadas em dispositivos diferentes, e dentro do aplicativo móvel do SharePoint. Como as soluções da também funcionam com a experiência clássica do SharePoint, elas podem ser usadas por organizações que ainda não migraram para a experiência moderna.
Mais robusta e durável
No passado, os desenvolvedores personalizavam o SharePoint anexando a elementos específicos de DOM na interface do usuário. Com essa abordagem, eles podiam mudar a experiência padrão do usuário ou fornecer funcionalidade adicional para usuários finais. Porém, essas soluções eram propensas a erros. Como o DOM de página do SharePoint nunca foi pensado como uma superfície de extensibilidade, sempre que era alterado, as soluções que dependiam dele travavam.
A Estrutura do SharePoint oferece aos desenvolvedores pontos de extensibilidade e API padronizada para criar soluções do lado do cliente e fornecer recursos adicionais aos usuários finais. Os desenvolvedores podem usar a Estrutura do SharePoint para criar soluções com suporte e duráveis, e você não precisará se preocupar com o modo como alterações futuras à interface de usuário do SharePoint possam afetar a sua solução.
Acesso mais fácil às informações no SharePoint e no Office 365
A Microsoft está continuamente ampliando os recursos do SharePoint e do Office 365. À medida que as organizações fazem mais uso de ambas as plataformas, está se tornando cada vez mais importante que os desenvolvedores toquem nas informações e insights armazenados em Office 365 para criar soluções avançadas. Um dos objetivos do SharePoint Framework é facilitar para os desenvolvedores se conectarem a várias APIs do Office 365 e do SharePoint.
Permitir que os usuários configurem soluções para as suas necessidades
As soluções do lado do cliente criadas por meio da inserção de scripts muitas vezes não ofereceram aos usuários finais uma maneira fácil de configurá-las às suas necessidades. A única maneira de configurar essa solução era alterando seu código ou por meio de uma interface do usuário personalizada criada especificamente para essa finalidade.
As Web Parts do lado do cliente do SharePoint Framework oferecem uma maneira padrão de configurar Web Parts usando um painel de propriedades familiar aos usuários que trabalharam com as Web Parts clássicas no passado. Os desenvolvedores que criam Web Parts do lado do cliente podem escolher se suas Web Parts devem ter um painel de propriedade reativo (padrão), onde cada alteração em uma propriedade da Web Part é diretamente refletida no corpo da Web Part, ou um painel de propriedade não reativo, onde as alterações de propriedades da Web Part devem ser aplicadas explicitamente.
Trabalhar em sites sem script
Para ajudar as organizações a governarem suas personalizações, a Microsoft lançou o recurso sem script no SharePoint Online. Quando o conjunto de sites específico ou de um locatário tem o sinalizador de não script habilitado, as personalizações que dependem de inserção de script e incorporação são desabilitadas.
Como as web parts do lado do cliente da Estrutura do SharePoint são implantadas pelo catálogo de aplicativos com uma aprovação prévia, elas podem ser executadas em sites sem script. Por padrão, os sites de equipe modernos têm a configuração de não script habilitada e não é possível incorporar scripts nesses sites. Isso ocorre usando a Estrutura do SharePoint, a única forma aceita para compilar as personalizações do lado do cliente em sites de equipe modernos.
Semelhanças entre soluções da Estrutura do SharePoint e personalizações de Web Part do Editor de Scripts
Embora criadas em um novo modelo de desenvolvimento usando um novo conjunto de ferramentas, Estrutura do SharePoint soluções são semelhantes às personalizações de Web Part do Editor de Script que você construiu no passado. Como elas têm os mesmos conceitos, isso facilita você migrá-las para o novo SharePoint Framework.
Executar como parte da página
Da mesma forma que as personalizações incorporadas nas Web Parts do Editor de Scripts, as soluções da Estrutura do SharePoint 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.
Diferentemente de Suplementos do SharePoint, as web parts do lado do cliente da Estrutura do SharePoint não são isoladas em um iframe. Como consequência, os recursos aos quais uma Web Part do lado do cliente específica tem 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 as web parts do lado do cliente 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 sua Web Part
Ao criar personalizações usando a Web Part do Editor de Scripts, 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 as Web Parts do lado do cliente da Estrutura do SharePoint, você pode usar qualquer biblioteca do lado do cliente para enriquecer sua solução, da mesma maneira que teria feito 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 Web Parts na mesma página para usar uma versão diferente do jQuery sem entrar em conflito 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 Web Part do Editor de Scripts, 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 também não requer outras etapas de autenticação para se comunicar com o SharePoint.
Usar somente o código do lado do cliente
As soluções de Web Part Estrutura do SharePoint e editor de script 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 uma série de limitações, como não elevar permissões no SharePoint ou entrar em contato com APIs externas que não dão suporte a CORS (comunicação entre origens) ou autenticação usando o fluxo implícito OAuth. Nesses casos, a solução do lado do cliente pode aproveitar uma API remota do lado do servidor para fazer a operação necessária e retornar os resultados ao cliente.
Solução de host no SharePoint
Uma das vantagens de criar personalizações do SharePoint usando Web Parts do Editor de Scripts foi o fato de que seu código poderia ser hospedado em uma biblioteca de documentos regular do SharePoint. Em comparação com Suplementos do SharePoint, isso exigia menos infraestrutura e simplificava a hospedagem da solução. Além disso, as organizações podiam usar permissões do SharePoint para controlar o acesso aos arquivos de solução.
Embora hospedar as soluções da Estrutura do SharePoint em um CDN ofereça várias vantagens, isso não será necessário e você pode escolher hospedar seu código em uma biblioteca de documentos regular 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. Não há restrições em relação a qual deve ser a URL, contanto que o usuário que navegue na página com a Web Part nela possa baixar o script do local especificado.
O Office 365 oferece o recurso de CDN público que permite que você publique arquivos de uma biblioteca de documentos específica do SharePoint para um CDN. O CDN público do Office 365 oferece um bom equilíbrio entre os benefícios de usar um 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 fiquem disponíveis publicamente, usar a CDN pública do Office 365 é uma opção que vale a pena considerar.
Diferenças entre soluções da Estrutura do SharePoint e personalizações de Web Part do Editor de Scripts
As personalizações do SharePoint criadas usando a Estrutura do SharePoint e Web Part do Editor de Scripts são semelhantes. Todas são executadas como parte da página no contexto do usuário atual e são criadas usando JavaScript do lado do cliente. Mas também há algumas diferenças significativas que podem influenciar suas decisões de arquitetura e o que você deve ter em mente ao desenvolver a sua solução.
Executar em sites sem script
Durante a criação de personalizações do lado do cliente usando a Web Part do Editor de Scripts, você precisava levar em consideração se o site onde a personalização seria usada era um site sem script ou não. Se o site fosse sem script, você precisaria solicitar que o administrador desabilitasse a configuração sem script ou criasse uma solução diferente, por exemplo, usar o modelo de suplemento.
Como as soluções da Estrutura do SharePoint são implantadas por meio do catálogo de aplicativos com uma aprovação prévia, elas não estão sujeitas às restrições sem script e funcionam em todos os sites.
Implantado e atualizado por meio de TI
As Web Parts de Editor de Scripts são usadas para compilar as personalizações do SharePoint principalmente por desenvolvedores cidadãos. Com nada além de permissões de proprietário de site, os desenvolvedores cidadãos podem compilar personalizações do SharePoint interessantes que adicionam valor ao negócio. Sempre que a personalização deve ser atualizada, os usuários com as permissões necessárias poderão aplicar atualizações aos arquivos de script da solução e as alterações estarão imediatamente visíveis a todos os usuários.
As soluções de Web Part do Editor de Script dificultam que as organizações de TI acompanhem quais personalizações estão sendo usadas e onde estão sendo usadas. Além disso, as organizações não conseguem identificar quais scripts externos estão sendo utilizados na sua intranet e têm acesso aos seus dados.
O SharePoint Framework devolve o controle a TI. Como as soluções do SharePoint Framework são implantadas e gerenciadas centralmente no catálogo de aplicativos, as organizações têm a oportunidade de examinar a solução antes de implantá-la. Além disso, as atualizações são implantadas por meio do catálogo de aplicativos, permitindo que as organizações as verifiquem e as aprovem antes da implantação.
Concentrar-se mais na experiência do usuário uniforme
Durante a criação de personalizações usando a Web Part do Editor de Scripts, os desenvolvedores cidadãos eram proprietários do DOM completo de suas personalizações. Não havia nenhuma diretriz relacionada à experiência do usuário e como essa personalização deveria funcionar. Como resultado disso, diferentes desenvolvedores criavam personalizações de maneiras diferentes, o que levava a uma experiência de usuário inconsistente para os usuários finais.
Uma das metas da Estrutura do SharePoint é padronizar a compilação de personalizações do lado do cliente para que elas fiquem uniformes do ponto de vista da implantação, da manutenção e da experiência de usuário. Com o Office UI Fabric, os desenvolvedores podem fazer suas soluções personalizadas parecerem e se comportarem como uma parte do SharePoint, simplificando a adoção dos usuários. A cadeia de ferramentas da Estrutura do SharePoint gera arquivos de pacote para as soluções, que são implantadas no catálogo de aplicativos, e os pacotes de scripts, que são implantados no local de hospedagem de sua escolha. Todas as soluções são estruturadas e gerenciadas da mesma maneira.
Não modifique o DOM fora da personalização
As Web Parts do Editor de Scripts eram usadas no passado para modificar as partes da página, como adicionar botões à barra de ferramentas ou alterar o título ou identidade visual da página. Essas personalizações dependiam da existência de elementos específicos de DOM e sempre que a UI do SharePoint era atualizada, havia uma probabilidade de a personalização ser corrompida.
A Estrutura do SharePoint estimula uma abordagem mais estruturada e confiável para a personalização do SharePoint. Em vez de usar elementos específicos de DOM para personalizar o SharePoint, a Estrutura do SharePoint fornece aos desenvolvedores uma API pública que eles podem usar para estender o SharePoint. A Web Part do lado do cliente é o único formato com suporte pela Estrutura do SharePoint, mas outras formas, como equivalentes do JSLink e ações personalizadas do usuário, estão sendo levadas em consideração para o futuro para que os desenvolvedores possam implementar os cenários mais comuns de personalização usando a Estrutura do SharePoint Framework.
Distribuído como pacotes
As personalizações do lado do cliente do SharePoint geralmente usavam bibliotecas e listas do SharePoint para armazenar seus dados. Quando criado usando a Web Part do Editor de Scripts, não havia uma maneira fácil de provisionar automaticamente os pré-requisitos necessários. Implantar a mesma personalização para outro site geralmente significava copiar a Web Part, mas também corretamente recriar e manter o armazenamento de dados necessários.
As soluções da Estrutura do SharePoint são distribuídas como pacotes podem provisionar automaticamente seus pré-requisitos, como campos, tipos de conteúdo ou listas. Os desenvolvedores que criam o pacote podem especificar quais artefatos são exigidos pela solução e sempre que ele for instalado em um site, os artefatos especificados serão criados. Isso simplifica consideravelmente o processo de implantação e gerenciamento da solução em vários sites.
Use TypeScript para compilar de maneira mais robusta e manter as soluções com mais facilidade
Durante a criação de personalizações usando a Web Part do Editor de Scripts, os desenvolvedores cidadãos 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 você pode migrar seu JavaScript simples para TypeScript gradualmente ao longo do tempo aumentando a capacidade de manutenção de sua solução.
Não depender do objeto spPageContextInfo
Ao criar personalizações reutilizáveis do lado do cliente, no passado, os desenvolvedores usavam o objeto JavaScript spPageContextInfo para obter informações sobre a página, site ou usuário atual. Esse objeto oferecia a eles uma maneira fácil de deixar sua solução reutilizável entre os diferentes sites no SharePoint e não tem que usar URLs fixas.
Embora o objeto spPageContextInfo ainda esteja presente nas páginas clássicas do SharePoint, ele não pode ser usado com segurança com páginas modernas e bibliotecas do SharePoint. Ao criar soluções na Estrutura do SharePoint, os desenvolvedores são recomendados a usar o objeto [IWebPartContext.pageContext](/javascript/api/sp-webpart-base/iwebpartcontext), que contém as informações de contexto para a solução específica.
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á-los por conta própria, a recomendação é usar a API REST. 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 você preferir trabalhar com uma API, em vez disso, pode usar a Biblioteca Principal do JavaScript de Padrões e Práticas do SharePoint que oferece uma API fluente e tipificações TypeScript.
Migrar personalização existente para a Estrutura do SharePoint
Migrar personalizações de Web Parts do Editor de Scripts existente para a Estrutura do SharePoint oferece aos usuários finais e aos desenvolvedores muitos benefícios. Ao considerar a migração de personalizações existentes para a Estrutura do SharePoint, você pode escolher reutilizar o máximo de scripts existentes possível ou reescrever completamente a personalização.
Reutilizar scripts existentes
Ao migrar as personalizações de Web Parts do Editor de Scripts existentes para a Estrutura do SharePoint, você pode 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 específica para um período de tempo 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, as soluções da Estrutura do SharePoint são empacotadas como módulos do JavaScript e são carregadas de forma assíncrona em uma página. Algumas bibliotecas do JavaScript não funcionam corretamente quando referenciadas em um módulo ou precisam ser referenciadas de uma maneira específica. Além disso, depender de eventos da página, como onload() ou usar a função ready() do jQuery pode levar a resultados indesejados.
Considerando a variedade de bibliotecas do JavaScript, não há maneira fácil de saber antecipadamente se seus scripts existentes 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 oferecer suporte a sua solução por um período de tempo mais longo, gostaria de usar melhor a Estrutura do SharePoint ou se acabou de descobrir que os scripts existentes não podem ser reutilizados com a Estrutura do SharePoint, talvez seja necessário reescrever completamente sua personalização. Embora seja mais caro que reutilizar scripts existentes, isso oferece a você melhores resultados no longo prazo: uma solução de melhor desempenho e mais fácil de manter e usar.
Ao reescrever uma personalização de Web Part do Editor de Scripts existente para uma solução da Estrutura do SharePoint, você deverá 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. Para componentes específicos como gráficos ou controles deslizantes, tente procurar bibliotecas modernas que são distribuídas como módulos e têm tipagens TypeScript. Isso facilitará a integração do componente em sua solução.
Embora não haja uma única resposta sobre qual componente é o melhor para usar em qual cenário, a Estrutura do SharePoint é flexível o suficiente para acomodar os cenários mais populares e você pode transformar suas personalizações existentes do lado do cliente em soluções da Estrutura do SharePoint totalmente completas.
Dicas de migração
Ao transformar personalizações de Web Part do Editor de Scripts existentes para a Estrutura do SharePoint, há alguns padrões comuns.
Mover o código existente para a Estrutura do SharePoint
As personalizações do SharePoint criadas usando a Web Part do Editor de Scripts normalmente são compostas por algumas marcações de HTML, incluídas na Web Part, e uma ou mais referências a arquivos JavaScript. Ao transformar sua personalização existente em uma solução da Estrutura do SharePoint, a marcação de HTML da web part do Editor de Scripts provavelmente teria que ser movida para o método render() do lado do cliente da Estrutura do SharePoint. As referências a scripts externos seriam alteradas para referências na propriedade externals no arquivo ./config/config.json. Os scripts internos seriam copiados para a pasta de origem da Web Part e referenciados a partir da classe da web part usando instruções require().
Funções de referência de arquivos de script
Para fazer referência a funções de arquivos de script, essas funções precisam ser definidas como uma exportação. Considere um arquivo JavaScript existente que você gostaria de usar em uma Web Part do lado do cliente da Estrutura do SharePoint:
var greeting = function() {
alert('How are you doing?');
return false;
}
Para chamar a função greeting da classe da web part, você precisaria alterar o arquivo JavaScript para:
var greeting = function() {
alert('How are you doing?');
return false;
}
module.exports = {
greeting: greeting
};
Em seguida, na classe da Web Part, poderia referenciar o script e chamar a função greeting:
public render(): void {
this.domElement.innerHTML = `<input type="button" value="Click me"/>`;
const myScript = <any> require('./my-script.js');
this.domElement.querySelector('input').addEventListener('click', myScript.greeting);
}
Executar chamadas AJAX
Muitas personalizações do lado do cliente usam jQuery para solicitações de AJAX devido a sua simplicidade e compatibilidade entre vários navegadores. Se você estiver usando jQuery para isso, poderá executar as chamadas de AJAX usando o cliente HTTP padrão fornecido com a Estrutura do SharePoint.
A Estrutura do SharePoint oferece dois tipos de cliente de HTTP: o SPHttpClient, destinado para executar solicitações à API REST do SharePoint e o HttpClient, projetado para emitir solicitações da Web para outras APIs REST. Veja como você pode executar uma chamada usando o SPHttpClient para obter o título do site do SharePoint atual:
this.context.spHttpClient.get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
SPHttpClient.configurations.v1,
{
headers: {
'Accept': 'application/json;odata=nometadata',
'odata-version': ''
}
})
.then((response: SPHttpClientResponse): Promise<{Title: string}> => {
return response.json();
})
.then((web: {Title: string}): void => {
// web.Title
}, (error: any): void => {
// error
});