SVG-ikone po meri v WordPressu 7.1: vodič za razvijalce
WordPress 7.1 uvaja javni API za SVG-ikone po meri. Brez JavaScripta, build koraka ali začasnih rešitev lahko vtičnik registrira zbirko ikon, jih prikaže v izbirniku bloka core/icon, izriše v PHP in ponudi prek REST API-ja.
V tem vodiču boš pripravil majhen vtičnik z eno zbirko, tremi ikonami in samodejno registracijo vseh datotek SVG v mapi. Iste ikone boš nato uporabil v urejevalniku, predlogah PHP, shortcodeu in kot ikone lastnih blokov.
Kaj potrebuješ
Za razvoj potrebuješ WordPress 7.1 ali novejši; za razvoj zadošča tudi izdaja 7.1 RC. Pripravi nekaj datotek SVG, lokalno razvojno okolje, kot so LocalWP, WordPress Studio ali wp-env, ter osnovno znanje PHP.
Kako deluje API za ikone
API sestavljajo tri funkcije in koncept zbirk. Zbirka loči imena ikon med seboj: zato se core/plus razlikuje od myplugin/plus, tudi če imata ikoni enak zaključni del imena. Tako se ikone vtičnikov ne spopadajo z ikonami WordPress core ali drugih vtičnikov.
wp_register_icon_collection( $name, $args )registrira imenovano zbirko ikon.wp_register_icon( $name, $args )registrira posamezno ikono.wp_get_icon( $name, $args )v PHP izriše SVG in vrne niz SVG.
Ob registraciji posamezne ikone SVG podaš na enega od dveh načinov. Argument content vsebuje SVG-markup kot niz neposredno v PHP, argument file_path pa absolutno pot do datoteke .svg na disku. Za posamezno ikono uporabi le enega; content je primeren za eno ali dve ikoni, file_path pa lažje vzdržuje večjo mapo ikon.
1. Ustvari vtičnik in najprej registriraj zbirko
V mapi wp-content/plugins/ ustvari naslednjo strukturo. Zbirko moraš registrirati pred ikonami; če poskusiš registrirati ikono v zbirki, ki še ne obstaja, se ikona v izbirniku tiho ne prikaže.
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgV datoteko myplugin-custom-icons.php dodaj glavo vtičnika in registracijo zbirke. Ime zbirke myplugin tvori predpono vseh njenih ikon, na primer myplugin/heart in myplugin/star; label pa določa naslov razdelka v izbirniku ikon.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registers custom SVG icons for WordPress 7.1+.
* Version: 1.0.0
* Author: MyPlugin
* Requires at least: 7.1
* Requires PHP: 7.4
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
define( 'MYPLUGIN_ICONS_PATH', plugin_dir_path( __FILE__ ) );
/**
* Registrira zbirko ikon pred posameznimi ikonami.
*/
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Vtičnik aktiviraj v meniju Vtičniki → Nameščeni vtičniki. Zbirka se še ne pokaže, saj brez ikon nima česa izrisati.
2. Registriraj ikone z content in file_path
Ikona v PHP z argumentom content
Pri eni ali dveh ikonah lahko SVG zapišeš neposredno v datoteko PHP. Naslednja ikona srca se na init prijavi s prioriteto 20, medtem ko se zbirka prijavi s privzeto prioriteto 10; zato zbirka obstaja, še preden se ji ikona pridruži.
/**
* Registrira ikono z vdelano vsebino SVG.
*/
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>',
)
);
}Ime myplugin/heart sledi vzorcu zbirka/slug-ikone. Oznaka label se pokaže v izbirniku, content pa vsebuje SVG. Atribut stroke="currentColor" omogoči, da ikona samodejno podeduje barvo okoliškega besedila, ne da bi ji določil trdo zapisano barvo.
Ikone iz datotek SVG z argumentom file_path
Za ikone na disku dodaj v mapo icons/ spodnji datoteki. Obe uporabljata viewBox, poteze in currentColor, zato ju lahko tema barvno prilagodi.
<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>Nato obe datoteki registriraj iz PHP. Funkcija in zbirka ostaneta enaki, content le zamenja file_path; WordPress datoteko prebere, ko jo potrebuje.
/**
* Registrira ikone iz datotek 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',
)
);
}Odpri blok core/icon v urejevalniku. Izbirnik zdaj prikaže razdelek MyPlugin z ikonami Heart, Star in Bookmark. Če katere ne vidiš, najprej preveri vrstni red registracije: zbirko registriraj s privzeto prioriteto, ikone pa pozneje, na primer s prioriteto 20.
core/icon. — Forrás: WPVibes3. Samodejno registriraj celo mapo ikon
Ročna registracija tridesetih ikon ni vzdržna. Posamezno funkcijo myplugin_register_file_icons() zamenjaj z naslednjim vzorcem: PHP ob vsakem zahtevku prebere vse datoteke SVG v mapi in vsako samodejno registrira.
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' )vrne vse datoteke s končnico.svgv izbrani mapi.basename( $file_path, '.svg' )iz imena odstrani pot in končnico;advanced-button.svgtako spremeni vadvanced-button.ucwords( str_replace( '-', ' ', $slug ) )iz sluga pripravi berljivo oznako za izbirnik;advanced-buttonspremeni vAdvanced Button.- Zanka vsako ikono registrira v zbirki
myplugin/.
Novo datoteko SVG samo dodaj v mapo icons/ in osveži urejevalnik; dodatne spremembe kode ne potrebuješ. Vzorec enako obvlada nekaj ikon ali več sto ikon, pri tem pa lahko ikona srca še vedno ostane registrirana neposredno v PHP.
4. Uporabi registrirane ikone na treh mestih
V bloku core/icon in prek REST API-ja
Izbirnik bloka core/icon samodejno prikaže vse registrirane zbirke. Uporabnik vstavi blok, izbere ikono in WordPress jo izriše tudi na javnem delu spletnega mesta, brez dodatne kode.
Ikone so na voljo tudi na endpointu REST API-ja /wp-json/wp/v2/icons, zbirke pa na spremljevalnem endpointu /wp-json/wp/v2/icon-collections. Zunanja orodja, ki berejo podatke WordPressa, lahko zato odkrijejo obe vrsti podatkov.
V predlogah PHP s wp_get_icon()
Funkcija wp_get_icon() vrne SVG kot niz, zato ga lahko neposredno izpišeš. Najosnovnejši klic izriše ikono srca.
echo wp_get_icon( 'myplugin/heart' );V dejanski predlogi drugemu argumentu dodaj velikost, razred CSS in dostopno oznako. size nastavi atributa width in height SVG-ja v slikovnih pikah, class doda razred elementu SVG, label pa nastavi aria-label za bralnike zaslona.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);Shortcode za vsebino objav
Naslednji shortcode [myplugin_icon] omogoči vstavljanje katere koli registrirane ikone v objavo, stran ali gradnik. Pred izrisom očisti ime ikone, velikost, razred CSS in besedilo; če ikona ne obstaja, vrne prazen niz.
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 se pokaže ob besedilu v velikosti atributa size. Ker SVG uporablja currentColor, samodejno prevzame barvo okoliškega besedila.
Kot ikona lastnega bloka
Pri register_block_type() lahko generični Dashicon zamenjaš z imenom registrirane ikone. Vstavljalnik blokov nato pokaže tvojo SVG-ikono; pristop deluje za bloke, registrirane z JavaScriptom, in za bloke, registrirane samo s PHP.
'icon' => 'warning', // Uporabi Dashicon'icon' => 'myplugin/star', // Uporabi registrirano SVG-ikono po meri5. Oblikuj ikone s CSS
Registrirane ikone so privzeto videti skladne z WordPressom, vendar se morajo pri dejanski rabi prilagoditi okolici: podedovati barvo besedila, slediti velikosti pisave in se odzvati na prehod miške. Argument class pri wp_get_icon() doda neposreden CSS-hook na SVG, pravila CSS pa lahko ciljajo tudi ovojni element, kadar ikono izbira blokovni urejevalnik in argument class ni na voljo.
Naj SVG podeduje barvo z currentColor
Pri oblikovanju SVG uporabi stroke="currentColor" ali fill="currentColor" namesto trdo zapisane barve. Ikona ob rdečem besedilu postane rdeča, v temni temi temna, v povezavi pa prevzame barvo povezave; SVG se zato obnaša kot besedilo.
<!-- Ne uporabljaj: ikona bo vedno rdeča -->
<svg viewBox="0 0 24 24"
stroke="#dc2626"
stroke-width="2">
<path d="..."/>
</svg>Ikone brez trdo zapisanih barv se lažje vključijo v katero koli temo. Ikona s fiksno barvo se lahko v delu tem vizualno spopade z okolico.
Kadar potrebuješ fiksno barvo
Blagovna oznaka ali indikator stanja včasih potrebuje določeno barvo ne glede na okolico. Ker SVG uporablja currentColor, lastnost color na SVG-ju prek razreda prodre v njegovo potezo ali polnilo.
.featured-icon {
color: #f59e0b; /* Jantarna barva ne glede na barvo besedila */
}Velikost in stanje ob prehodu miške
Pri ikonah iz shortcodea ali wp_get_icon() natančno velikost v slikovnih pikah določi argument size. Če želiš velikost upravljati s CSS ali dodati odziv ob prehodu miške, uporabi pravila na SVG-ju znotraj ovoja.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Argument
sizevwp_get_icon()uporabi pri enkratnih primerih, ko potrebuješ natančno velikost in se CSS ne izplača. - Razrede CSS, podane z argumentom
classali na ovojnem elementu, uporabi, ko se ikona pojavlja na več mestih, mora ostati slogovno enotna ali pa je videz odvisen od stanja, kot sohover,focusinactive, oziroma od konteksta, na primer povezave ali naslova. - Pri shortcodeu lahko manjše lokalne prilagoditve opraviš z atributom
size, za enoten videz po spletnem mestu pa ciljaš.myplugin-icon-inline svgs CSS.
6. Odstrani ikone in zbirke
Odstrani posamezno ikono
Med razvojem ali ob posodobitvi vtičnika lahko odstraniš posamezno ikono. Ob naslednjem zahtevku izgine iz izbirnika, vendar obstoječi blok core/icon, ki jo že uporablja v vsebini, izriše prazno mesto; WordPress vsebine objave ne prepiše.
wp_unregister_icon( 'myplugin/bookmark' );Ob deaktivaciji odstrani celo zbirko
Ko vtičnik deaktiviraš, se njegove ikone ne smejo več pojavljati v izbirniku. wp_unregister_icon_collection() odstrani zbirko in vse ikone v njej, zato ti ni treba iterirati čez posamezne ikone.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Pogosta vprašanja
Ali mora zbirka obstajati pred registracijo ikon?
Da. Ikone morajo pripadati obstoječi zbirki, sicer se tiho ne prikažejo v izbirniku. Zbirko registriraj na hooku init s privzeto prioriteto, ikone pa z višjo prioriteto, na primer 20.
Ali lahko ena zbirka združuje content in file_path?
Da. Vsak klic wp_register_icon() je neodvisen. Za eno ali dve ikoni uporabi content, za preostale file_path; WordPress obe vrsti po registraciji obravnava enako.
Ali ikone po meri delujejo kot ikone blokov v register_block_type()?
Da. Ključu icon posreduj polno ime registrirane ikone, na primer 'myplugin/star'. Vstavljalnik blokov bo namesto Dashicona prikazal SVG-ikono po meri, ne glede na to, ali blok registrira JavaScript ali samo PHP.
Ali wp_get_icon() vrne HTML ali niz?
wp_get_icon() vrne SVG kot niz. Lahko ga neposredno izpišeš ali oviješ v lasten HTML; drugo polje $args sprejme size, class, label za aria-label in title.
Katere atribute SVG odstrani pred registracijo?
Odstrani trdo zapisane barve fill in stroke, atributa width in height na korenskem elementu <svg>, bloke <style> ter skripte. Ohrani viewBox in strukturne atribute, za sklic na barvo pa uporabi currentColor.
Ali lahko ikone registrira tema namesto vtičnika?
Da. Isti klic wp_register_icon() lahko uporabiš v datoteki functions.php teme in za pot do datotek uporabiš get_stylesheet_directory(). Upoštevaj, da ikone, registrirane v temi, izginejo, ko uporabnik zamenja temo.
Kaj se zgodi, če imata zbirki ikono z enakim imenom?
Zbirke uporabljajo imenski prostor, zato lahko myplugin/heart in otherplugin/heart obstajata hkrati brez konflikta. Enoličnost določa celotno ime skupaj s predpono zbirke.
Ali WordPress ob registraciji očisti SVG?
Ne. WordPress vsebine SVG ob registraciji ne spremeni; ponudi natanko niz, ki ga podaš, oziroma vsebino datoteke, na katero pokažeš. Pred distribucijo SVG očisti sam: odstrani skripte, zunanje reference in vse nepotrebne dele.
Kaj naredi zdaj
API temelji na vzorcu »registriraj enkrat, uporabi povsod«: isti register bere blok core/icon, funkcija wp_get_icon() v PHP in REST API. Začni z zbirko, za večjo knjižnico uporabi glob() nad mapo SVG, v ikonah pa ohrani viewBox in uporabi currentColor. Tako lahko vtičnik brez build koraka registrira bloke, njihove ikone in enotno izkušnjo urejevalnika.
Maja Novak
Urednica slovenskega tima, zagovornica zelenega kodiranja in trajnostnega spletnega razvoja. Energetsko učinkovite spletne strani in ogljično ozaveščen razvoj sta moja cilja.
Vse objave
