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.

Agrupar um script

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.

Exemplo

  1. Incluas a cadeia de caracteres validando o pacote validator de biblioteca em uma Web Part.

  2. 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

  3. 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.

  4. No arquivo da web part, importe as declarações:

    import * as validator from 'validator';
    
  5. Use a biblioteca de validador no código da Web Part:

    validator.isEmail('someone@example.com');
    

Compartilhar uma biblioteca entre várias Web Parts

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.

Exemplo

Neste exemplo, você compartilhará o pacote marcado (um compilador markdown) em um pacote separado.

  1. Baixe o pacote marcado do npm:

    npm install marked --save
    
  2. Instalar o pacote de declarações de tipo em seu projeto:

    npm install @types/marked --save-dev
    
  3. 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"
    
  4. 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';
    
  5. Use a biblioteca na Web Part:

    console.log(marked('I am using __markdown__.'));
    

Carregar um script de uma CDN

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.

Exemplo

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.

  1. Instale declarações de tipo para jQuery:

    npm install --save-dev @types/jquery
    
  2. 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"
    
  3. Importe jQuery para a Web Part:

    import * as $ from 'jquery';
    
  4. Use jQuery na Web Part:

    alert( $('#foo').val() );
    

Carregar um módulo não AMD

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.

Exemplo

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 + '!'); }
};
  1. 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;
    }
    
  2. 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"
      }
    }
    
  3. Adicione uma importação ao código da Web Part:

    import contoso from 'contoso';
    
  4. Use a biblioteca da contoso no código:

    contoso.sayHello(username);
    

Carregar uma biblioteca que tem uma dependência em outra biblioteca

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.

O módulo não AMD tem uma dependência de módulo não AMD

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'];
  }
};
  1. 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;
    }
    
  2. 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"]
      }
    }
    
  3. Adicione importações para Contoso e ContosoUI:

    import contoso = require('contoso');
    require('contoso-ui');
    
  4. Use as bibliotecas no código:

    contoso.EventList.alert();
    

Carregar JSOM do SharePoint

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.

  1. 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
    
  2. Instale declarações de tipo para JSOM:

    npm install @types/sharepoint --save-dev
    
  3. 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" ]
      }
    }
    
  4. Na sua web part, adicione as instruções require:

    require('sp-init');
    require('microsoft-ajax');
    require('sp-runtime');
    require('sharepoint');
    

Carregar recursos localizados

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"
    }
  });
  1. 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"
    }
    
  2. 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;
    }
    
  3. Adicione importações para as cadeias de caracteres no projeto:

    import * as strings from 'mystrings';
    
  4. Use as cadeias de caracteres no projeto:

    alert(strings.initialPrompt);
    

Confira também