Librerías de iconos

Para ofrecer una mayor flexibilidad a la hora de representar los datos, Gstock Web Components incopora una serie de formateadores para añadir flexibilidad en la representación de datos en los componentes web.

Librerías de iconos

Puede registrar íconos adicionales para usar con el componente <gstock-icon> a través de bibliotecas de íconos. Los archivos de íconos pueden existir localmente o en un punto final habilitado para CORS (por ejemplo, una CDN). No hay límite en la cantidad de bibliotecas de íconos que puede registrar y no hay ningún costo asociado con registrarlas, ya que los íconos individuales solo se solicitan cuando se usan.

Los componentes web de Gstock se entregan con dos bibliotecas de íconos integradas, default y weather. La biblioteca de íconos predeterminada contiene todos los íconos necesarios para la mayoría de los escenarios. La biblioteca de íconos del clima contiene un conjunto de íconos que se usan para representar estados relacionados con el clima.

Para registrar una biblioteca de íconos adicional, use la función registerIconLibrary() que se exporta desde utilities/icon-library.js. Como mínimo, debe proporcionar un nombre y una función de resolución. La función resolver traduce el nombre de un icono a una URL donde existe el archivo SVG correspondiente. Consulta los ejemplos a continuación para comprender mejor cómo funciona.

Si es necesario, se puede utilizar una función mutadora para mutar el elemento SVG antes de renderizarlo. Esto es necesario para algunas bibliotecas debido a las muchas formas posibles en que se crean los SVG. Por ejemplo, lo ideal es que los iconos hereden el color de texto actual a través de currentColor, por lo que es posible que debas aplicar fill="currentColor o stroke="currentColor" al elemento SVG mediante esta función.

A continuación, se incluye un ejemplo que registra una biblioteca de iconos ubicada en el directorio /assets/icons.

<script type="module">
  import { registerIconLibrary } from '/dist/utilities/icon-library.js';

  registerIconLibrary('my-icons', {
    resolver: name => `/assets/icons/${name}.svg`,
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
  });
</script>

To display an icon, set the library and name attributes of an <gstock-icon> element.

<!-- This will show the icon located at /assets/icons/smile.svg -->
<gstock-icon library="my-icons" name="smile"></gstock-icon>

Si se utiliza un icono antes de que se realice el registro, estará vacío inicialmente, pero se mostrará cuando se registre.

Los siguientes ejemplos demuestran cómo registrar una serie de bibliotecas de iconos de código abierto populares a través de CDN. Siéntete libre de adaptar el código como creas conveniente para utilizar tu propio origen o convenciones de nomenclatura.

Default icons

Weather icons

Use the weather library to use the weather icons.

<div style="font-size: 24px;">
  <gstock-icon library="weather" name="day-sunny"></gstock-icon>
  <gstock-icon library="weather" name="day-partly-cloudy"></gstock-icon>
  <gstock-icon library="weather" name="day-overcast"></gstock-icon>
  <gstock-icon library="weather" name="day-patchy-moderate-snow"></gstock-icon>
</div>

Personalización de la librería predeterminada

La librería de iconos predeterminada contiene más de 1300 iconos cortesía del proyecto Bootstrap Icons. Estos son los iconos que se muestran cuando se usa <gstock-icon> sin el atributo library. Si prefiere que estos iconos se resuelvan en otro lugar o en una librería de iconos diferente, registre una librería de iconos con el nombre default y un solucionador personalizado.

Este ejemplo cargará el mismo conjunto de iconos desde la CDN de jsDelivr en lugar de su carpeta de activos local.

<script type="module">
  import { registerIconLibrary } from '/dist/utilities/icon-library.js';

  registerIconLibrary('default', {
    resolver: name => `https://cdn.jsdelivr.net/npm/bootstrap-icons@1.0.0/icons/${name}.svg`,
  });
</script>

Personaliza la librería predeterminada para usar sprites SVG

Para mejorar el rendimiento, puede utilizar sprites SVG para evitar múltiples viajes para cada SVG. El navegador cargará la hoja de sprites una vez y luego usted hace referencia al SVG particular dentro de la hoja de sprites usando el selector hash.

Como siempre, asegúrese de comparar estos cambios. Al usar HTTP/2, de hecho puede ser más amigable con el ancho de banda usar múltiples solicitudes pequeñas en lugar de una hoja de sprites grande.

<script type="module">
  import { registerIconLibrary } from '/dist/utilities/icon-library.js';

  registerIconLibrary('sprite', {
    resolver: name => `/assets/images/sprite.svg#${name}`,
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
    spriteSheet: true,
  });
</script>

<div style="font-size: 24px;">
  <gstock-icon library="sprite" name="clock"></gstock-icon>
  <gstock-icon library="sprite" name="speedometer"></gstock-icon>
</div>

Personalización de la librería meteorológica

La librería del sistema contiene solo los íconos que utilizan internamente los componentes de Gstock. A diferencia de la librería de íconos predeterminada, la librería del sistema no depende de activos físicos. En cambio, sus íconos están codificados como URI de datos en el solucionador para garantizar su disponibilidad.

Si desea cambiar los íconos que Shoelace utiliza internamente, puede registrar una librería de íconos utilizando el nombre system y un solucionador personalizado. Si elige hacer esto, es su responsabilidad proporcionar todos los íconos que requieren los componentes. Puede consultar src/components/library.system.ts para obtener una lista completa de los íconos del sistema que utiliza Gstock.

<script type="module">
  import { registerIconLibrary } from '/dist/utilities/icon-library.js';

  registerIconLibrary('system', {
    resolver: name => `/path/to/custom/icons/${name}.svg`,
  });
</script>