fswp-block-developer

FSWP Block Developer

Grundlegend (immer anwenden): fswp-developer/references/lean-coding.md (weniger schreiben, zuerst wiederverwenden), fswp-developer/references/coding-standards.md (Codierungsstandards, Doku, i18n, Barrierefreiheit) und fswp-security-engineer (Eingabe, Ausgabe, Autorisierung).

Verwende zuerst Kernblöcke; schreibe einen benutzerdefinierten Block nur, wenn Kernblöcke und Patterns die Anforderung nicht abbilden können. Offizielle Referenzen: Block Editor Handbook Links in fswp-developer/references/official-docs.md. Prüfe die Mindest-WordPress-Version für jede API gegen die im Projekt deklarierte Mindestversion.

Aufbau

blocks/my-block/
  block.json      name, title, category, attributes, supports, render, editorScript, viewScriptModule, style
  edit.js         Editor-UI (verwendet useBlockProps)
  save.js         Statisches Markup, oder weglassen für dynamische Blöcke
  render.php      Server-Rendering für dynamische Blöcke
  view.js         Frontend-Verhalten (Modul)
  style.scss / editor.scss

Von Metadaten registrieren: register_block_type( __DIR__ . '/build/my-block' ) bei init (verwende eine benannte Funktion für den init-Callback). Setze "apiVersion": 3 (aktuell seit WordPress 6.3) und füge "$schema": "https://schemas.wp.org/trunk/block.json" hinzu. Feld-für-Feld-Referenz, geprüft gegen das Block Editor Handbook: references/block-json.md.

Entscheidungen

Frage	Wahl
Ausgabe hängt nur von gespeicherten Attributen ab	Statischer Block (save.js)
Ausgabe hängt von Live-Daten ab, muss sich ohne erneutes Speichern ändern oder enthält Logik	Dynamischer Block (render.php); save gibt null zurück oder nur InnerBlocks
Verschachtelte Inhalte	InnerBlocks mit allowedBlocks und template
Attribut an Daten binden (Beitragsmeta, benutzerdefinierte Quelle)	Block Bindings API (register_block_bindings_source) wenn die WordPress-Mindestversion dies erlaubt
Alternative Voreinstellungen eines bestehenden Blocks	Blockvariationen oder -stile, kein neuer Block
Wiederverwendbares Layout	Ein Pattern, kein Block

Regeln

• Attribute: gib jedem Attribut einen type und default; beziehe sie konsistent aus Markup oder Kommentaren; validiere in render.php.
• Verwende supports (color, spacing, typography, align, anchor) anstatt Steuerungen zu schreiben.
• Editor-Markup muss useBlockProps() verwenden; dynamisches PHP verwendet get_block_wrapper_attributes().
• render.php (block.json render, WordPress 6.1+) erhält $attributes, $content und $block (ein WP_Block). Es wird einmal pro Blockinstanz auf der Seite geladen, deklariere daher niemals Funktionen oder Klassen darin; rufe gemeinsamen Code aus einer anderen Datei auf.
• Skripte vs. Module: viewScript ist für klassische Skripte (und alles, was von WordPress-Skripten abhängt); viewScriptModule (6.5+) ist für Skriptmodule wie die Interactivity API. Sie sind nicht austauschbar, daher keine Abhängigkeiten zwischen beiden mischen.
• Alles in render.php escapen (fswp-security-engineer); Attribute sind Benutzereingaben.
• Das Ändern des gespeicherten Markups eines ausgelieferten statischen Blocks zerbricht bestehende Inhalte. Füge einen deprecated-Eintrag mit dem alten save, den Attributen und einer migrate-Funktion hinzu, ändere dann den Block.
• Zeichenketten übersetzen (__() mit der Textdomäne) in JS und PHP; wp_set_script_translations oder block.json textdomain.
• Lade Frontend-Skripte nur dort, wo der Block gerendert wird (block.json viewScriptModule/script erledigen dies).

Patterns

Mehr Details zu Patterns, Variationen, Block-Hooks und Bindings: references/patterns-variations.md. Tiefe der Interactivity API (Server-Rendering, asynchrone Aktionen, data-wp-each, Watcher, Performance): references/interactivity.md.

Registriere in PHP mit register_block_pattern() (und register_block_pattern_category()), oder als Dateien im patterns/-Verzeichnis eines Themes. Patterns verwenden Voreinstellungen und übersetzten Text; keine Remote-Bilder; gib ihnen einen klaren Titel, Kategorien und Schlüsselwörter.

Interactivity API

Server-gerendertes Markup plus kleines reaktives Verhalten, kein Framework nötig.

• Aktiviere mit "supports": { "interactivity": true } und "viewScriptModule": "file:./view.js".
• Markup-Direktiven: data-wp-interactive="namespace", data-wp-context='{"open":false}', data-wp-on--click="actions.toggle", data-wp-bind--hidden="!context.open", data-wp-class--is-open="context.open", data-wp-text="state.label".
• Store in view.js: import { store, getContext } from '@wordpress/interactivity'; store( 'namespace', { state: {...}, actions: { toggle() { const c = getContext(); c.open = ! c.open; } } } );
• Seed-Server-Status mit wp_interactivity_state( 'namespace', array(...) ), damit der erste Paint korrekt ist und kein Flackern auftritt. Halte den Status serialisierbar.
• Namespace alles, um Kollisionen zu vermeiden; setze niemals Geheimnisse in Status oder Kontext (beide werden in die Seite gedruckt).
• Für Barrierefreiheit: binde aria-expanded und Fokus-Behandlung an den Status und teste die Tastaturnutzung.

Build und Test

npx @wordpress/create-block als Ausgangspunkt; @wordpress/scripts für build, start, lint-js, lint-style, test-unit-js. Liefere die gebauten Dateien zusammen mit src/, package.json und der Lockdatei aus (Verzeichnisregel für kompilierten Code). Teste im Editor (einfügen, bearbeiten, speichern, neu laden, zur Code-Ansicht wechseln) und im Frontend. Übergib an fswp-qa-engineer.