Kohandatud SVG-ikoonid WordPress 7.1-s
WordPress 7.1 toob avaliku API, millega saad registreerida oma SVG-ikoone ilma JavaScripti, build step’i või ebakindlate ajutiste lahendusteta. Sama ikoonide register jõuab plokiredaktorisse, PHP-mallidesse ja REST API-sse, nii et määratled ikooni ühe korra ning kasutad seda mitmes kohas.
Väljalase on kavandatud 19. augustile 2026. Arendust saad alustada ka WordPress 7.1 RC-ga, kuid kontrolli enne tootmiskasutust kood üle lõpliku väljalaskega.
Eeldused
Juhendi näidetes kasutame neutraalset pluginat myplugin. Enne alustamist vajad WordPressi versiooni 7.1 või uuemat, kohalikku arenduskeskkonda (näiteks LocalWP, WordPress Studio või wp-env), SVG-faile ja PHP-algteeadmisi.
Ikoonide API kolm funktsiooni ja kogud
API keskmes on ikoonikogu ehk nimega kogum. Iga ikoon peab kuuluma kogusse ning kogu nimi on ikooni täieliku nime eesliide. Seetõttu saavad core/plus ja myplugin/plus kõrvuti eksisteerida: kogu eraldab pluginate ikoonid WordPressi core’i ja teiste pluginate omadest.
wp_register_icon_collection( $name, $args )registreerib nimega ikoonikogu.wp_register_icon( $name, $args )registreerib ühe ikooni.wp_get_icon( $name, $args )renderdab PHP-s ikooni SVG-na ja tagastab SVG-stringi.
Ikooni registreerides anna SVG kaasa ühel kahest viisist: content sisaldab SVG-märgistust otse PHP-stringina, file_path viitab aga absoluutsele teele kettal asuva .svg-failini. Ära kasuta ühe ikooni juures mõlemat. Kui ikooni on üks või kaks, sobib hästi content; suurema kausta puhul skaleerub paremini file_path.
1. Loo plugin ja registreeri kogu
Loo wp-content/plugins/ kataloogi järgmine struktuur. Kogu tuleb registreerida enne sinna kuuluvate ikoonide lisamist. Kui registreerid ikooni enne kogu olemasolu, ei ilmu see ikoonivalijasse ning WordPress ei anna selle kohta nähtavat veateadet.
myplugin/
├── myplugin.php
└── icons/
├── star.svg
└── bookmark.svgLisa faili myplugin.php plugina päis, turvakontroll, failitee konstant ja kogu registreerimine.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registreerib WordPress 7.1+ jaoks kohandatud SVG-ikoone.
* 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__ ) );
// Registreeri kõigepealt ikoonikogu.
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Kogu nimi myplugin saab kõigi järgmiste ikoonide eesliiteks, näiteks myplugin/heart ja myplugin/star. label kuvatakse plokiredaktori ikoonivalijas kogurühma pealkirjana. Aktiveeri plugin menüüs Pluginad → Paigaldatud pluginad; ainult kogu ei renderda veel midagi, kuni sinna ei kuulu ühtegi ikooni.
2. Registreeri SVG-d otse koodist ja failidest
Südameikoon jääb PHP-faili sisse. Seo funktsioon init hook’iga prioriteedil 20, sest kogu registreerimise vaikimisi prioriteet on 10 ja kogu peab selleks ajaks juba olemas olema.
// Registreeri SVG-märgistus otse PHP-stringina.
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>',
)
);
}Nimi järgib mustrit kogu/ikooni-slug, label ilmub valijasse ja content kannab SVG-märgistust. Atribuut stroke="currentColor" paneb ikooni pärima ümbritseva teksti värvi ega seo seda kindla täite- või joonevärviga.
Pane tähe ja järjehoidja SVG-d kausta icons/. Failipõhiste ikoonide korral loeb WordPress SVG-faili vajaduse korral.
<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>// Registreeri kettal olevad SVG-failid.
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',
)
);
}Ainus sisuline erinevus on content asemel kasutatav file_path; mõlemad ikoonid kuuluvad siiski samasse kogusse. Ava nüüd redaktoris plokk core/icon: valijasse ilmub uus rühm MyPlugin, kus näed ikoone Heart, Star ja Bookmark.
core/icon valijasse oma koguna. — Forrás: AlgallikasLevinud tõrge
Kui ikooni valijas ei ole, kontrolli esmalt hook’ide järjekorda. Registreeri kogu init vaikimisi prioriteedil ja ikoonid sellest hiljem, näiteks prioriteedil 20.
3. Registreeri terve SVG-kaust korraga
Kui haldad päris ikooniteeki, ei tasu kirjutada käsitsi kümneid wp_register_icon() väljakutseid. Asenda eelmine failipõhine funktsioon järgmise variandiga: see leiab igal päringul kataloogist kõik .svg-failid ja registreerib need automaatselt.
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' ) kogub kaustast kõik SVG-failid. basename( $file_path, '.svg' ) eemaldab failinimelt laiendi, mistõttu advanced-button.svg saab slug’iks advanced-button; ucwords( str_replace( '-', ' ', $slug ) ) muudab selle valijas loetavaks sildiks „Advanced Button”. Tsükkel lisab iga faili kogusse myplugin/.
Lisa nüüd uus SVG lihtsalt kausta icons/ ja värskenda redaktorit. Ikoon ilmub valijasse ilma PHP-koodi muutmata. Sama muster sobib nii kolme kui ka kolmesaja ikooni jaoks; inline registreeritud südameikoon jääb sellest eraldi alles.
4. Kasuta registreeritud ikoone kolmes kohas
Plokk core/icon loeb kõik registreeritud kogud automaatselt ning kasutaja saab valida ikooni ja lisada selle lehele ilma lisakoodita. REST API pakub ikoone endpoint’is /wp-json/wp/v2/icons ja kogusid endpoint’is /wp-json/wp/v2/icon-collections, mistõttu saavad neid kasutada ka WordPressi andmeid lugevad välised tööriistad, sealhulgas AI-agendid.
PHP-mallis tagastab wp_get_icon() SVG-stringi, mille saad kohe välja trükkida.
echo wp_get_icon( 'myplugin/heart' );Teises argumendis saad juhtida suurust, CSS-klassi ja ligipääsetavust. size määrab SVG width-i ja height-i pikslites, class lisab SVG-elemendile CSS-klassi ning label määrab ekraanilugejate jaoks aria-label-i.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Esile tõstetud', 'myplugin-icons' ),
)
);Kui soovid, et toimetaja saaks ikooni sisusse lühikoodiga lisada, registreeri näiteks [myplugin_icon]. Kood puhastab ikooni nime, suuruse ja CSS-klassi; tundmatu ikooni puhul tagastab see tühja stringi.
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="Esile tõstetud postitus" size="32"]
[myplugin_icon name="bookmark" text="Salvesta hilisemaks" size="20"]Ikoon asetub teksti kõrvale ja kasutab size atribuudiga määratud suurust. Kuna SVG kasutab currentColor-it, pärib see automaatselt ümbritseva teksti värvi.
Ikooniga saad asendada ka ploki registreerimisel tavapärase Dashiconi. See töötab nii JavaScriptiga registreeritud kui ka ainult PHP-s registreeritud plokkides.
'icon' => 'warning', // Dashicon'icon' => 'myplugin/star', // Registreeritud kohandatud SVG-ikoonPlokkide lisaja näitab nüüd üldise Dashiconi asemel sinu ikooni. Üks registreerimine teenindab seega redaktorit, PHP-malle ja REST API-t; sama „registreeri üks kord, kasuta kõikjal” arhitektuur on kasutusel ka Abilities API-s.
5. Kujunda ikoonid CSS-iga
Ikoonid sobituvad vaikimisi WordPressi välimusega, kuid korralik integratsioon tähendab ka teksti värvi pärimist, fondisuurusega skaleerumist ja hover-olekute toetamist. wp_get_icon() argumendina antud class annab SVG-le CSS-hook’i; plokiredaktoris, kus seda argumenti kasutada ei saa, rakenda stiile ümbrise või muu kontekstivalija kaudu.
Kõige olulisem SVG-muster on stroke="currentColor" või fill="currentColor", mitte fikseeritud värv. Kõva väärtusega stroke="#dc2626" ikoon jääb alati punaseks, kuid currentColor muudab selle punase teksti sees punaseks, tumeda teema sees tumedaks ja lingi sees lingivärvi. Nii käitub SVG nagu tekst ning sobib eri teemadega.
<!-- Väldi: ikoon jääb alati punaseks. -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>
<!-- Eelista: ikoon pärib ümbritseva värvi. -->
<svg viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
<path d="..."/>
</svg>Kui ikoon peab kontekstist sõltumata olema kindlat värvi, näiteks staatuse tähis või brändimärk, määra värv CSS-is. currentColor paneb SVG joone või täite selle väärtuse pärima.
.featured-icon {
color: #f59e0b; /* Merevaigukollane ka tumeda teksti sees. */
}Lühikoodi või wp_get_icon() kaudu lisatud ikooni täpset pikslisuurust juhib mugavalt size. CSS sobib paremini korduvaks kujunduseks ning olekuteks nagu hover, focus ja active.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Kasuta
wp_get_icon()argumendissize, kui vajad üksikus kohas täpset pikslisuurust ega soovi selleks CSS-i kirjutada. - Kasuta CSS-klassi, mille annad
classargumendiga või ümbriselemendile, kui ikoon esineb paljudes kohtades, peab püsima ühtlane või sõltub kujundus olekust ja kontekstist.
6. Eemalda ikoon või kogu
Arenduse ajal või siis, kui plugina uuendus eemaldab ühe ikooni, kasuta wp_unregister_icon().
wp_unregister_icon( 'myplugin/bookmark' );Ikoon kaob valijast järgmisel päringul. Juba postituses oleva core/icon ploki sisu WordPress ümber ei kirjuta ning selline plokk renderdub tühjana.
Plugina deaktiveerimisel eemalda kogu ühe väljakutsega. See eemaldab korraga kõik sellesse kogusse kuuluvad ikoonid, mistõttu ei pea neid eraldi tsüklis deregistreerima.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Korduma kippuvad küsimused
Kas kogu tuleb enne ikoone registreerida?
Jah. Ikoon peab kuuluma olemasolevasse kogusse, vastasel juhul ei ilmu see valijasse. Registreeri kogu init hook’is vaikimisi prioriteediga ning ikoonid suurema prioriteediga, näiteks 20.
Kas samas kogus võib segada content– ja file_path-ikoone?
Jah. Iga wp_register_icon() väljakutse on iseseisev. Kasuta content-i ühe või kahe ikooni jaoks ja file_path-i ülejäänute jaoks; pärast registreerimist kohtleb WordPress neid ühtemoodi.
Kas kohandatud ikoon töötab register_block_type() plokiikoonina?
Jah. Anna icon võtmele registreeritud täisnimi, näiteks 'myplugin/star'. Plokkide lisaja näitab Dashiconi asemel kohandatud SVG-d ning lahendus töötab JavaScripti-plokkide ja ainult PHP-s loodud plokkidega.
Kas wp_get_icon() tagastab HTML-i või stringi?
Funktsioon tagastab SVG stringina. Saad selle otse echo-ga välja kirjutada või paigutada enda HTML-i sisse. Teine argument $args toetab väärtusi size, class, label (aria-label jaoks) ja title.
Millised SVG atribuudid tuleb enne registreerimist eemaldada?
Eemalda fikseeritud fill– ja stroke-värvid, juurelemendi <svg> atribuudid width ja height, samuti kõik <style>-plokid ning skriptid. Hoia alles viewBox ja SVG struktuuri kirjeldavad atribuudid. Värviviidetes kasuta currentColor-it.
Kas ikoone saab registreerida plugina asemel teemast?
Jah. Sama wp_register_icon() väljakutse töötab teema failis functions.php; failitee jaoks kasuta get_stylesheet_directory() funktsiooni. Arvesta siiski, et teemast registreeritud ikoonid kaovad teema vahetamisel.
Mis juhtub, kui kahes kogus on sama ikooni nimi?
Kogud moodustavad nimeruumi. myplugin/heart ja anotherplugin/heart saavad eksisteerida konfliktita, sest unikaalne on kogu eesliidet sisaldav täisnimi.
Kas WordPress puhastab SVG-d registreerimisel?
Ei. WordPress ei muuda registreeritud SVG sisu: väljundisse jõuab täpselt sinu antud string või viidatud faili sisu. Puhasta SVG-d enne levitamist ise ning eemalda skriptid, välised viited ja kõik ebavajalik.
Võta API kasutusele
Kohandatud ikoonide API täidab lünga, mille lahendamiseks pidid pluginaarendajad varem JavaScripti või erilahendusi kasutama. Registreeri esmalt kogu, lisa SVG-d kas stringina või failidest ning kasuta neid plokiredaktoris, PHP-s ja REST API kaudu. glob()-iga kaustapõhine lahendus kasvab vähese koodiga mõnest ikoonist sadadeni.
Järgmise sammuna pane oma plugina SVG-d ühte kataloogi, hoia nende värvid currentColor-i peal ning seo need plokkide icon võtmetega. Nii saad plokid, nende ikoonid ja redaktori brändingu pakkida ilma build step’ita ühtseks tervikuks.
Viited / Allikad
Kadri Sepp
Startup-treener ja tehnoloogiakogukonna ehitaja. Häkatonide korraldamine ja mentorlus on minu kirg. Olen Eesti startup-ökosüsteemi saadik.
Kõik postitused
