Referencia a estilos CSS de terceros en elementos web de SharePoint Framework

2023-03-21

Para compilar elementos web del lado cliente completos de SharePoint Framework, puede aprovechar muchas bibliotecas de terceros. Además de los scripts, estas bibliotecas suelen contener recursos adicionales como las hojas de estilo. En este artículo, se describen dos métodos para incluir estilos CSS de terceros en elementos web, así como el efecto de cada uno de estos en la agrupación de elementos web resultante. El elemento web de ejemplo que se describe en este artículo usa jQuery y jQuery UI para mostrar un menú de tipo acordeón.

Menú de tipo acordeón de jQuery UI representado con un elemento web del lado cliente de SharePoint Framework

Nota:

Antes de seguir los pasos que se indican en el artículo, asegúrese de configurar el entorno de desarrollo del elemento web del lado cliente de SharePoint.

Preparar el proyecto

Crear un proyecto

Cree una carpeta para el proyecto.
```
md js-thirdpartycss
```
Vaya a la carpeta del proyecto.
```
cd js-thirdpartycss
```
En la carpeta del proyecto, ejecute el generador de Yeoman de SharePoint Framework para crear el scaffolding para un nuevo proyecto de SharePoint Framework.
```
yo @microsoft/sharepoint
```
Cuando se le pida, especifique los siguientes valores:
- js-thirdpartycss como el nombre de la solución
- Usar la carpeta actual como la ubicación para colocar los archivos.
- Ningún marco de JavaScript como punto de partida para compilar el elemento web
- Menú tipo acordeón de jQuery como el nombre del elemento web.
- Muestra un menú tipo acordeón de jQuery como la descripción del elemento web.
Abra la carpeta del proyecto en el editor de código. En los pasos y capturas de pantalla de este artículo, se usa Visual Studio Code, pero puede usar el editor que prefiera.

Agregar contenido de prueba

En el editor de código, abra el archivo ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts y cambie el método render() a:

export default class JQueryAccordionWebPart extends BaseClientSideWebPart<IJQueryAccordionWebPartProps> {
  // ...
  public render(): void {
    this.domElement.innerHTML = `
      <div>
        <div class="accordion">
          <h3>Information</h3>
          <div>
            <p>
            The Volcanoes, crags, and caves park is a scenic destination for
            many visitors each year. To ensure everyone has a good
            experience and to preserve the natural beauty, access is
            restricted based on a permit system.
            </p>
            <p>
            Activities include viewing active volcanoes, skiing on mountains,
            walking across lava fields, and caving (spelunking) in caves
            left behind by the lava.
            </p>
          </div>
          <h3>Snow permit</h3>
          <div>
            <p>
            The Northern region has snow in the mountains during winter.
            Purchase a snow permit for access to approved ski areas.
            </p>
          </div>
          <h3>Hiking permit</h3>
          <div>
            <p>
            The entire region has hiking trails for your enjoyment.
            Purchase a hiking permit for access to approved trails.
            </p>
          </div>
          <h3>Volcano access</h3>
          <div>
            <p>
            The volcanic region is beautiful but also dangerous. Each
            area may have restrictions based on wind and volcanic
            conditions. There are three type of permits based on activity.
            </p>
            <ul>
              <li>Volcano drive car pass</li>
              <li>Lava field access permit</li>
              <li>Caving permit</li>
            </ul>
          </div>
        </div>
      </div>`;

      ($('.accordion', this.domElement) as any).accordion();
  }
  // ...
}

Si compila el proyecto ahora, obtendrá un error que indica que $ no está definido. Esto se debe a que el proyecto hace referencia a jQuery sin haberlo cargado primero. Existen dos métodos para cargar las bibliotecas. Ninguno afecta al uso de las secuencias de comandos en el código.

Método 1: Incluir bibliotecas de terceros en la agrupación

La forma más sencilla de hacer referencia a una biblioteca de terceros en los proyectos de SharePoint Framework consiste en incluirla en la agrupación que se genera. La biblioteca se instala como un paquete y se hace referencia a ella en el proyecto. Al crear la agrupación del proyecto, Webpack obtiene la referencia a la biblioteca y la incluye en la agrupación que se genera.

Instalar bibliotecas

Ejecute el comando siguiente para instalar jQuery y jQuery UI:
```
npm install jquery jquery-ui --save
```
Debido a que quiere compilar su elemento web en TypeScript, también necesitará declaraciones de tipo TypeScript para jQuery, las cuales puede instalar si ejecuta el siguiente comando:
```
npm install @types/jquery --save-dev
```

Hacer referencia a bibliotecas en el elemento web

Después de instalar las bibliotecas, el siguiente paso consiste en crear referencias a estas en el proyecto.

En el editor de código, abra el archivo ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts. En la parte superior, justo debajo de la última instrucción import, agregue las referencias a jQuery y jQuery UI.
```
import * as $ from 'jquery';
require('../../../node_modules/jquery-ui/ui/widgets/accordion');
```
Debido a que ha instalado las declaraciones de TypeScript para el paquete de jQuery, puede hacer referencia a estas mediante la instrucción import. En cambio, el paquete de jQuery UI se compila de otra forma. A diferencia de la forma en que se estructuran muchos módulos, no hay ningún punto de entrada principal que incluya una referencia a todos los componentes que use. En su lugar, debe usar referencias directas al componente concreto que quiera usar. El punto de entrada de ese componente contiene todas las referencias a las dependencias que necesita para funcionar correctamente.
Para confirmar que el proyecto se está compilando, ejecute el comando siguiente:
```
gulp serve
```
Después de agregar el elemento web al lienzo, debería ver el menú de tipo acordeón en funcionamiento.

Hasta ahora, solo ha hecho referencia a los scripts de jQuery UI, lo que explica por qué el acordeón no tiene estilo. A continuación, agregue la hoja de estilo CSS que falta para personalizar el menú de tipo acordeón.

Hacer referencia a hojas de estilo CSS de terceros en el elemento web

Agregar referencias a hojas de estilo CSS de terceros que forman parte de los paquetes instalados en el proyecto es tan simple como agregar referencias a los paquetes. SharePoint Framework ofrece compatibilidad estándar para cargar archivos CSS mediante Webpack.

En el editor de código, abra el archivo ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts. Justo debajo de la última instrucción require, agregue referencias a los archivos CSS de acordeón para jQuery UI.
```
require('../../../node_modules/jquery-ui/themes/base/core.css');
require('../../../node_modules/jquery-ui/themes/base/accordion.css');
require('../../../node_modules/jquery-ui/themes/base/theme.css');
```
Hacer referencia a archivos CSS que forman parte de un paquete en el proyecto funciona de modo parecido a agregar referencias a archivos JavaScript. Solo debe especificar la ruta de acceso relativa al archivo CSS que quiera cargar, incluida la extensión .css. Al empaquetar el proyecto, Webpack procesa estas referencias e incluye los archivos en la agrupación de elementos web que se ha generado.
Para confirmar que el proyecto se está compilando, ejecute el comando siguiente:
```
gulp serve
```

El menú de tipo acordeón debería mostrarse correctamente y personalizado según el tema de jQuery UI estándar.

Menú de tipo acordeón de jQuery UI personalizado usando el tema de jQuery UI estándar, que ha representado un elemento web del lado cliente de SharePoint Framework

Analizar el contenido del paquete de elementos web que se ha generado

La forma más sencilla de usar bibliotecas de terceros y sus recursos consiste en incluirlas en la agrupación de elementos web que se ha generado. Según este método, Webpack resuelve automáticamente todas las dependencias existentes entre las distintas bibliotecas y se asegura de que todos los scripts se carguen en el orden correcto. La desventaja de este método es que todos los recursos a los que se hace referencia se cargan por separado con cada elemento web. Por ello, si tiene un proyecto con varios elementos web que usan jQuery UI, cada elemento web cargará su propia copia de jQuery UI y ralentizará la página.

Para ver el impacto de las bibliotecas en el tamaño de la agrupación de elementos web generada, abra el archivo ./temp/stats/js-thirdpartycss.stats.html en el explorador web después de empaquetar el proyecto. Mueva el ratón sobre el gráfico y verá, por ejemplo, que los archivos CSS de jQuery UI referenciados por el elemento web representan el 6 % del tamaño total de la agrupación de elementos web.

CSS de jQuery UI resaltado en el gráfico que muestra el tamaño de las distintas partes de la agrupación de elementos web generada

Tal como se explica en el aviso de declinación de responsabilidades situado después del gráfico, los tamaños son un indicativo del tamaño total de la versión de depuración de la agrupación. La versión de la agrupación es menor. Aun así, se recomienda observar qué partes forman la agrupación de elementos web, así como cuál es su tamaño relativo comparado con otros elementos de la agrupación.

Método 2: Cargar bibliotecas de terceros desde una dirección URL

Otra forma de hacer referencia a bibliotecas de terceros en SharePoint Framework consiste en hacerlo desde una dirección URL, como una red CDN pública o una ubicación administrada en privado. La mayor ventaja de este método es que, si quiere cargar una biblioteca usada con frecuencia desde una ubicación pública, puede que los usuarios ya hayan descargado esa biblioteca específica en su ordenador. En ese caso, SharePoint Framework reutiliza la biblioteca en caché, cargando su elemento web con más rapidez.

Incluso si no puede usar una red CDN pública para cargar bibliotecas desde una ubicación central, es recomendable desde el punto de vista del rendimiento. Apuntar a una URL permite a los usuarios descargar el script solo una vez y reutilizarlo en todo el portal, lo que acelera la carga de las páginas de forma considerable y mejora la experiencia del usuario.

Al cargar bibliotecas de terceros desde direcciones URL públicas, tenga en cuenta que existe un riesgo implícito en el uso de esas bibliotecas. Puesto que no administra la ubicación de host de ningún script específico, no puede conocer su contenido a ciencia cierta. Los scripts que carga SharePoint Framework se ejecutan para el usuario actual. Además, pueden realizar las mismas acciones que él. Si la ubicación de host se encuentra sin conexión, el elemento web no funcionará.

Agregar declaraciones de tipos para las bibliotecas

Al hacer referencia a bibliotecas de terceros desde una URL, no es necesario instalarlas como paquetes en su proyecto. Es necesario que instale sus declaraciones de tipo TypeScript si desea aprovechar las comprobaciones de seguridad de tipos durante el desarrollo.

Suponiendo que empiece con un proyecto vacío que haya sido creado como se ha descrito anteriormente en este artículo, instale las declaraciones de tipo TypeScript para jQuery ejecutando el siguiente comando:

npm install @types/jquery --save-dev

Especifique las direcciones URL de las bibliotecas

Para cargar bibliotecas de terceros desde una dirección URL, tendrá que especificar la dirección URL en la que se encuentran en la configuración de su proyecto. En el editor de código, abra el archivo ./config/config.json. En la sección externals, agregue el siguiente JSON:

{
  //...
  "externals": {
    //...
    "jquery": "https://code.jquery.com/jquery-3.1.1.min.js",
    "jquery-ui": "https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
    //...
  }
  //...
}

Hacer referencia a bibliotecas desde la dirección URL en el elemento web

Una vez especificada la dirección URL que debería usar SharePoint Framework para cargar jQuery y jQuery UI, el paso siguiente consiste en hacer referencia a esta en el proyecto.

En el editor de código, abra el archivo ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts. En la sección superior, justo debajo de la última instrucción import, agregue las siguientes referencias para jQuery y jQuery UI:
```
import * as $ from 'jquery';
require('jquery-ui');
```
A diferencia de la forma en que referenciaba ambas bibliotecas cuando se instalaron como paquetes en su proyecto, referirlas desde la URL es similar. Debido a que jQuery tiene sus declaraciones de tipo TypeScript instaladas, puede ser referenciado usando una instrucción import. En el caso de jQuery UI, solo debe cargar el script en la página.

Debido a que ha registrado jquery y jquery-ui como recursos externos en la configuración del proyecto, SharePoint Framework usa las direcciones URL especificadas para cargarlas en tiempo de ejecución cuando hace referencia a cualquiera de estas bibliotecas. Al agrupar el proyecto, estos recursos se marcan como externos y se excluyen de la agrupación.

Una diferencia que hay que tener en cuenta es que ha especificado que quiere cargar el menú de tipo acordeón desde el paquete de jQuery UI. En este caso, sin embargo, hace referencia a jQuery UI desde la red CDN que contiene todos los componentes de jQuery UI.
Para confirmar que el proyecto se está compilando, ejecute el comando siguiente:
```
gulp serve
```
Después de agregar el elemento web al lienzo, debería ver el menú de tipo acordeón en funcionamiento.
En el explorador web, abra las herramientas de desarrollo, cambie a la pestaña que muestra las solicitudes de red y vuelva a cargar la página. Debería ver como jQuery y jQuery UI se cargan desde la red CDN.

Hasta ahora solo ha hecho referencia a los scripts de jQuery UI, lo que explica por qué el menú de tipo acordeón no aplica ningún estilo. A continuación, agregue la hoja de estilo CSS que falta para personalizar el menú de tipo acordeón.

Hacer referencia a hojas de estilo CSS de terceros desde la dirección URL en el elemento web

Agregar referencias a hojas de estilo CSS de terceros desde la URL funciona de modo distinto a hacerlo a recursos desde paquetes de proyecto. Mientras que la configuración del proyecto del archivo config.json le permite especificar recursos externos, solo se aplica a los scripts. Para hacer referencia a hojas de estilo CSS desde una dirección URL, debe usar SPComponentLoader.

Cargar hojas CSS desde la dirección URL mediante SPComponentLoader

En el editor de código, abra el archivo ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts. En la sección superior del archivo, justo después de la última instrucción import, agregue el siguiente código:
```
import { SPComponentLoader } from '@microsoft/sp-loader';
```
En el mismo archivo, anule el método onInit() de la siguiente manera:
```
export default class JQueryAccordionWebPart extends BaseClientSideWebPart<IJQueryAccordionWebPartProps> {
  protected onInit(): Promise<void> {
    SPComponentLoader.loadCss('https://code.jquery.com/ui/1.12.1/themes/base/jquery-ui.min.css');
    return super.onInit();
  }

  // ...
}
```
Cuando se crea una instancia del elemento web en la página, se carga la hoja CSS de jQuery UI desde la dirección URL especificada. Esta hoja de estilo CSS es la versión combinada y optimizada de la hoja CSS de jQuery UI que contiene los estilos básicos, el tema y el diseño de todos los componentes.
Para confirmar que el proyecto se está compilando, ejecute el comando siguiente:
```
gulp serve
```