Kā izmantot pielāgotas SVG ikonas WordPress 7.1
Pielāgota SVG ikona līdz šim blokredaktorā bieži prasīja JavaScript, būvēšanas soli vai nepilnīgu apiešanas risinājumu. WordPress 7.1 ievieš publisku API, ar kuru spraudnis var reģistrēt SVG ikonas PHP pusē un bez JavaScript būvēšanas soļa padarīt tās pieejamas redaktorā, veidnēs un REST API.
WordPress 7.1 izlaidumu plāno 2026. gada 19. augustā. Izstrādei var izmantot arī 7.1 RC, bet pirms ieviešanas produkcijas vietnē pārbaudi API galīgajā laidienā.
Ko izveidosi un kas vajadzīgs darbam
Izveidosi nelielu spraudni ar ikonu kolekciju myplugin. Tajā reģistrēsi sirdi ar SVG marķējumu pašā PHP failā, kā arī zvaigzni un grāmatzīmi no .svg failiem. Pēc tam izmantosi mapes masveida reģistrāciju, īskodu, PHP veidnes un pielāgotu bloka ikonu.
Sagatavo WordPress 7.1 vai jaunāku versiju, dažus SVG failus, lokālo vidi – piemēram, LocalWP, WordPress Studio vai wp-env – un PHP pamatzināšanas. Ikonu kolekcija ir nosaukta ikonu grupa; tās nosaukums veido katras ikonas prefiksu un pasargā no sadursmēm ar WordPress core vai citu spraudņu ikonām.
Trīs API funkcijas un ikonu kolekcijas
Pielāgoto ikonu API veido trīs funkcijas. wp_register_icon_collection( $name, $args ) reģistrē nosauktu kolekciju, wp_register_icon( $name, $args ) pievieno vienu ikonu, savukārt wp_get_icon( $name, $args ) PHP pusē atgriež ikonas SVG virkni.
Ikonai vienmēr jāpieder kolekcijai. Tāpēc core/plus un myplugin/plus ir divas atšķirīgas ikonas: kolekcijas prefikss ir daļa no pilnā ikonas nosaukuma.
Reģistrējot ikonu, SVG vari nodot vienā no diviem veidiem: ar content, kur PHP virknē ieraksti SVG marķējumu, vai ar file_path, kur norādi absolūtu ceļu uz .svg failu. Vienai ikonai lieto tikai vienu no šiem argumentiem. content ir ērts vienai vai divām ikonām, bet file_path labāk der plašai ikonu bibliotēkai.
1. Izveido spraudni un reģistrē kolekciju
Vispirms izveido spraudņa mapi wp-content/plugins/myplugin/ ar galveno PHP failu un ikonu apakšmapi. Kolekcijai jābūt reģistrētai, pirms tai pievieno ikonas. Ja mēģināsi pievienot ikonu neesošai kolekcijai, tā klusējot neparādīsies atlasītājā.
myplugin/
├── myplugin.php
└── icons/
├── star.svg
└── bookmark.svgFailā myplugin.php ievieto spraudņa galveni, aizsardzību pret tiešu izsaukumu un kolekcijas reģistrāciju. init hook noklusējuma prioritāte ir 10, tādēļ kolekcija būs gatava ikonu reģistrēšanai ar lielāku prioritāti.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Reģistrē pielāgotas SVG ikonas 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' ),
)
);
}Aktivizē spraudni sadaļā Spraudņi → Instalētie spraudņi. Tukša kolekcija redaktorā vēl nebūs redzama, jo tā sāk parādīties tikai tad, kad tai ir vismaz viena ikona.
2. Reģistrē ikonas ar content un file_path
Sirds ikona tieši PHP kodā
Nelielam ikonu skaitam SVG vari turēt pašā PHP failā. Ikonu nosaukumā lieto shēmu kolekcija/ikonas-slug, bet label parādās ikonu atlasītājā.
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>',
)
);
}Šis hook darbojas ar prioritāti 20, tātad pēc kolekcijas reģistrācijas. stroke="currentColor" liek ikonai pārmantot apkārtējā teksta krāsu, nevis izmantot cieti ierakstītu toni.
Zvaigzne un grāmatzīme no failiem
Ja SVG glabā diskā, norādi file_path. Saglabā abus failus spraudņa mapē icons/.
<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',
)
);
}WordPress nolasa SVG failu pēc pieprasījuma. Atver redaktorā core/icon bloku: atlasītājā parādīsies kolekcijas sadaļa MyPlugin ar Heart, Star un Bookmark ikonām. Ja ikonas nav, pārbaudi reģistrācijas secību – kolekcijai jāreģistrējas agrāk nekā ikonām.
Zemāk redzams, kā pielāgotā kolekcija tiek pievienota core/icon bloka atlasītājam.
core/icon bloka atlasītājā. — Forrás: Avota materiāls3. Reģistrē visu SVG mapi automātiski
Atsevišķi wp_register_icon() izsaukumi kļūst neērti, kad bibliotēkā ir desmitiem ikonu. Aizstāj iepriekšējo myplugin_register_file_icons() funkciju ar masveida variantu: PHP katrā pieprasījumā atradīs visus mapes SVG failus un reģistrēs tos.
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' ) atgriež visus mapē esošos .svg failus. basename( $file_path, '.svg' ) no advanced-button.svg iegūst advanced-button, bet ucwords( str_replace( '-', ' ', $slug ) ) izveido atlasītājam lasāmu nosaukumu “Advanced Button”. Cikls katru failu reģistrē kolekcijā myplugin/.
Pievieno jaunu SVG mapē icons/, atsvaidzini redaktoru, un ikona būs atlasītājā bez PHP koda izmaiņām. Šis paņēmiens der gan trim, gan simtiem ikonu; SVG, kas iepriekš reģistrēts ar content, piemēram, sirds, paliek atsevišķi reģistrēts.
4. Lieto reģistrētās ikonas trīs vietās
Blokā core/icon un REST API
core/icon bloks automātiski nolasa visas reģistrētās kolekcijas. Redaktors var ievietot MyPlugin ikonu, un tā bez papildu koda parādīsies vietnes priekšpusē.
Ikonas ir pieejamas arī REST endpoint /wp-json/wp/v2/icons, bet kolekcijas – companion endpoint /wp-json/wp/v2/icon-collections. Tādēļ ārējs rīks, kas lasa WordPress datus, tostarp AI aģents, var tās atrast.
PHP veidnēs ar wp_get_icon()
wp_get_icon() atgriež SVG kā virkni, tādēļ vienkāršā gadījumā to uzreiz izvada ar echo.
echo wp_get_icon( 'myplugin/heart' );Otrajā argumentā vari noteikt izmēru, CSS klasi un pieejamības etiķeti.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);size SVG elementam piešķir width un height pikseļos. class pievieno SVG elementam CSS klasi, savukārt label ekrānlasītājiem iestata aria-label. Funkcija pieņem arī title.
Īskodā satura redaktoram
Šis īskods ļauj ievietot jebkuru reģistrēto ikonu ierakstā, lapā vai logdaļā. Tas validē ikonas nosaukumu, izmēru un CSS klasi, bet neeksistējošai ikonai atgriež tukšu virkni.
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"]Ikona parādās līdzās tekstam ar size atribūtā norādīto izmēru. Tā kā SVG izmanto currentColor, tā automātiski pārņem apkārtējā teksta krāsu.
Bloka ikonā ar register_block_type()
Pielāgota ikona var aizstāt Dashicon jebkurā bloka reģistrācijā. Tā darbojas gan JavaScript reģistrētos blokos, gan blokos, kurus reģistrē tikai PHP pusē.
'icon' => 'warning', // Dashicon'icon' => 'myplugin/star', // Reģistrēta pielāgota SVG ikonaBloku ievietotājs tad parāda tava zīmola SVG, nevis vispārīgu Dashicon. Tā pati reģistrācija apkalpo redaktoru, PHP un REST API – ikonu reģistrē vienreiz, bet izmanto vairākos kontekstos.
5. Pielāgo ikonu izskatu ar CSS
Liec ikonai mantot teksta krāsu
SVG vissvarīgākais paņēmiens ir stroke="currentColor" vai fill="currentColor", nevis fiksēta krāsa. Ikona sarkanā tekstā kļūs sarkana, tumšā tēmā – tumša, bet saitē pārņems saites krāsu un vizuāli iederēsies tēmā.
<!-- Nepareizi: ikona vienmēr būs sarkana -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>Piespied konkrētu krāsu, ja tā nepieciešama
Zīmola zīmei vai statusa indikatoram dažreiz vajag nemainīgu krāsu. Ja SVG izmanto currentColor, CSS color vērtība no SVG klases pāriet uz ikonas stroke vai fill, arī tad, ja apkārtējais teksts ir citā krāsā.
.featured-icon {
color: #f59e0b; /* Dzintara tonis neatkarīgi no teksta krāsas */
}Izmērs un hover stāvoklis
Īskodā vai wp_get_icon() izvadītai ikonai precīzu pikseļu izmēru nosaka size arguments. Ja izmēru vēlies vadīt ar CSS vai hover stāvoklī animēt ikonu, stilē SVG caur aptverošo elementu.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}Lieto size vienreizējiem gadījumiem, kuros vajag konkrētu izmēru un CSS nav jāraksta. Lieto CSS klases – caur class argumentu vai aptverošo elementu – ikonām, kas atkārtojas daudzviet, kurām jāizskatās vienādi vai kuru stils atkarīgs no stāvokļa (hover, focus, active) un konteksta, piemēram, saites vai virsraksta.
Blokredaktorā class arguments no wp_get_icon() nav pieejams, tādēļ vispārīgi CSS paņēmieni ir īpaši noderīgi ikonām, kas nonāk core/icon blokā.
6. Noņem ikonas un kolekcijas
Noņem vienu ikonu
Izstrādes laikā vai spraudņa atjauninājumā vari atcelt vienas ikonas reģistrāciju. Nākamajā pieprasījumā tā pazudīs no atlasītāja.
wp_unregister_icon( 'myplugin/bookmark' );Ja ierakstā jau ir ievietots šādas ikonas core/icon bloks, tas kļūs tukšs. WordPress nepārraksta ieraksta saturu, kad ikonu atceļ.
Noņem visu kolekciju, deaktivizējot spraudni
Spraudņa deaktivizācijā atcel visas tā ikonas ar vienu kolekcijas izsaukumu. Nav jāveido cikls katrai ikonai atsevišķi.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Biežākie jautājumi
Vai kolekcija jāreģistrē pirms ikonām?
Jā. Ikonai jāpieder jau esošai kolekcijai, pretējā gadījumā tā klusējot nebūs redzama atlasītājā. Kolekciju reģistrē init hook noklusējuma prioritātē, bet ikonas – vēlāk, piemēram, ar prioritāti 20.
Vai vienā kolekcijā drīkst kombinēt content un file_path?
Jā. Katrs wp_register_icon() izsaukums ir neatkarīgs. Vienai vai divām ikonām izmanto content, pārējām file_path; pēc reģistrācijas WordPress abas apstrādā vienādi.
Vai pielāgotas ikonas darbojas register_block_type() bloka ikonā?
Jā. Nodod reģistrētās ikonas pilno nosaukumu, piemēram, 'myplugin/star', register_block_type() masīva atslēgai icon. Bloku ievietotājs tad Dashicon vietā rāda pielāgoto SVG; tas darbojas gan JavaScript blokiem, gan tikai PHP blokiem.
Vai wp_get_icon() atgriež HTML vai virkni?
wp_get_icon() atgriež SVG kā virkni. Vari to uzreiz izvadīt ar echo vai ietvert savā HTML marķējumā. Otrais $args masīvs pieņem size, class, label atribūtam aria-label un title.
Kurus SVG atribūtus noņemt pirms ikonas reģistrācijas?
Noņem fiksētas fill un stroke krāsas, saknes <svg> elementa width un height atribūtus, kā arī visus <style> blokus un skriptus. Atstāj viewBox un strukturālos atribūtus, bet krāsai izmanto currentColor.
Vai ikonas var reģistrēt tēmā, nevis spraudnī?
Jā. Tēmas functions.php var lietot to pašu wp_register_icon() izsaukumu un faila ceļam izmantot get_stylesheet_directory(). Jārēķinās, ka, nomainot tēmu, šādi reģistrētās ikonas pazudīs.
Kas notiek, ja divās kolekcijās ir ikona ar vienādu nosaukumu?
Konflikta nav, jo ikonu nosaukumiem ir kolekcijas nosaukumtelpa. myplugin/heart un cits-spraudnis/heart var pastāvēt līdzās; unikāls ir pilnais nosaukums ar prefiksu.
Vai WordPress sanitizē SVG reģistrācijas laikā?
Nē. WordPress reģistrējot nemaina SVG saturu: tiek padota tieši tava virkne vai norādītā faila saturs. Pirms publicēšanas pats sanitizē SVG un izņem skriptus, ārējās atsauces un visu lieko.
Ko darīt tālāk
Sāc ar kolekciju, reģistrē ikonas pēc tās un izvēlies content vai file_path atbilstoši bibliotēkas apjomam. Ja ikonu ir vairāk par dažām, izmanto glob() mapes reģistrācijai; veidnēs izmanto wp_get_icon() ar size, class un pieejamības label, bet SVG failos saglabā viewBox un currentColor.
Šis reģistrē-vienreiz, izmanto-visur modelis savieno core/icon bloku, PHP, REST API un bloku ikonas vienā reģistrā. Kopā ar PHP reģistrētiem blokiem tas ļauj spraudnim veidot pilnīgi zīmolotu redaktora pieredzi bez būvēšanas soļa.
Pilns piemēra spraudnis ar SVG paraugiem, README un masveida reģistrācijas variantu ir pieejams GitHub.
Atsauces / Avoti
Līga Bērziņa
Latvijas komandas galvenā redaktore, IT projektu vadītāja un digitālās transformācijas konsultante. Agile pāreja un digitālā stratēģija ir mana specialitāte.
Visas publikācijas
