easy_svg_registrable_icons

Filter · Easy SVG · Status: Stabil

easy_svg_registrable_icons gibt dir die ganze Icon-Bibliothek, kurz bevor Easy SVG sie bei WordPress (Version 7.1 oder neuer) registriert. Was du zurückgibst, bietet der Core-Block Icon an, und genau das gibt wp_get_icon( 'easy-svg/...' ) aus. Nur hier kannst du dieses Markup ändern, denn die Icon-Registry von WordPress hat keinen eigenen Filter.

Verwendung

add_filter( 'easy_svg_registrable_icons', 'myplugin_registrable_icons' );

function myplugin_registrable_icons( array $icons ): array {
	return $icons;
}

Wann du es brauchst

• Du willst Icons in der Icon-Auswahl des Editors verstecken, etwa Entwürfe, Logos für den internen Gebrauch oder Icons, die ein Kunde nicht wählen soll.
• Du willst Icons für den Icon-Block umfärben oder in der Größe ändern, bevor WordPress sie speichert.
• Du willst der Sammlung easy-svg per Code Icons hinzufügen (aus einem Theme-Ordner, aus einem Build-Schritt), ohne sie in der Bibliothek zu speichern.
• Du willst ändern, was die Auswahl als Namen zeigt, ohne den gespeicherten Titel anzufassen.

Wann nicht:

• Für Templates, die easy_svg_icon() aufrufen oder den Shortcode nutzen. Die lesen das gespeicherte Icon direkt, dort hilft dir easy_svg_icon_markup.
• Um eine eigene Sammlung zu registrieren. Jeder Eintrag landet in easy-svg. Für eine eigene Sammlung rufst du wp_register_icon_collection() und wp_register_icon() selbst auf.

Parameter

Rückgabewert

Standardwert

Die Ausgabe von easy_svg_stored_icons(): jedes Icon der Bibliothek.

Beispiele

Icons in der Auswahl verstecken

Icons, deren Slug mit internal- beginnt, bleiben in der Bibliothek und funktionieren in Templates weiter, aber Redakteure können sie im Icon-Block nicht wählen.

add_filter( 'easy_svg_registrable_icons', 'myplugin_hide_internal_icons' );

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

Jedes Icon folgt der Textfarbe

Das Stylesheet des Cores setzt schon fill: currentColor auf das SVG des Icon-Blocks, aber ein fill direkt am Pfad gewinnt. Entfernst du fest eingetragene Füllfarben an den Pfaden, erreicht die Farbeinstellung des Blocks das Icon.

add_filter( 'easy_svg_registrable_icons', 'myplugin_icons_follow_text_colour' );

function myplugin_icons_follow_text_colour( $icons ) {
	foreach ( (array) $icons as $i => $icon ) {
		if ( empty( $icon['content'] ) ) {
			continue;
		}
		$icons[ $i ]['content'] = preg_replace(
			'/\sfill="(?!none")[^"]*"/i',
			'',
			(string) $icon['content']
		);
	}
	return $icons;
}

fill="none" bleibt absichtlich stehen: Ein Umriss-Icon braucht es, und Easy SVG macht daraus seine Strich-Klassen (siehe So funktioniert es).

Icons aus einem Theme-Ordner ergänzen

add_filter( 'easy_svg_registrable_icons', 'mytheme_add_theme_icons' );

function mytheme_add_theme_icons( $icons ) {
	$sanitizer = function_exists( 'easy_svg_sanitizer' ) ? easy_svg_sanitizer() : null;
	if ( null === $sanitizer ) {
		return $icons;
	}

	foreach ( glob( get_theme_file_path( 'icons/*.svg' ) ) ?: array() as $file ) {
		$slug  = sanitize_title( basename( $file, '.svg' ) );
		$clean = $sanitizer->sanitize( (string) file_get_contents( $file ) );
		if ( '' === $slug || ! is_string( $clean ) ) {
			continue;
		}
		$icons[] = array(
			'slug'    => 'theme-' . $slug,
			'label'   => ucwords( str_replace( '-', ' ', $slug ) ),
			'content' => $clean,
		);
	}

	return $icons;
}

Das läuft bei jeder Anfrage. Bei vielen Dateien cachst du die Liste besser (etwa in einem Transient mit der Theme-Version im Schlüssel). Zwei Einträge mit demselben Slug kollidieren im Core, und der zuerst registrierte gewinnt.

Defensiv: die Vertragsversion prüfen

Der Filter gehört seit EASY_SVG_ICONS_API 1 zum Icon-Vertrag. Einen Filter kann man nicht abfragen, also prüfst du die Konstante.

add_action( 'plugins_loaded', 'myplugin_register_icon_filters' );

function myplugin_register_icon_filters() {
	if ( ! defined( 'EASY_SVG_ICONS_API' ) ) {
		return; // Easy SVG fehlt oder ist älter als 5.4.0.
	}
	add_filter( 'easy_svg_registrable_icons', 'myplugin_hide_internal_icons' );
}

So funktioniert es

Der Filter läuft in easy_svg_boot_icons(), eingehängt auf init mit Priorität 10, nachdem WordPress seine eigenen Sammlungen mit Priorität 0 registriert hat. Dieser Hook wird nur gesetzt, solange die Icon-Bibliothek unter Icons, Einstellungen eingeschaltet ist, und die Funktion bricht unter WordPress ohne wp_register_icon() und wp_register_icon_collection() (vor 7.1) früh ab.

Was für deinen Callback zählt:

• Caching. Die Liste, die du bekommst, stammt aus dem Transient easy_svg_icons (ein Tag), verknüpft mit der Option easy_svg_icons_version, die jede Änderung an einem Icon erhöht. Dein Filter wird nicht zwischengespeichert: Er läuft bei jeder Anfrage, eine Codeänderung wirkt also sofort.
• Nach deinem Filter läuft der content jedes Eintrags durch easy_svg_core_icon(): Kreise, Rechtecke, Ellipsen, Linien und Polylinien werden zu Pfaden, Gruppen werden auf ihre Kinder aufgelöst, und ein Icon, das nur aus Strichen besteht, bekommt die Klassen esvg-stroke, esvg-sw-*, esvg-cap-round und esvg-join-round. Ein kleines Inline-Stylesheet (fill: none; stroke: currentColor) stellt den Strich überall wieder her, wo der Core das Icon ausgibt. Ist dein Markup kein gültiges XML, entfällt dieser Umbau, und dein Markup geht unverändert weiter.
• Danach lässt der Core wp_kses mit seiner eigenen Erlaubnisliste laufen: svg (mit class, xmlns, width, height, viewBox, aria-hidden, role, focusable), path und polygon (mit fill, fill-rule, d bzw. points, transform). Alles andere fällt weg, auch title, Verläufe, Masken, use, text und stroke-Attribute.
• Für die Klassen unterstützte Strichstärken sind 1, 1.25, 1.5, 1.75, 2, 2.5 und 3. Jede andere Stärke fällt auf 1 zurück.

Stolperfallen

• Filter zu spät registriert. Setz ihn in einer Plugin-Datei oder in der functions.php, nicht in einem init-Callback mit einer Priorität über 10.
• Die Liste verlieren. Gib das Array auf jedem Weg zurück. Gibst du nichts zurück, verschwinden alle Icons aus dem Icon-Block (gespeicherte Blöcke zeigen dann im Editor einen Hinweis, dass ihr Icon fehlt).
• Nur gültige Namen. Ein Slug mit Großbuchstaben, Leerzeichen oder Schrägstrich wird still übersprungen. Nutz sanitize_title() und prüf gegen EASY_SVG_ICON_NAME_PATTERN.
• Keine Wirkung auf Templates. easy_svg_icon() und der Shortcode ignorieren diesen Filter.
• Nicht unterstützte Zeichnungen. Alles außer Pfaden und Polygonen (Text, Verläufe, Masken, use) übersteht die Erlaubnisliste des Cores nicht.
• Ein entferntes Icon bricht gespeicherte Blöcke. Ein Block, der mit easy-svg/old-logo gespeichert wurde, zeichnet nichts mehr, sobald der Eintrag fehlt.

Siehe auch

• easy_svg_icon_markup
• easy-svg
• easy_svg_boot_icons()
• easy_svg_stored_icons()
• easy_svg_core_icon()
• EASY_SVG_ICONS_API
• EASY_SVG_STROKE_WIDTHS