Iconify и unplugin-icons в Vue 3 — быстрый гид

Кратко

Iconify — крупная библиотека SVG-иконок; в Vue 3 её можно подключить через @iconify/vue или через плагин unplugin-icons для Vite. В статье показаны пошаговые установки, конфигурация, рекомендации по производительности и доступности, а также чеклисты и сценарии тестирования.

Образцы различных иконок и стилей интерфейса

Лучшие веб-приложения состоят из текста и изображений. Иконки дают визуальные подсказки, повышают вовлечённость и помогают пользователю быстро ориентироваться. Iconify — это фреймворк и каталог SVG-иконок, который поддерживает множество наборов (Bootstrap, Material Design и другие) и работает с популярными фронтенд-фреймворками.

Что такое Iconify

Iconify — это набор SVG-иконок плюс API и пакеты для разных сред. Кратко: это единый интерфейс доступа к тысячам SVG-иконок из разных коллекций.

Определение в одну строку: Iconify предоставляет иконки в формате SVG и средства их интеграции в приложения.

Важно: в этой статье рассмотрена работа с Vue 3 и сборщиком Vite (рекомендованный стек). Для Vue 2 есть отдельный пакет, но поддержка Vue 2 прекращается — см. раздел «Миграция».

Сравнение подходов — решение для вашей задачи

Если вам нужен быстрый доступ к иконкам в рантайме и простая интеграция — используйте @iconify/vue. Если вы хотите, чтобы иконки включались в бандл на этапе сборки (устраняет ошибки раннего рендеринга и уменьшает runtime-зависимости), предпочитайте unplugin-icons + @iconify-json.

flowchart TD
  A[Нужно быстро добавить иконки в Vue 3?] -->|Да| B{Будет ли SSR или prerendering?}
  B -->|Нет| C[@iconify/vue — быстрый старт]
  B -->|Да| D[unplugin-icons — интеграция на этапе сборки]
  A -->|Нет — нужен полный локальный набор| D
  C --> E[Лёгкая настройка, runtime-загрузка]
  D --> F[Иконки в бандле, согласованность, меньше ошибок]

Как установить @iconify/vue в приложение на Vue 3

Пакет @iconify/vue — это интеграция Iconify для Vue 3.

Запустите в терминале проекта:

npm install --save-dev @iconify/vue

Эта команда устанавливает пакет как dev-зависимость. Пакет предназначен для Vue 3 и не поддерживает Vue 2. Для Vue 2 есть отдельный пакет:

npm install @iconify/vue2

Примечание: официальная поддержка Vue 2 закончилась 31 декабря 2023 года; изучение Vue 3 поможет оставаться актуальным в сообществе.

Как добавить иконку в компонент с @iconify/vue

Импортируйте компонент Icon и используйте его в шаблоне.

  
import { Icon } from '@iconify/vue'

На сайте Iconify вы выбираете нужную иконку по имени и копируете её использование. Пример использования, полученный на сайте:

Это устанавливает цвет иконки в красный и задаёт размеры 500 пикселей по ширине и высоте.

Интерфейс сайта Iconify с поиском и выбором иконки

Результаты поиска и вариантов иконки

Предварительный просмотр выбранной красной иконки

Когда @iconify/vue даёт проблемы и почему

Частые симптомы:

ошибки при pre-rendering или SSR;
сообщения об отсутствии в DOM или пустые контейнеры;
Vue «не успевает» отрендерить компонент до загрузки иконки.

Причина обычно в последовательности загрузки: runtime-загрузка иконок может конфликтовать с универсальным рендерингом или порядком монтирования компонента. Если вы сталкиваетесь с этими проблемами, безопаснее подключать иконки на этапе сборки с помощью unplugin-icons.

Подключение unplugin-icons (рекомендуем для Vite и Vue 3)

unplugin-icons генерирует Vue-компоненты для каждой иконки на этапе сборки. Это решает проблемы с SSR и пререндерингом, а также даёт более детерминированный бандл.

Установка:

npm install unplugin-icons

Далее отредактируйте vite.config.js и добавьте плагин:

import { fileURLToPath, URL } from 'node:url'  
  
import { defineConfig } from 'vite'  
import vue from '@vitejs/plugin-vue'  
import Icons from 'unplugin-icons/vite';  
  
// https://vitejs.dev/config/  
export default defineConfig({  
  plugins: [vue(), Icons()],  
  resolve: {  
    alias: {  
      '@': fileURLToPath(new URL('./src', import.meta.url))  
    }  
  }  
})

Плагин Icons() автоматически генерирует компоненты по конвенции импорта ~icons/{set}/{icon-name}.

Чтобы иметь доступ ко всем коллекциям иконок офлайн, можно установить JSON-пакет Iconify:

npm i -D @iconify/json

Внимание: размер установки примерно 200 МБ. Если вам не нужны все наборы, установите только нужный пакет, например Phosphor:

npm i -D @iconify-json/ph

После установки импортируйте иконку как компонент (пример для Phosphor):

  
import CheckFill from "~icons/ph/check-fill"

Конвенция импорта:

~icons — псевдоним пути, предоставляемый плагином;
{set} — код набора (ph, mdi, bx и т.д.);
{iconName} — имя иконки в kebab-case.

Производительность и размер бандла

unplugin-icons генерирует только используемые иконки, что уменьшает runtime-зависимости.
Установка полного @iconify/json даёт офлайн-доступ, но увеличит локальный объём проекта (~200 МБ).
Рекомендация: установить только те наборы, которые реально используются.

Совет: используйте tree-shaking и анализ бандла (например, vite-plugin-visualizer) после подключения иконок.

Доступность (Accessibility)

Иконки должны быть доступными:

Если иконка служит декоративной — добавьте aria-hidden=”true” и role=”img” при необходимости.
Если иконка передаёт смысл (кнопки, статусы) — предоставьте текстовую подпись через aria-label или скрытый текст (sr-only).
Убедитесь, что цветовые контрасты соответствуют требованиям WCAG (минимум 4.5:1 для обычного текста).

Примеры:

Декоративная иконка: <Icon icon=”ph:star” aria-hidden=”true” />
Иконка-кнопка: <button><Icon icon=”ph:trash” aria-hidden=”true” /><span class=”sr-only”>Удалить

`Безопасность и приватность`

Иконки — статические SVG, не должны содержать приватных данных. Однако при загрузке иконок с CDN учитывайте политику вендора и CSP (Content Security Policy). Лучше включать иконки в бандл на этапе сборки (unplugin-icons), чтобы уменьшить внешние зависимости.

`Практическое руководство: мини-методология выбора иконок`

Определите роль иконки: декоративная, интерактивная, навигационная, статусная.
Выберите стиль, соответствующий вашему дизайну (outline, fill, rounded).
Стандартизируйте размеры (например, 16/24/32/48/64 пикселей) и валюту размеров в проекте.
Назначьте семантику (aria-label) для всех значимых иконок.
Документируйте наборы и правила в Design System.

`Роль‑ориентированные чеклисты`

Разработчик:

Установил нужный пакет (@iconify/vue или unplugin-icons).
Конфигурировал vite.config.js если использует unplugin-icons.
Импортировал только используемые иконки. Дизайнер:
Выбрал набор и стиль иконок.
Утвердил размеры и визуальные веса. QA:
Проверил отображение в разных браузерах.
Проверил доступность (скринридеры, keyboard navigation). Accessibility lead:
Проверил aria-атрибуты и контрастность.

`Типичные ошибки и способы их устранения`

Проблема: иконки не отображаются при SSR. Решение: используйте unplugin-icons или предрендерьте иконки в бандл.
Проблема: увеличился размер бандла. Решение: не устанавливайте @iconify/json полностью, используйте отдельные наборы.
Проблема: скринридер игнорирует иконку-кнопку. Решение: добавьте aria-label или скрытый текст.

`Критерии приёмки`

Иконки отображаются корректно в основных целевых браузерах.
Для значимых иконок присутствует семантическая подпись (aria-label или текст).
Размер бандла не вырос больше допустимого лимита (команда определяет порог).
Набор иконок задокументирован в репозитории и в дизайн-системе.

`Тесты и критерии приёмки`

E2E: проверить страницу, где используется ключевая иконка; убедиться, что SVG пришёл и виден.
Unit: компонент, который рендерит иконку, должен иметь snapshot-тесты (если используете snapshot).
Accessibility: проходить автоматические проверки (axe, pa11y) и ручное тестирование с клавиатурой и скринридером.

`Миграция с Vue 2 на Vue 3 (коротко)`

Если проект на Vue 2 использует @iconify/vue2, планируйте переход на Vue 3 и @iconify/vue для долгосрочной поддержки.
Проверяйте совместимость плагинов и сборщика (Vite удобнее для современной экосистемы).
При миграции учитывайте изменения API компонентов и lifecycle-хуков.

`Шаблон для документации набора иконок (README)`

Используемый пакет: @iconify/vue или unplugin-icons
Установленные наборы: ph, mdi
Стандартные размеры: 16, 24, 32, 48
Правила доступа: aria-hidden для декоративных, aria-label для значимых
Примеры использования: (вставьте сниппеты)

`Быстрые советы (cheat sheet)`

Импорт через unplugin-icons: import Icon from “~icons/ph/check-fill”
Декоративная иконка: aria-hidden=”true”
Иконка-кнопка: добавлять sr-only или aria-label
Минимизируйте набор подключаемых коллекций

`Пример полного рабочего сценария (шаги)`

Выберите стратегию (runtime vs build-time).
Установите пакет (@iconify/vue или unplugin-icons + @iconify-json/*).
Настройте vite.config.js для unplugin-icons.
Импортируйте иконки по конвенции ~icons/{set}/{name}.
Проведите тестирование и проверку доступности.
Документируйте в дизайн-системе.

`Итог`

Iconify даёт гибкий способ добавить тысячи SVG-иконок в ваши Vue-приложения. Для простоты можно использовать @iconify/vue, но для стабильности, совместимости с SSR и предсказуемости бандла лучше применять unplugin-icons и локальные наборы @iconify-json. Обязательно продумайте доступность, размер бандла и процесс тестирования.

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

Краткое резюме: