WordPress 7.1: kaip registruoti ir naudoti savo SVG piktogramas
Iki šiol nuosavą SVG piktogramą blokų redaktoriuje dažniausiai tekdavo prijungti per JavaScript, build procesą arba nepatikimą apėjimo būdą. WordPress 7.1 įveda viešą API, su kuriuo piktogramas galėsite registruoti vien PHP įskiepyje: jos atsiras core/icon parinkiklyje, veiks PHP šablonuose ir bus pasiekiamos per REST API.
Numatytas WordPress 7.1 leidimas – 2026 m. rugpjūčio 19 d. Toliau pateiktas kodas skirtas šiai versijai; kuriant jau galima naudoti 7.1 RC. Sukursime įskiepį su myplugin kolekcija, viena įterpta SVG piktograma, dviem piktogramomis iš failų, masine katalogo registracija ir shortcode.
Ko reikės ir kaip veikia API
Dirbkite su WordPress 7.1 ar naujesne versija, turėkite kelis SVG failus, vietinę aplinką, pavyzdžiui, LocalWP, WordPress Studio arba wp-env, ir bazines PHP žinias. API sudaro trys funkcijos bei kolekcijų principas.
wp_register_icon_collection( $name, $args )užregistruoja vardinę piktogramų grupę.wp_register_icon( $name, $args )užregistruoja vieną piktogramą.wp_get_icon( $name, $args )PHP pusėje sugeneruoja piktogramos SVG ir grąžina jį kaip eilutę.
Kiekviena piktograma priklauso kolekcijai. Kolekcijos vardas tampa piktogramos prefiksu, todėl core/plus ir myplugin/plus nesikerta nei tarpusavyje, nei su kito įskiepio vardais.
Registruodami piktogramą SVG pateikite vienu iš dviejų būdų: content parametre įrašykite SVG žymėjimą kaip PHP eilutę arba file_path parametre nurodykite absoliutų kelią iki .svg failo. Vienai piktogramai nenaudokite abiejų parametrų. content patogu vienai ar dviem piktogramoms, o file_path geriau tinka didesniam katalogui.
1. Sukurkite įskiepio struktūrą ir kolekciją
Pirmiausia užregistruokite kolekciją. Jei mėginsite pridėti piktogramą prie dar neegzistuojančios kolekcijos, ji tyliai nepateks į parinkiklį.
Kataloge wp-content/plugins/ sukurkite tokią struktūrą:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgFaile myplugin-custom-icons.php įrašykite įskiepio antraštę, apsaugą nuo tiesioginio kvietimo, kelią iki įskiepio katalogo ir kolekcijos registraciją.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registers 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' ),
)
);
}Vardas myplugin taps visų šios kolekcijos piktogramų prefiksu: myplugin/heart, myplugin/star ir panašiai. label reikšmę redaktorius rodys kaip kolekcijos skyriaus antraštę. Įjunkite įskiepį per Įskiepiai → Įdiegti įskiepiai; tuščia kolekcija dar nieko nerodys.
2. Užregistruokite SVG eilute ir iš failų
Širdies piktogramą įrašykite tiesiai į PHP
Kai turite tik kelias piktogramas, SVG galite laikyti PHP faile. Kolekcija registruojama su numatytuoju init prioritetu 10, todėl piktogramą pridėkite vėliau – šiame pavyzdyje su prioritetu 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>',
)
);
}Pavadinimas laikosi formato kolekcija/piktogramos-slug, label bus matoma parinkiklyje, o content saugo SVG. Atributas stroke="currentColor" leidžia piktogramai paveldėti aplinkinio teksto spalvą, todėl SVG nereikia fiksuoti spalvos.
Žvaigždę ir žymę įkelkite iš .svg failų
Daugiau piktogramų patogiau laikyti diske. Į icons/ katalogą įrašykite šiuos du failus.
<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',
)
);
}Čia pasikeičia tik content į file_path; WordPress SVG failą perskaito pagal poreikį. Atidarykite redaktoriuje core/icon bloką: parinkiklyje turėtų atsirasti MyPlugin skyrius su Heart, Star ir Bookmark piktogramomis.
core/icon bloko parinkiklyje. — Forrás: Šaltinio iliustracija3. Registruokite visą SVG katalogą
Rašyti atskirą wp_register_icon() kvietimą kelioms dešimtims failų neverta. Vietoj ankstesnės myplugin_register_file_icons() funkcijos naudokite masinę versiją, kuri per kiekvieną užklausą suranda visus katalogo SVG failus.
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' ) grąžina kiekvieną katalogo .svg failą. basename( $file_path, '.svg' ) iš advanced-button.svg sukuria advanced-button, o ucwords( str_replace( '-', ' ', $slug ) ) paverčia jį parinkikliui suprantama etikete „Advanced Button“. Ciklas kiekvieną rezultatą priskiria myplugin/ kolekcijai.
Naują SVG tiesiog įkelkite į icons/ katalogą ir atnaujinkite redaktorių – kodo keisti nereikės. Toks būdas vienodai tinka kelioms piktogramoms ir keliems šimtams; įterptą širdies SVG galite palikti atskirai, o žvaigždę, žymę bei visus kitus failus registruoti ciklu.
4. Naudokite tas pačias piktogramas trijose vietose
Blokų redaktoriuje ir REST API
core/icon blokas automatiškai perskaito visas užregistruotas kolekcijas. Redaktoriaus naudotojas įterpia bloką, pasirenka piktogramą, o ji rodoma ir svetainės lankytojams – papildomo kodo nereikia.
Piktogramas taip pat pateikia REST endpoint /wp-json/wp/v2/icons, o kolekcijas – /wp-json/wp/v2/icon-collections. Todėl WordPress duomenis skaitantys išoriniai įrankiai, įskaitant AI agentus, gali jas atrasti per tą patį registrą.
PHP šablone su wp_get_icon()
wp_get_icon() grąžina SVG eilutę, todėl paprasčiausiu atveju ją išveskite su echo. Antrasis argumentas leidžia nustatyti dydį, CSS klasę ir prieinamą etiketę.
echo wp_get_icon( 'myplugin/heart' );
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);size SVG elementui nustato width ir height pikseliais. class prideda CSS klasę, o label sukuria ekrano skaitytuvams skirtą aria-label; funkcija taip pat priima title.
Turinyje su shortcode
Šis shortcode leidžia įraše, puslapyje ar valdiklyje įdėti bet kurią užregistruotą piktogramą šalia teksto. Vardo raktą, dydį ir CSS klasę jis išvalo prieš perduodamas API.
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"]Piktograma bus rodoma šalia teksto ir naudos size atributo dydį. Kadangi SVG remiasi currentColor, ji automatiškai perims aplinkinio teksto spalvą.
Bloko piktogramoje
Registruota SVG gali pakeisti numatytą Dashicon bet kurio bloko register_block_type() apraše. Vietoj bendrinės reikšmės nurodykite pilną registruotos piktogramos vardą.
'icon' => 'warning', // Dashicon
'icon' => 'myplugin/star', // Užregistruota pasirinktinė SVGBlokų įterpimo lange tada matysite savo SVG, o ne bendrinę Dashicon piktogramą. Tai veikia tiek JavaScript registruotiems blokams, tiek vien PHP aprašomiems blokams.
5. Pritaikykite išvaizdą su CSS
Kad piktograma natūraliai prisitaikytų prie temos, SVG naudokite stroke="currentColor" arba fill="currentColor", o ne fiksuotą spalvą. Taip ji perims raudono teksto, tamsios temos ar nuorodos spalvą ir elgsis kaip tekstas.
<!-- Netinka: piktograma visada liks raudona -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>Kartais spalvą reikia primesti sąmoningai, pavyzdžiui, prekės ženklo ženklui ar būsenos indikatoriui. Kadangi SVG naudoja currentColor, pakanka klasei, kurią perdavėte per wp_get_icon(), nustatyti color.
.featured-icon {
color: #f59e0b; /* Gintarinė spalva, nepaisant aplinkinio teksto */
}
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}Vienkartiniam tiksliam dydžiui rinkitės size argumentą wp_get_icon() kvietime. CSS klasę pridėkite, kai piktograma kartojasi daugelyje vietų, turi išlikti vienoda arba jos stilius priklauso nuo būsenos – hover, focus, active – ar konteksto, pavyzdžiui, nuorodos arba antraštės. Shortcode atveju smulkius pakeitimus patogu daryti size atributu, o visos svetainės nuoseklumą palaikyti CSS taisykle, skirta .myplugin-icon-inline svg.
6. Pašalinkite piktogramas ir kolekcijas
WordPress 7.1 pateikia atitinkamas šalinimo funkcijas vienai piktogramai ir visai kolekcijai. Kūrimo metu arba pašalindami piktogramą iš įskiepio naujinimo, išregistruokite ją taip:
wp_unregister_icon( 'myplugin/bookmark' );Piktograma iš parinkiklio dings per kitą užklausą. Jau paskelbtuose įrašuose esantis core/icon blokas nebus perrašytas, todėl vietoje neberandamos piktogramos bus rodoma tuštuma.
Išjungiant įskiepį, išregistruokite visą kolekciją. Vienas kvietimas pašalina ir visas jai priklausančias piktogramas, todėl ciklo per kiekvieną vardą nereikia.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Svarbios ribos ir dažni klausimai
Kolekciją visada registruokite anksčiau už piktogramas: init kabliuke palikite numatytą prioritetą kolekcijai, o piktogramoms naudokite didesnį, pavyzdžiui, 20. Jei nesilaikysite šios eilės, piktograma tyliai nepasirodys parinkiklyje.
Vienoje kolekcijoje laisvai maišykite content ir file_path, nes kiekvienas wp_register_icon() kvietimas yra nepriklausomas. Duomenų vardų sritis taip pat leidžia kelioms kolekcijoms turėti tokią pačią piktogramą: myplugin/heart ir anotherplugin/heart sugyvena be konflikto, nes unikalumą lemia visas vardas su kolekcijos prefiksu.
Prieš pateikdami SVG išvalykite patys. WordPress registracijos metu SVG turinio nekeičia: bus pateikta tiksliai ta eilutė arba failo turinys, kurį nurodėte. Pašalinkite skriptus, išorines nuorodas ir visa, kas nebūtina.
Taip pat pašalinkite šakninio <svg> elemento width bei height atributus ir visus <style> blokus, palikite viewBox bei struktūrinius atributus. Išmeskite fiksuotas fill ir stroke spalvas, o spalvai naudokite currentColor.
Piktogramas galima registruoti ir temos functions.php faile; failo kelią tuomet sudarykite su get_stylesheet_directory(). Šis sprendimas turi kainą: pakeitus temą, jos registruotos piktogramos dings.
Ką taikyti savo įskiepyje
Ši API įtvirtina modelį „užregistruokite kartą, naudokite visur“: tą patį registrą skaito core/icon, PHP funkcija wp_get_icon() ir REST API. Toks pats atrandamas modelis taikomas Abilities API, blokų susiejimams ir kitoms pamatinėms WordPress API, todėl įskiepis gali patekti į redaktorių, REST sluoksnį bei įrankius, kurie naudoja WordPress duomenų modelį.
Pradėkite nuo kolekcijos, tada pasirinkite content kelioms įterptoms SVG arba file_path katalogui. Didesniam rinkiniui naudokite glob(), šablonuose perduokite size, class ir prieinamą label, o pačiose SVG palikite viewBox bei currentColor. Taip blokams, jų piktogramoms ir redaktoriaus išvaizdai nereikės JavaScript build žingsnio.
Pilną pavyzdžio įskiepį su SVG failais, README ir masinės registracijos versija rasite GitHub saugykloje.
Hannah Turing
WordPress kūrėja ir techninė rašytoja HelloWP. Padedu kūrėjams kurti geresnes svetaines naudojant šiuolaikinius įrankius, tokius kaip Laravel, Tailwind CSS ir WordPress ekosistema. Aistringai vertinu švarų kodą ir kūrėjo patirtį.
Visi įrašai
