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

Установка

Установите пакет с помощью менеджера пакетов вашего проекта:

Yarn

yarn add @omnicajs/icons

npm

npm install @omnicajs/icons

pnpm

pnpm add @omnicajs/icons

Выберите уровень поставки

Используйте корневую точку входа, когда приложению нужен полный каталог с выбором начертания во время выполнения:

import { iconUrl } from '@omnicajs/icons'

const href = iconUrl('filled', 'actions', 'add')
const outlinedHref = iconUrl('outlined', 'actions', 'add-circle')

Используйте точку входа начертания, чтобы получить один полный набор:

import { iconUrl } from '@omnicajs/icons/filled'

const href = iconUrl('actions', 'add')

Используйте точку входа группы, чтобы получить готовый спрайт меньшего размера:

import { iconUrl } from '@omnicajs/icons/filled/actions'

const href = iconUrl('add')

Каждый helper возвращает URL внешнего SVG-символа:

<svg width="24" height="24" aria-hidden="true">
    <use :href="href" />
</svg>

URL общего и группового спрайтов заканчиваются одинаково — #actions/add. Различается только файл спрайта. У контурного начертания собственная сокращённая карта имён, и оно никогда не откатывается к варианту с заливкой.

Полноцветные и исходные ресурсы

Флаги и логотипы сохраняют исходные цвета:

import { iconUrl as flagUrl } from '@omnicajs/icons/flags'
import { iconUrl as logoUrl } from '@omnicajs/icons/logos'

Исходные файлы остаются доступны для собственных пайплайнов потребителя:

import addUrl from '@omnicajs/icons/assets/icons/filled/actions/add.svg?url'

Vue-компоненты по импортам

После подключения opt-in плагина для Vite, Webpack или Rspack импорт монохромного SVG без query возвращает Vue-компонент. Production-сборка объединяет только импортированные символы в один спрайт с хешем содержимого; ?url сохраняет поведение исходного ресурса.

filled/actions/clear-circle

<script setup lang="ts">
import IconClearCircle from '@omnicajs/icons/assets/icons/filled/actions/clear-circle.svg'
</script>

<template>
    <IconClearCircle width="24" height="24" aria-hidden="true" />
</template>

Полные настройки сборщика и TypeScript приведены в README пакета.

Собственный поднабор

Чтобы собрать компактный спрайт из нескольких групп, настройте CLI или адаптер сборщика:

import { defineConfig } from '@omnicajs/icons/build'

export default defineConfig({
    include: {
        filled: {
            actions: ['add', 'remove'],
            alerts: ['warning'],
        },
    },
})

omnica-icons build --config omnica-icons.config.mjs

Сгенерированный TypeScript-модуль ссылается на расположенный рядом SVG через new URL(..., import.meta.url). Затем Vite или Webpack копирует ресурс и добавляет хеш содержимого.

Готовые адаптеры доступны как @omnicajs/icons/vite и @omnicajs/icons/webpack: оба предоставляют выбранный поднабор через virtual:omnicajs-icons и могут сгенерировать точный файл деклараций. Полные примеры конфигурации приведены в README пакета.

Инвалидация кеша

В production-сборке поручите сборщику сформировать URL спрайта с хешем содержимого:

/assets/filled.616dce3a.svg#actions/add

Фрагмент не участвует в HTTP-запросе. Если стабильный URL спрайта используется напрямую, добавьте детерминированный идентификатор сборки перед фрагментом:

/icons/filled.svg?v=<build-id>#actions/add

Каталог использует такой query-параметр только во время разработки. Опубликованные runtime-helper'ы не добавляют временные метки и другие побочные эффекты для production.