Egyedi SVG-ikonok a WordPress 7.1-ben: teljes fejlesztői útmutató
A saját SVG-ikonok eddig jellemzően JavaScriptet, build folyamatot vagy megbízhatatlan kerülőmegoldást igényeltek a blokkszerkesztőben. A WordPress 7.1 egy publikus API-val zárja le ezt a hiányt: bővítményből, JavaScript build lépés nélkül regisztrálhatsz ikonokat, amelyek a core/icon blokknál, PHP-ban és a REST API-n keresztül is elérhetők lesznek.
Az alábbi útmutató egy kis myplugin-custom-icons bővítményt épít fel. Létrehozunk egy ikonkollekciót, egy ikont közvetlen SVG-markupból, kettőt fájlból, majd automatikus mappafeldolgozással skálázzuk a megoldást. Az ikonokat a szerkesztőben, PHP-sablonban, shortcode-ban és egyedi blokk ikonjaként is használni fogod.
A WordPress 7.1 kiadását 2026. augusztus 19-re tervezik. Fejlesztéshez már a 7.1 RC is használható, de éles oldalon csak a végleges kiadással dolgozz.
Mire lesz szükséged?
A példák követéséhez készíts elő egy helyi WordPress-környezetet, például LocalWP-t, WordPress Studio-t vagy wp-env-et. Kell továbbá néhány SVG-fájl és alapvető PHP-ismeret.
Használd a WordPress 7.1-et vagy újabb verziót. A megoldás egy önálló bővítményben működik, ezért a sablon működésétől függetlenül megmaradnak az ikonok.
Az új ikon API három függvénye
A WordPress 7.1 egy regiszteren keresztül kezeli az ikonokat. Három függvény és az ikonkollekció fogalma adja az API teljes alapját.
wp_register_icon_collection( $name, $args ): névvel ellátott ikonkollekciót regisztrál.wp_register_icon( $name, $args ): egyetlen ikont vesz fel a regiszterbe.wp_get_icon( $name, $args ): PHP-ban kirendereli az ikont, és SVG-sztringet ad vissza.
Minden ikon egy kollekcióhoz tartozik. A kollekció neve az ikon teljes nevének prefixe, ezért különbözik például a core/plus a myplugin/plus ikontól. A névtér megakadályozza, hogy a saját ikonjaid ütközzenek a WordPress core vagy más bővítmények ikonneveivel.
Ikon regisztrálásakor kétféleképpen adhatod át az SVG-t. A content közvetlenül a PHP-kódban tárolt SVG-markupot vár, a file_path pedig egy lemezen lévő .svg fájl abszolút útvonalát. Egy ikonnál csak az egyik módszert használd: egy-két ikonhoz kényelmes a content, sok ikonhoz a file_path skálázódik jobban.
1. Hozd létre a bővítményt és a kollekciót
Mindig előbb regisztráld a kollekciót, és csak utána vedd fel az ikonokat. Ha nem létező kollekcióhoz próbálsz ikont hozzáadni, az ikon hibaüzenet nélkül kimarad a választóból.
Hozd létre az alábbi könyvtárstruktúrát a wp-content/plugins/ mappában:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgEzután készítsd el a bővítmény főfájlját. A kollekció myplugin neve lesz minden későbbi ikon prefixe, például myplugin/heart vagy myplugin/star; a label pedig az ikonválasztó szakaszcímeként jelenik meg.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Egyedi SVG-ikonok regisztrálása WordPress 7.1+-hoz.
* 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__ ) );
// Előbb hozzuk létre az ikonkollekciót.
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Kapcsold be a bővítményt a Bővítmények → Telepített bővítmények képernyőn. Egyelőre nem látsz változást, mert az üres kollekció nem jelenik meg a felületen.
2. Regisztrálj ikonokat közvetlenül és fájlból
A következő példában mindkét támogatott regisztrációs módot használjuk. A szív ikon SVG-je közvetlenül a PHP-fájlban lesz, a csillag és a könyvjelző pedig különálló .svg fájlból érkezik.
2.1. Közvetlen SVG a content paraméterrel
Ha csak egy vagy két ikonod van, a közvetlen markup megspórolja a külön fájlok kezelését. Egészítsd ki a fő bővítményfájlt ezzel a regisztrációval:
// A közvetlenül megadott SVG-ikon regisztrálása.
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>',
)
);
}Az init hookon a 20 prioritás később fut le, mint a kollekció alapértelmezett, 10-es prioritású regisztrációja. Az ikon ezért biztosan egy már létező kollekcióhoz kapcsolódik. A stroke="currentColor" azt is biztosítja, hogy az ikon a környező szöveg színét örökölje, ne rögzített kitöltőszínt használjon.
2.2. SVG-fájlok regisztrálása a file_path paraméterrel
Nagyobb ikoncsomagnál tartsd az SVG-ket külön fájlokban. Mentsd az alábbi két fájlt az icons/ könyvtárba.
<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>A PHP-ból csak a content paramétert kell file_path-ra cserélned. A WordPress szükség esetén olvassa be a fájl tartalmát.
// SVG-fájlokból származó ikonok regisztrálása.
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',
)
);
}Nyisd meg a szerkesztőben a core/icon blokkot. Az ikonválasztóban megjelenik a MyPlugin szakasz a Heart, Star és Bookmark ikonokkal.
Ha valamelyik ikon hiányzik, elsőként a regisztrációk sorrendjét ellenőrizd. A kollekció fusson az alapértelmezett prioritással, az ikonokat pedig későbbi prioritással – a fenti példákban 20-szal – regisztráld.
3. Dolgozz teljes ikonmappával
Harminc vagy több ikont nem érdemes kézzel, külön wp_register_icon() hívásokkal felvenni. Praktikusabb, ha a PHP a következő kérésnél beolvassa a mappában lévő összes SVG-fájlt, és automatikusan regisztrálja őket.
Cseréld le az előző myplugin_register_file_icons() függvényt erre a tömeges regisztrációs változatra:
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,
)
);
}
}A glob( $icons_dir . '*.svg' ) összegyűjti a könyvtár valamennyi .svg fájlját. A basename( $file_path, '.svg' ) levágja a kiterjesztést, így az advanced-button.svg ikon slugja advanced-button lesz.
A ucwords( str_replace( '-', ' ', $slug ) ) olvasható címkét készít az ikonválasztóhoz: az advanced-button neve például „Advanced Button” lesz. A ciklus ezután minden fájlt a myplugin/ kollekcióba regisztrál.
Ezután elég új SVG-ket bemásolnod az icons/ mappába, majd frissítened a szerkesztőt. Kódmódosítás nélkül megjelennek az új ikonok a választóban. A közvetlenül regisztrált heart ikon maradhat külön, a mappában lévő star, bookmark és minden új fájl pedig automatikusan bekerül.
4. Használd az ikonokat három helyen
Egyetlen regisztráció után a blokkszerkesztő, a PHP és a REST API ugyanazt az ikonregisztert használja. Emiatt ugyanazokat az ikonokat több felhasználási környezetben is elérheted külön integráció nélkül.
4.1. A core/icon blokkban
A core/icon blokk ikonválasztója automatikusan felsorolja az összes regisztrált kollekciót. A szerkesztő felhasználója behelyezi a blokkot, kiválaszt egy MyPlugin ikont, a WordPress pedig a frontenden további kód nélkül kirendereli.
Az ikonok külső eszközök számára is elérhetők a /wp-json/wp/v2/icons REST endpointon. A kollekciók listáját a kapcsolódó /wp-json/wp/v2/icon-collections endpoint adja vissza, így bármely WordPress-adatokat olvasó külső eszköz – AI-agent is – fel tudja fedezni őket.
4.2. PHP-ban a wp_get_icon() függvénnyel
A wp_get_icon() SVG-sztringet ad vissza, ezért a legegyszerűbb esetben közvetlenül kiírhatod:
echo wp_get_icon( 'myplugin/heart' );Sablonban a második argumentummal beállíthatod a méretet, a CSS-osztályt és az akadálymentes címkét is:
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Kiemelt', 'myplugin-icons' ),
)
);- A
sizepixelben állítja az SVGwidthésheightattribútumát. - A
classCSS-osztályt tesz az SVG-elemre. - A
labelazaria-labelértékét adja meg a képernyőolvasóknak.
Ha tartalomszerkesztőknek is adnál egyszerű hozzáférést, készíts shortcode-ot. Az alábbi [myplugin_icon] shortcode ikont és opcionális szöveget szúr be a bejegyzésbe, oldalba vagy widgetbe.
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'] )
);
}A shortcode-ot így használhatod:
[myplugin_icon name="heart" text="Hello World"]
[myplugin_icon name="star" text="Kiemelt bejegyzés" size="32"]
[myplugin_icon name="bookmark" text="Mentés későbbre" size="20"]Az ikon a szöveg mellett jelenik meg, a size attribútum pedig meghatározza a méretét. Mivel az SVG currentColor értéket használ, automatikusan átveszi a környező szöveg színét.
4.3. Egyedi blokk ikonjaként
A regisztrált ikonok a register_block_type() hívásban is helyettesíthetik az alapértelmezett Dashicont. Egy korábbi, Dashicont használó blokkbeállítás például így néz ki:
'icon' => 'warning', // Dashicont használA WordPress 7.1-től ugyanezt a saját ikonnevedre cserélheted:
'icon' => 'myplugin/star', // Regisztrált egyedi ikont használA blokkbeszúró így általános Dashicon helyett a saját SVG-det mutatja. Ez JavaScripttel regisztrált blokkoknál és csak PHP-val készülő blokkoknál is működik.
5. Igazítsd az ikonokat CSS-sel
Az ikonok alapból natív módon illeszkednek a felülethez, de akkor működnek igazán jól, ha öröklik a szöveg színét, követik a méretezést és reagálnak az interakciókra. A wp_get_icon() class argumentuma CSS hookot ad közvetlenül az SVG-hez; a következő minták a blokkban megjelenő ikonokra is alkalmazhatók, ahol ez az argumentum nem áll rendelkezésre.
5.1. Használd a currentColor értéket
SVG-nél a legfontosabb szabály, hogy rögzített színek helyett stroke="currentColor" vagy fill="currentColor" értéket adj meg. Az alábbi megoldás problémás, mert az ikon mindig vörös marad:
<!-- Kerüld: az ikon mindig vörös marad. -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>A currentColor használatával a vörös szövegben lévő ikon vörös, sötét témában sötét, hivatkozásban pedig a link színét kapja meg. Így az SVG szövegszerűen viselkedik, és sokkal több témába illeszkedik ütközés nélkül.
5.2. Kényszeríts ki konkrét színt, amikor szükséges
Márkajelzésnél vagy állapotjelzőnél előfordulhat, hogy az ikonnak mindig ugyanazt a színt kell mutatnia. A currentColor mellett ezt CSS-sel egyszerűen felülírhatod:
.featured-icon {
color: #f59e0b; /* Borostyánszín a környezettől függetlenül. */
}Mivel az SVG a currentColor értéket használja, az SVG-re tett color szabály átadódik a körvonalnak vagy kitöltésnek. Az ikon sötét szövegkörnyezetben is borostyánszínű marad.
5.3. Méret és hover állapot
Shortcode-ból vagy wp_get_icon() segítségével kirenderelt ikonoknál a size argumentum közvetlenül kezeli a pixeles méretet. Ha CSS-ből méreteznél vagy hover állapotot adnál hozzá, használj burkolóelemet és az alábbi szabályokat:
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}5.4. Mikor válaszd a size argumentumot, és mikor a CSS-t?
- A
wp_get_icon()sizeargumentumát válaszd egyszeri esetekhez, amikor pontos pixelméret kell, és nem indokolt külön CSS-t írni. - CSS-osztályt használj – a
classargumentummal vagy egy burkolóelemen – ha az ikon sok helyen jelenik meg és következetes maradjon, illetve ha az állapotától vagy környezetétől függ a stílus. Ilyen a hover, focus, active állapot, a hivatkozás vagy a címsor környezete.
A shortcode-nál mindkét megközelítés működik. Egyedi, kis módosításokhoz add meg a size attribútumot; egységes, webhelyszintű megjelenéshez célozd a .myplugin-icon-inline svg elemet CSS-ből.
6. Távolíts el ikonokat és kollekciókat
A WordPress 7.1 az ikonok regisztrációjához illeszkedő törlőfüggvényeket is ad. Egyetlen ikont vagy teljes kollekciót is eltávolíthatsz.
6.1. Egy ikon eltávolítása
Fejlesztés közben, vagy amikor egy bővítményfrissítés kivezet egy ikont, ezt a hívást használd:
wp_unregister_icon( 'myplugin/bookmark' );Az ikon a következő kérésnél eltűnik a választóból. Azok a korábbi bejegyzések azonban, amelyek már core/icon blokkban használták, üresen renderelnek, mert a WordPress nem írja át a bejegyzések tartalmát.
6.2. Teljes kollekció eltávolítása kikapcsoláskor
Bővítmény kikapcsolásakor a hozzá tartozó ikonok se maradjanak az ikonválasztóban. A kollekció törlése egyetlen hívással eltávolítja a benne lévő összes ikont:
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Nem kell külön végigiterálnod az ikonokon. A kollekció törlése elvégzi a teljes takarítást.
Biztonsági és architekturális szempontok
A WordPress az SVG-t regisztrációkor nem módosítja és nem tisztítja. Pontosan azt a sztringet vagy fájltartalmat szolgálja ki, amelyet átadsz, ezért a kiadás előtt neked kell eltávolítanod a scripteket, külső hivatkozásokat és minden szükségtelen elemet.
Tartsd meg a viewBox és a szerkezeti attribútumokat, de a gyökér <svg> elemről töröld a rögzített fill, stroke, width és height attribútumokat. Távolítsd el a <style> blokkokat és a scripteket is, a színhez pedig használj currentColor hivatkozást.
A rendszer a „regisztráld egyszer, használd mindenhol” mintát követi: a core/icon blokk, a wp_get_icon() és a REST API ugyanazt a regisztert olvassa. Ez a megközelítés az Abilities API és a block bindings működésével is összhangban van, így a bővítményed a szerkesztőben, a REST rétegben és a WordPress-adatmodellre épülő eszközökben is következetesen integrálódik.
Gyakori kérdések
Kötelező a kollekciót az ikonok előtt regisztrálni?
Igen. Az ikonoknak létező kollekcióhoz kell tartozniuk, különben nem jelennek meg az ikonválasztóban. Regisztráld a kollekciót init hookon alapértelmezett prioritással, az ikonokat pedig későbbi prioritással, például 20-szal.
Keverhetem ugyanabban a kollekcióban a content és file_path ikonokat?
Igen. Minden wp_register_icon() hívás önálló: egy-két ikonnál használhatod a content paramétert, a többinél pedig a file_path megoldást. A WordPress a regisztráció után azonosan kezeli őket.
Használhatók az egyedi ikonok blokkikonként a register_block_type() függvényben?
Igen. Add át a regisztrált ikon teljes nevét – például 'myplugin/star' – a register_block_type() icon kulcsának. A blokkbeszúró Dashicon helyett az egyedi SVG-t mutatja. JavaScriptből regisztrált és csak PHP-s blokkokkal is működik.
A wp_get_icon() HTML-t vagy sztringet ad vissza?
SVG-sztringet ad vissza, ezért közvetlenül kiírhatod echo-val, vagy saját HTML-be burkolhatod. A második, $args tömbben megadhatod a size, class, label – az aria-label értékéhez – és title opciót.
Milyen SVG-attribútumokat távolítsak el regisztráció előtt?
Töröld a rögzített fill és stroke színeket, a gyökér <svg> elem width és height attribútumát, valamint minden <style> blokkot és scriptet. A viewBox-ot és a szerkezeti attribútumokat tartsd meg, a színekhez pedig currentColor értéket használj.
Bővítmény helyett regisztrálhatok ikonokat sablonból?
Igen. Ugyanaz a wp_register_icon() hívás működik a sablon functions.php fájljából is; fájlútvonalhoz a get_stylesheet_directory() függvényt használd. Vedd figyelembe, hogy sablonváltáskor a sablonból regisztrált ikonok eltűnnek.
Mi történik, ha két kollekcióban ugyanaz az ikon neve?
Nem ütköznek. A kollekció névteret biztosít, ezért a myplugin/heart és egy másik kollekció heart ikonja együtt létezhet. Az egyediséget mindig a kollekcióprefixet is tartalmazó teljes név adja.
A WordPress megtisztítja az SVG-ket regisztrációkor?
Nem. A WordPress nem alakítja át az SVG-t: a megadott sztringet vagy a hivatkozott fájl pontos tartalmát szolgálja ki. Mielőtt kiadod a bővítményt, tisztítsd meg az SVG-ket, és távolítsd el belőlük a scripteket, külső hivatkozásokat és minden felesleges tartalmat.
Következő lépés
Kezdd a kollekció regisztrálásával, majd adj hozzá egyetlen currentColor-t használó SVG-ikont. Ha a core/icon választóban már megjelenik, válts a glob() alapú mappafeldolgozásra, és kösd ugyanazt az ikonnevet a blokkjaid icon beállításához vagy a PHP-sablonodhoz.
A két regisztrációs mód, a tömeges fájlkezelés és a wp_get_icon() együtt JavaScript build folyamat nélkül ad egységes, márkázott ikonrendszert a szerkesztőhöz, a frontendhez és a REST réteghez.
Nagy Eszter
Frontend fejlesztő, a CSS és a reszponzív design megszállottja. Hiszek abban, hogy a szép kód szép weboldalakat eredményez. Tailwind CSS evangelista.
Összes bejegyzés
