window.EasySvgPanel

JavaScript · Easy SVG · Status: Stabil

window.EasySvgPanel ist das eine globale Objekt, mit dem ein Add-on spricht, wenn es das Icons-Panel erweitert. Das Panel legt es auf der Icons-Seite an, bevor es irgendetwas zeichnet. Dein Script registriert darauf Tabs und Icon-Sammlungen, und das Panel übernimmt sie, egal ob du vor oder nach seinem ersten Rendern registrierst.

Verwendung

window.EasySvgPanel;

// Mitglieder, auf die sich ein Add-on verlassen darf:
window.EasySvgPanel.api; // Zahl, die Stufe des Panel-Vertrags
window.EasySvgPanel.registerTab( tab );
window.EasySvgPanel.registerCollections( provider ); // Stufe 3

Wann du es brauchst

• In einem Script, das du über easy_svg_panel_enqueue einreihst, um einen Tab oder einen Sammlungs-Anbieter hinzuzufügen.
• Um über api herauszufinden, welche Vertragsstufe das installierte Panel spricht.

Wann nicht:

• Auf einer anderen Seite als Icons. Das Objekt gibt es nur dort, wo das Panel-Bundle läuft.
• Um Funktionen auf get(), list(), subscribe() oder collectionProviders() aufzubauen. Es gibt sie, das Panel nutzt sie selbst, aber die readme nennt sie nicht als Teil des Add-on-Vertrags, sie können sich also ändern.
• Um Daten von PHP an dein Script zu geben. Dafür nimmst du dein eigenes Handle mit wp_add_inline_script().

Parameter

Keine. window.EasySvgPanel ist ein Objekt, keine Funktion. Seine Mitglieder stehen unten.

Rückgabewert

Standardwert

undefined, bis das Panel-Bundle gelaufen ist. Auf der Icons-Seite legt es die allererste Anweisung von build/panel.js an, jedes Script, das vom Panel-Handle abhängt, sieht es also.

Beispiele

Prüfen, ob die Registry da ist

Ein Script, das auch woanders geladen werden könnte (etwa von einem Build-Tool, das mehrere Einstiegspunkte bündelt), sollte ohne Panel leise aussteigen.

( function () {
	const panel = window.EasySvgPanel;

	if ( ! panel || 'function' !== typeof panel.registerTab ) {
		return;
	}

	// Ab hier kannst du gefahrlos registrieren.
} )();

Ein Bundle, ein Tab und eine Sammlung

Ein Add-on kann beide Erweiterungspunkte aus derselben Datei nutzen. Die Tab-Komponente nutzt wp.element, also das React, das WordPress mitbringt und das auch das Panel verwendet.

( function () {
	const panel = window.EasySvgPanel;
	if ( ! panel ) {
		return;
	}

	const { createElement: el } = window.wp.element;
	const { __ } = window.wp.i18n;

	function ReportTab() {
		return el( 'p', null, __( 'Nothing to report yet.', 'myaddon' ) );
	}

	panel.registerTab( {
		id: 'myaddon-report',
		label: __( 'SVG report', 'myaddon' ),
		area: 'inspect',
		render: () => el( ReportTab ),
	} );

	if ( 'function' === typeof panel.registerCollections ) {
		panel.registerCollections( {
			id: 'myaddon',
			load: () => Promise.resolve( [] ),
		} );
	}
} )();

Das Script richtig laden (PHP)

Die Registry existiert nur deshalb, wenn dein Script läuft, weil dein Script vom Panel-Handle abhängt.

add_action( 'easy_svg_panel_enqueue', 'myaddon_enqueue_panel' );

function myaddon_enqueue_panel( $handle ) {
	wp_enqueue_script(
		'myaddon-panel',
		plugins_url( 'assets/panel.js', __FILE__ ),
		array( $handle, 'wp-element', 'wp-i18n' ),
		'1.0.0',
		true
	);
}

So funktioniert es

Die Registry steht in src/panel/registry.js und wird von installRegistry() angelegt, das src/panel/main.jsx aufruft, bevor es die React-Wurzel erzeugt.

• Einmal angelegt. Gibt es window.EasySvgPanel schon mit dem internen Kennzeichen __installed, passiert nichts. Sonst entsteht ein frisches Objekt mit zwei privaten Maps (Tabs und Sammlungs-Anbieter, beide nach id) und einer Menge von Listenern.
• Kaum Prüfung. registerTab() speichert das Objekt nur mit id und render-Funktion, registerCollections() nur mit id und load-Funktion. Alles andere wird ohne Fehlermeldung ignoriert. Ein zweiter Aufruf mit derselben ID ersetzt den ersten.
• Dein Objekt wird so gespeichert, wie es ist. Unbekannte Felder bleiben erhalten, das Panel liest nur die, die es versteht.
• Jede Registrierung benachrichtigt. Die Listener werden nacheinander aufgerufen, und wirft einer eine Ausnahme, wird sie abgefangen, die Registrierung läuft weiter.
• Das Panel hört zu. Die Hauptkomponente des Panels meldet sich beim Einhängen an und rendert bei jeder Benachrichtigung neu. Direkt nach dem Anmelden liest sie die Registry noch einmal, damit eine Registrierung zwischen erstem Rendern und Anmeldung nicht verloren geht. Auch der Tab Icon-Bibliothek meldet sich an und lädt bei jeder Benachrichtigung alle Sammlungs-Anbieter neu.

Stolperfallen

• Weise window.EasySvgPanel nichts zu. Liegt dort schon ein Objekt mit gesetztem __installed, überspringt das Panel seine eigene Einrichtung und nimmt deins, und damit ist das Panel für jedes Add-on auf der Site kaputt.
• Bündle weder registry.js noch eine eigene React-Kopie. Nimm das globale Objekt, und für Elemente wp.element oder window.React. Eine zweite React-Kopie lässt Hooks mit „Invalid hook call“ scheitern.
• Alle Add-ons teilen sich die IDs. Stell ihnen den Slug deines Add-ons voran, bei Tabs wie bei Sammlungs-Anbietern.
• Stille Fehler. Fehlt render oder load, wird der Aufruf ohne Meldung ignoriert. Zeigt sich dein Tab nicht, lass dir in der Browser-Konsole zuerst window.EasySvgPanel.get( 'deine-id' ) ausgeben.
• Das Objekt gibt es nur auf der Icons-Seite, und nur, wenn build/panel.js geladen wurde.

Siehe auch

• window.EasySvgPanel.registerTab()
• window.EasySvgPanel.registerCollections()
• window.EasySvgPanel.api
• easy_svg_panel_enqueue
• easy_svg_panel_menu_tabs
• window.EasySvgPanelData
• Ein Add-on für das Icons-Panel bauen