Sådan bruger du egne SVG-ikoner i WordPress 7.1
Med WordPress 7.1 får du en offentlig API til egne SVG-ikoner. Du kan registrere ikoner fra et plugin uden JavaScript eller build step og derefter bruge dem i blokeditoren, PHP-skabeloner og WordPress’ REST API.
Her bygger du et lille plugin, der opretter en ikonsamling, registrerer tre ikoner på to forskellige måder og gør dem tilgængelige i core/icon. Du får også et mønster, der automatisk indlæser alle SVG-filer fra en mappe, en shortcode og et eksempel på at bruge et ikon til en custom block.
Forudsætninger
Eksemplerne kræver WordPress 7.1 eller nyere. En 7.1 RC kan bruges under udvikling. Du skal desuden have et lokalt udviklingsmiljø, for eksempel LocalWP, WordPress Studio eller wp-env, grundlæggende PHP-kendskab og nogle SVG-filer.
Sådan er API’et bygget op
API’et består af tre funktioner og ét organiserende princip. En ikonsamling er en navngivet gruppe, som alle ikoner skal høre til. Samlingens navn bliver præfiks i ikonnavnet, så core/plus og myplugin/plus ikke kolliderer med hinanden eller med ikoner fra andre plugins.
wp_register_icon_collection( $name, $args )registrerer en navngivet ikonsamling.wp_register_icon( $name, $args )registrerer ét ikon.wp_get_icon( $name, $args )renderer ikonets SVG i PHP og returnerer SVG’en som en streng.
Når du registrerer et ikon, kan du enten sende SVG-markup direkte i content eller angive den absolutte filsti med file_path. Brug kun den ene metode for hvert ikon. content passer til et eller to ikoner, mens file_path er bedre, når du vedligeholder en større mappe med SVG-filer.
1. Opret plugin og registrér ikonsamlingen
Registrér altid samlingen før dens ikoner. Hvis du prøver at registrere et ikon til en samling, der ikke findes endnu, dukker ikonet ikke op i vælgeren uden en fejlmeddelelse.
Opret denne struktur i wp-content/plugins/:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgOpret derefter pluginfilen. Samlingen registreres på init med standardprioriteten 10, så den findes, før ikonerne kobles på.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Registrerer egne SVG-ikoner til 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__ ) );
/**
* Trin 1: Registrér ikonsamlingen.
*/
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Navnet myplugin bliver præfikset på hvert ikon, for eksempel myplugin/heart og myplugin/star. label er overskriften, som blokeditorens ikonvælger viser. Aktivér pluginet under Plugins → Installerede plugins; samlingen bliver først synlig, når den indeholder ikoner.
2. Registrér ikoner med content og file_path
Du kan bruge begge registreringsformer i samme samling. I dette eksempel ligger hjertet inline i PHP, mens stjerne og bogmærke læses fra selvstændige .svg-filer.
Registrér et inline-ikon
Et inline-SVG er praktisk, når du kun har et par ikoner og vil undgå ekstra filer. Tilføj funktionen herunder til pluginfilen.
/**
* Trin 2: Registrér ikoner med inline SVG-indhold.
*/
add_action( 'init', 'myplugin_register_inline_icons', 20 );
function myplugin_register_inline_icons() {
wp_register_icon(
'myplugin/heart',
array(
'label' => __( 'Hjerte', '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>',
)
);
}Hooket bruger prioritet 20 og kører derfor efter samlingsregistreringen. Navnet følger mønsteret samling/ikon-slug, label vises i vælgeren, og content indeholder SVG-markuppen. Attributten stroke="currentColor" lader ikonet arve tekstfarven i stedet for at låse farven i SVG’en.
Registrér ikoner fra SVG-filer
Gem først følgende filer i pluginets icons/-mappe. Når SVG’er ligger på disken, skal du bruge file_path i stedet for 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">
<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>/**
* Trin 3: Registrér ikoner fra .svg-filer.
*/
add_action( 'init', 'myplugin_register_file_icons', 20 );
function myplugin_register_file_icons() {
wp_register_icon(
'myplugin/star',
array(
'label' => __( 'Stjerne', 'myplugin-icons' ),
'file_path' => MYPLUGIN_ICONS_PATH . 'icons/star.svg',
)
);
wp_register_icon(
'myplugin/bookmark',
array(
'label' => __( 'Bogmærke', 'myplugin-icons' ),
'file_path' => MYPLUGIN_ICONS_PATH . 'icons/bookmark.svg',
)
);
}Her er samlingen og registreringsfunktionen de samme som før; kun content er erstattet af file_path. WordPress læser filen efter behov. Åbn nu core/icon i blokeditoren, og vælg et ikon fra afsnittet MyPlugin.
core/icon-blokkens vælger. — Forrás: WPVibesTjek rækkefølgen
Vises et ikon ikke, har du typisk registreret det før samlingen. Lad samlingen bruge standardprioriteten på init, og registrér ikonerne bagefter, for eksempel ved prioritet 20.
3. Registrér en hel ikonmappe automatisk
En manuel wp_register_icon()-linje pr. ikon er ikke holdbar for et rigtigt ikonbibliotek. Erstat funktionen myplugin_register_file_icons() med denne bulk-variant, der finder og registrerer alle SVG-filer i mappen på hver request.
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' )henter alle.svg-filer i mappen.basename( $file_path, '.svg' )fjerner sti og filendelse, såadvanced-button.svgbliver tiladvanced-button.ucwords( str_replace( '-', ' ', $slug ) )laver sluggen til en læsbar label, såadvanced-buttonbliver tilAdvanced Buttoni vælgeren.- Løkken registrerer hvert ikon under samlingen
myplugin/.
Læg en ny SVG-fil i icons/, og genindlæs editoren. Ikonet bliver derefter synligt uden kodeændringer. Mønstret kan håndtere alt fra få ikoner til flere hundrede; hjertet registreres fortsat inline, mens stjernen, bogmærket og alle nye filer kommer fra mappen.
4. Brug de registrerede ikoner tre steder
I core/icon-blokken og REST API’et
core/icon viser automatisk alle registrerede samlinger. Redaktøren indsætter blot blokken og vælger et ikon, som derefter renderes på frontend uden ekstra kode.
Ikonerne eksponeres også via REST-endpointet /wp-json/wp/v2/icons. Samlingerne har et ledsagende endpoint på /wp-json/wp/v2/icon-collections, som eksterne værktøjer, der læser WordPress-data, kan bruge.
I PHP med wp_get_icon()
wp_get_icon() returnerer SVG’en som en streng. Du kan derfor outputte den direkte i en skabelon.
echo wp_get_icon( 'myplugin/heart' );I en egentlig skabelon kan du styre størrelse, CSS-klasse og tilgængelighed gennem funktionens andet argument.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Fremhævet', 'myplugin-icons' ),
)
);sizesætter SVG’enswidthogheighti pixels.classtilføjer en CSS-klasse på SVG-elementet.labelsætteraria-labelfor skærmlæsere.
En shortcode gør samme funktion tilgængelig i indlæg, sider og widgets. Koden nedenfor validerer ikonnavn, størrelse og klasse, og returnerer en tom streng, hvis ikonet ikke findes.
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="Hej verden"]
[myplugin_icon name="star" text="Fremhævet indlæg" size="32"]
[myplugin_icon name="bookmark" text="Gem til senere" size="20"]Shortcoden placerer ikonet ved siden af teksten og bruger værdien fra size som størrelse. Da SVG’erne anvender currentColor, overtager de automatisk den omgivende tekstfarve.
Som blokikon i register_block_type()
Et registreret ikon kan erstatte den normale Dashicon i en blokregistrering. I stedet for dette:
'icon' => 'warning', // Bruger en Dashiconbruger du ikonets fulde registrerede navn:
'icon' => 'myplugin/star', // Bruger et registreret, eget ikonBlokindsætteren viser herefter dit SVG-ikon i stedet for en generisk Dashicon. Det gælder både blocks, som er registreret med JavaScript, og PHP-only blocks.
5. Stil ikonerne med CSS
Ikonerne passer som udgangspunkt ind i WordPress, men de bør også følge omgivelserne: tekstfarve, skriftstørrelse og tilstande som hover. class-argumentet til wp_get_icon() giver dig en CSS-hook til SVG’en, mens CSS på et wrapper-element også virker i andre sammenhænge, herunder i blokeditoren.
Lad currentColor arve farven
Brug stroke="currentColor" eller fill="currentColor" frem for en fast farvekode. Så bliver et ikon rødt i rød tekst, mørkt i et mørkt tema og får linkets farve, når det ligger i et link.
<!-- Undgå faste farver: ikonet er altid rødt -->
<svg viewBox="0 0 24 24"
stroke="#dc2626"
stroke-width="2">
<path d="..."/>
</svg>SVG’er uden hårdkodede farver fungerer på tværs af temaer, hvorimod faste farver ofte skærer sig mod designet. Brug derfor currentColor som farvereference i de SVG’er, du distribuerer.
Tving en bestemt farve, når det er nødvendigt
Et brandmærke eller en statusindikator kan kræve en fast farve uanset konteksten. Sæt da color på SVG’en via klassen, som du sendte til wp_get_icon().
.featured-icon {
color: #f59e0b; /* Ravfarvet uanset den omgivende tekst */
}Fordi SVG’en bruger currentColor, arver stroke eller fill denne CSS-farve. Ikonet bliver dermed ravfarvet, også når den omgivende tekst er mørk.
Størrelse og hover-tilstande
Ved output fra shortcode eller wp_get_icon() kan size sætte en konkret pixelstørrelse. Vil du i stedet styre størrelsen med CSS eller tilføje interaktion, kan du style SVG’en gennem et wrapper-element.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Brug
sizeiwp_get_icon()ved enkeltstående tilfælde, hvor en præcis pixelstørrelse er vigtig, og CSS ikke giver mening. - Brug CSS-klasser via
classeller et wrapper-element, når ikonet bruges mange steder og skal være ens, eller når udseendet afhænger af tilstande som hover, focus og active eller af kontekst som et link eller en overskrift.
I shortcode-eksemplet kan du kombinere begge dele: Brug size til små justeringer i den enkelte shortcode, og brug CSS på .myplugin-icon-inline svg for et ensartet udtryk på hele sitet.
6. Fjern ikoner og samlinger
WordPress 7.1 har også funktioner til at afregistrere ét ikon eller en hel samling. Det er nyttigt under udvikling og ved oprydning, når et plugin ikke længere skal levere bestemte ikoner.
Fjern ét ikon
wp_unregister_icon( 'myplugin/bookmark' );Ikonet forsvinder fra vælgeren ved næste request. Indlæg, der allerede har indsat ikonet i en core/icon-blok, renderes tomme, fordi WordPress ikke omskriver eksisterende indhold.
Fjern hele samlingen ved deaktivering
Når pluginet deaktiveres, bør dets ikoner ikke fortsat ligge i vælgeren. Ved at afregistrere samlingen fjernes alle ikoner i den med ét kald, så du ikke skal loope gennem dem enkeltvis.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Vigtige sikkerheds- og navngivningsregler
WordPress ændrer ikke SVG-indholdet, når du registrerer et ikon. Den nøjagtige streng i content eller indholdet af filen fra file_path bliver leveret, så du skal selv rense SVG’er, før du pakker dem i et plugin: fjern scripts, eksterne referencer og alt overflødigt.
Fjern også hårdkodede fill– og stroke-farver, width og height på det yderste <svg>-element samt eventuelle <style>-blokke eller scripts. Behold viewBox og SVG’ens strukturelle attributter, og brug currentColor, hvor ikonet skal have farve.
Samlinger fungerer som namespaces. Derfor kan myplugin/heart og andetplugin/heart eksistere side om side uden konflikt; det fulde navn med samlingspræfikset gør ikonet entydigt. Du kan også registrere ikoner fra et temas functions.php ved at bruge get_stylesheet_directory() til filstien, men ikonerne forsvinder, når brugeren skifter tema.
Ofte stillede spørgsmål
Skal samlingen registreres før ikonerne?
Ja. Et ikon skal tilhøre en eksisterende samling, ellers dukker det ikke op i vælgeren. Registrér samlingen på init med standardprioritet og ikonerne ved en højere prioritet, for eksempel 20.
Kan content- og file_path-ikoner ligge i samme samling?
Ja. Hvert kald til wp_register_icon() er uafhængigt. Brug content til et eller to ikoner og file_path til resten; efter registreringen behandler WordPress dem ens.
Virker egne ikoner som blokikoner i register_block_type()?
Ja. Send det registrerede ikonnavn, for eksempel 'myplugin/star', til nøglen icon i register_block_type(). Blokindsætteren viser så dit SVG-ikon frem for en Dashicon, både for JavaScript-registrerede blocks og PHP-only blocks.
Returnerer wp_get_icon() HTML eller en streng?
wp_get_icon() returnerer SVG’en som en streng. Du kan outputte den direkte eller pakke den ind i din egen HTML. Det andet $args-array understøtter size, class, label til aria-label og title.
Hvad sker der, hvis to samlinger har samme ikonnavn?
Der opstår ingen konflikt, fordi samlingerne navngiver ikonerne. myplugin/heart og andetplugin/heart kan derfor eksistere samtidig.
Renser WordPress SVG’er under registreringen?
Nej. WordPress ændrer ikke SVG-indholdet ved registrering. Rens selv SVG’er, før du distribuerer dem, og fjern scripts, eksterne referencer og unødvendigt indhold.
Opsummering
Den nye API samler editor, PHP og REST om samme ikonregistrering: Opret først en samling, registrér derefter ikoner med enten content eller file_path, og hent dem, hvor de skal bruges. glob()-mønstret gør filbaserede ikonbiblioteker skalerbare, mens wp_get_icon() giver dig kontrol over størrelse, klasse og tilgængelighed i skabeloner.
Når WordPress 7.1 er tilgængelig, kan du starte med et lille plugin som eksemplet her. Rens SVG-filerne, brug currentColor, vælg et entydigt samlingsnavn og registrér samlingen før ikonerne, så får du en sammenhængende ikonintegration uden et JavaScript-build step.
Freja Hansen
Developer relations og community manager. At bygge tech-fællesskaber og forbedre udvikleroplevelsen er min passion. Fællesskabets kraft er uendelig.
Alle indlæg
