Icons in Themes ausgeben

Tutorial · Easy SVG

Easy SVG hält auf deiner Website eine Bibliothek bereinigter SVG-Icons. In diesem Tutorial siehst du die drei Wege, ein Icon auf eine Seite zu bringen, wie du jeden davon barrierefrei machst, wie du Icons mit CSS in Größe und Farbe steuerst und wie du ihr Markup mit Filtern änderst. Jedes Snippet funktioniert mit Easy SVG 5.4.

Bevor du loslegst

Welcher Weg passt

Der Unterschied in der letzten Spalte zählt: Der Icon-Block und wp_get_icon() zeichnen, was die Icon-Registry von WordPress behält, und das sind nur Pfade und Polygone. Easy SVG baut Kreise, Rechtecke, Linien und Umriss-Striche um, damit die meisten Icons trotzdem richtig aussehen, aber Verläufe, Masken, Text und title-Elemente überleben dort nicht. easy_svg_icon() und der Shortcode geben die gespeicherte Datei unverändert aus.

Icons in PHP-Templates

easy_svg_icon() gibt das Markup zurück, du gibst es mit echo aus. Übergib einen reinen Slug oder easy-svg/slug.

<a class="site-header__search" href="<?php echo esc_url( home_url( '/?s=' ) ); ?>">
	<?php echo easy_svg_icon( 'search', array( 'class' => 'icon' ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>
	<span><?php esc_html_e( 'Search', 'mytheme' ); ?></span>
</a>

Pack das Ergebnis nicht in esc_html() oder wp_kses_post(): Beide zerstören SVG. Das Markup darf so ausgegeben werden, weil es beim Speichern bereinigt und gehärtet wurde.

Ein Theme sollte nicht kaputtgehen, wenn das Plugin fehlt oder ein Icon gelöscht wurde. Kapsel den Aufruf einmal:

/**
 * Gibt ein Icon aus Easy SVG aus, oder nichts.
 *
 * @param string $name  Icon slug or easy-svg/slug.
 * @param array  $args  class, label, decorative.
 */
function mytheme_the_icon( $name, $args = array() ) {
	if ( ! function_exists( 'easy_svg_icon' ) ) {
		return;
	}
	echo easy_svg_icon( $name, $args ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
}

Icons im Inhalt: der Shortcode

[easy_svg_icon name="easy-svg/heart" class="icon" label="Favourite"]

Er nimmt name (Pflicht), class und label und gibt genau das aus, was easy_svg_icon() ausgibt. Solange die Icon-Bibliothek ausgeschaltet ist, ist der Shortcode nicht registriert und erscheint als reiner Text.

Gibt dein Theme ein eigenes Feld aus, das den Shortcode enthalten kann, ruf do_shortcode() zuletzt auf, nach jedem Escaping, sonst wird das SVG entfernt:

$note = wp_kses_post( get_post_meta( get_the_ID(), 'mytheme_note', true ) );
echo do_shortcode( $note ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped

Icons im Block-Editor

Ab WordPress 7.1 fügst du einen Icon-Block ein und wählst in seiner Auswahl die Sammlung "Easy SVG". Die Sammlung erscheint, sobald die Bibliothek ein gültiges Icon enthält. In einem Pattern oder Block-Template schreibst du:

<!-- wp:icon {"icon":"easy-svg/arrow-right"} /-->

In PHP liefert dir wp_get_icon( 'easy-svg/arrow-right', array( 'size' => 20 ) ) dieselbe Zeichnung, die der Block zeigt. Beachte: Der Core setzt width und height auf 24 Pixel, außer du übergibst eine andere size, oder null, um die eigene Größe der Datei zu behalten.

Wird ein Icon gelöscht, zeigen Icon-Blöcke, die es genutzt haben, im Editor einen Hinweis und auf der Seite nichts.

Barrierefreiheit

Jedes Icon ist entweder Dekoration oder Inhalt. Entscheide das je Einsatz, nicht je Icon.

Faustregeln:

• Sagt der sichtbare Text neben dem Icon schon dasselbe, ist das Icon dekorativ. Ein Label würde Screenreader es doppelt sagen lassen.
• Ein Knopf oder Link nur mit Icon braucht ein Label. Übersetze es: __( 'Close', 'mytheme' ).
• Easy SVG gibt nie role="img" ohne Namen aus. Markierst du ein Icon als bedeutungstragend ohne Label, fällt der Name auf den gespeicherten Titel zurück, sonst auf den Slug als Wörter.
• focusable="false" verhindert, dass alte Versionen von Internet Explorer und Edge das SVG zum Tab-Stopp machen.
• Ein title-Element im SVG zeigt beim Überfahren einen Tooltip, verlass dich aber nicht darauf als zugänglichen Namen. Nimm label. Ein title kannst du mit dem Filter easy_svg_icon_markup ergänzen (Beispiel unten), im Icon-Block kommt es nicht an.

Größe und Farbe mit CSS

Easy SVG setzt in Templates und im Shortcode kein width und kein height. Ein SVG mit nur einer viewBox füllt seinen Container, gib deiner Icon-Klasse also eine Größe:

.icon {
	display: inline-block;
	width: 1em;
	height: 1em;
	vertical-align: -0.125em;
	flex-shrink: 0;
}

Damit die Farbe dem Text folgt, darf das SVG sie nicht fest eintragen. Zwei Fälle:

• Gefüllte Icons ohne eigenes fill nehmen die Farbe aus dem CSS: Ergänze fill: currentColor; in .icon. Icons mit fill="#000" an ihren Pfaden bleiben schwarz. Bereinige die Datei, oder entferne das Attribut mit einem Filter.
• Umriss-Icons (Feather, Lucide, Tabler, Heroicons Outline) nutzen meist stroke="currentColor" und fill="none". In Templates folgen sie der Textfarbe, so wie sie sind. Im Icon-Block trägt Easy SVG den Strich als Klassen, und sein Strich-Stylesheet setzt stroke: currentColor mit der ursprünglichen Stärke (1, 1.25, 1.5, 1.75, 2, 2.5 oder 3, andere Stärken fallen auf 1 zurück). Auch eine feste Strichfarbe wird dort zu currentColor.

Willst du die Strichstärke von Umriss-Icons in Templates ändern, zielst du auf die Formen, denn dort steht die Stärke:

.icon--bold path,
.icon--bold circle,
.icon--bold line,
.icon--bold polyline,
.icon--bold rect {
	stroke-width: 2.5;
}

Markup mit Filtern ändern

Zwei Filter, zwei Ausgabewege:

Einem Icon in Templates einen Tooltip-Titel geben:

add_filter( 'easy_svg_icon_markup', 'mytheme_icon_tooltip', 10, 3 );

function mytheme_icon_tooltip( $markup, $slug, $collection ) {
	if ( 'easy-svg' !== $collection || 'info' !== $slug || '' === $markup ) {
		return $markup;
	}
	$title = '<title>' . esc_html__( 'More information', 'mytheme' ) . '</title>';
	return preg_replace( '/(<svg\b[^>]*>)/i', '$1' . $title, $markup, 1 );
}

Interne Icons in der Auswahl des Editors verstecken, während Templates sie weiter nutzen:

add_filter( 'easy_svg_registrable_icons', 'mytheme_hide_internal_icons' );

function mytheme_hide_internal_icons( $icons ) {
	return array_values(
		array_filter(
			(array) $icons,
			static function ( $icon ) {
				return 0 !== strpos( (string) ( $icon['slug'] ?? '' ), 'internal-' );
			}
		)
	);
}

Caching

Meist musst du nicht darüber nachdenken, aber es hilft zu wissen, was zwischengespeichert wird:

• Templates und Shortcode. Jeder Aufruf sucht das Icon mit get_page_by_path(). WordPress hält diese Antwort im Objekt-Cache, bis sich irgendein Beitrag ändert, dasselbe Icon zweimal auf einer Seite kostet also eine Abfrage. Mit persistentem Objekt-Cache überlebt das auch zwischen Anfragen. Deine Callbacks auf easy_svg_icon_markup werden nicht zwischengespeichert, teure Arbeit cachst du selbst.
• Icon-Block. Die Icon-Liste, die WordPress bekommt, liegt einen Tag im Transient easy_svg_icons, verknüpft mit der Option easy_svg_icons_version. Hinzufügen, Ersetzen, Umbenennen oder Löschen eines Icons über das Plugin, WP-CLI oder einen Importer erhöht die Version, die nächste Anfrage ist also aktuell. easy_svg_registrable_icons läuft bei jeder Anfrage zusätzlich zu diesem Cache.
• Seiten-Caches. Ein Ganzseiten-Cache (Plugin oder CDN) liefert nach dem Ersetzen eines Icons weiter altes HTML. Leere ihn wie nach jeder Inhaltsänderung.

Checkliste

• Die Bibliothek ist eingeschaltet, wenn du Shortcode oder Icon-Block nutzt.
• Template-Aufrufe sind in function_exists( 'easy_svg_icon' ) gekapselt.
• Links und Knöpfe nur mit Icon haben ein übersetztes label, Icons neben Text haben keins.
• Deine Icon-Klasse setzt width, height und bei gefüllten Icons fill: currentColor.
• Nichts maskiert das Icon-Markup, nachdem es ausgegeben wurde.
• Filter geben für jedes Icon, das sie nicht behandeln, das Original-Markup zurück.

Siehe auch

• easy_svg_icon()
• [easy_svg_icon]
• easy-svg
• easy_svg_icon_markup
• easy_svg_registrable_icons
• Ein Add-on bauen