Собствени SVG икони в WordPress 7.1: практическо ръководство
WordPress 7.1 добавя публичен API за собствени SVG икони. Вместо JavaScript, build процес или несигурно заобиколно решение, можеш да регистрираш икони от разширение и да ги използваш в избора на блока core/icon, в PHP шаблони и през REST API.
Ще създадем малко разширение myplugin-custom-icons: то добавя колекция, регистрира сърце директно от SVG код, звезда и отметка от файлове, автоматично зарежда цяла папка с икони и предлага кратък код за съдържанието. Ще видиш и как същата икона влиза като икона на собствен блок без build стъпка.
Какво ще създадеш
- Разширение
myplugin-custom-iconsс колекция икониmyplugin. - Три готови икони: сърце чрез вграден SVG, плюс звезда и отметка от
.svgфайлове. - Шаблон за масова регистрация, който чете всеки SVG файл в папка.
- Кратък код, с който вмъкваш регистрирана икона в публикации.
- Икона за собствен блок чрез
register_block_type(). - Интеграция в редактора, PHP и REST API от една регистрация.
Какво ти трябва
Работи с WordPress 7.1 или по-нова версия; за разработка става и 7.1 RC. Подготви няколко SVG файла, локална среда като LocalWP, WordPress Studio или wp-env и базови познания по PHP. Версия 7.1 е планирана за 19 август 2026 г.
API-то накратко
API-то има три основни функции. wp_register_icon_collection( $name, $args ) създава именувана група, wp_register_icon( $name, $args ) добавя отделна икона, а wp_get_icon( $name, $args ) връща SVG низа за визуализиране в PHP.
Всяка икона принадлежи към колекция. Името ѝ става префикс – например core/plus и myplugin/plus са различни записи. Това предотвратява конфликтите с иконите от ядрото на WordPress и с други разширения.
При регистрацията подаваш SVG по един от два начина: content съдържа SVG markup като низ в PHP, а file_path сочи абсолютния път към .svg файл. Не комбинирай двата аргумента за една икона. content е удобен за една-две икони, докато file_path е по-подходящ за библиотека във файлова папка.
1. Създай разширението и колекцията
Първо регистрирай колекцията. Ако добавиш икона към несъществуваща колекция, тя няма да се появи в избора на икони и WordPress няма да покаже грешка.
Създай следната структура в wp-content/plugins/:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgДобави главния файл myplugin-custom-icons.php. Колекцията се закача към init с приоритет по подразбиране – 10.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Register custom SVG icons for WordPress 7.1+.
* Version: 1.0.0
* Requires at least: 7.1
* Requires PHP: 7.4
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
define( 'MYPLUGIN_ICONS_PATH', plugin_dir_path( __FILE__ ) );
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Префиксът на всички следващи икони ще бъде myplugin: например myplugin/heart и myplugin/star. Стойността на label става заглавие на секцията в избора на икони. Активирай разширението от „Разширения → Инсталирани разширения“; колекцията още няма да се вижда, защото не съдържа икони.
2. Регистрирай SVG икони по два начина
Можеш да смесваш вградени SVG низове и SVG файлове в една колекция. В този пример сърцето е в PHP файла, а звездата и отметката са на диска.
Икона чрез content
Вграденият SVG е практичен, когато поддържаш само една или две икони и не искаш допълнителни файлове. Регистрирай го с приоритет 20, така че колекцията вече да съществува.
add_action( 'init', 'myplugin_register_inline_icons', 20 );
function myplugin_register_inline_icons() {
wp_register_icon(
'myplugin/heart',
array(
'label' => __( 'Heart', 'myplugin-icons' ),
'content' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"/></svg>',
)
);
}Името следва формата collection/icon-slug, а label се показва в picker-а. Атрибутът stroke="currentColor" кара SVG да наследи цвета на околния текст, вместо да налага цвят.
Икони чрез file_path
Запиши следните файлове в папката icons/. При този вариант WordPress чете файла, когато му потрябва.
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
</svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/>
</svg>add_action( 'init', 'myplugin_register_file_icons', 20 );
function myplugin_register_file_icons() {
wp_register_icon(
'myplugin/star',
array(
'label' => __( 'Star', 'myplugin-icons' ),
'file_path' => MYPLUGIN_ICONS_PATH . 'icons/star.svg',
)
);
wp_register_icon(
'myplugin/bookmark',
array(
'label' => __( 'Bookmark', 'myplugin-icons' ),
'file_path' => MYPLUGIN_ICONS_PATH . 'icons/bookmark.svg',
)
);
}Отвори блока core/icon в редактора. Ще видиш секция MyPlugin с Heart, Star и Bookmark. Ако някоя икона липсва, почти винаги причината е грешният ред: регистрирай колекцията на стандартния приоритет и иконите на 20.
3. Зареждай автоматично цяла папка
Ръчната регистрация не е удобна за библиотека от десетки икони. Вместо това обхождай папката и добавяй всеки SVG при следващата заявка. Замени функцията myplugin_register_file_icons() с тази версия.
add_action( 'init', 'myplugin_register_all_file_icons', 20 );
function myplugin_register_all_file_icons() {
$icons_dir = MYPLUGIN_ICONS_PATH . 'icons/';
$svg_files = glob( $icons_dir . '*.svg' );
if ( empty( $svg_files ) ) {
return;
}
foreach ( $svg_files as $file_path ) {
$slug = basename( $file_path, '.svg' );
$label = ucwords( str_replace( '-', ' ', $slug ) );
wp_register_icon(
'myplugin/' . $slug,
array(
'label' => $label,
'file_path' => $file_path,
)
);
}
}glob( $icons_dir . '*.svg' ) връща всички SVG файлове в папката. basename( $file_path, '.svg' ) премахва разширението – advanced-button.svg става advanced-button – а ucwords( str_replace( '-', ' ', $slug ) ) го превръща в четим етикет „Advanced Button“. Цикълът добавя всяка икона към myplugin/.
Копирай нов SVG в папката, обнови редактора и той ще се появи в picker-а без промяна по PHP кода. Шаблонът работи еднакво за star и bookmark, както и за стотици допълнителни файлове; сърцето от предишната стъпка остава регистрирано чрез content.
4. Използвай иконите на три места
В блока core/icon и през REST API
Picker-ът на core/icon показва автоматично всяка регистрирана колекция. Потребителят избира иконата, вмъква блока и тя се визуализира на сайта без допълнителен код.
Регистърът е наличен и за външни инструменти през endpoint-а /wp-json/wp/v2/icons. Колекциите са достъпни от придружаващия /wp-json/wp/v2/icon-collections endpoint, включително за инструменти, които четат данни от WordPress.
В PHP чрез wp_get_icon()
wp_get_icon() връща SVG като низ. Можеш директно да го изведеш:
echo wp_get_icon( 'myplugin/heart' );В шаблон подай втори масив, ако трябва да зададеш размер, CSS клас и достъпно име.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);sizeзадаваwidthиheightна SVG в пиксели.classдобавя CSS клас към SVG елемента.labelзадаваaria-labelза екранни четци.
Функцията приема и title в масива $args. Тъй като връща низ, можеш да го обвиеш и в собствен HTML.
Кратък код за публикации
Следният кратък код myplugin_icon вмъква избрана икона до текст в публикация, страница или джаджа. Той валидира името, размера и CSS класа, а при липсваща икона не връща нищо.
add_shortcode( 'myplugin_icon', 'myplugin_icon_shortcode' );
function myplugin_icon_shortcode( $atts ) {
$atts = shortcode_atts(
array(
'name' => 'heart',
'text' => '',
'size' => 24,
'class' => '',
),
$atts
);
$icon = wp_get_icon(
'myplugin/' . sanitize_key( $atts['name'] ),
array(
'size' => absint( $atts['size'] ),
'class' => sanitize_html_class( $atts['class'] ),
)
);
if ( ! $icon ) {
return '';
}
return sprintf(
'<span>%s %s</span>',
$icon,
esc_html( $atts['text'] )
);
}[myplugin_icon name="heart" text="Hello World"]
[myplugin_icon name="star" text="Featured post" size="32"]
[myplugin_icon name="bookmark" text="Save for later" size="20"]Иконата ще стои до текста с размера от атрибута size. Понеже SVG използва currentColor, той автоматично взема цвета на околния текст.
Като икона на собствен блок
Регистрирана SVG икона може да замени стандартната Dashicon икона на блок. Вместо това:
'icon' => 'warning', // Използва Dashiconподай пълното име на твоята икона:
'icon' => 'myplugin/star', // Използва регистрирана SVG иконаВмъквачът на блокове ще покаже SVG иконата вместо обща Dashicon. Подходът работи и за блокове, регистрирани с JavaScript, и за блокове само с PHP чрез register_block_type(). Една регистрация обслужва редактора, PHP и REST API.
5. Оформи иконите с CSS
SVG иконите изглеждат естествено по подразбиране, но трябва да следват контекста си: да наследяват цвят, да се мащабират с текста и да реагират при hover. Класът от wp_get_icon() е директна CSS кука; в редактора, където този аргумент не участва, използвай клас на обвиващия елемент.
Наследявай цвета с currentColor
Използвай stroke="currentColor" или fill="currentColor", а не фиксирани цветове. Така иконата в червен текст става червена, в тъмна тема следва темата, а в линк приема цвета на линка – държи се като текст.
<!-- Неподходящо: иконата винаги е червена -->
<svg viewBox="0 0 24 24"
stroke="#dc2626"
stroke-width="2">
<path d="..."/>
</svg>SVG без фиксирани цветове пасва на всяка тема. Икона с твърдо зададен цвят често влиза в конфликт с нея.
Наложи цвят при нужда
За брандов знак или индикатор за състояние понякога цветът трябва да остане конкретен. Задай color на SVG през класа му; currentColor ще се прехвърли към stroke или fill.
.featured-icon {
color: #f59e0b; /* Кехлибарен цвят независимо от текста */
}Размер и hover състояния
Аргументът size контролира размера в пиксели при shortcode и wp_get_icon(). Ако искаш размерът и поведението да идват от CSS, използвай например следното правило:
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Използвай
sizeвwp_get_icon()за единичен случай с точен размер, когато не си струва да пишеш CSS. - Използвай CSS класове – през
classили върху обвивката – когато иконата се повтаря на много места, трябва да е последователна или стилът зависи от hover, focus, active и контекст като линк или заглавие. - При краткия код можеш да коригираш отделен случай с
size, а за единен стил в целия сайт да добавиш CSS към.myplugin-icon-inline svg.
6. Премахвай икони и колекции
WordPress 7.1 има съответни функции за отрегистриране на една икона и на цяла колекция.
Премахни една икона
Това е полезно при разработка или когато обновление на разширението премахва икона.
wp_unregister_icon( 'myplugin/bookmark' );При следващата заявка иконата изчезва от picker-а. Ако съществуваща публикация вече я е вмъкнала в блок core/icon, блокът ще се визуализира празен – WordPress не пренаписва съдържанието на публикациите.
Премахни колекцията при деактивиране
Когато деактивираш разширението, иконите му не бива да остават в picker-а. Отрегистрирай колекцията с hook за деактивиране; това премахва всички нейни икони и не изисква цикъл поотделно.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Чести въпроси
Трябва ли колекцията да се регистрира преди иконите?
Да. Иконите трябва да принадлежат към съществуваща колекция, иначе тихо няма да се покажат в picker-а. Закачи колекцията към init с приоритета по подразбиране, а иконите с по-висок, например 20.
Мога ли да смесвам content и file_path в една колекция?
Да. Всеки извикване на wp_register_icon() е самостоятелно. Ползвай content за една-две икони, а file_path за останалите; след регистрацията WordPress ги третира еднакво.
Работят ли иконите като икони на блок в register_block_type()?
Да. Подай регистрираното име, например 'myplugin/star', на ключа icon. Вмъквачът ще покаже SVG вместо Dashicon и това важи както за JavaScript блокове, така и за блокове само с PHP.
Какво връща wp_get_icon()?
Функцията връща SVG като низ, не го извежда сама. Можеш директно да го echo-неш или да го поставиш в собствен HTML. Вторият масив $args приема size, class, label за aria-label и title.
Какво да премахна от SVG преди регистрация?
Премахни фиксирани fill и stroke цветове, както и width и height от основния <svg> елемент, но запази viewBox. Махни още всички <style> блокове и скриптове; остави структурните атрибути. За цвят използвай currentColor.
Мога ли да регистрирам икони от тема?
Да. Същото извикване на wp_register_icon() работи във functions.php на тема, като за пътя до файла използваш get_stylesheet_directory(). Компромисът е, че иконите изчезват, когато смениш темата.
Какво става, ако две колекции имат икона с еднакво име?
Колекциите действат като namespace. myplugin/heart и otherplugin/heart съществуват едновременно без конфликт, защото уникално е цялото име с префикса на колекцията.
WordPress филтрира ли SVG при регистрация?
Не. WordPress не променя SVG съдържанието при регистрация: подаденият низ или съдържанието на посочения файл се сервира точно така. Почисти SVG файловете преди публикуване – премахни скриптове, външни препратки и всичко излишно.
Следващата стъпка
Пълното разширение с примерни SVG файлове, README и масовата регистрация е достъпно в GitHub хранилището. След като WordPress 7.1 е наличен в средата ти, регистрирай първо колекцията, добави SVG файловете и провери иконите едновременно в core/icon, шаблоните и блока ти.
Този модел „регистрирай веднъж, използвай навсякъде“ съвпада с посоката на API-тата в WordPress, включително Abilities API и PHP-only блоковете: регистърът захранва редактора, PHP слоя, REST API и външни инструменти. За разширенията това означава брандирано изживяване в редактора без JavaScript build стъпка.
Георги Петров
Backend разработчик и системен архитект. Експерт по PHP и Laravel, изграждането на уеб приложения с голям трафик е моята специалност.
Всички публикации
