Описание API

Этот раздел содержит информацию о том, как импортировать и использовать иконки, как правильно инициализировать их на странице, и также какие функции библиотеки доступны.

Import

Импорт иконок осуществляется двумя способами:

1. Импорт объекта icons, который содержит все доступные иконки библиотеки

import { icons } from "@web-global/icons";

2. Импорт конкретной иконки по её имени в camelCase формате

import { home } from "@web-global/icons";

Каждая иконка представлена как свойство этого объекта, где ключ — это имя иконки, а значение — это данные SVG, необходимые для её отображения.

Создание иконок реализовано через функцию createIcons, которая должна быть вызвана внутри жизненного цикла компонента, такого как onMounted во Vue или useEffect в React. Это необходимо, потому что инициализация иконок должна происходить после рендеринга DOM-элементов, к которым они привязываются.

createIcons

Name	Type	Default	Description
icons	{[key: string]: IconNode}	{}	Объект с иконками, где ключ — это имя иконки (в camelCase формате), а значение — данные для создания иконки. Обязательный параметр
iconIds	string[]	[]	Массив ID элементов, которые должны быть заменены на иконки. Если массив пуст, то замена происходит для всех элементов с атрибутом nameAttr
nameAttr	string	"data-icon"	Имя атрибута, по которому будут найдены элементы для замены иконками. Например, если nameAttr равно "data-icon", заменятся элементы с атрибутом data-icon
attrs	Object	{}	Дополнительные HTML-атрибуты, которые будут добавлены к заменённым элементам. Например, классы или стили
linearGradient	string	-	Если передана CSS-строка, представляющая линейный градиент (например, linear-gradient(45deg, #f06, transparent)), то для иконок будет применён данные градиент
replaceAll	boolean	false	Если true, заменяются все элементы, независимо от переданного массива iconIds. По умолчанию замена происходит только для указанных iconIds

Возвращаемое значение:

• Тип: void
• Описание: Функция не возвращает значения. Её цель — заменить элементы на странице с атрибутом, заданным параметром nameAttr, на соответствующие SVG иконки на основе переданного объекта icons

Пример 1:

<div data-icon="home" />

<script>
import { createIcons, icons } from '@web-global/icons';

// Инициализация иконок
createIcons({
  icons: icons,
  nameAttr: 'data-icon',
  attrs: { class: 'icon-class' },
});
</script>

Пример 2:

<div id="icon-id" id= data-icon="home" />

<script>
import { createIcons, home } from '@web-global/icons';

// Инициализация иконки
createIcons({
  iconIds: ["icon-id"],
  icons: {
    home,
  },
  linearGradient: "linear-gradient(45deg, #f06, transparent)",
});
</script>

metadata

В качестве информации об иконках доступен объект metadata, который можно использовать для получения данных о каждой иконке, включая ее название, дату добавления, стили, категории и области применения.

Возвращаемое значение:

• Тип: Object
• Описание: Возвращает объект с метаинформацией об иконках.

Пример:

import { metadata } from "@web-global/icons";

console.log(metadata.add); // { "name": "add", "date-added": "2024-11-25", "date-modified": null, "global": true, "style": ["outlined"], "categories": [], "instances": ["india", "mexico", "pakistan"] }

convertGradient

Name	Type	Default	Description
gradient	string	-	CSS-строка, представляющая линейный градиент (например, linear-gradient(45deg, #f06, transparent)), которая будет преобразована в SVG <linearGradient>
id	unknown	-	Идентификатор, который будет добавлен к атрибуту id элемента <linearGradient>. Если не указан, будет создан автоматически в виде "generatedGradient". Этот градиент будет применим ко всем иконкам с таким же fill url

Возвращаемое значение:

• Тип: string
• Описание: Возвращает строку с разметкой SVG <linearGradient>, которая содержит преобразованные остановки цвета и угол, если он задан

Пример:

<div data-icon="home" />

<script>
import { convertGradient } from '@web-global/icons';

const gradient = 'linear-gradient(45deg, #f06, transparent)';
const svgGradient = convertGradient(gradient, 'my-gradient');
console.log(svgGradient);

// Вывод:
// <linearGradient id="generatedGradient-my-gradient" gradientTransform="rotate(45)">
//   <stop offset="0%" stop-color="#f06" />
//   <stop offset="100%" stop-color="transparent" />
// </linearGradient>

toCamelCase

Name	Type	Default	Description
string	string	-	Cтрока, которую необходимо преобразовать в camelCase формат

Возвращаемое значение:

• Тип: string
• Описание: Возвращает строку в формате camelCase

Пример:

<div data-icon="home" />

<script>
import { toCamelCase } from '@web-global/icons';

console.log(toCamelCase('example_string-name')); // exampleStringName