fswp-block-developer

FSWP Block Developer

Fondamental (toujours appliqué) : fswp-developer/references/lean-coding.md (écrire moins, réutiliser d'abord), fswp-developer/references/coding-standards.md (normes de codage, documentation, i18n, accessibilité), et fswp-security-engineer (entrée, sortie, autorisation).

Utilisez d'abord les blocs de base ; ne créez un bloc personnalisé que lorsque les blocs et motifs de base ne peuvent pas exprimer le besoin. Références officielles : liens du Block Editor Handbook dans fswp-developer/references/official-docs.md. Vérifiez la version minimale de WordPress pour chaque API par rapport à la version minimale déclarée du projet.

Anatomie

blocks/my-block/
  block.json      name, title, category, attributes, supports, render, editorScript, viewScriptModule, style
  edit.js         interface de l'éditeur (utilise useBlockProps)
  save.js         balisage statique, ou omettre pour les blocs dynamiques
  render.php      rendu serveur pour les blocs dynamiques
  view.js         comportement frontal (module)
  style.scss / editor.scss

Enregistrement à partir des métadonnées : register_block_type( __DIR__ . '/build/my-block' ) sur init (utilisez une fonction nommée pour le callback init). Définissez "apiVersion": 3 (actuel depuis WordPress 6.3) et ajoutez "$schema": "https://schemas.wp.org/trunk/block.json". Référence champ par champ, vérifiée par rapport au Block Editor Handbook : references/block-json.md.

Décisions

Question	Choisissez
La sortie ne dépend que des attributs enregistrés	Bloc statique (save.js)
La sortie dépend de données en direct, doit changer sans réenregistrement, ou contient de la logique	Bloc dynamique (render.php) ; save renvoie null ou uniquement InnerBlocks
Contenu imbriqué	InnerBlocks avec allowedBlocks et template
Lier un attribut à des données (méta d'article, source personnalisée)	API Block Bindings (register_block_bindings_source) si la version minimale de WordPress le permet
Préréglages alternatifs d'un bloc existant	Variations ou styles de bloc, pas un nouveau bloc
Mise en page réutilisable	Un motif, pas un bloc

Règles

• Attributs : donnez à chaque attribut un type et une default ; sourcez-les à partir du balisage ou des commentaires de manière cohérente ; validez dans render.php.
• Utilisez supports (couleur, espacement, typographie, alignement, ancre) au lieu d'écrire des contrôles.
• Le balisage de l'éditeur doit utiliser useBlockProps() ; le PHP dynamique utilise get_block_wrapper_attributes().
• render.php (block.json render, WordPress 6.1+) reçoit $attributes, $content et $block (un WP_Block). Il se charge une fois par instance de bloc sur la page, donc ne déclarez jamais de fonctions ou de classes à l'intérieur ; appelez le code partagé depuis un autre fichier.
• Scripts vs modules : viewScript est pour les scripts classiques (et tout ce qui dépend des scripts WordPress) ; viewScriptModule (6.5+) est pour les modules de script comme l'API d'interactivité. Ils ne sont pas interchangeables, donc ne mélangez pas les dépendances entre les deux.
• Échappez tout dans render.php (fswp-security-engineer) ; les attributs sont des entrées utilisateur.
• Modifier le balisage enregistré d'un bloc statique déjà livré casse le contenu existant. Ajoutez une entrée deprecated avec l'ancien save, les attributs et une fonction migrate, puis modifiez le bloc.
• Traduisez les chaînes (__() avec le domaine de texte) en JS et PHP ; wp_set_script_translations ou block.json textdomain.
• Chargez les scripts frontaux uniquement là où le bloc s'affiche (block.json viewScriptModule/script le font).

Motifs

Plus de détails sur les motifs, les variations, les accroches de blocs et les liaisons : references/patterns-variations.md. Approfondissement de l'API d'interactivité (rendu serveur, actions asynchrones, data-wp-each, watchers, performances) : references/interactivity.md.

Enregistrez en PHP avec register_block_pattern() (et register_block_pattern_category()), ou sous forme de fichiers dans le dossier patterns/ d'un thème. Les motifs utilisent des préréglages et du texte traduit ; pas d'images distantes ; donnez-leur un titre clair, des catégories et des mots-clés.

API d'interactivité

Balisage rendu côté serveur avec un petit comportement réactif, sans framework nécessaire.

• Activez avec "supports": { "interactivity": true } et "viewScriptModule": "file:./view.js".
• Directives de balisage : 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 dans view.js : import { store, getContext } from '@wordpress/interactivity'; store( 'namespace', { state: {...}, actions: { toggle() { const c = getContext(); c.open = ! c.open; } } } );
• Initialisez l'état serveur avec wp_interactivity_state( 'namespace', array(...) ) pour que le premier affichage soit correct et sans flash. Gardez l'état sérialisable.
• Utilisez des espaces de noms pour tout afin d'éviter les collisions ; ne mettez jamais de secrets dans l'état ou le contexte (les deux sont imprimés dans la page).
• Pour l'accessibilité, liez aria-expanded et la gestion du focus à l'état, et testez l'utilisation au clavier.

Build et tests

npx @wordpress/create-block pour un point de départ ; @wordpress/scripts pour build, start, lint-js, lint-style, test-unit-js. Livrez les fichiers générés avec src/, package.json et le fichier de verrouillage (règle de répertoire pour le code compilé). Testez dans l'éditeur (insérer, modifier, enregistrer, recharger, passer en vue code) et sur le front-end. Passez à fswp-qa-engineer.