Usar las bibliotecas de JavaScript existentes en los elementos web del lado cliente de SharePoint Framework

Al compilar elementos web del lado cliente en SharePoint Framework, puede beneficiarse de usar las bibliotecas de JavaScript existentes para compilar soluciones eficaces. En cambio, existen algunas consideraciones que debe tener en cuenta para garantizar que los elementos web no afecten negativamente al rendimiento de las páginas de SharePoint en las que se usan.

Hacer referencia a bibliotecas existentes como paquetes

La manera más común de hacer referencia a bibliotecas de JavaScript existentes en elementos web del lado cliente de SharePoint Framework es instalándolas como un paquete en el proyecto.

1. Tomando Angular como ejemplo, para usarlo en un elemento web del lado cliente, primero instalará Angular mediante npm:

   npm install angular --save
   

2. Para usar Angular con TypeScript, instale las declaraciones de tipos con npm:

   npm install @types/angular --save-dev
   

3. Agregará una referencia a Angular en el elemento web con la instrucción import:

   import { Version } from '@microsoft/sp-core-library';
   import {
     BaseClientSideWebPart,
     IPropertyPaneConfiguration,
     PropertyPaneTextField
   } from '@microsoft/sp-webpart-base';
   import { escape } from '@microsoft/sp-lodash-subset';
   
   import styles from './HelloWorld.module.scss';
   import * as strings from 'helloWorldStrings';
   import { IHelloWorldWebPartProps } from './IHelloWorldWebPartProps';
   
   import * as angular from 'angular';
   
   export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
     public render(): void {
       this.domElement.innerHTML = `
         <div class="${styles.helloWorld}">
           <!-- omitted for brevity -->
         </div>`;
   
         angular.module('helloworld', []);
   
         angular.bootstrap(this.domElement, ['helloworld']);
     }
   
     // omitted for brevity
   }
   

Empaquetar recursos de elementos web

SharePoint Framework usa una cadena de herramientas de compilación que se basa en herramientas de código abierto como Gulp y Webpack. Al compilar proyectos de SharePoint Framework, estas herramientas de compilación combinan automáticamente todos los recursos a los que se hace referencia en un solo archivo JavaScript en un proceso denominado agrupación.

La agrupación le ofrece una serie de ventajas. En primer lugar, todos los recursos que necesite su elemento web están disponibles en un solo archivo JavaScript. Esto simplifica la implementación, ya que el elemento web se compone de un único archivo y es imposible perder una dependencia en el proceso de implementación.

Como su elemento web usa recursos diferentes, es importante que se carguen en el orden correcto. La agrupación de elementos web, generada por Webpack durante la compilación, administra la carga de los diferentes recursos, incluida la resolución de cualquier dependencia entre estos recursos.

La agrupación de elementos web también tiene ventajas para los usuarios finales: por lo general, es más rápido descargar un único archivo más grande que varios archivos pequeños. Al combinar un número de archivos más pequeños en una agrupación más grande, el elemento web se carga más rápido en la página.

En cambio, la agrupación de bibliotecas de JavaScript existentes con los elementos web del lado cliente de SharePoint Framework no está exenta de inconvenientes.

Al empaquetar marcos de JavaScript existentes en SharePoint Framework, todos los scripts a los que se hace referencia se incluyen en el archivo de agrupación que se ha generado. Siguiendo con el ejemplo de Angular, una agrupación de elementos web optimizada que incluye Angular supera los 170 KB.

Si agrega otro elemento web a su proyecto que también use Angular y compila el proyecto, obtiene dos archivos de agrupación (uno para cada elemento web y cada uno de ellos superior a 170 KB).

Si agrega estos elementos web a una página, cada usuario descargaría Angular varias veces (una con cada elemento web de la página). Este enfoque es ineficaz y ralentiza el tiempo de carga de la página.

Hacer referencia a bibliotecas existentes como recursos externos

Un enfoque mejor para aprovechar las bibliotecas existentes en el elemento web del lado cliente de SharePoint Framework consiste en hacerles referencia como recursos externos. De esa manera, la única información sobre el script determinado que se incluye en el elemento web es la dirección URL del script. Cuando se agrega a la página, el elemento web intenta cargar automáticamente todos los recursos necesarios desde las direcciones URL especificadas.

Hacer referencia a las bibliotecas de JavaScript existentes en SharePoint Framework es sencillo y no requiere ningún cambio específico en el código. Como la biblioteca se carga en tiempo de ejecución desde la dirección URL especificada, no es necesario que se instale como un paquete en el proyecto.

Usando Angular como ejemplo, para hacer referencia a este como un recurso externo en su elemento web del lado cliente, empiece por instalar sus declaraciones de tipos con npm:

npm install @types/angular --save-dev

En el archivo config/config.json, agregue la entrada siguiente a la propiedad externals:

"angular": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.5.8/angular.min.js",
  "globalName": "angular"
}

El archivo config/config.json completo tendrá un aspecto similar a:

{
  "entries": [
    {
      "entry": "./lib/webparts/helloWorld/HelloWorldWebPart.js",
      "manifest": "./src/webparts/helloWorld/HelloWorldWebPart.manifest.json",
      "outputPath": "./dist/hello-world.bundle.js"
    }
  ],
  "externals": {
    "angular": {
      "path": "https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.5.8/angular.min.js",
      "globalName": "angular"
    }
  },
  "localizedResources": {
    "helloWorldStrings": "webparts/helloWorld/loc/{locale}.js"
  }
}

Agregue una referencia a Angular en el elemento web:

import { Version } from '@microsoft/sp-core-library';
import {
  BaseClientSideWebPart,
  IPropertyPaneConfiguration,
  PropertyPaneTextField
} from '@microsoft/sp-webpart-base';
import { escape } from '@microsoft/sp-lodash-subset';

import styles from './HelloWorld.module.scss';
import * as strings from 'helloWorldStrings';
import { IHelloWorldWebPartProps } from './IHelloWorldWebPartProps';

import * as angular from 'angular';

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    this.domElement.innerHTML = `
      <div class="${styles.helloWorld}">
        <!-- omitted for brevity -->
      </div>`;

      angular.module('helloworld', []);

      angular.bootstrap(this.domElement, ['helloworld']);
  }

  // omitted for brevity
}

Si compila su proyecto ahora y observa el tamaño del archivo de agrupación que se ha generado, verá que solo es de 6 KB.

Si agrega otro elemento web que también usa Angular al proyecto y vuelve a compilar el proyecto, ambas agrupaciones serán de 6 KB cada una.

No es correcto presuponer que acaba de ahorrarse más de 300 KB. Ambos elementos web todavía necesitan Angular y este se carga la primera vez que el usuario visita la página donde se encuentra uno de los elementos web.

Aunque agregue ambos elementos web de Angular a la página, SharePoint Framework sigue descargando Angular solo una vez.

La ventaja real de hacer referencia a bibliotecas de JavaScript existentes como recursos externos se da si su organización tiene una ubicación centralizada para todos los scripts que se usan habitualmente o si usa una red CDN. En tales casos, existe una posibilidad de que la biblioteca de JavaScript determinada ya esté presente en la caché del explorador del usuario. Como consecuencia, lo único que necesita cargarse es la agrupación de elementos web que hace que la página se cargue de forma más rápida.

En el ejemplo anterior, se muestra cómo cargar Angular desde una CDN, pero la red CDN no tiene por qué ser pública. En la configuración, puede indicar cualquier ubicación: desde una red CDN pública o un repositorio hospedado de manera privada hasta una biblioteca de documentos de SharePoint. Siempre que los usuarios que trabajen con sus elementos web puedan tener acceso a las direcciones URL especificadas, los elementos web funcionarán de la manera esperada.

Las redes CDN están optimizadas para una entrega rápida de recursos en todo el mundo. La ventaja adicional de hacer referencia a scripts de redes CDN públicas es que existe una posibilidad de que el mismo script se haya usado en algún otro sitio web que el usuario haya visitado anteriormente. Como el script ya está presente en la caché del explorador local, no necesitaría cargarse específicamente para el elemento web, lo que haría que la página con el elemento web se cargara incluso más rápido.

Algunas organizaciones no permiten el acceso a las redes CDN públicas desde la red corporativa. En tales casos, es una buena alternativa usar una ubicación de almacenamiento hospedada de manera privada para los marcos de JavaScript que se usan habitualmente. Como su organización hospeda las bibliotecas, también puede controlar los encabezados de caché, que pueden ayudarle a optimizar aún más los recursos para el rendimiento.

Formatos de bibliotecas de JavaScript

Las diferentes bibliotecas de JavaScript se crean y empaquetan de maneras diferentes. Algunas se empaquetan como módulos, mientras que otras son scripts sin formato que se ejecutan en el ámbito global (estos scripts suelen conocerse como scripts que no son módulos). Al cargar bibliotecas de JavaScript desde una dirección URL, la forma en que se registra un script externo en un proyecto de SharePoint Framework depende del formato del script. Existen varios formatos de módulo (como AMD, UMD o CommonJS), pero lo único que tiene que saber es si el script específico es un módulo o no.

Al registrar scripts empaquetados como módulos, lo único que tiene que especificar es la dirección URL de la que debe descargarse el script en cuestión. Las dependencias a otros scripts se controlan dentro de la construcción del módulo del script.

Los scripts que no son módulos necesitan, como mínimo, la dirección URL desde donde tiene que descargarse el script y el nombre de la variable con la que se registrará el script en el ámbito global. Si el script que no es un módulo depende de otros scripts, pueden mostrarse como dependencias. Para demostrar esto, veamos algunos ejemplos.

Angular v1.x es un script que no es un módulo. Para registrarlo como un recurso externo en un proyecto de SharePoint Framework, especifique su dirección URL y el nombre de la variable global con la que tiene que registrarse:

"angular": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/angular.js/1.5.8/angular.min.js",
  "globalName": "angular"
}

Es importante que el nombre especificado en la globalName propiedad se corresponda con el nombre usado por el script. De esa manera, puede exponerse correctamente a otros scripts que puedan depender de él.

ngOfficeUIFabric, las directivas de Angular para Office UI Fabric, es un módulo UMD que depende de Angular. La dependencia de Angular ya se controla dentro del módulo, por lo que, para registrarla, solo tiene que especificar su dirección URL:

"ng-office-ui-fabric": "https://cdnjs.cloudflare.com/ajax/libs/ngOfficeUiFabric/0.12.3/ngOfficeUiFabric.js"

jQuery es un script AMD. Para registrarlo, podría usar simplemente:

"jquery": "https://code.jquery.com/jquery-2.2.4.js"

Imagine ahora que quiere usar jQuery con un complemento de jQuery que se distribuye como un script que no es un módulo.

Si ha registrado los dos scripts con el siguiente código, al cargar el elemento web lo más probable es que reciba un mensaje de error. Puede ocurrir que ambos scripts se carguen en paralelo y el complemento no pueda registrarse con jQuery.

"jquery": "https://code.jquery.com/jquery-2.2.4.js",
"simpleWeather": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/jquery.simpleWeather/3.1.0/jquery.simpleWeather.min.js",
  "globalName": "jQuery"
}

Como se ha indicado anteriormente, SharePoint Framework le permite especificar dependencias para complementos que no son módulos. Estas dependencias se especifican con la propiedad globalDependencies:

"jquery": "https://code.jquery.com/jquery-2.2.4.js",
"simpleWeather": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/jquery.simpleWeather/3.1.0/jquery.simpleWeather.min.js",
  "globalName": "jQuery",
  "globalDependencies": [ "jquery" ]
}

Cada dependencia especificada en la propiedad globalDependencies debe indicar a otra dependencia en la sección externals del archivo config/config.json.

Si intenta compilar el proyecto ahora, obtendría otro error, esta vez indicando que no puede especificar una dependencia en un script que no es un módulo.

Para solucionar este problema, lo único que necesita hacer es registrar jQuery como un script que no es un módulo:

"jquery": {
  "path": "https://code.jquery.com/jquery-2.1.1.min.js",
  "globalName": "jQuery"
},
"simpleWeather": {
  "path": "https://cdnjs.cloudflare.com/ajax/libs/jquery.simpleWeather/3.1.0/jquery.simpleWeather.min.js",
  "globalName": "jQuery",
  "globalDependencies": [ "jquery" ]
}

De esta manera, se especifica que el script simpleWeather debe cargarse después de jQuery y que jQuery debe estar disponible en una variable jQuery disponible de forma global, ya que la necesita el complemento de jQuery simpleWeather para registrarse.

Nota:

Observe cómo la entrada para registrar jQuery usa jquery para el nombre del recurso externo, pero jQuery como nombre de variable global. El nombre del recurso externo es el nombre que usa en las instrucciones import en el código. Este es también el nombre que debe coincidir con las declaraciones de tipo TypeScript. El nombre de la variable global, especificado mediante la globalName propiedad , es el nombre conocido por otros scripts, como complementos basados en la biblioteca. Aunque para algunas bibliotecas estos nombres pueden ser los mismos, no es necesario y debe comprobar cuidadosamente que usa nombres correctos para evitar problemas.

Es difícil determinar manualmente si el script que intenta cargar es un módulo o un script que no es de módulo. (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.

Consideraciones sobre scripts que no son módulos

Muchas bibliotecas y scripts de JavaScript desarrollados anteriormente se distribuyen como scripts que no son módulos. Aunque SharePoint Framework admite la carga de scripts que no son módulos, intente no usarlos siempre que sea posible.

Los scripts que no son de módulo se registran en el ámbito global de la página: un script cargado por un elemento web está disponible para todos los demás elementos web de la página. Si tenía dos elementos web que usaban versiones distintas de jQuery y los dos se cargaron como scripts que no son módulos, el último elemento web que se cargó sobrescribirá todas las versiones de jQuery registradas anteriormente.

Como puede imaginar, esto puede causar resultados inesperados y sería difícil depurar problemas producidos solo en determinados escenarios (por ejemplo, solo con otros elementos web que usen una versión distinta de jQuery en la página o solo cuando se carguen en un orden específico). La arquitectura de módulo soluciona este problema aislando scripts y evitando que se afecten entre sí.

Cuándo usar uniones

La agrupación de bibliotecas de JavaScript existentes en el elemento web puede dar lugar a archivos de elementos web de gran tamaño y puede provocar un rendimiento deficiente de las páginas que usan ese elemento web. Aunque por lo general debe evitar la agrupación de bibliotecas de JavaScript con sus elementos web, existen escenarios en los que esta puede suponer una ventaja.

Si compila una solución estándar que deba funcionar en todas las intranets, agrupe todos los recursos con su elemento web para garantizar que este funcione de la manera esperada. Como no sabe por adelantado dónde se instalará la solución, incluir todas las dependencias del archivo de agrupación del elemento web permitirá que esta funcione correctamente, incluso si la organización no permite la descarga de recursos desde una red CDN u otra ubicación externa.

Si su solución consta de varios elementos web que comparten alguna funcionalidad entre sí, entonces sería mejor compilar la funcionalidad compartida como una biblioteca independiente y hacerle referencia como un recurso externo en todos los elementos web. De esa manera, los usuarios solo tienen que descargar la biblioteca común una vez y volver a usarla con todos los elementos web.

Resumen

Al compilar elementos web del lado cliente en SharePoint Framework, puede beneficiarse de las bibliotecas de JavaScript existentes para compilar soluciones eficaces. SharePoint Framework le permite empaquetar estas bibliotecas junto con sus elementos web o cargarlas como un recurso externo. Aunque cargar las bibliotecas existentes desde una dirección URL suele ser el enfoque recomendado, existen escenarios en los que la agrupación puede resultar beneficiosa y es esencial que evalúe sus requisitos cuidadosamente para elegir el enfoque que mejor se adapte a sus necesidades.

Vea también

• Información general sobre SharePoint Framework