mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
108 lines
4.1 KiB
Markdown
108 lines
4.1 KiB
Markdown
|
# SVG-спрайт для сайта без сборщика
|
|||
|
|
|
|||
|
|
Соберите SVG-иконки в один файл и используйте их на HTML-странице.
|
|||
|
|
|
|||
|
|
## Генерация спрайта
|
|||
|
|
|
|||
|
|
Устанавливать пакет в проект не нужно.
|
|||
|
|
|
|||
|
|
В руководстве используется следующая структура проекта:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
/
|
|||
|
|
├── index.html
|
|||
|
|
└── assets/
|
|||
|
|
├── app-icons/
|
|||
|
|
└── svg-icons/
|
|||
|
|
├── check.svg
|
|||
|
|
└── warning.svg
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 1. Создайте конфиг спрайта
|
|||
|
|
|
|||
|
|
Выберите папку для спрайта. В этом примере используется `assets/app-icons`. Создайте в ней файл `svg-sprite.config.json`:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"mode": "standalone",
|
|||
|
|
"name": "icons"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. Укажите источник иконок
|
|||
|
|
|
|||
|
|
В `input` можно указать папку, отдельный SVG-файл или glob-шаблон. Для нескольких источников используйте массив с любой комбинацией этих значений:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"mode": "standalone",
|
|||
|
|
"name": "icons",
|
|||
|
|
"input": "../svg-icons/**/*.svg"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. Сгенерируйте спрайт
|
|||
|
|
|
|||
|
|
Передайте команде путь к конфигу:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
npx --yes @gromlab/svg-sprites assets/app-icons/svg-sprite.config.json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Пакет соберёт иконки в каталог `.svg-sprite` рядом с конфигом:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
assets/app-icons/.svg-sprite/
|
|||
|
|
├── sprite.svg
|
|||
|
|
└── svg-sprite.manifest.json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- `sprite.svg` — готовый спрайт для использования на сайте.
|
|||
|
|
- `svg-sprite.manifest.json` — данные об иконках для Viewer.
|
|||
|
|
|
|||
|
|
Каталог `.svg-sprite` создаётся автоматически и полностью заменяется при каждой генерации. Не редактируйте его содержимое вручную.
|
|||
|
|
|
|||
|
|
### 4. Используйте иконку
|
|||
|
|
|
|||
|
|
В `index.html` укажите путь к созданному `sprite.svg`. После `#` добавьте имя нужной иконки без расширения `.svg`:
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<svg
|
|||
|
|
width="24"
|
|||
|
|
height="24"
|
|||
|
|
aria-label="Готово"
|
|||
|
|
>
|
|||
|
|
<use href="./assets/app-icons/.svg-sprite/sprite.svg#check"></use>
|
|||
|
|
</svg>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Иконка из файла `check.svg` будет доступна как `#check`.
|
|||
|
|
|
|||
|
|
## Дебаг и превью
|
|||
|
|
|
|||
|
|
`sprite.svg` — технический файл, а не галерея иконок. При его открытии нельзя удобно просмотреть весь набор. Кроме того, градиенты, маски, фильтры и ссылки на внутренние `id` могут отображаться с артефактами.
|
|||
|
|
|
|||
|
|
Для визуальной проверки используйте официальный Viewer. Он показывает все иконки спрайта и помогает проверить их цвета и отображение.
|
|||
|
|
|
|||
|
|
Viewer необязателен и предназначен только для разработки. Устанавливать пакет через npm не нужно.
|
|||
|
|
|
|||
|
|
Viewer работает напрямую с файлами из `.svg-sprite`. Ничего копировать не нужно.
|
|||
|
|
|
|||
|
|
### Добавьте Viewer на страницу
|
|||
|
|
|
|||
|
|
Добавьте в `index.html` module script и укажите пути к generated manifest и спрайту:
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<script
|
|||
|
|
type="module"
|
|||
|
|
src="https://cdn.jsdelivr.net/npm/@gromlab/svg-sprites/dist/viewer-element.js"
|
|||
|
|
></script>
|
|||
|
|
|
|||
|
|
<gromlab-sprite-viewer
|
|||
|
|
viewer-title="Иконки проекта"
|
|||
|
|
manifest-url="./assets/app-icons/.svg-sprite/svg-sprite.manifest.json"
|
|||
|
|
sprite-url="./assets/app-icons/.svg-sprite/sprite.svg"
|
|||
|
|
></gromlab-sprite-viewer>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Viewer можно вынести в отдельный HTML-файл в корне сайта, предназначенный только для разработки и проверки иконок.
|