Documents et blocs
Le document versionné, le texte enrichi et les blocs d’extension à copie native.
Sur cette page
Structure d’un document
{
"version": 1,
"blocks": [{
"id": "62ce899c-47a4-4f9e-9ffd-995d2fc2e1b9",
"type": "paragraph", "version": 1,
"props": { "text": "Bonjour." }, "children": []
}]
}parseDocument(input, scope) contrôle version, UUID uniques, propriétés et enfants : 500 blocs et huit niveaux maximum. group, columns, synced-pattern et extension acceptent des enfants. Les autres types ne peuvent pas en conserver.
L’enveloppe BlockDocument reste en version 1. Les blocs paragraph, heading, list et quote utilisent désormais la version 2, avec texte enrichi et copie texte cohérente. parseDocument valide d’abord un ancien bloc, applique ses migrations successives puis valide le résultat ; il refuse une version future ou un document corrompu. Les révisions stockées ne sont pas réécrites. Utilisez currentBlockVersion(type) plutôt qu’un numéro commun à tous les types.
Types disponibles
| Portée | Types |
|---|---|
| Contenu | paragraph, heading, list, quote, image, gallery, video, embed, code, button, separator, columns, group, spacer, html, synced-pattern, extension |
| Site | site-title, navigation, content-title, content-body, content-fields, content-terms, content-parent, archive-title, content-list, search-form, template-part |
Les blocs de site exigent la portée template. createBlock(type) conserve une structure initiale de version 1 pour les thèmes existants ; certaines valeurs doivent être complétées avant parseDocument, qui produit la version courante. parseDraftDocument préserve les saisies incomplètes récupérables sans les rendre publiables. Les images peuvent porter mediaId, width, height et sources avec src et width pour le rendu responsive.
availableBlockTransforms et transformBlock exposent les transformations compatibles. Elles préservent les segments de texte, les enfants et les limites de validation, et refusent les conversions avec perte de données. Le plan de l’éditeur parcourt les groupes et colonnes ; une composition synchronisée ou un bloc d’extension y reste une entrée distincte de ses enfants de secours.
Texte enrichi et sécurité
Les paragraphes et titres peuvent porter des segments validés pour gras, italique et liens. Le rendu React échappe le texte. Le bloc html passe par un sanitizer à liste positive ; scripts, handlers d’événements et styles arbitraires sont refusés.
Les intégrations vidéo acceptent des URL YouTube HTTPS transformées vers youtube-nocookie.com. Validez toujours documents et URL, y compris ceux fournis par une intégration.
Déclarer un bloc d’extension
PluginDefinition.blocks contient name, label, version numérique, fields et render(values, context). Le renderer retourne un BlockDocument natif de contenu. L’administration édite les champs déclarés ; aucun composant JavaScript tiers n’est chargé dans le navigateur.
Le document persiste un bloc extension avec pluginId, name, version et values dans props, plus les blocs natifs de secours dans children. Le serveur valide les valeurs et régénère ce secours lors de l’enregistrement explicite. Les UUID sont renouvelés par instance et les limites du document final sont revérifiées.
Un secours ne peut contenir de bloc extension. Une contribution inactive devient non modifiable et conserve son rendu ; on peut détacher sa copie native. Un nouveau bloc inactif sans secours valide doit être retiré ou réactivé avant publication. Une mise à jour du renderer prend effet au prochain réenregistrement, pas rétroactivement sur tous les documents. props.version versionne le contrat de la contribution et reste distinct de la version native du bloc extension.
pnpm cms block:create agency.notice /chemin/neuf/notice