Compartir a través de

Agregar una biblioteca externa a su elemento web del lado cliente de SharePoint

  • Artículo

Puede que quiera incluir una o más bibliotecas JavaScript en su elemento web. En este artículo se muestra cómo agrupar una biblioteca externa y cómo compartir bibliotecas.

Incluir un script

De manera predeterminada, el elemento web que instala varios programas incluye automáticamente cualquier biblioteca que sea una dependencia del módulo del elemento web. Esto significa que la biblioteca se implementa en el mismo archivo de agrupación JavaScript que su elemento web. Esto es más útil para las bibliotecas más pequeñas que no se usan en varios elementos web.

Ejemplo

  1. Incluya la cadena de validación del paquete validator de la biblioteca en un elemento web.

  2. Descargue el paquete validator desde npm:

    npm install validator --save

    Nota:

    Dado que usa TypeScript, es probable que desee las declaraciones de tipo para el paquete que agregue. Esto resulta útil cuando se escribe código porque TypeScript es solo un superconjunto de JavaScript. Todo el código TypeScript todavía se convierte en código JavaScript cuando compila. Puede instalar declaraciones de tipo mediante NPM, por ejemplo: npm install @types/{package} --save-dev

  3. Cree un archivo en la carpeta del elemento web denominado validator.d.ts y agregue lo siguiente:

    declare module "validator" {
    export function isEmail(email: string): boolean;
    export function isAscii(text: string): boolean;
}

    Nota:

    Algunas bibliotecas no tienen declaraciones de tipos. Aunque la biblioteca validator sí que tiene un archivo de declaraciones de tipos proporcionado por la comunidad, en este escenario vamos a suponer que no lo tiene. En este caso, definirá su propio archivo .d.ts de definición de declaraciones de tipos para la biblioteca. El código anterior muestra un ejemplo.

  4. En el archivo del elemento web, importe las declaraciones de tipos:

    import * as validator from 'validator';

  5. Use la biblioteca de validator en su código de elemento web:

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

Compartir una biblioteca entre varios elementos web

Su solución del lado cliente puede incluir varios elementos web. Estos elementos web puede que necesiten importarse o compartir la misma biblioteca. En estos casos, en lugar de agrupar la biblioteca, debe incluirla en un archivo JavaScript independiente para mejorar el rendimiento y el almacenamiento en caché. Este es principalmente el caso de las bibliotecas más grandes.

Ejemplo

En este ejemplo, compartirá el paquete marked (un compilador Markdown) en una agrupación independiente.

  1. Descargue el paquete marked de NPM:

    npm install marked --save

  2. Instale el paquete de declaraciones de tipo en el proyecto:

    npm install @types/marked --save-dev

  3. Edite config/config.json y agregue una entrada al mapa externals. Esto es lo que indica al elemento que instala varios programas que lo coloque en un archivo independiente. Así se evita que el elemento que instala varios programas agrupe esta biblioteca:

    "marked": "node_modules/marked/marked.min.js"

  4. Agregue la instrucción que se va a importar en la biblioteca marked en su elemento web ahora que hemos agregado el paquete y las declaraciones de tipos para la biblioteca:

    import * as marked from 'marked';

  5. Use la biblioteca en su elemento web:

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

Cargar un script de una red CDN

En lugar de cargar la biblioteca desde un paquete NPM, puede que quiera cargar un script de una red de entrega de contenido (CDN). Para ello, edite el archivo config.json para cargar la biblioteca desde la dirección URL de la red CDN.

Ejemplo

En este ejemplo, cargará jQuery desde la red CDN. No es necesario instalar el paquete NPM. Sin embargo, todavía tiene que instalar las declaraciones de tipo.

  1. Instale las declaraciones de tipo para jQuery:

    npm install --save-dev @types/jquery

  2. Actualice config.json en la carpeta config para cargar jQuery desde la red CDN. Agregue una entrada al campo externals:

    "jquery": "https://code.jquery.com/jquery-3.1.0.min.js"

  3. Importe jQuery en su elemento web:

    import * as $ from 'jquery';

  4. Use jQuery en su elemento web:

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

Cargar un módulo que no es AMD

Algunos scripts siguen el patrón JavaScript heredado de almacenar la biblioteca en el espacio de nombres global. Ahora, este patrón está en desuso a favor de la Definición de módulo universal (UMD)/Definición de módulo asíncrono (AMD) o los módulos ES6. En cambio, puede que necesite cargar dichas bibliotecas en su elemento web.

Sugerencia

Es difícil determinar de forma manual si el script que intenta cargar es un script AMD o no (especialmente cuando está reducido).

Si el script está hospedado en una dirección URL de acceso público, puede usar la herramienta gratuita Rencore SharePoint Framework Script Check para determinar el tipo de script. Además, esta herramienta le permite saber si la ubicación de hospedaje desde la que carga el script está correctamente configurada. Esta herramienta también está disponible en la extensión de VS Code Rencore SPFx Script Check

Para cargar un módulo que no sea AMD, agregue una propiedad adicional a la entrada del archivo config.json.

Ejemplo

En este ejemplo, cargará un módulo ficticio que no sea AMD desde la red CDN de Contoso. Estos pasos se aplican a cualquier script que no sea AMD en el directorio src/o node_modules/.

El script se denomina Contoso.js y se almacena en https://contoso.com/contoso.js. Su contenido es:

var ContosoJS = {
  say: function(text) { alert(text); },
  sayHello: function(name) { alert('Hello, ' + name + '!'); }
};

  1. Cree declaraciones de tipos para el script en un archivo denominado contoso.d.ts en la carpeta del elemento web.

    declare module "contoso" {
  interface IContoso {
    say(text: string): void;
    sayHello(name: string): void;
  }
  var contoso: IContoso;
  export = contoso;
}

  2. Actualice el archivo config.json para que incluya este script. Agregue una entrada al mapa externals:

    {
  "contoso": {
    "path": "https://contoso.com/contoso.js",
    "globalName": "ContosoJS"
  }
}

  3. Agregue una importación a su código de elemento web:

    import contoso from 'contoso';

  4. Use la biblioteca de Contoso en su código:

    contoso.sayHello(username);

Cargar una biblioteca que tiene una dependencia en otra biblioteca

Muchas bibliotecas tienen dependencias en otra biblioteca. Puede especificar tales dependencias en el archivo config.json con la propiedad globalDependencies.

Importante

Tenga en cuenta que no tiene que especificar este campo para los módulos que son AMD; estos se importarán correctamente entre sí. Sin embargo, un módulo que no sea AMD no puede tener un módulo AMD como dependencia. En algunos casos, se puede cargar un script AMD como un script que no es AMD. A menudo, es necesario al trabajar con jQuery (que es un script AMD por sí mismo) y complementos jQuery (que, en la mayoría de los casos, se distribuyen como scripts que no son AMD y que dependen de jQuery).

Existen dos ejemplos de esto.

Módulo que no es AMD tiene una dependencia de módulo no AMD

Este ejemplo implica dos scripts ficticios. Se encuentran en la carpeta src/, aunque también pueden cargarse desde una 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. Agregue o cree declaraciones de tipo para esta clase. En este caso, creará Contoso.d.ts, que contiene declaraciones de tipo para ambos archivos JavaScript.

    contoso.d.ts

    declare module "contoso" {
  interface IEventList {
    alert(): void;
  }
  interface IContoso {
    getEvents(): string[];
    EventList: IEventList;
  }
  var contoso: IContoso;
  export = contoso;
}

  2. Actualice el archivo config.json. Agregue dos entradas a externals:

    {
  "contoso": {
    "path": "/src/ContosoCore.js",
    "globalName": "Contoso"
  },
  "contoso-ui": {
    "path": "/src/ContosoUI.js",
    "globalName": "Contoso",
    "globalDependencies": ["contoso"]
  }
}

  3. Agregue importaciones para Contoso y ContosoUI:

    import contoso = require('contoso');
require('contoso-ui');

  4. Use las bibliotecas de su código:

    contoso.EventList.alert();

Cargar JSOM de SharePoint

Cargar JSOM de SharePoint es esencialmente el mismo escenario que cargar scripts que no son AMD que tengan dependencias. Esto significa usar las globalName opciones y globalDependency .

Importante

Tenga en cuenta que el siguiente enfoque produce errores en páginas clásicas de SharePoint, donde JSOM de SharePoint ya está cargado. Si necesita que su elemento web funcione con páginas clásicas y modernas, debería comprobar primero si JSOM de SharePoint ya está disponible y, si no lo está, cargarlo de forma dinámica mediante SPComponentLoader.

  1. Instale las declaraciones de tipos para Microsoft Ajax, que es una dependencia de las declaraciones de tipos JSOM:

    npm install @types/microsoft-ajax --save-dev

  2. Instale las declaraciones de tipos para JSOM:

    npm install @types/sharepoint --save-dev

  3. Agregue entradas al archivo 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. En su elemento web, agregue las instrucciones require:

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

Cargar recursos localizados

Puede usar un mapa en config.json denominado localizedResources para describir cómo cargar recursos localizados. Las rutas de este mapa son relativas a la carpeta lib y no deben contener una barra inicial (/).

En este ejemplo, tiene una carpeta src/strings/. En esta carpeta, hay varios archivos JavaScript con nombres como en-us.js, fr-fr.js, de-de.js. Como el cargador de módulos debe poder cargar cada uno de estos archivos, estos deben contener un contenedor CommonJS. Por ejemplo, en en-us.js:

  define([], function() {
    return {
      "PropertyPaneDescription": "Description",
      "BasicGroupName": "Group Name",
      "DescriptionFieldLabel": "Description Field"
    }
  });

  1. Edite el archivo config.json. Agregue una entrada a localizedResources. {locale} es un token de marcador de posición para el nombre de la configuración regional:

    {
  "strings": "strings/{locale}.js"
}

  2. Agregue declaraciones de tipo para las cadenas. En este caso, tiene un archivo MyStrings.d.ts:

    declare interface IStrings {
  webpartTitle: string;
  initialPrompt: string;
  exitPrompt: string;
}

declare module 'mystrings' {
  const strings: IStrings;
  export = strings;
}

  3. Agregue las importaciones a las cadenas de su proyecto:

    import * as strings from 'mystrings';

  4. Use las cadenas de su proyecto:

    alert(strings.initialPrompt);

Vea también