Start » Dokumentation » So verbindest du deine BlockStyle-Komponenten

So verbindest du deine BlockStyle-Komponenten

In diesem Abschnitt wird gezeigt, wie ein Opacity-Style für Blöcke implementiert wird, sowohl im Editor per JavaScript als auch serverseitig per PHP. Beide Implementierungen müssen vorhanden sein.

Inhaltsverzeichnis

JavaScript-Implementierung

Schritt 1: Renderer registrieren

Rufe die WordPress-Editor-Hooks und den Datastore ab, um deinen Renderer wie unten gezeigt zu registrieren. Stelle sicher, dass dies auf domReady ausgeführt wird, um auf den Datastore zu warten.

/**
 * Lokale WP-Referenzen.
 *
 * - `addFilter`: Ermöglicht das Modifizieren von Blockeinstellungen oder Editorverhalten.
 * - `dispatch`: Zugriff auf Datastores, z.B. zum Registrieren von Renderern.
 * - `domReady`: Führt Code aus, wenn der Editor-DOM vollständig geladen ist.
 */
const {
    hooks: { addFilter },
    data: { dispatch },
    domReady,
} = wp;

/**
 * Registriert den Opacity-Renderer, sobald der Editor bereit ist.
 *
 * - `opacity` ist der Style-Key im Block-Attribut.
 * - `renderStyles` generiert das CSS für den Block basierend auf seinen Attributen.
 * - `10` ist die Priorität des Renderers (wie add_filter in WordPress).
 */
domReady( () => {
    dispatch( 'quantumpress/viewports' )?.registerRenderer(
        'opacity',
        renderStyles,
        10
    );
} );

Schritt 2: Hilfsfunktion zur CSS-Erzeugung

stylesToCss wandelt Key-Value-Style-Objekte in gültige CSS-Strings um und trennt so die CSS-Generierung von der Hauptlogik des Renderers.

/**
 * Wandelt ein Objekt mit CSS-Eigenschaften in einen gültigen CSS-String um.
 *
 * Beispiel:
 * { opacity: 0.5, color: 'red' } => "opacity:0.5;color:red;"
 *
 * @param styles - Objekt mit CSS-Eigenschafts-Wert-Paaren
 *
 * @returns Ein String mit den zusammengefügten CSS-Regeln.
 */
function stylesToCss( styles ) {
    let css = '';

    for ( const property in styles ) {
        if ( Object.prototype.hasOwnProperty.call( styles, property ) ) {
            css += property + ':' + styles[ property ] + ';';
        }
    }

    return css;
}

Schritt 3: CSS aus Block-Attributen rendern

Die Funktion renderStyles liest das Opacity-Attribut, wandelt es von Prozent in Dezimal um und gibt einen CSS-String für die Editor-Vorschau aus.

/**
 * Render CSS für den Opacity-Style.
 *
 * Wandelt den gespeicherten Wert (0–100) in Dezimal (0–1) um
 * und gibt einen CSS-Regel-String für den angegebenen Selektor zurück.
 *
 * @param styles - Style-Attribute des Blocks
 * @param options.selector - CSS-Selektor des Blocks
 *
 * @returns Ein String mit der CSS-Regel
 */
function renderStyles(
    styles,
    { selector }
): string {
    const { value } = styles.opacity || {};

    if ( value === undefined ) {
        return '';
    }

    const compiled = {
        opacity: +(value / 100).toFixed( 2 ),
    };

    return selector + '{' + stylesToCss( compiled ) + '}';
}

PHP-Implementierung

Schritt 1: Opacity-Renderer definieren

Serverseitig wird eine Klasse erstellt, die die Opacity-Styles verarbeitet.
Sie wandelt einen gespeicherten Prozentwert (0–100) in einen CSS-Dezimalwert (0.0–1.0) um und liefert einen CSS-Regel-String.

Der constructor hängt die Methode render an einen dynamischen WordPress-Filter:

quantum_viewports_register_renderer_${styleKey}

Schritt 2: Hilfsmethode zur CSS-Erzeugung

Die kleine Hilfsmethode stylesToCss wandelt ein assoziatives Array von CSS-Eigenschaften in einen gültigen CSS-String um. Sie entspricht der JavaScript-Funktion stylesToCss und sorgt für konsistente Ausgabe zwischen Editor und Frontend.

Schritt 3: Opacity-CSS rendern

Die render-Methode:

  1. Liest den gespeicherten Opacity-Wert aus dem Block aus.
  2. Wandelt ihn von 0–100 in 0.0–1.0 um.
  3. Gibt eine CSS-Regel zurück, wobei der Platzhalter % für den Block-Selektor verwendet wird.
<?php

defined( 'ABSPATH' ) || exit;

/**
 * Class OpacityRenderer
 *
 * Verarbeitet Opacity-Styles für Blöcke.
 * Wandelt Prozentwerte in gültige CSS-Opacity-Regeln um.
 *
 * Registrierung:
 *  - Gehookt an 'quantum_viewports_register_renderer_opacity'
 *    und wird beim Generieren der Viewport-Styles aufgerufen.
 */
class OpacityRenderer
{
    /** @var string Style-Key für diesen Renderer */
    protected string $property = 'opacity';

    /** Konstruktor: registriert den Render-Callback */
    public function __construct()
    {
        add_filter(
            'quantum_viewports_register_renderer_' . $this->property,
            [ $this, 'render' ],
            10,
            3
        );
    }

    /** Wandelt ein Array von CSS-Eigenschaften in einen CSS-String um */
    protected function stylesToCss( array $styles ): string
    {
        $css = '';
        foreach ( $styles as $key => $value ) {
            $css .= $key . ':' . $value . ';';
        }
        return $css;
    }

    /** Rendert die CSS-Regel für Opacity */
    public function render( string $css, array $styles, array $valids ): string
    {
        $value = $styles['value'] ?? null;

        if ( $value === null ) {
            return '';
        }

        $compiled = [
            'opacity' => number_format( $value / 100, 2, '.', '' ),
        ];

        return '%' . '{' . $this->stylesToCss( $compiled ) . '}';
    }
}

Wie alles zusammenwirkt

  • Der JavaScript-Renderer steuert die Editor-Vorschau. Er liest Block-Attribute, wandelt Werte um und erzeugt CSS in Echtzeit.
  • Der PHP-Renderer generiert das finale CSS für das Frontend. Er stellt sicher, dass die im Editor angezeigten Styles auf der Website konsistent wiedergegeben werden.
  • Beide Renderer teilen denselben Style-Key (opacity) und die CSS-Generierungslogik (stylesToCss), wodurch konsistente Ergebnisse zwischen Editor und Frontend gewährleistet sind.