easy-svg

Block · Easy SVG · Status: Stabil

Easy SVG bringt keinen eigenen Block mit. Stattdessen hängt es deine Icon-Bibliothek als Sammlung "Easy SVG" (Slug easy-svg) an den Core-Block Icon. Redakteure wählen deine Icons in der Icon-Auswahl des Blocks, und Themes geben sie mit der WordPress-eigenen Funktion wp_get_icon() aus. Dafür brauchst du WordPress 7.1 oder neuer, dort kam die Icon-Registry dazu.

Verwendung

// Was das Plugin auf init mit Priorität 10 tut:
wp_register_icon_collection( 'easy-svg', array( 'label' => 'Easy SVG' ) );
wp_register_icon( 'easy-svg/heart', array( 'label' => 'Heart', 'content' => '...' ) );

Im Block-Inhalt wird ein Icon aus der Sammlung so gespeichert:

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

Wann du es brauchst

• Redakteure sollen Icons im Block-Editor oder Website-Editor visuell setzen, mit den Farb- und Größenreglern des Blocks.
• Ein Block-Theme oder Pattern braucht Icons: Schreib das Block-Markup oben ins Pattern.
• Ein PHP-Template ab 7.1 will dieselbe Zeichnung, die der Block zeigt: wp_get_icon( 'easy-svg/heart' ).

Wann nicht:

• Unter WordPress älter als 7.1: Dort gibt es keinen Icon-Block. Nimm easy_svg_icon() oder den Shortcode [easy_svg_icon].
• Für Icons mit Verläufen, Masken, Text oder use-Verweisen: Die Registry behält nur Pfade und Polygone. Gib solche Icons mit easy_svg_icon() aus, das die gespeicherte Datei ausgibt.

Parameter

Die Sammlung selbst hat keine Parameter, die du ändern kannst. Jedes Icon darin heißt easy-svg/ plus Slug, zum Beispiel easy-svg/arrow-left. Der Slug muss zu EASY_SVG_ICON_NAME_PATTERN passen (Kleinbuchstaben, Ziffern, - und _, Anfang und Ende Buchstabe oder Ziffer), die Bibliothek legt nur solche Slugs an.

Für wp_get_icon() (eine Funktion des WordPress-Cores, nicht Teil von Easy SVG):

Rückgabewert

Standardwert

Registriert wird sie nur, wenn alles zutrifft: WordPress hat wp_register_icon() und wp_register_icon_collection() (7.1 oder neuer), die Icon-Bibliothek ist unter Icons, Einstellungen eingeschaltet, und mindestens ein Icon hat einen brauchbaren Slug. Ihr Label ist "Easy SVG", übersetzt über die Textdomain des Plugins.

Beispiele

Die Zeichnung des Blocks aus einem Template ausgeben

if ( function_exists( 'wp_get_icon' ) ) {
	echo wp_get_icon( // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
		'easy-svg/heart',
		array(
			'size'  => 20,
			'class' => 'card__icon',
			'label' => __( 'Favourite', 'mytheme' ),
		)
	);
}

Icon-Block in einem Pattern

<!-- wp:group {"layout":{"type":"flex"}} -->
<div class="wp-block-group">
	<!-- wp:icon {"icon":"easy-svg/phone"} /-->
	<!-- wp:paragraph --><p>030 1234567</p><!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

Rückfall auf älteres WordPress

function mytheme_icon( $slug, $label = '' ) {
	if ( function_exists( 'wp_get_icon' ) ) {
		$svg = wp_get_icon( 'easy-svg/' . $slug, array( 'label' => $label ) );
		if ( '' !== $svg ) {
			return $svg;
		}
	}
	if ( function_exists( 'easy_svg_icon' ) ) {
		return easy_svg_icon( $slug, array( 'label' => $label ) );
	}
	return '';
}

Bei Icons mit Formen oder Strichen können die beiden Wege unterschiedlich aussehen, weil die Fassung des Blocks für die Registry umgebaut wurde (siehe So funktioniert es).

Prüfen, ob die Sammlung da ist

Lass das nach init mit Priorität 10 laufen, zum Beispiel in einem Template oder auf wp_loaded.

$has_collection = class_exists( 'WP_Icon_Collections_Registry' )
	&& WP_Icon_Collections_Registry::get_instance()->is_registered( 'easy-svg' );

false heißt: WordPress ist älter als 7.1, die Icon-Bibliothek ist ausgeschaltet, oder die Bibliothek hat noch kein brauchbares Icon.

So funktioniert es

1. Wann. Auf init mit Priorität 10, nachdem WordPress seine eigene Sammlung core mit Priorität 0 registriert hat. Nicht nur im Admin: Der Icon-Block wird auf dem Server gerendert, die Icons müssen also auch für Besucher existieren.
2. Was. Jedes gespeicherte Icon, die ältesten zuerst, in Seiten zu 100 gelesen und einen Tag zwischengespeichert. Der Cache wird verworfen, sobald ein Icon hinzugefügt, ersetzt, umbenannt oder gelöscht wird.
3. Umbau für die Registry. WordPress lässt wp_kses mit einer festen Erlaubnisliste über jedes Icon laufen: svg, path und polygon, und an Pfaden nur fill, fill-rule, d und transform. Damit Icons sichtbar bleiben, baut Easy SVG jede Zeichnung vorher um: Kreise, Rechtecke (auch mit runden Ecken), Ellipsen, Linien und Polylinien werden zu Pfaden, Gruppen werden auf ihre Kinder aufgelöst (ihr transform und fill wandern mit), und ein Umriss-Icon bekommt die Klassen esvg-stroke, esvg-sw-* (Strichstärken 1, 1.25, 1.5, 1.75, 2, 2.5, 3), esvg-cap-round und esvg-join-round.
4. Strich-Stylesheet. Trägt mindestens ein registriertes Icon diese Klassen, wird ein kleines Inline-Stylesheet (easy-svg-stroke-icons) im Frontend und im Editor ausgegeben. Es setzt fill: none; stroke: currentColor auf die Pfade, Umriss-Icons nehmen also die Textfarbe des Blocks an.
5. Fehlende Icons. Im Editor zeigt ein Icon-Block, dessen Icon nicht mehr registriert ist, einen Hinweis. Das Frontend bleibt still, und der Block zeichnet nichts.

Caching: Von Hand musst du nichts leeren. Die Icon-Liste liegt im Transient easy_svg_icons, zusammen mit der Versionsnummer aus der Option easy_svg_icons_version. Jeder Schreibvorgang über das Plugin erhöht die Version.

Stolperfallen

• Farben. Eine feste Strichfarbe wird zu currentColor. Ein gemischtes Icon (Teile gefüllt, Teile mit Strich) behält seine Füllungen, verliert aber die Striche, weil eine Klasse nicht beides ausdrücken kann.
• Was verloren geht. Verläufe, Masken, Clip-Pfade, use, text, title und Deckkraft an einzelnen Elementen kommen nicht durch die Erlaubnisliste des Cores. Diese Teile fehlen im Block, easy_svg_icon() zeigt sie weiter.
• Bibliotheks-Schalter. Schaltest du die Icon-Bibliothek aus, fehlt die Sammlung ab der nächsten Anfrage. Gespeicherte Blöcke behalten ihren Verweis und zeichnen nichts, bis du sie wieder einschaltest.
• Ein Icon löschen. Gespeicherte Blöcke, die es nutzen, zeichnen nichts mehr. Benenne lieber um, statt zu löschen und neu hinzuzufügen, denn Umbenennen behält den Slug.
• Der Kopieren-Knopf der Bibliothek. Er bietet die Block-Form weiter nur für Icons an, die aus Pfaden und Polygonen bestehen, obwohl das Plugin einfache Formen inzwischen für den Block umbaut.
• Kein Template-Filter. Was du mit easy_svg_icon_markup änderst, erreicht den Block nicht. Nimm easy_svg_registrable_icons.

Siehe auch

• easy_svg_registrable_icons
• easy_svg_icon()
• easy_svg_register_icons()
• easy_svg_core_icon()
• easy_svg_icons_supported()
• EASY_SVG_ICON_COLLECTION
• Icons in Themes ausgeben