Cum adaugi iconițe SVG personalizate în WordPress 7.1
WordPress 7.1 introduce o API publică pentru iconițe SVG personalizate. Poți înregistra colecții și iconițe dintr-un plugin, le poți afișa în selectorul blocului core/icon, în șabloane PHP și prin REST API, fără JavaScript și fără un build step.
În acest ghid construiești un plugin mic care declară o colecție, adaugă o inimă definită direct în PHP, o stea și un semn de carte din fișiere .svg, le înregistrează în masă dintr-un director și le expune printr-un shortcode. Ai nevoie de WordPress 7.1 sau mai nou – inclusiv 7.1 RC pentru dezvoltare -, de câteva fișiere SVG, de un mediu local precum LocalWP, WordPress Studio sau wp-env și de noțiuni de bază de PHP.
WordPress 7.1 este programat să apară pe 19 august 2026. Codul de mai jos corespunde API-ului preconizat pentru versiunea finală.
API-ul pentru iconițe: colecții, înregistrare și randare
API-ul are trei funcții și un concept de organizare. O colecție grupează iconițele și le pune într-un namespace: de exemplu, core/plus și myplugin/plus sunt nume diferite, chiar dacă folosesc același slug. Astfel eviți conflictele cu iconițele din WordPress core și cu cele din alte pluginuri.
wp_register_icon_collection( $name, $args )declară un grup de iconițe cu nume.wp_register_icon( $name, $args )declară o iconiță individuală.wp_get_icon( $name, $args )randează iconița în PHP și returnează SVG-ul ca șir.
Când înregistrezi o iconiță, alege una dintre cele două surse pentru SVG: content, adică markup SVG inclus direct în PHP, sau file_path, adică o cale absolută către un fișier .svg de pe disc. Nu le combina pentru aceeași iconiță. content este potrivit pentru una-două iconițe, iar file_path devine mai ușor de întreținut pentru o bibliotecă întreagă.
1. Creează pluginul și declară colecția înaintea iconițelor
Creează directorul pluginului în wp-content/plugins/, apoi adaugă fișierul principal și directorul pentru SVG-uri.
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgColecția trebuie să existe înainte să înregistrezi iconițe în ea. Dacă încerci să adaugi o iconiță într-o colecție inexistentă, ea nu apare în selector fără să primești o eroare vizibilă.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Înregistrează iconițe SVG personalizate pentru 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__ ) );
// Declară mai întâi colecția de iconițe.
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Numele colecției devine prefixul tuturor iconițelor: myplugin/heart, myplugin/star sau myplugin/bookmark. Opțiunea label devine titlul secțiunii din selector. Activează pluginul din Pluginuri → Pluginuri instalate; deocamdată nu vei vedea nimic, deoarece o colecție goală nu randează iconițe.
2. Înregistrează SVG-ul direct în PHP sau din fișiere
Poți folosi ambele metode în aceeași colecție. În exemplul următor, inima folosește content, iar steaua și semnul de carte folosesc fișiere separate.
Iconiță inline cu content
Include SVG-ul direct în fișierul PHP atunci când ai doar una sau două iconițe și nu vrei să gestionezi fișiere suplimentare. Prioritatea 20 face ca acest callback să ruleze după înregistrarea colecției, care folosește prioritatea implicită 10.
// Înregistrează o iconiță cu SVG inclus direct în PHP.
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>',
)
);
}Numele myplugin/heart respectă formatul colecție/slug. Eticheta apare în selector, iar content conține markupul. Atributul stroke="currentColor" permite SVG-ului să moștenească automat culoarea textului din jur, fără să fixezi o culoare în fișier.
Iconițe din fișiere .svg cu file_path
Păstrează următoarele două fișiere în directorul icons/. Pentru un set de iconițe păstrat pe disc, file_path este alegerea mai practică.
<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>// Înregistrează iconițe din fișiere 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',
)
);
}Singura schimbare față de varianta inline este înlocuirea lui content cu file_path. WordPress citește fișierul la cerere. Deschide apoi blocul core/icon în editor: selectorul va afișa secțiunea MyPlugin, cu Heart, Star și Bookmark.
// Dacă o iconiță lipsește din selector, verifică ordinea hookurilor:
add_action( 'init', 'myplugin_register_icon_collection' ); // prioritate 10
add_action( 'init', 'myplugin_register_file_icons', 20 ); // după colecțieÎn practică, înregistrarea iconiței înaintea colecției este cauza cea mai frecventă pentru care aceasta nu apare.
3. Înregistrează automat toate SVG-urile dintr-un director
Nu merită să scrii zeci de apeluri wp_register_icon() pentru o bibliotecă reală. Înlocuiește funcția individuală myplugin_register_file_icons() cu următoarea variantă, care citește toate fișierele SVG din 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' ) găsește toate fișierele SVG din director. basename( $file_path, '.svg' ) elimină extensia, astfel încât advanced-button.svg devine advanced-button, iar ucwords( str_replace( '-', ' ', $slug ) ) generează eticheta lizibilă „Advanced Button”. Bucla înregistrează fiecare fișier în colecția myplugin/.
După ce adaugi un SVG nou în director, reîncarcă editorul: iconița apare în selector fără să modifici PHP-ul. Același tipar poate înregistra câteva iconițe sau sute; iconița inline rămâne separată, iar toate fișierele adăugate în director intră automat în colecție.
4. Folosește aceeași iconiță în editor, PHP și blocuri
În blocul core/icon și prin REST API
Selectorul blocului core/icon detectează automat fiecare colecție înregistrată. Utilizatorul inserează blocul, alege iconița din secțiunea MyPlugin, iar WordPress o randează pe site fără cod suplimentar.
WordPress expune iconițele și la endpointul REST /wp-json/wp/v2/icons, iar colecțiile la /wp-json/wp/v2/icon-collections. Instrumentele externe care consumă date WordPress pot citi astfel aceleași informații.
În șabloane PHP cu wp_get_icon()
wp_get_icon() returnează SVG-ul ca șir, deci îl poți afișa direct sau îl poți încadra în propriul HTML.
echo wp_get_icon( 'myplugin/heart' );Într-un șablon real, trimite al doilea argument pentru dimensiune, clasă CSS și accesibilitate.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);sizeseteazăwidthșiheightale SVG-ului în pixeli.classadaugă o clasă CSS pe elementul SVG.labelseteazăaria-labelpentru cititoarele de ecran.
Shortcode pentru conținutul articolelor
Shortcode-ul următor permite inserarea unei iconițe în articole, pagini sau widgeturi. El curăță slugul, clasa CSS și dimensiunea înainte să ceară SVG-ul, iar dacă nu găsește iconița returnează un șir gol.
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"]Iconița apare lângă text și respectă atributul size. Deoarece SVG-urile folosesc currentColor, ele preiau automat culoarea textului care le înconjoară.
Ca iconiță pentru un bloc personalizat
Poți înlocui Dashicon-ul implicit din configurarea unui bloc cu numele complet al unei iconițe înregistrate. Funcționează atât pentru blocuri înregistrate prin JavaScript, cât și pentru blocuri declarate exclusiv în PHP.
'icon' => 'warning', // Folosește un Dashicon'icon' => 'myplugin/star', // Folosește SVG-ul personalizat înregistratInserterul de blocuri va afișa iconița personalizată în locul unui Dashicon generic. Același registry deservește editorul, șabloanele PHP și REST API: înregistrezi o dată și consumi în mai multe contexte.
5. Stilizează iconițele cu CSS
Pentru ca o iconiță să se integreze în temă, las-o să moștenească culoarea textului, să se dimensioneze odată cu interfața și aplică stiluri de stare când ai nevoie. Argumentul class din wp_get_icon() îți oferă un hook CSS pentru SVG; în editor, unde nu trimiți acest argument, aplică reguli care acoperă contextul în care apare blocul.
Folosește currentColor, nu culori fixate
În SVG, preferă stroke="currentColor" sau fill="currentColor" în locul unei valori hardcodate. O iconiță din text roșu devine roșie, una dintr-o temă întunecată preia culoarea acelui context, iar una dintr-un link preia culoarea linkului.
<!-- Evită o culoare fixată: iconița va rămâne mereu roșie. -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..." />
</svg>
<!-- Lasă iconița să preia culoarea contextului. -->
<svg viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
<path d="..." />
</svg>O iconiță fără culori fixate se adaptează la orice temă; una cu o culoare impusă poate intra în conflict cu multe dintre ele.
Forțează o culoare doar când contextul o cere
Pentru un semn de brand sau un indicator de stare, poți impune o culoare prin CSS. Cum SVG-ul folosește currentColor, proprietatea color aplicată prin clasă ajunge în stroke sau fill.
.featured-icon {
color: #f59e0b; /* Chihlimbar, indiferent de culoarea textului. */
}Controlează dimensiunea și stările hover
Folosește size în wp_get_icon() sau în shortcode pentru o dimensiune punctuală în pixeli. Când vrei o regulă consecventă sau stări precum hover, focus și activ, stilizează printr-o clasă pe SVG sau pe elementul care îl încadrează.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Folosește
sizeînwp_get_icon()când ai un caz izolat și contează o dimensiune exactă în pixeli. - Folosește clase CSS – trimise prin
classsau aplicate pe un wrapper – când iconița apare în mai multe locuri, trebuie să rămână uniformă sau își schimbă stilul după stare ori context.
6. Elimină iconițe și colecții
WordPress 7.1 oferă și funcții pentru dezînregistrare: una pentru o iconiță individuală și una pentru întreaga colecție.
Elimină o singură iconiță
În timpul dezvoltării sau după ce un update al pluginului retrage o iconiță, apelează wp_unregister_icon(). Iconița dispare din selector la următoarea cerere, însă blocurile core/icon deja salvate cu acea iconiță vor randa gol: WordPress nu rescrie conținutul articolelor.
wp_unregister_icon( 'myplugin/bookmark' );Elimină colecția la dezactivarea pluginului
Când utilizatorul dezactivează pluginul, elimină întreaga colecție pentru ca iconițele să nu mai apară în selector. Nu trebuie să parcurgi iconițele una câte una.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Întrebări frecvente
Trebuie să declar colecția înainte să declar iconițele?
Da. Fiecare iconiță trebuie să aparțină unei colecții existente; altfel, nu va apărea în selector. Declară colecția pe init la prioritatea implicită și declară iconițele la o prioritate mai mare, de exemplu 20.
Pot combina content și file_path în aceeași colecție?
Da. Fiecare apel wp_register_icon() este independent. Poți păstra una sau două iconițe în content și restul în fișiere indicate prin file_path; după înregistrare, WordPress le tratează la fel.
Funcționează iconițele personalizate ca iconițe de bloc în register_block_type()?
Da. Trimite numele complet al iconiței înregistrate, precum 'myplugin/star', la cheia icon din register_block_type(). Inserterul va afișa SVG-ul în locul unui Dashicon, pentru blocuri înregistrate prin JavaScript sau exclusiv în PHP.
wp_get_icon() returnează HTML sau un șir?
Funcția returnează SVG-ul ca șir. Îl poți afișa cu echo sau îl poți include în propriul HTML. Al doilea array, $args, acceptă size, class, label pentru aria-label și title.
Ce atribute SVG trebuie să elimin înainte de înregistrare?
Elimină valorile fixe pentru fill și stroke, atributele width și height de pe elementul rădăcină <svg> – dar păstrează viewBox – precum și orice bloc <style> sau script. Păstrează viewBox și atributele structurale, iar pentru culoare folosește currentColor.
Pot înregistra iconițe dintr-o temă, nu dintr-un plugin?
Da. Același apel wp_register_icon() funcționează din functions.php al temei dacă formezi calea cu get_stylesheet_directory(). Compromisul este că iconițele declarate de temă dispar când utilizatorul schimbă tema.
Ce se întâmplă dacă două colecții au iconițe cu același nume?
Colecțiile pun numele în namespace, așadar myplugin/heart și anotherplugin/heart coexistă fără conflict. Numele complet, inclusiv prefixul colecției, identifică unic iconița.
WordPress igienizează SVG-urile la înregistrare?
Nu. WordPress nu modifică SVG-ul primit prin content sau conținutul fișierului indicat prin file_path; livrează exact conținutul respectiv. Igienizează SVG-urile înainte să le distribui: elimină scripturi, referințe externe și orice element inutil.
Ce faci mai departe
Pornește cu o colecție înregistrată pe init, apoi alege content pentru câteva SVG-uri sau file_path pentru o bibliotecă păstrată în fișiere. Dacă setul crește, treci la glob() pentru a înregistra automat tot directorul, păstrează viewBox și currentColor în SVG-uri, apoi verifică iconițele în core/icon, într-un șablon cu wp_get_icon() și ca valoare icon pentru blocurile tale.
Poți consulta implementarea completă, cu SVG-uri de exemplu, README și tiparul de înregistrare în masă, în repository-ul GitHub.
core/icon. — Forrás: Materialul-sursă
glob() poate încărca toate fișierele SVG dintr-un director. — Forrás: Materialul-sursăReferințe / Surse
Maria Popa
Cercetător UX și designer de produs. Testarea utilizatorilor și prototiparea sunt preferatele mele. Cred în designul centrat pe om.
Toate articolele
