easy_svg_icon()

Funktion · Easy SVG · Status: Stabil

easy_svg_icon() liefert dir ein Icon aus der Icon-Bibliothek der Website als Inline-SVG, fertig zum echo im Template. Du übergibst den Namen des Icons und optional eine CSS-Klasse und ein Label. Ohne Label gilt das Icon als Dekoration und ist für Screenreader unsichtbar, mit Label wird es als Bild mit diesem Namen vorgelesen.

Verwendung

easy_svg_icon( string $name, array $args = array() ): string

Wann du es brauchst

• In einem klassischen oder hybriden Theme-Template (header.php, ein Template-Part, ein Helfer in der functions.php), wenn neben einem Link oder einer Überschrift ein Icon stehen soll.
• In der render.php eines Blocks oder einem render_callback, wo du HTML in PHP baust.
• In einem Page-Builder-Widget oder einer Ausgabe für eigene Felder, die PHP ausführt.
• Unter WordPress älter als 7.1: Die Funktion liest das gespeicherte Icon direkt und braucht keine Icon-Registry des Cores.

Wann nicht:

• In Beitragsinhalten, die Redakteure schreiben. Nimm dort den Shortcode [easy_svg_icon] oder den Core-Block Icon mit der Sammlung easy-svg.
• Wenn du genau die Zeichnung brauchst, die der Icon-Block zeigt. Der Block zeichnet, was beim init an die Icon-Registry übergeben wurde, und das kann vom gespeicherten Markup abweichen (Formen in Pfade umgebaut, Striche als Klassen). easy_svg_icon() gibt das gespeicherte Markup selbst aus.

Parameter

Rückgabewert

Standardwert

Beispiele

Ein dekoratives Icon neben Text

Der Link sagt schon, was er tut, das Icon ist also Dekoration und bleibt für Screenreader unsichtbar.

<a class="site-cart" href="<?php echo esc_url( home_url( '/cart/' ) ); ?>">
	<?php echo easy_svg_icon( 'cart', array( 'class' => 'site-cart__icon' ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>
	<?php esc_html_e( 'Cart', 'mytheme' ); ?>
</a>

Ein Knopf nur mit Icon, mit Label

Es gibt keinen sichtbaren Text, also trägt das Icon den Namen. Übersetze das Label.

<button type="button" class="menu-toggle" aria-expanded="false">
	<?php
	echo easy_svg_icon( // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
		'easy-svg/menu',
		array(
			'class' => 'menu-toggle__icon',
			'label' => __( 'Open menu', 'mytheme' ),
		)
	);
	?>
</button>

Ein Theme-Helfer, der ein fehlendes Plugin übersteht

Das Theme läuft weiter, wenn Easy SVG deaktiviert oder das Icon gelöscht ist, und zeigt dann ein Textzeichen.

function mytheme_icon( $name, $args = array() ) {
	if ( ! function_exists( 'easy_svg_icon' ) ) {
		return '';
	}

	$svg = easy_svg_icon( $name, $args );
	if ( '' === $svg ) {
		return '<span class="mytheme-icon-missing" aria-hidden="true">&bull;</span>';
	}

	return '<span class="mytheme-icon">' . $svg . '</span>';
}

// Im Template:
echo mytheme_icon( 'phone', array( 'class' => 'contact__icon' ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped

Bedeutungstragend, ohne ein Label zu schreiben

Mit decorative false bekommt das Icon den Titel aus der Bibliothek als Namen. Praktisch, wenn der Titel schon ein guter Text ist.

echo easy_svg_icon( 'award', array( 'decorative' => false ) ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
// aria-label ist der gespeicherte Titel, zum Beispiel "Award"

So funktioniert es

1. Der Name wird am ersten Schrägstrich in Sammlung und Slug geteilt. Ohne Schrägstrich ist die Sammlung easy-svg.
2. easy_svg_icon_markup() sucht den esw_icon-Beitrag mit diesem Slug über get_page_by_path() (nur für die Sammlung easy-svg) und nimmt seinen post_content. Jede andere Sammlung startet mit einem leeren String.
3. Der Filter easy_svg_icon_markup läuft über dieses Markup, mit Slug und Sammlung.
4. Ist das Ergebnis leer, endet es hier mit einem leeren String. Es wird kein leerer Container erfunden.
5. Klasse und Barrierefreiheits-Attribute werden gebaut und in den ersten echten svg-Tag eingesetzt (ein Tag wie svgfoo wird übersprungen). Sie werden als Text eingefügt, nicht mit preg_replace(), damit ein Label wie Preis $20 nicht verstümmelt wird.

Caching: Einen eigenen Cache gibt es nicht. get_page_by_path() merkt sich seine Antwort in der Objekt-Cache-Gruppe post-queries, bis sich irgendein Beitrag ändert. Mehrere Aufrufe für dasselbe Icon in einer Anfrage kosten also eine Datenbankabfrage. Mit persistentem Objekt-Cache überlebt das Ergebnis auch zwischen Anfragen. Der Schalter unter Icons, Einstellungen spielt hier keine Rolle: Die Funktion ist immer geladen und liest die Beiträge direkt, auch wenn die Bibliothek ausgeschaltet ist.

Stolperfallen

• Größe. Die Funktion setzt kein width und kein height. Ein SVG mit nur einer viewBox wird so breit wie sein Container. Gib der Klasse eine Größe, zum Beispiel width: 1em; height: 1em;.
• Farbe. Das Markup wird so ausgegeben, wie es gespeichert ist. Das Icon folgt der Textfarbe nur, wenn das SVG selbst currentColor nutzt (oder fill nicht setzt und dein CSS fill: currentColor setzt). Fest eingetragene Farben in der Datei bleiben fest.
• Doppelte Attribute. Klasse und ARIA-Attribute werden eingefügt, nicht zusammengeführt. Hat die gespeicherte Wurzel schon ein class, hat sie danach zwei, und Browser behalten das erste, also deins. Schreib alle Klassen, die du brauchst, in class.
• Label "0". Ein Label 0 gilt in PHP als leer, das Icon bleibt dann dekorativ, außer du übergibst decorative false.
• Geänderter Slug. Umbenennen in der Bibliothek behält den Slug, Templates laufen weiter. Löschen und neu Hinzufügen kann einen neuen Slug ergeben (heart-2), und jeder Aufruf liefert dann einen leeren String.
• Nicht die Zeichnung des Blocks. Was du mit easy_svg_registrable_icons änderst, erreicht nur den Icon-Block und wp_get_icon(), nie diese Funktion.

Siehe auch

• [easy_svg_icon]
• easy_svg_icon_markup
• easy_svg_icon_markup()
• easy_svg_icon_label()
• easy-svg
• EASY_SVG_ICON_NAME_PATTERN
• Icons in Themes ausgeben