Adicione uma biblioteca externa à Web Part do SharePoint no lado do cliente
Talvez você queira incluir uma ou mais bibliotecas JavaScript na Web Part. Este artigo mostra como agrupar uma biblioteca externa e compartilhar bibliotecas.
Por padrão, o empacotador de Web Part incluirá automaticamente qualquer biblioteca que for uma dependência do módulo de Web Part. Isso significa que a biblioteca será implantada no mesmo arquivo de pacote JavaScript que a Web Part. Isso é mais útil para bibliotecas menores que não são usadas em várias web parts.
Incluas a cadeia de caracteres validando o pacote validator de biblioteca em uma Web Part.
Baixe o pacote de validação do NPM:
npm install validator --save
Nota
Como você está usando TypeScript, provavelmente desejará as declarações de tipo para o pacote que você adicionar. Isso é útil quando você está escrevendo código porque TypeScript é apenas um superconjunto de JavaScript. Todo o código de TypeScript ainda é convertido em código JavaScript quando você realiza a compilação. Você pode instalar declarações de tipo usando o NPM, por exemplo: instalação @types/{package} do npm --save-dev
Crie um arquivo na pasta da web part chamado
validator.d.ts
e adicione o seguinte:declare module "validator" { export function isEmail(email: string): boolean; export function isAscii(text: string): boolean; }
Nota
Algumas bibliotecas não têm declarações de tipo. Embora a biblioteca de validação tenha um arquivo de declarações de tipo fornecido pela comunidade , para esse cenário, vamos supor que ela não tenha. Nesse caso, convém definir seu próprio arquivo
.d.ts
de definição de tipificações para a biblioteca. O código anterior mostra um exemplo.No arquivo da web part, importe as declarações:
import * as validator from 'validator';
Use a biblioteca de validador no código da Web Part:
validator.isEmail('someone@example.com');
A solução do lado do cliente pode incluir várias Web Parts. Essas Web Parts talvez precisem importar ou compartilhar a mesma biblioteca. Nesses casos, em vez de empacotar a biblioteca, você deve incluí-la em um arquivo JavaScript separado para melhorar o desempenho e o armazenamento em cache. Isso se aplica particularmente a bibliotecas maiores.
Neste exemplo, você compartilhará o pacote marcado (um compilador markdown) em um pacote separado.
Baixe o pacote marcado do npm:
npm install marked --save
Instalar o pacote de declarações de tipo em seu projeto:
npm install @types/marked --save-dev
Edite config/config.json e adicione uma entrada ao mapa
externals
. Isso é o que informa o empacotador que ele deve colocá-lo em um arquivo separado. Isso impede que o empacotador empacote essa biblioteca:"marked": "node_modules/marked/marked.min.js"
Adicione a instrução para importar a biblioteca marcada no seu web part, agora que adicionamos o pacote e as tipificações para a biblioteca:
import * as marked from 'marked';
Use a biblioteca na Web Part:
console.log(marked('I am using __markdown__.'));
Em vez de carregar a biblioteca de um pacote NPM, talvez você queira carregar um script de uma Rede de Distribuição de Conteúdo (CDN - Content Delivery Network). Para fazer isso, edite o arquivo config.json para carregar a biblioteca por meio de sua URL de CDN.
Neste exemplo, você carregará jQuery da CDN. Você não precisa instalar o pacote NPM. No entanto, você ainda precisa instalar as declarações de tipo.
Instale declarações de tipo para jQuery:
npm install --save-dev @types/jquery
Atualize o config.json na pasta config para carregar jQuery da CDN. Adicione uma entrada ao campo
externals
:"jquery": "https://code.jquery.com/jquery-3.1.0.min.js"
Importe jQuery para a Web Part:
import * as $ from 'jquery';
Use jQuery na Web Part:
alert( $('#foo').val() );
Alguns scripts seguem o padrão JavaScript herdado de armazenar a biblioteca no namespace global. Esse padrão agora está obsoleto, sendo substituído por UMD (Definições de Módulo Universal)/AMD (Definições de Módulo Assíncrono) ou módulos ES6. No entanto, talvez você precise carregar essas bibliotecas para a Web Part.
Gorjeta
É difícil determinar manualmente se o script que você está tentando carregar é AMD ou não AMD. Esse acontecerá especialmente se o script que você estiver tentando carregar for reduzido.
Se o script estiver hospedado em uma URL publicamente acessível, você poderá usar a ferramenta gratuita de Rencore SharePoint Framework Script Check para determinar o tipo de script ideal. Além disso, esta ferramenta informará se o local de hospedagem do qual você está carregando o script está configurado corretamente. Esta ferramenta também está disponível na extensão VS Code Rencore SPFx Script Check
Para carregar um módulo não AMD, inclua uma propriedade adicional na entrada no arquivo config.json.
Neste exemplo, você carregará um módulo não AMD fictício da CDN da Contoso. Essas etapas se aplicam a qualquer script não AMD em seu diretório src/ou node_modules/.
O script se chama Contoso.js e é armazenado em https://contoso.com/contoso.js. Seu conteúdo é:
var ContosoJS = {
say: function(text) { alert(text); },
sayHello: function(name) { alert('Hello, ' + name + '!'); }
};
Crie declarações de tipo para o script em um arquivo chamado contoso.d.ts na pasta web part.
declare module "contoso" { interface IContoso { say(text: string): void; sayHello(name: string): void; } var contoso: IContoso; export = contoso; }
Atualize o arquivo config.json para incluir esse script. Adicione uma entrada ao mapa itens externos:
{ "contoso": { "path": "https://contoso.com/contoso.js", "globalName": "ContosoJS" } }
Adicione uma importação ao código da Web Part:
import contoso from 'contoso';
Use a biblioteca da contoso no código:
contoso.sayHello(username);
Muitas bibliotecas têm dependências em outra biblioteca. Você pode especificar essas dependências no arquivo config.json usando a propriedade globalDependencies
.
Importante
Observe que você não precisa especificar esse campo para módulos AMD. Eles importam uns aos outros adequadamente. No entanto, um módulo não AMD não pode ter um módulo AMD como uma dependência. Em alguns casos, é possível carregar um script AMD como um script não AMD. Isso geralmente é necessário ao trabalhar com o jQuery, que é um script AMD, e plug-ins do jQuery que, na maioria das vezes, são distribuídos como scripts não AMD e que dependem do jQuery.
Há dois exemplos disso.
Esse exemplo envolve dois scripts fictícios. Eles estão na pasta src/, embora também possam ser carregados de uma CDN.
ContosoUI.js
Contoso.EventList = {
alert: function() {
var events = Contoso.getEvents();
events.forEach( function(event) {
alert(event);
});
}
}
ContosoCore.js
var Contoso = {
getEvents: function() {
return ['A', 'B', 'C'];
}
};
Adicione ou crie declarações de tipo para essa classe. Nesse caso, você criará Contoso.d.ts, que contém declarações de tipo para ambos os arquivos JavaScript.
contoso.d.ts
declare module "contoso" { interface IEventList { alert(): void; } interface IContoso { getEvents(): string[]; EventList: IEventList; } var contoso: IContoso; export = contoso; }
Atualize o arquivo config.json. Adicione duas entradas a
externals
:{ "contoso": { "path": "/src/ContosoCore.js", "globalName": "Contoso" }, "contoso-ui": { "path": "/src/ContosoUI.js", "globalName": "Contoso", "globalDependencies": ["contoso"] } }
Adicione importações para Contoso e ContosoUI:
import contoso = require('contoso'); require('contoso-ui');
Use as bibliotecas no código:
contoso.EventList.alert();
O carregamento do SharePoint JSOM é basicamente o mesmo cenário que o carregamento de scripts não AMD que têm dependências de carregamento. Isso significa usar as globalName
opções e globalDependency
.
Importante
Observe que a seguinte abordagem causará erro nas páginas clássicas do SharePoint, onde o SharePoint JSOM já foi carregado. Se você exigir que a Web Part funcione com páginas clássicas e modernas, primeiro deve verificar se o SharePoint JSOM já está disponível e, se não estiver, carregá-lo dinamicamente usando o SPComponentLoader.
Instalação de declarações de tipo para o Microsoft Ajax, que é uma dependência para declarações de tipo JSOM:
npm install @types/microsoft-ajax --save-dev
Instale declarações de tipo para JSOM:
npm install @types/sharepoint --save-dev
Adicione entradas ao
config.json
:{ "sp-init": { "path": "https://CONTOSO.sharepoint.com/_layouts/15/init.js", "globalName": "$_global_init" }, "microsoft-ajax": { "path": "https://CONTOSO.sharepoint.com/_layouts/15/MicrosoftAjax.js", "globalName": "Sys", "globalDependencies": [ "sp-init" ] }, "sp-runtime": { "path": "https://CONTOSO.sharepoint.com/_layouts/15/SP.Runtime.js", "globalName": "SP", "globalDependencies": [ "microsoft-ajax" ] }, "sharepoint": { "path": "https://CONTOSO.sharepoint.com/_layouts/15/SP.js", "globalName": "SP", "globalDependencies": [ "sp-runtime" ] } }
Na sua web part, adicione as instruções
require
:require('sp-init'); require('microsoft-ajax'); require('sp-runtime'); require('sharepoint');
Você pode usar um mapa em config.json chamado localizedResources
para descrever como carregar recursos localizados. Os caminhos nesse mapa são relativos à pasta lib e não devem conter uma barra (/).
Nesse exemplo, há uma pasta src/strings/. Nesta pasta, há vários arquivos JavaScript com nomes como en-us.js, fr-fr.js, de-de.js. Como cada um desses arquivos deve ser carregável pelo carregador de módulo, eles devem conter um invólucro CommonJS. Por exemplo, em en us.js:
define([], function() {
return {
"PropertyPaneDescription": "Description",
"BasicGroupName": "Group Name",
"DescriptionFieldLabel": "Description Field"
}
});
Edite o arquivo config.json. Adicione uma entrada a
localizedResources
.{locale}
é um token de espaço reservado para o nome da localidade:{ "strings": "strings/{locale}.js" }
Adicione declarações de tipo para suas cadeias de caracteres. Nesse caso, você tem um arquivo MyStrings.d.ts:
declare interface IStrings { webpartTitle: string; initialPrompt: string; exitPrompt: string; } declare module 'mystrings' { const strings: IStrings; export = strings; }
Adicione importações para as cadeias de caracteres no projeto:
import * as strings from 'mystrings';
Use as cadeias de caracteres no projeto:
alert(strings.initialPrompt);