Custom SVG icons στο WordPress 7.1: οδηγός για plugins
Τα προσαρμοσμένα SVG icons στο WordPress 7.1 φέρνουν μια ενιαία API για τον editor, τα PHP templates και το REST API. Αντί να γράφετε JavaScript, να στήνετε build step ή να καταφεύγετε σε προσωρινές λύσεις, μπορείτε να δηλώσετε μια συλλογή icons από ένα plugin και να τη χρησιμοποιήσετε παντού.
Η έκδοση 7.1 του WordPress αναμένεται στις 19 Αυγούστου 2026. Ο παρακάτω οδηγός βασίζεται στην API που προβλέπεται να περιλαμβάνει η τελική έκδοση και δείχνει πώς θα δημιουργήσετε ένα μικρό plugin με ένα inline icon, icons από αρχεία SVG, μαζική καταχώριση, shortcode και χρήση icon σε custom block.
Τι χρειάζεστε και τι θα υλοποιήσετε
Θα δημιουργήσετε το plugin myplugin-custom-icons, το οποίο δηλώνει τη συλλογή myplugin. Η συλλογή θα περιέχει ένα heart icon που ορίζετε μέσα στην PHP, καθώς και star και bookmark icons που φορτώνονται από αρχεία .svg.
Χρειάζεστε WordPress 7.1 ή νεότερο – μπορείτε να αναπτύξετε με το 7.1 RC -, μερικά αρχεία SVG, τοπικό περιβάλλον όπως LocalWP, WordPress Studio ή wp-env, και βασική εξοικείωση με PHP. Στη συνέχεια θα προσθέσετε κάθε SVG ενός φακέλου αυτόματα, θα εισάγετε icons σε περιεχόμενο με shortcode και θα χρησιμοποιήσετε ένα registered icon στο register_block_type().
Η API των custom icons
Η API έχει τρεις συναρτήσεις και μία βασική έννοια οργάνωσης: τις συλλογές. Κάθε icon ανήκει υποχρεωτικά σε μια συλλογή και το όνομά της λειτουργεί ως πρόθεμα. Έτσι το core/plus διαφέρει από το myplugin/plus και αποφεύγετε συγκρούσεις με icons του core ή άλλων plugins.
Χρησιμοποιήστε τις εξής συναρτήσεις:
wp_register_icon_collection( $name, $args ): δηλώνει μια ονομασμένη συλλογή icons.wp_register_icon( $name, $args ): δηλώνει ένα icon.wp_get_icon( $name, $args ): αποδίδει ένα SVG από PHP και επιστρέφει το SVG ως string.
Για κάθε icon διαλέγετε μία από δύο πηγές SVG. Με το content περνάτε το SVG markup ως string μέσα στην PHP. Με το file_path περνάτε το απόλυτο path ενός αρχείου .svg. Μη συνδυάζετε τα δύο στο ίδιο icon: το content εξυπηρετεί ένα ή δύο icons, ενώ το file_path κλιμακώνεται καλύτερα όταν διαχειρίζεστε φάκελο με πολλά αρχεία.
Δημιουργήστε το plugin και δηλώστε πρώτα τη συλλογή
Η σειρά καταχώρισης είναι κρίσιμη. Πρέπει να δηλώσετε τη συλλογή πριν δηλώσετε icons που ανήκουν σε αυτήν· διαφορετικά τα icons δεν εμφανίζονται στον picker χωρίς να λάβετε εμφανές σφάλμα.
Δημιουργήστε την ακόλουθη δομή μέσα στο wp-content/plugins/:
myplugin-custom-icons/
├── myplugin-custom-icons.php
└── icons/
├── star.svg
└── bookmark.svgΣτο αρχείο myplugin-custom-icons.php, προσθέστε το header του plugin και δηλώστε τη συλλογή στο hook init.
<?php
/**
* Plugin Name: MyPlugin Custom Icons
* Description: Δηλώνει custom SVG icons για 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' ),
)
);
}Το myplugin θα αποτελεί το πρόθεμα όλων των icons, όπως myplugin/heart και myplugin/star. Το label εμφανίζεται ως τίτλος ενότητας στον picker. Ενεργοποιήστε το plugin από το «Plugins → Installed Plugins»· σε αυτό το στάδιο δεν θα δείτε κάτι, επειδή μια κενή συλλογή δεν αποδίδει περιεχόμενο.
Δηλώστε icons με inline SVG και από αρχεία
Ορίστε ένα inline icon με content
Κρατήστε ένα απλό SVG απευθείας στην PHP όταν δεν θέλετε επιπλέον αρχεία για ένα ή δύο icons. Συνδέστε τη συνάρτηση στο init με προτεραιότητα 20, ώστε να εκτελεστεί μετά την καταχώριση της συλλογής, που χρησιμοποιεί την προεπιλεγμένη προτεραιότητα 10.
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>',
)
);
}Το όνομα ακολουθεί το μοτίβο collection/icon-slug και το label εμφανίζεται στον picker. Το stroke="currentColor" επιτρέπει στο SVG να κληρονομεί το χρώμα του γύρω κειμένου, χωρίς σταθερό χρώμα μέσα στο αρχείο.
Φορτώστε icons από αρχεία SVG
Αποθηκεύστε τα επόμενα αρχεία στον φάκελο icons/. Για icons που βρίσκονται στον δίσκο, χρησιμοποιήστε το file_path αντί για το content. Το WordPress διαβάζει το αρχείο όταν το χρειάζεται.
<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',
)
);
}Ανοίξτε το block core/icon στον editor. Ο picker εμφανίζει ενότητα «MyPlugin» με τα Heart, Star και Bookmark, από όπου μπορείτε να εισαγάγετε καθένα στο περιεχόμενο. Αν λείπει κάποιο icon, ελέγξτε πρώτα τη σειρά των hooks: δηλώστε τη συλλογή στην προεπιλεγμένη προτεραιότητα και τα icons αργότερα, για παράδειγμα στην 20.
core/icon. — Forrás: WPVibesΚαταχωρίστε αυτόματα όλα τα SVG ενός φακέλου
Οι μεμονωμένες κλήσεις wp_register_icon() δεν εξυπηρετούν μια πραγματική βιβλιοθήκη με δεκάδες icons. Αντικαταστήστε τη myplugin_register_file_icons() με την επόμενη συνάρτηση, η οποία εντοπίζει κάθε .svg στον φάκελο και το δηλώνει στο επόμενο 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' ) επιστρέφει όλα τα SVG του φακέλου. Η basename( $file_path, '.svg' ) αφαιρεί το path και την επέκταση, άρα το advanced-button.svg γίνεται advanced-button. Στη συνέχεια, η ucwords( str_replace( '-', ' ', $slug ) ) το μετατρέπει σε αναγνώσιμο label «Advanced Button».
Προσθέστε νέο SVG στον φάκελο icons/ και ανανεώστε τον editor. Το νέο icon θα εμφανιστεί στον picker χωρίς να αλλάξετε PHP. Το μοτίβο λειτουργεί μαζί με inline icons: μπορείτε να κρατήσετε το heart inline και να δηλώνετε από τον φάκελο το star, το bookmark και όσα επιπλέον icons προσθέσετε.
Χρησιμοποιήστε τα icons στον editor, σε PHP και σε blocks
Εισαγάγετέ τα με το block core/icon
Το core/icon εμφανίζει αυτόματα κάθε registered συλλογή. Ο χρήστης εισάγει το block, επιλέγει ένα icon της συλλογής και το WordPress το αποδίδει στο frontend χωρίς πρόσθετο κώδικα.
Τα icons διατίθενται επίσης στο REST endpoint /wp-json/wp/v2/icons, ενώ οι συλλογές εκτίθενται στο /wp-json/wp/v2/icon-collections. Έτσι μπορούν να τα διαβάσουν εξωτερικά εργαλεία που αντλούν δεδομένα από το WordPress.
Αποδώστε SVG σε PHP με wp_get_icon()
Η wp_get_icon() επιστρέφει το SVG ως string, επομένως μπορείτε να το εμφανίσετε απευθείας σε template. Η απλούστερη χρήση είναι η εξής:
echo wp_get_icon( 'myplugin/heart' );Περάστε δεύτερο array ορισμάτων όταν χρειάζεστε ακριβές μέγεθος, CSS class ή προσβάσιμο όνομα. Το size ορίζει width και height σε pixels, το class προσθέτει class στο στοιχείο SVG και το label ορίζει aria-label για screen readers. Η συνάρτηση δέχεται επίσης title.
echo wp_get_icon(
'myplugin/star',
array(
'size' => 32,
'class' => 'featured-icon',
'label' => __( 'Προτεινόμενο', 'myplugin-icons' ),
)
);Προσθέστε shortcode για το περιεχόμενο
Το επόμενο shortcode επιτρέπει σε συντάκτες να βάζουν ένα registered icon δίπλα σε κείμενο σε άρθρα, σελίδες ή widgets. Καθαρίζει το όνομα, το μέγεθος και το CSS class πριν καλέσει τη 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="Προτεινόμενο άρθρο" size="32"]
[myplugin_icon name="bookmark" text="Αποθήκευση για αργότερα" size="20"]Το shortcode εμφανίζει το icon δίπλα στο κείμενο, στο μέγεθος που ορίζει το size. Εφόσον τα SVG χρησιμοποιούν currentColor, κληρονομούν αυτόματα το χρώμα του κειμένου που τα περιβάλλει.
Χρησιμοποιήστε custom icon σε register_block_type()
Μπορείτε να αντικαταστήσετε το προεπιλεγμένο Dashicon σε κάθε block που δηλώνετε. Αντί για ένα όνομα Dashicon όπως το warning, περάστε το πλήρες όνομα του custom icon στο κλειδί icon.
'icon' => 'warning', // Χρησιμοποιεί Dashicon
'icon' => 'myplugin/star', // Χρησιμοποιεί registered custom iconΟ block inserter θα εμφανίσει το SVG της συλλογής αντί για γενικό Dashicon. Η προσέγγιση λειτουργεί τόσο σε blocks που δηλώνετε με JavaScript όσο και σε blocks μόνο με PHP.
Δώστε στα SVG σωστό χρώμα και συμπεριφορά
Χρησιμοποιήστε stroke="currentColor" ή fill="currentColor" αντί για σταθερό χρώμα. Ένα icon μέσα σε κόκκινο κείμενο θα γίνει κόκκινο, σε dark theme θα ακολουθήσει το αντίστοιχο χρώμα και μέσα σε link θα ταιριάξει με το link. Με αυτόν τον τρόπο το SVG συμπεριφέρεται σαν κείμενο και προσαρμόζεται στο theme.
<!-- Μη χρησιμοποιείτε σταθερό χρώμα: το icon θα μένει πάντα κόκκινο -->
<svg viewBox="0 0 24 24" stroke="#dc2626" stroke-width="2">
<path d="..."/>
</svg>Όταν ένα icon πρέπει να έχει συγκεκριμένο χρώμα, όπως ένα brand mark ή δείκτης κατάστασης, επιβάλετέ το από CSS. Επειδή το SVG διαβάζει το currentColor, η ιδιότητα color στο SVG μεταφέρεται στο stroke ή στο fill.
.featured-icon {
color: #f59e0b; /* Amber, ανεξάρτητα από το γύρω κείμενο */
}Για icons που αποδίδετε με shortcode ή με wp_get_icon(), το size καλύπτει το μέγεθος σε pixels. Χρησιμοποιήστε CSS όταν θέλετε σταθερό μέγεθος σε πολλά σημεία ή κατάσταση όπως hover, focus και active. Το CSS είναι επίσης η κατάλληλη επιλογή όταν θέλετε να στοχεύσετε icons του editor, όπου δεν περνάτε το όρισμα class.
.myplugin-icon-inline svg {
transition: transform 0.15s ease-in-out;
}
.myplugin-icon-inline:hover svg {
transform: scale(1.1);
}Αφαιρέστε icons και συλλογές
Κατά την ανάπτυξη ή όταν μια ενημέρωση plugin καταργεί ένα icon, αφαιρέστε ένα συγκεκριμένο όνομα με την wp_unregister_icon(). Το icon θα εξαφανιστεί από τον picker στο επόμενο request.
wp_unregister_icon( 'myplugin/bookmark' );Προσέξτε ότι ένα core/icon block που έχει ήδη αποθηκεύσει αυτό το icon θα αποδίδει κενό περιεχόμενο. Το WordPress δεν ξαναγράφει το αποθηκευμένο περιεχόμενο των άρθρων όταν αφαιρείτε ένα icon.
Κατά την απενεργοποίηση του plugin, αφαιρέστε ολόκληρη τη συλλογή. Η wp_unregister_icon_collection() αφαιρεί μαζί όλα τα icons της, άρα δεν χρειάζεται να κάνετε loop για καθένα ξεχωριστά.
register_deactivation_hook( __FILE__, 'myplugin_unregister_icons' );
function myplugin_unregister_icons() {
wp_unregister_icon_collection( 'myplugin' );
}Συχνές ερωτήσεις
Πρέπει να δηλώσω συλλογή πριν από τα icons;
Ναι. Τα icons πρέπει να ανήκουν σε υπάρχουσα συλλογή, αλλιώς δεν εμφανίζονται στον picker. Δηλώστε τη συλλογή στο init με την προεπιλεγμένη προτεραιότητα και τα icons σε υψηλότερη προτεραιότητα, όπως 20.
Μπορώ να συνδυάσω content και file_path στην ίδια συλλογή;
Ναι. Κάθε κλήση wp_register_icon() είναι ανεξάρτητη. Χρησιμοποιήστε content για ένα ή δύο icons και file_path για τα υπόλοιπα· μετά την καταχώριση, το WordPress τα χειρίζεται με τον ίδιο τρόπο.
Λειτουργούν τα custom icons ως icons block;
Ναι. Περάστε το registered όνομα, όπως 'myplugin/star', στο κλειδί icon του register_block_type(). Ο inserter εμφανίζει το custom SVG αντί για Dashicon, τόσο σε JavaScript-registered blocks όσο και σε blocks μόνο με PHP.
Η wp_get_icon() επιστρέφει HTML ή string;
Η wp_get_icon() επιστρέφει το SVG ως string. Μπορείτε να το εμφανίσετε με echo ή να το τυλίξετε στο δικό σας HTML. Το δεύτερο array, $args, δέχεται size, class, label για το aria-label και title.
Ποια attributes πρέπει να αφαιρέσω από ένα SVG;
Αφαιρέστε σταθερά χρώματα fill και stroke, καθώς και τα width και height από το root <svg>, αλλά κρατήστε το viewBox. Αφαιρέστε επίσης blocks <style>, scripts και οτιδήποτε περιττό. Κρατήστε τα δομικά attributes και χρησιμοποιήστε currentColor για αναφορές χρώματος.
Μπορώ να δηλώσω icons από theme αντί για plugin;
Ναι. Η ίδια κλήση wp_register_icon() λειτουργεί στο functions.php ενός theme, με το get_stylesheet_directory() για το file path. Τα icons όμως θα εξαφανιστούν όταν αλλάξετε theme.
Τι γίνεται όταν δύο συλλογές έχουν icon με το ίδιο όνομα;
Οι συλλογές λειτουργούν ως namespace. Τα myplugin/heart και anotherplugin/heart συνυπάρχουν χωρίς σύγκρουση, επειδή μοναδικό είναι το πλήρες όνομα που περιλαμβάνει το πρόθεμα της συλλογής.
Καθαρίζει το WordPress τα SVG κατά την καταχώριση;
Όχι. Το WordPress δεν αλλάζει το SVG κατά την καταχώριση: σερβίρει ακριβώς το string που δώσατε ή το περιεχόμενο του αρχείου που δείξατε. Καθαρίστε τα SVG πριν τα διανείμετε και αφαιρέστε scripts, εξωτερικές αναφορές και κάθε μη απαραίτητο στοιχείο.
Ενσωματώστε τη συλλογή στο plugin σας
Δηλώστε πρώτα τη συλλογή, προτιμήστε file_path και τη μαζική καταχώριση με glob() όταν συντηρείτε βιβλιοθήκη SVG, και κρατήστε currentColor στα αρχεία σας. Με μία καταχώριση, το ίδιο icon μπορεί να τροφοδοτεί τον block editor, τα PHP templates, το REST API και το icon ενός custom block χωρίς JavaScript build step.
Αναφορές / Πηγές
Ελένη Γεωργίου
Προγραμματίστρια τουριστικής τεχνολογίας και πλατφορμών φιλοξενίας. Συστήματα online κρατήσεων και λογισμικό φιλοξενίας είναι ο τομέας μου. Η μεσογειακή φιλοξενία λειτουργεί και ψηφιακά.
Όλες οι αναρτήσεις
