svgifier

Библиотека для автоматической вставки в DOM иконок и изображений в формате SVG. Под капотом svgifier использует асинхронный код, Fetch API с кешированием SVG узлов и Mutation API для отслеживания изменений в DOM дереве (только если это необходимо).

Внимание! Не применяйте svgifier совместно с React, Vue и т.п. Эта библиотека предназначена для проектов, в которых не используются концепция виртуальных деревьев, а вместо этого применяется манипуляция с реальными узлами DOM-дерева, либо манипулирование DOM вообще отсутствует.

Цель проекта

Библиотека создавалась как компактная автономная альтернатива таких проектов так:

• iconify.design (для устаревшего варианта)
• SVGInject

Установка и подключение

NPM:

npm install svgifier

Или PNPM:

pnpm add svgifier

Использование модуля:

import svgifier from 'svgifier'
// ...
svgifier.svgify()
// ...

Или UNPKG в процессе быстрого прототипирования:

<script type="module">
import svgifier from 'https://unpkg.com/svgifier/dist/svgifier.esm.min.js'
// ...
svgifier.svgify()
// ...
</script>

Использование

При настройках по умолчанию

Плейсхолдер в HTML:

<i class="svgify icon" data-src="/path/to/icon.svg"><i>

Замена плейсхолдеров:

svgifier.svgify()

Автоматическое отслеживание изменений в DOM-дереве:

const observer = svgifier.observe() // возвращает объект MutationObserver
// ...
observer.disconnect() // при необходимости можно завершить отслеживание

Расширенные настройки

Вы можете предварительно скачать иконки в файлы. Расположите их в отдельной папке, там где расположен остальной статический контент. Например:

public/                     # папка для статического контента
    icons/                  # папка для иконок
        mdi/                # папка с именем провайдера иконок
            map-marker.svg  # иконка с маркером
            ...
    ...

Предположим в проекте используются плейсхолдеры следующего вида (например, такие несколько лет назад выдавались сервисом iconify.design):

<span class="iconify" data-icon="mdi:map-marker"></span>

В атрибуте data-icon видим составной идентификатор иконки вида PROVIDER:ICON, который нужно преобразовать в ссылку на предварительно скаченный файл:

const options = {
    // функция обратного вызова для получения имени класса - маркера плейсхолдеров
    getClassName: () => 'iconify', // плейсхолдеры маркированы классом iconify
    // функция обратного вызова для извлечения URL иконки для найденного плейсхолдера
    getUrl: node => { // node - найденный плейсхолдер (является элементом DOM) 
        // рассмотрим атрибут data-icon
        const m = `${node.dataset.icon}`.match(/^([a-z0-9\-]+)\:([a-z0-9\-]+)$/)
        return m // совпадает с шаблоном PROVIDER:ICON?
            ? `/icons/${m[1]}/${m[2]}.svg` // строим ссылку вида /icons/PROVIDER/ICON.svg 
            : node.dataset.src // путь отступления: считаем, что ссылка в атрибуте data-src
    }
}
await svgifier.svgify(document.body, options) // заменить плейсхолдеры на иконки
// ...
// используйте обозреватель изменений DOM для автоматической
// замены плейсхолдеров на иконки всякий раз когда меняется DOM:
const observer = svgifier.observe(document.body, options)
// ...
observer.disconnect() // при необходимости можно завершить отслеживание

Описание API

Метод svgifier.svgify(node, options)

Ищет в заданном поддереве элементы-плейсхолдеры, извлекает из них данные для загрузки изображений в формате SVG, загружает их асинхронно, по возможности используя кеш, и заменяет плейсхолдеры на SVG-изображение.

Опциональный параметр node, представляет собой узел дерева DOM, являющийся поддеревом, в котором нужно найти плейсхолдеры и произвести манипуляции по их замене.

Опциональный параметр options, представляет собой объект с методами для выполнения более тонкой настройки. Допустимы следующие методы:

• getClassName() - возвращает название CSS-класса для селектора при поиске плейсходнеров.
• getUrl(node) - принимает на вход узел DOM, являющийся плейсхолдером, и возвращает URL изображения.
• getHeaders(node) - принимает на вход узел DOM, являющийся плейсхолдером, и возвращает объект с заголовками для запроса функцией fetch.

По умолчанию в качестве маркеров для плейсхолдеров используется класс svgify, а для URL изображения атрибут data-src.

Возвращает объект Promise, который переходит в состояние fulfilled по завершению загрузки изображений и замены плейсхолдеров.

Метод svgifier.observe(node, options)

Запускает механизм отслеживания изменений в DOM дереве, путем подписки на MutationEvent.

При возникновении MutationEvent, код MutationObserver вызывает метод .svgify(node, options) передавая опциональные параметры node и options.

Возвращает объект MutationObserver, сохраняя его функциональность в полной мере.

Лицензия

MIT