Så registrerar du egna SVG-ikoner i WordPress 7.1
WordPress 7.1 introducerar ett offentligt API för egna SVG-ikoner. Du kan registrera ikonsamlingar från ett tillägg utan JavaScript eller buildsteg och sedan använda samma ikoner i blockredigeraren, PHP och REST API:t.
I den här guiden bygger du ett litet tillägg som registrerar ikoner både som inline-SVG och från filer. Du får också ett mönster för att automatiskt läsa in en hel ikonmapp, en shortcode och ett exempel på hur en registrerad ikon ersätter en Dashicon i ett eget block.
Det här bygger du
- Ett tillägg med namnet
myplugin-custom-iconsoch en registrerad ikonsamling som hetermyplugin. - Tre färdiga ikoner: ett hjärta som registreras inline samt en stjärna och ett bokmärke som läses från
.svg-filer. - Ett mönster för massregistrering som automatiskt registrerar varje SVG-fil i en mapp.
- En shortcode som lägger in valfri registrerad ikon i innehållet.
- En blockikon som använder en egen SVG-ikon i
register_block_type().
Förutsättningar
- WordPress 7.1 eller senare. Du kan använda 7.1 RC under utvecklingen.
- Några SVG-ikonfiler, eller filerna i exemplen nedan.
- En lokal utvecklingsmiljö, exempelvis LocalWP, WordPress Studio eller wp-env.
- Grundläggande PHP-kunskaper.
Så fungerar API:t
API:t för egna ikoner har tre centrala funktioner och bygger på ikonsamlingar. En samling grupperar ikoner och ger dem ett namnrymdsprefix, så att core/plus och myplugin/plus inte krockar med varandra eller med ikoner från andra tillägg.
wp_register_icon_collection( $name, $args )registrerar en namngiven ikonsamling.wp_register_icon( $name, $args )registrerar en enskild ikon.wp_get_icon( $name, $args )renderar en ikon i PHP och returnerar SVG:n som en sträng.
När du registrerar en ikon väljer du antingen content, alltså SVG-markup som en PHP-sträng, eller file_path, en absolut sökväg till en .svg-fil. Använd bara ett av alternativen för varje ikon. content passar för en eller två ikoner, medan file_path är smidigare för större ikonbibliotek.
Skapa tillägget och registrera samlingen
Registrera alltid samlingen före ikonerna. Om du försöker lägga till en ikon i en samling som inte redan finns visas ikonen inte i väljaren, utan något tydligt felmeddelande.
Skapa följande mappstruktur i wp-content/plugins/:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgSkapa sedan myplugin-custom-icons.php. Samlingens label visas som sektionsrubrik i ikonväljaren.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Register 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__ ) );
/**
* Steg 1: Registrera ikonsamlingen.
*/
add_action( 'init', 'myplugin_register_icon_collection' );
function myplugin_register_icon_collection() {
wp_register_icon_collection(
'myplugin',
array(
'label' => __( 'MyPlugin', 'myplugin-icons' ),
)
);
}Samlingens namn blir prefixet för dess ikoner: myplugin/heart, myplugin/star och myplugin/bookmark. Aktivera tillägget under Tillägg → Installerade tillägg. Samlingen syns inte förrän den innehåller minst en ikon.
Registrera ikoner inline och från filer
Registrera en inline-ikon med content
När du bara har en eller två ikoner kan du lägga SVG-markupen direkt i PHP-filen. Följande hook körs på init med prioritet 20, efter samlingsregistreringens standardprioritet 10. Därmed finns samlingen när ikonen registreras.
/**
* Steg 2: Registrera ikon med inline-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>',
)
);
}Namnet myplugin/heart följer formatet samling/ikon-slug. label ger ikonen ett läsbart namn i väljaren. Attributet stroke="currentColor" gör att ikonen ärver färgen från omgivande text i stället för att låsa den till en hårdkodad färg.
Registrera ikoner från SVG-filer
Lägg följande filer i tilläggets icons/-mapp. När ikonerna ligger på disk använder du file_path i stället för content; WordPress läser då filen vid behov.
<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>/**
* Steg 3: Registrera ikoner från .svg-filer.
*/
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',
)
);
}Öppna därefter blocket core/icon i blockredigeraren. Ikonväljaren visar en ny sektion med samlingens etikett och ikonerna Heart, Star och Bookmark.
core/icon. — Forrás: WPVibesOm en ikon saknas beror det oftast på fel registreringsordning. Låt samlingen registreras med standardprioriteten och registrera ikonerna senare, exempelvis med prioritet 20.
Registrera en hel ikonmapp automatiskt
Att skriva ett anrop till wp_register_icon() för varje ikon skalar dåligt när biblioteket växer. Ersätt funktionen myplugin_register_file_icons() med nedanstående variant, som hittar och registrerar samtliga SVG-filer i mappen.
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' )returnerar alla.svg-filer i mappen.basename( $file_path, '.svg' )tar fram filnamnet utan filändelse.advanced-button.svgblir alltsåadvanced-button.ucwords( str_replace( '-', ' ', $slug ) )omvandlar sluggen till en läsbar etikett.advanced-buttonblir exempelvisAdvanced Button.- Loopen registrerar varje ikon under samlingen
myplugin/.
Lägg en ny SVG-fil i icons/ och ladda om redigeraren, så visas den i väljaren utan kodändringar. Mönstret fungerar lika bra för några få ikoner som för hundratals, medan hjärtikonen fortfarande kan ligga inline om du vill.
Använd ikonerna i block, PHP och REST API
Efter registreringen kan tre konsumenter använda samma ikonregister. Du behöver inte skapa separata integrationer för blockredigeraren, mallar och externa verktyg.
Visa ikoner i core/icon-blocket
Väljaren i core/icon visar automatiskt alla registrerade samlingar. Redaktören kan välja en ikon och WordPress renderar den på webbplatsens frontend utan extra kod. Ikonerna exponeras också via REST-endpointen /wp-json/wp/v2/icons, och samlingarna finns på /wp-json/wp/v2/icon-collections för externa verktyg som läser WordPress-data.
Rendera ikoner i PHP med wp_get_icon()
wp_get_icon() returnerar SVG-koden som en sträng. Du kan därför skriva ut den direkt i en mall.
echo wp_get_icon( 'myplugin/heart' );Skicka en andra argumentarray när du behöver styra storlek, CSS-klass eller tillgänglighet.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Featured', 'myplugin-icons' ),
)
);sizesätter SVG:nswidthochheighti pixlar.classlägger till en CSS-klass på SVG-elementet.labelsätteraria-labelför skärmläsare.
Lägg in ikoner med en shortcode
Följande shortcode, [myplugin_icon], låter redaktörer lägga in en registrerad ikon i inlägg, sidor och widgetar. Koden sanerar ikonens namn, storlek och CSS-klass innan den skickar värdena till wp_get_icon().
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"]Shortcoden placerar ikonen bredvid texten och använder värdet i attributet size. Eftersom SVG-filerna använder currentColor tar ikonen automatiskt samma färg som den omgivande texten.
Använd en egen ikon för ett block
Du kan ersätta ett blocks vanliga Dashicon genom att ange en registrerad ikon i register_block_type(). Detta fungerar både för block som JavaScript registrerar och för block som bara registreras i PHP.
'icon' => 'warning', // Använder en Dashicon'icon' => 'myplugin/star', // Använder en registrerad egen ikonBlockinfogaren visar då din SVG-ikon i stället för en generell Dashicon. Samma registrering räcker alltså för redigeraren, PHP-mallar och REST API:t.
Styla egna SVG-ikoner med CSS
Egna ikoner kan se integrerade ut från början, men CSS hjälper dem att följa textfärg, skala med sammanhanget och reagera vid hover. Klassen som du skickar via wp_get_icon() ger dig en CSS-hook för SVG-elementet. I blockredigeraren kan du i stället styla utifrån dess omgivande element, eftersom argumentet class inte används där.
Låt currentColor ärva textens färg
Använd stroke="currentColor" eller fill="currentColor" i stället för hårdkodade färger. En ikon med en fast röd färg förblir röd oavsett var den visas.
<!-- Undvik hårdkodad färg -->
<svg viewBox="0 0 24 24"
stroke="#dc2626"
stroke-width="2">
<path d="..."/>
</svg>Med currentColor blir ikonen röd i röd text, mörk i ett mörkt tema och får länkens färg när den ligger i en länk. SVG:n fungerar då som text och passar i fler teman.
Sätt en bestämd färg när sammanhanget kräver det
En varumärkesmarkering eller statusindikator kan behöva en egen färg oavsett omgivningen. Sätt då CSS-egenskapen color på SVG:n via klassen från wp_get_icon().
.featured-icon {
color: #f59e0b; /* Bärnstensfärgad oavsett omgivande text */
}När SVG:n använder currentColor går den satta färgen vidare till dess stroke eller fill. Ikonen blir därför bärnstensfärgad även om texten omkring är mörk.
Styr storlek och hover-läge
Argumentet size passar när du renderar en ikon med shortcode eller wp_get_icon() och behöver ett exakt pixelmått. Använd CSS när du vill styra storleken genom regler eller skapa tillstånd som hover.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}- Använd
sizeiwp_get_icon()för enstaka fall där ett exakt pixelmått är viktigt och CSS inte tillför något. - Använd CSS-klasser, via argumentet
classeller på ett omslutande element, när samma ikon förekommer på många ställen och ska vara konsekvent. CSS passar också när utseendet beror på tillstånd som hover, fokus och aktivt läge eller på ett sammanhang som en länk eller rubrik.
I shortcode-exemplet kan du använda size för små justeringar i varje shortcode. Styr i stället .myplugin-icon-inline svg med CSS när du vill skapa ett konsekvent utseende på hela webbplatsen.
Avregistrera ikoner och samlingar
WordPress 7.1 har två motsvarande funktioner för avregistrering: en för en specifik ikon och en för en hel samling.
Ta bort en enskild ikon
Under utveckling, eller när en tilläggsuppdatering tar bort en ikon, kan du avregistrera den med ett anrop.
wp_unregister_icon( 'myplugin/bookmark' );Ikonen försvinner ur väljaren vid nästa request. Inlägg som redan har lagt in ikonen i ett core/icon-block renderar däremot tomt, eftersom WordPress inte skriver om innehållet i inläggen.
Ta bort samlingen när tillägget avaktiveras
När du avaktiverar tillägget bör dess ikoner inte längre visas i väljaren. Avregistrera samlingen i avaktiveringshooken, så tar WordPress bort alla ikoner i den med ett enda anrop.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Du behöver inte loopa över de enskilda ikonerna. När du tar bort samlingen hanterar WordPress alla dess ikoner.
Vanliga frågor
Måste jag registrera samlingen före ikonerna?
Ja. Varje ikon måste tillhöra en befintlig samling, annars visas den inte i väljaren. Registrera samlingen på init med standardprioritet och ikonerna med en högre prioritet, exempelvis 20.
Kan jag blanda content och file_path i samma samling?
Ja. Varje anrop till wp_register_icon() är oberoende. Använd content för en eller två ikoner och file_path för resten; efter registreringen behandlar WordPress dem på samma sätt.
Fungerar egna ikoner som blockikoner i register_block_type()?
Ja. Ange det registrerade namnet, exempelvis 'myplugin/star', för nyckeln icon i register_block_type(). Blockinfogaren visar då SVG-ikonen i stället för en Dashicon. Lösningen fungerar för både JavaScript-registrerade block och block som bara använder PHP.
Returnerar wp_get_icon() HTML eller en sträng?
wp_get_icon() returnerar SVG:n som en sträng. Du kan skriva ut den direkt eller omsluta den med egen HTML. Den andra arrayen, $args, accepterar size, class, label för aria-label och title.
Vilka SVG-attribut bör jag ta bort före registrering?
Ta bort hårdkodade fill– och stroke-färger, samt width och height på det översta <svg>-elementet. Behåll viewBox och strukturella attribut. Ta också bort alla <style>-block, script och använd currentColor där ikonen behöver en färgreferens.
Kan jag registrera ikoner från ett tema i stället för ett tillägg?
Ja. Samma anrop till wp_register_icon() fungerar i ett temas functions.php; använd get_stylesheet_directory() för filsökvägen. Ikoner som temat registrerar försvinner dock när du byter tema.
Vad händer om två samlingar använder samma ikonname?
Samlingarna fungerar som namnrymder. myplugin/heart och anotherplugin/heart kan därför samexistera utan konflikt, eftersom det fullständiga namnet med samlingsprefixet gör varje ikon unik.
Sanerar WordPress SVG-filer vid registrering?
Nej. WordPress ändrar inte SVG-innehållet vid registrering utan använder exakt den sträng eller fil som du anger. Sanera därför SVG-filerna före leverans: ta bort script, externa referenser och allt innehåll som inte behövs.
Nästa steg
Installera WordPress 7.1 eller en 7.1 RC i din lokala miljö och börja med en namngiven samling samt en enda ikon. När flödet fungerar byter du till glob()-mönstret för ikonbiblioteket, använder currentColor i varje SVG och återanvänder samma registrerade namn i block, PHP-mallar och REST-baserade verktyg.
Det kompletta exempeltillägget med SVG-filer, README och mönstret för massregistrering finns på GitHub.
Elin Andersson
Chefredaktör för det svenska teamet, evangelist för hållbar utveckling och grön IT. Miljömedvetna tekniska lösningar är mitt mål.
Alla inlägg
