---
title: "Icons API: SVG-иконки в WordPress 7.0 и 7.1"
description: "Регистрация и рендер SVG-иконок: коллекции, wp_register_icon(), wp_get_icon(), REST API, блок Icon и обходные пути для WordPress 7.0."
---
Icons API — система регистрации и вывода SVG-иконок в ядре WordPress. Иконка регистрируется один раз и дальше доступна везде: в редакторе (блок Icon), в PHP-шаблонах и паттернах, через REST API.
## История и доступность по версиям
| Версия | Что появилось |
|--------|----------------|
| **WordPress 7.0** | Встроенный набор SVG-иконок (коллекция `core`), блок `core/icon`, REST-эндпоинт `/wp/v2/icons`. Публичного API регистрации нет — метод `WP_Icons_Registry::register()` объявлен `protected`. |
| **WordPress 7.1** | Полноценный публичный API: регистрация коллекций и иконок, `wp_get_icon()` для серверного рендера, группировка иконок по коллекциям в пикере блока Icon. |
До 7.1 кастомные иконки добавляются через плагин [Icon Block](https://wordpress.org/plugins/icon-block/) (Nick Diego) — именно его код лёг в основу ядерного блока. Обход через Reflection описан ниже, но не рекомендуется для продакшена.
## Коллекции иконок (WordPress 7.1)
Каждая иконка принадлежит **коллекции** — именованной группе. Имя коллекции становится префиксом: `core/plus` и `my-plugin/plus` — разные иконки, которые не конфликтуют. Ядро регистрирует одну коллекцию `core` с бандленными иконками.
### Регистрация коллекции
Иконку можно добавить только в уже существующую коллекцию, поэтому сначала регистрируем её через `wp_register_icon_collection()`:
```php
function my_plugin_register_icon_collection() {
wp_register_icon_collection(
'my-plugin',
array(
'label' => __( 'My Plugin Icons', 'my-plugin' ),
'description' => __( 'Icons provided by My Plugin.', 'my-plugin' ),
)
);
}
add_action( 'init', 'my_plugin_register_icon_collection' );
```
- Первый аргумент — имя коллекции: начинается и заканчивается строчной буквой или цифрой, внутри допустимы строчные буквы, цифры, дефисы и подчёркивания.
- Второй аргумент — массив с обязательным `label` и опциональным `description`.
### Удаление коллекции
`wp_unregister_icon_collection()` удаляет коллекцию **вместе со всеми её иконками** — по одной удалять не нужно. Запускаем на `init` с приоритетом позже регистрации:
```php
function my_plugin_unregister_icon_collection() {
wp_unregister_icon_collection( 'my-plugin' );
}
add_action( 'init', 'my_plugin_unregister_icon_collection', 20 );
```
## Регистрация иконок (WordPress 7.1)
Имя иконки всегда имеет вид `collection/icon-name`, например `my-plugin/star`. Коллекция должна быть зарегистрирована до регистрации иконки.
### wp_register_icon()
Иконке передаём `label` и сам SVG — строкой (`content`) или абсолютным путём к `.svg`-файлу (`file_path`). Только один из двух вариантов, не оба сразу:
```php
function my_plugin_register_icons() {
// Сначала коллекция.
wp_register_icon_collection(
'my-plugin',
array( 'label' => __( 'My Plugin Icons', 'my-plugin' ) )
);
// Иконка из инлайн-строки SVG.
wp_register_icon(
'my-plugin/star',
array(
'label' => __( 'Star', 'my-plugin' ),
'content' => '',
)
);
// Иконка из .svg-файла, поставляемого с плагином.
wp_register_icon(
'my-plugin/heart',
array(
'label' => __( 'Heart', 'my-plugin' ),
'file_path' => plugin_dir_path( __FILE__ ) . 'icons/heart.svg',
)
);
}
add_action( 'init', 'my_plugin_register_icons' );
```
Функция возвращает `true` при успехе и `false` при ошибке с `_doing_it_wrong()`. Причины отказа: невалидное имя, имя без неймспейса `collection/icon-name`, незарегистрированная коллекция, дубликат иконки, отсутствующий `label`, лишние ключи аргументов, отсутствие (или одновременное указание) `content` и `file_path`.
> **`file_path` читается лениво.** Файл не открывается при регистрации — только при первом обращении к содержимому (рендер или REST). Поэтому регистрация пройдёт даже с неверным путём, а проблема всплывёт позже как пустой контент. Проверяйте, что путь резолвится на том окружении, где иконка используется.
### Санитизация SVG
SVG прогоняется через `wp_kses` по строгому allowlist:
- Выживают только элементы `