Vlastný blok Gutenberg s @wordpress/scripts

Ak ste niekedy v editore videli hlásenie „Blok sa vykresľuje ako prázdny“ alebo blok, ktorý funguje lokálne, ale v produkcii zmizne, problém takmer vždy pochádza z rovnakého miesta: zle pripojená zostava, zle uložené prvky alebo chýbajúce vykreslenie na serveri, keď je na ňom váš blok závislý.

Problém / Potreba

Chcieť vytvoriť čistý, udržiavateľný a kompatibilný vlastný blok Gutenberg WordPress 6.9.4 (apríl 2026) bez manuálneho vytvárania skriptového dotazu pre každú iteráciu. Typická požiadavka: blok „Upozornenie“ (alebo „CTA“, „FAQ“, „Produkt“ atď.) s:

• un Editor Reactu (Ovládacie prvky inšpektora, farby, možnosti)
• un spoľahlivý predok (bez závislosti od runtime prostredia JS na strane návštevníka),
• une moderný stavebný reťazec via @wordpress/scripts (Webpack/Babel pripravený na použitie),
• une registrácia majetku robustný cez block.json a metadáta.

Nakoniec budete vedieť, ako dodať kompletný blok vo forme zapojiťs zostavovaním, verzovaním, internacionalizáciou a renderovaním na strane servera (dynamický blok), ak je to relevantné. Zdôrazňujem dynamické bloky, pretože som často videl, ako sa „statické“ bloky stali nezvládnuteľnými hneď, ako obsah musel závisieť od globálnych možností, CPT alebo kontextu.

Rýchle zhrnutie

• Vytvoríme plugin, ktorý uloží blok cez block.json et register_block_type().
• Používame @wordpress/scripts pre stavbu src/index.js na build/index.js + súbor .asset.php.
• Zapíšeme blok s používateľské rozhranie na strane editora (JS) a vykresľovanie na strane servera (PHP), aby sa predišlo nezrovnalostiam medzi front-endom a editorom.
• CSS/JS načítavame cez polia editorScript, style, editorStyle du block.json.
• Riešime body, ktoré spôsobujú problémy v produkcii: cesty, vyrovnávacia pamäť, závislosti, verzia PHP a registračné hooky.

Kedy použiť toto riešenie

• Chceš blok na opakované použitie sur niekoľko stránky, dodávané ako plugin.
• Potrebujete stabilizovaný Na strane front-endu (SEO, výkon, kompatibilita s vyrovnávacou pamäťou): odporúča sa dynamický blok.
• Chcete sa vyhnúť kopírovaniu a vkladaniu úryvku dotazu a prijať štandardný postup WordPress : block.json + zostaviť.
• Váš blok by sa mal vyvíjať (nové možnosti, variácie, štýly) bez narušenia existujúceho obsahu.
• Pracujete ako tím: budovanie prostredníctvom @wordpress/scripts štandardizuje prostredie.

Kedy toto riešenie NEPOUŽÍVAŤ

• Potrebujete len jednoduchý obsah: a blokový vzor (blokový vzor) je často postačujúci bez JS. Pozri Blokové vzory.
• Hľadáte zložité, ale nelogické rozloženie: a skupinový blok + globálne štýly + variácie môžu nahradiť vlastný blok.
• Nemôžete spravovať krok zostavenia (CI/CD, Node): v tomto prípade použite doplnok pre zostavovanie (scaffold) a potom pridajte priečinok zostavenia a vyhnite sa spúšťaniu Node v produkčnom prostredí.
• Nachádzate sa v uzamknutom prostredí, kde je Node zakázaný: môžete doručovať iba zostavené súbory, ale stratíte vývojovú slučku.

Predpoklady / pred začatím

Predpokladám, že vyvíjate pre WordPress 6.9.4 a PHP 8.1+. Mnoho starších tutoriálov dnes nefunguje, pretože nepoužívajú... block.json správne alebo zabudnite .asset.php.

• WordPress : 6.9.4 (alebo novšia).
• PHP 8.1+ (odporúčané). Referencia: Podporované verzie PHP.
• Node.js : nedávna LTS (18/20/22 v závislosti od vášho stacku). Vyhnite sa EOL verziám.
• Prístup : testovacie/lokálne prostredie. Netestujte zostavenie bloku priamo v produkcii bez zálohy.
• outils :
  • WP-CLI (voliteľné, ale užitočné).
  • Plugin pre protokoly (alebo prístup debug.log).

Prevencia:

• umožniť WP_DEBUG et WP_DEBUG_LOG vo vašom testovacom prostredí.
• Ak používate vyrovnávaciu pamäť (plugin, Varnish, Cloudflare), naplánujte si jej vyčistenie: Často som videl, že sa CSS bloku „nenačíta“, keď išlo len o agresívnu vyrovnávaciu pamäť.

Užitočné úradné dokumenty:

• Metadáta bloku (block.json)
• @wordpress/skripty
• typ_bloku_registra()

Naivný prístup (a prečo sa mu vyhnúť)

Klasika, ktorú vidím aj v roku 2026: „ručne vyrobený“ blok s veľkým wp_enqueue_script v wp_enqueue_scripts, bez .asset.php, bez deklarovaných závislostí a niekedy dokonca aj bez block.jsonFunguje to „pre mňa“, potom sa to po aktualizácii WordPressu/Gutenbergu pokazí.

Naivný príklad (nebude sa opakovať)

<?php
// Mauvaise pratique : charge partout, pas seulement dans l'éditeur, dépendances non gérées.
add_action( 'wp_enqueue_scripts', function () {
	wp_enqueue_script(
		'mon-bloc',
		plugins_url( 'build/index.js', __FILE__ ),
		array( 'wp-blocks', 'wp-element', 'wp-editor' ), // Souvent faux/incomplet.
		'1.0.0',
		true
	);
} );

Prečo je to problém:

• výkon JS bloku sa vzťahuje na celý front-end, aj keď sa nepoužije žiadny blok.
• Závislosti Ručne zostavený zoznam sa vždy ukáže ako nesprávny. WordPress vygeneruje .asset.php práve z toho dôvodu.
• údržba : duplikujete logiku registrácie aktív namiesto použitia metadát.
• Riziko konfliktu : globálny popisovač, kolízie a skripty načítané v nesprávnom kontexte.

Správny prístup – podrobný návod

Cieľ: plugin bpca-alert-block ktorý pridá blok „Upozornenie“ s:

• názov + obsah,
• úroveň (informácie/úspech/pozornosť/chyba),
• možnosť „ikona“ (áno/nie),
• Front-end rendering v PHP (dynamické bloky) pre zabezpečenie konzistencie a umožnenie budúceho vývoja.

Krok 1 – Vytvorenie štruktúry pluginu

Dans wp-content/plugins/ :

mkdir -p bpca-alert-block/src bpca-alert-block/build bpca-alert-block/assets

Vytvorte hlavný súbor:

<?php
/**
 * Plugin Name: BPCA Alert Block
 * Description: Bloc Gutenberg "Encart Alerte" (dynamic block) avec build via @wordpress/scripts.
 * Version: 1.0.0
 * Requires at least: 6.9
 * Requires PHP: 8.1
 * Author: BPCA
 * License: GPL-2.0-or-later
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

define( 'BPCA_ALERT_BLOCK_FILE', __FILE__ );
define( 'BPCA_ALERT_BLOCK_DIR', __DIR__ );

require_once BPCA_ALERT_BLOCK_DIR . '/includes/class-bpca-alert-block.php';

add_action( 'init', array( 'BPCA\AlertBlock\Plugin', 'init' ) );

vytvoriť includes/class-bpca-alert-block.php :

<?php
namespace BPCAAlertBlock;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

final class Plugin {

	public static function init(): void {
		// Enregistre le bloc via block.json + render_callback.
		add_action( 'init', array( __CLASS__, 'register_block' ) );
	}

	public static function register_block(): void {
		$block_json = BPCA_ALERT_BLOCK_DIR . '/block.json';

		// register_block_type() sait lire block.json et enregistrer les assets déclarés.
		register_block_type(
			$block_json,
			array(
				'render_callback' => array( __CLASS__, 'render' ),
			)
		);
	}

	/**
	 * Rendu serveur (dynamic block).
	 *
	 * @param array  $attributes Attributs du bloc.
	 * @param string $content    Contenu interne (InnerBlocks), non utilisé ici.
	 * @return string HTML rendu.
	 */
	public static function render( array $attributes, string $content ): string {
		$level   = isset( $attributes['level'] ) ? sanitize_key( $attributes['level'] ) : 'info';
		$title   = isset( $attributes['title'] ) ? sanitize_text_field( $attributes['title'] ) : '';
		$message = isset( $attributes['message'] ) ? wp_kses_post( $attributes['message'] ) : '';
		$icon    = ! empty( $attributes['showIcon'] );

		$allowed_levels = array( 'info', 'success', 'warning', 'error' );
		if ( ! in_array( $level, $allowed_levels, true ) ) {
			$level = 'info';
		}

		$classes = array(
			'bpca-alert',
			'bpca-alert--' . $level,
		);

		$icon_html = '';
		if ( $icon ) {
			// Icônes simples en SVG inline (pas de dépendance externe).
			$icon_html = '<span class="bpca-alert__icon" aria-hidden="true">' . self::get_icon_svg( $level ) . '</span>';
		}

		$title_html = '';
		if ( $title !== '' ) {
			$title_html = '<div class="bpca-alert__title">' . esc_html( $title ) . '</div>';
		}

		// Note : $message est déjà filtré via wp_kses_post() mais on l'échappe en contexte HTML.
		$message_html = '';
		if ( $message !== '' ) {
			$message_html = '<div class="bpca-alert__message">' . $message . '</div>';
		}

		$html  = '<div class="' . esc_attr( implode( ' ', $classes ) ) . '" role="note">';
		$html .= $icon_html;
		$html .= '<div class="bpca-alert__body">' . $title_html . $message_html . '</div>';
		$html .= '</div>';

		return $html;
	}

	private static function get_icon_svg( string $level ): string {
		// SVG minimalistes. Vous pouvez les remplacer par vos propres assets.
		switch ( $level ) {
			case 'success':
				return '<svg viewBox="0 0 24 24" width="20" height="20" focusable="false"><path d="M9 16.2 4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z"></path></svg>';
			case 'warning':
				return '<svg viewBox="0 0 24 24" width="20" height="20" focusable="false"><path d="M1 21h22L12 2 1 21zm12-3h-2v2h2v-2zm0-8h-2v6h2V10z"></path></svg>';
			case 'error':
				return '<svg viewBox="0 0 24 24" width="20" height="20" focusable="false"><path d="M12 2C6.5 2 2 6.5 2 12s4.5 10 10 10 10-4.5 10-10S17.5 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"></path></svg>';
			case 'info':
			default:
				return '<svg viewBox="0 0 24 24" width="20" height="20" focusable="false"><path d="M11 17h2v-6h-2v6zm0-8h2V7h-2v2zm1-7C6.5 2 2 6.5 2 12s4.5 10 10 10 10-4.5 10-10S17.5 2 12 2z"></path></svg>';
		}
	}
}

Krok 2 – Pridajte block.json (metadáta + prvky)

vytvoriť block.json v koreňovom adresári pluginu:

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "bpca/alert",
	"title": "Encart Alerte (BPCA)",
	"category": "widgets",
	"icon": "warning",
	"description": "Affiche un encart d'alerte avec niveau et option d'icône.",
	"textdomain": "bpca-alert-block",
	"attributes": {
		"level": { "type": "string", "default": "info" },
		"title": { "type": "string", "default": "" },
		"message": { "type": "string", "default": "" },
		"showIcon": { "type": "boolean", "default": true }
	},
	"supports": {
		"anchor": true,
		"html": false
	},
	"editorScript": "file:./build/index.js",
	"style": "file:./build/style-index.css",
	"editorStyle": "file:./build/index.css"
}

Praktické poznámky:

• apiVersion: 3 je súčasným základom pre moderné bloky.
• poľa file: spúšťa automatické ukladanie aktív s verziami prostredníctvom .asset.php vygenerované.
• supports.html: false bráni používateľovi v „úpravách v HTML“ a narušení štruktúry.

Krok 3 – Nainštalujte @wordpress/scripts a nakonfigurujte package.json

V priečinku s pluginom:

npm init -y
npm install --save-dev @wordpress/scripts

Vymeňte package.json (alebo prispôsobiť):

{
	"name": "bpca-alert-block",
	"version": "1.0.0",
	"private": true,
	"scripts": {
		"start": "wp-scripts start",
		"build": "wp-scripts build",
		"lint:js": "wp-scripts lint-js",
		"format": "wp-scripts format"
	},
	"devDependencies": {
		"@wordpress/scripts": "^30.0.0"
	}
}

Referencia: @wordpress/skripty.

Krok 4 — Napíšte kód pre blok (editor) do src/

vytvoriť src/index.js :

import { registerBlockType } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
import {
	InspectorControls,
	useBlockProps,
	RichText,
} from '@wordpress/block-editor';
import {
	PanelBody,
	SelectControl,
	ToggleControl,
	TextControl,
} from '@wordpress/components';

import './editor.css';
import './style.css';

registerBlockType( 'bpca/alert', {
	edit: ( { attributes, setAttributes } ) => {
		const { level, title, message, showIcon } = attributes;

		const blockProps = useBlockProps( {
			className: `bpca-alert bpca-alert--${ level }`,
		} );

		return (
			<>
				<InspectorControls>
					<PanelBody title={ __( 'Réglages', 'bpca-alert-block' ) }>
						<SelectControl
							label={ __( 'Niveau', 'bpca-alert-block' ) }
							value={ level }
							options={ [
								{ label: __( 'Info', 'bpca-alert-block' ), value: 'info' },
								{ label: __( 'Succès', 'bpca-alert-block' ), value: 'success' },
								{ label: __( 'Attention', 'bpca-alert-block' ), value: 'warning' },
								{ label: __( 'Erreur', 'bpca-alert-block' ), value: 'error' },
							] }
							onChange={ ( next ) => setAttributes( { level: next } ) }
						/>

						<ToggleControl
							label={ __( 'Afficher une icône', 'bpca-alert-block' ) }
							checked={ !! showIcon }
							onChange={ ( next ) => setAttributes( { showIcon: !! next } ) }
						/>

						<TextControl
							label={ __( 'Titre (optionnel)', 'bpca-alert-block' ) }
							value={ title }
							onChange={ ( next ) => setAttributes( { title: next } ) }
						/>
					</PanelBody>
				</InspectorControls>

				<div { ...blockProps }>
					{ showIcon && (
						<span className="bpca-alert__icon" aria-hidden="true">
							<span className="bpca-alert__icon-placeholder">!</span>
						</span>
					) }

					<div className="bpca-alert__body">
						{ title ? (
							<div className="bpca-alert__title">{ title }</div>
						) : null }

						<RichText
							tagName="div"
							className="bpca-alert__message"
							value={ message }
							allowedFormats={ [ 'core/bold', 'core/italic', 'core/link' ] }
							placeholder={ __( 'Votre message…', 'bpca-alert-block' ) }
							onChange={ ( next ) => setAttributes( { message: next } ) }
						/>
					</div>
				</div>
			</>
		);
	},

	// Dynamic block : save() doit retourner null.
	save: () => null,
} );

Dva súbory CSS:

/* src/style.css - CSS front + éditeur (partagé) */
.bpca-alert{
	display:flex;
	gap:12px;
	padding:14px 16px;
	border-radius:10px;
	border:1px solid transparent;
	align-items:flex-start;
}
.bpca-alert__icon svg{ display:block; fill: currentColor; }
.bpca-alert__title{ font-weight: 650; margin-bottom: 6px; }
.bpca-alert__message a{ text-decoration: underline; }

.bpca-alert--info{ background:#eef6ff; border-color:#cfe6ff; color:#0b3d91; }
.bpca-alert--success{ background:#eafff1; border-color:#c9f2d7; color:#0b5d2a; }
.bpca-alert--warning{ background:#fff7e6; border-color:#ffe3a3; color:#7a4a00; }
.bpca-alert--error{ background:#ffecec; border-color:#ffc2c2; color:#7a0000; }

/* src/editor.css - uniquement éditeur */
.wp-block-bpca-alert .bpca-alert__icon-placeholder{
	display:inline-flex;
	width:20px;
	height:20px;
	border-radius:4px;
	align-items:center;
	justify-content:center;
	background: rgba(0,0,0,.08);
	font-weight: 700;
}

Krok 5 – Tvorca

Spustenie:

npm run build

Musíte získať:

• build/index.js
• build/index.asset.php (kritické)
• build/index.css
• build/style-index.css

Krok 6 – Aktivujte doplnok a otestujte ho

• Aktivujte plugin v administrátorskom paneli.
• V editore blokov vyhľadajte „Upozornenie (BPCA)“.
• Pridajte to, zmeňte úroveň, otestujte s ikonou/bez ikony, publikujte.

Úplný kód

Nasleduje funkčný kopírovací a vložený súbor (plný plugin). Upozorňujeme, že zostavenie (build/) tu nie je zahrnuté: musíte spustiť npm run build na generovanie súborov.

1) bpca-alert-block.php

<?php
/**
 * Plugin Name: BPCA Alert Block
 * Description: Bloc Gutenberg "Encart Alerte" (dynamic block) avec build via @wordpress/scripts.
 * Version: 1.0.0
 * Requires at least: 6.9
 * Requires PHP: 8.1
 * Author: BPCA
 * License: GPL-2.0-or-later
 * Text Domain: bpca-alert-block
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

define( 'BPCA_ALERT_BLOCK_FILE', __FILE__ );
define( 'BPCA_ALERT_BLOCK_DIR', __DIR__ );

require_once BPCA_ALERT_BLOCK_DIR . '/includes/class-bpca-alert-block.php';

add_action( 'init', array( 'BPCA\AlertBlock\Plugin', 'init' ) );

2) obsahuje/class-bpca-alert-block.php

<?php
namespace BPCAAlertBlock;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

final class Plugin {

	public static function init(): void {
		add_action( 'init', array( __CLASS__, 'register_block' ) );
	}

	public static function register_block(): void {
		register_block_type(
			BPCA_ALERT_BLOCK_DIR . '/block.json',
			array(
				'render_callback' => array( __CLASS__, 'render' ),
			)
		);
	}

	public static function render( array $attributes, string $content ): string {
		$level   = isset( $attributes['level'] ) ? sanitize_key( $attributes['level'] ) : 'info';
		$title   = isset( $attributes['title'] ) ? sanitize_text_field( $attributes['title'] ) : '';
		$message = isset( $attributes['message'] ) ? wp_kses_post( $attributes['message'] ) : '';
		$icon    = ! empty( $attributes['showIcon'] );

		$allowed_levels = array( 'info', 'success', 'warning', 'error' );
		if ( ! in_array( $level, $allowed_levels, true ) ) {
			$level = 'info';
		}

		$classes = array( 'bpca-alert', 'bpca-alert--' . $level );

		$icon_html = '';
		if ( $icon ) {
			$icon_html = '<span class="bpca-alert__icon" aria-hidden="true">' . self::get_icon_svg( $level ) . '</span>';
		}

		$title_html = $title !== '' ? '<div class="bpca-alert__title">' . esc_html( $title ) . '</div>' : '';
		$message_html = $message !== '' ? '<div class="bpca-alert__message">' . $message . '</div>' : '';

		return '<div class="' . esc_attr( implode( ' ', $classes ) ) . '" role="note">'
			. $icon_html
			. '<div class="bpca-alert__body">' . $title_html . $message_html . '</div>'
			. '</div>';
	}

	private static function get_icon_svg( string $level ): string {
		switch ( $level ) {
			case 'success':
				return '<svg viewBox="0 0 24 24" width="20" height="20" focusable="false"><path d="M9 16.2 4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z"></path></svg>';
			case 'warning':
				return '<svg viewBox="0 0 24 24" width="20" height="20" focusable="false"><path d="M1 21h22L12 2 1 21zm12-3h-2v2h2v-2zm0-8h-2v6h2V10z"></path></svg>';
			case 'error':
				return '<svg viewBox="0 0 24 24" width="20" height="20" focusable="false"><path d="M12 2C6.5 2 2 6.5 2 12s4.5 10 10 10 10-4.5 10-10S17.5 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"></path></svg>';
			case 'info':
			default:
				return '<svg viewBox="0 0 24 24" width="20" height="20" focusable="false"><path d="M11 17h2v-6h-2v6zm0-8h2V7h-2v2zm1-7C6.5 2 2 6.5 2 12s4.5 10 10 10 10-4.5 10-10S17.5 2 12 2z"></path></svg>';
		}
	}
}

3) blok.json

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "bpca/alert",
	"title": "Encart Alerte (BPCA)",
	"category": "widgets",
	"icon": "warning",
	"description": "Affiche un encart d'alerte avec niveau et option d'icône.",
	"textdomain": "bpca-alert-block",
	"attributes": {
		"level": { "type": "string", "default": "info" },
		"title": { "type": "string", "default": "" },
		"message": { "type": "string", "default": "" },
		"showIcon": { "type": "boolean", "default": true }
	},
	"supports": {
		"anchor": true,
		"html": false
	},
	"editorScript": "file:./build/index.js",
	"style": "file:./build/style-index.css",
	"editorStyle": "file:./build/index.css"
}

4) src/index.js + src/style.css + src/editor.css

Vráťte sa a skontrolujte súbory z podrobnej časti.

Vysvetlenie kódu

Prečo block.json skutočne zjednodušuje život

block.json sa stal ústredným bodom. WordPress číta metadáta, ukladá blok a vie, ako načítať dáta na správne miesto (editor verzus front-end). Keď používate "file:./build/index.js"WordPress sa spolieha na súbor build/index.asset.php vygenerované zostavením pre:

• vyhlásiť presné závislosti (napr.: wp-element, wp-i18n, wp-block-editor),
• vyhlásiť verzia (hash) na vylúčenie vyrovnávacej pamäte.

Oficiálna referencia: Blok metadát.

Prečo dynamický blok (uloženie: null) zabraňuje skutočným chybám

Pri statickom bloku musíte udržiavať dve vykreslenia :

• vykresľovanie JSX v edit(),
• serializovaný HTML save().

V praxi, hneď ako pridáte možnosť, zabudnete ju aktualizovať. save()a v databáze skončíte s obsahom v „starom formáte“. Pri dynamickej blokovej architektúre používa front-end PHP, takže:

• HTML kód môžete vyvíjať bez migrácie obsahu.
• Centralizujete odsávacie a kanalizačné systémy,
• Lepšie zvládate kontexty (viacjazyčná stránka, globálne možnosti, A/B testovanie atď.).

Nevýhodou je, že vykresľovanie závisí od servera, takže musíte byť prísni, čo sa týka výkonu a ukladania do vyrovnávacej pamäte (k tomu sa ešte vrátime).

Háky a načasovanie

Uložíme blok ďalej initToto je očakávané načasovanie: typy blokov musia byť registrované dostatočne skoro, ale až po načítaní jadra. Referencia: typ_bloku_registra().

Dezinfekcia a únik

• sanitize_key() pre level (hodnota „slug“).
• sanitize_text_field() pre title.
• wp_kses_post() pre message pretože je povolená podmnožina HTML (odkazy, zvýraznenie). Dokument: wp_kses_post().
• esc_attr() čo sa týka triedy CSS, esc_html() na titule.

Pri tomto type bloku je hlavným rizikom vstreknutie HTML, ak dôverujete atribútom. Aj keď je editor „administrátor“, nechcete mať trvalú zraniteľnosť XSS, ak môže publikovať používateľ s nižšou rolou.

Varianty a prípady použitia

Možnosť 1 – Statický blok (ak trváte na serializovanom HTML)

Prípad: Chcete, aby bol obsah 100 % prenosný bez závislosti od pluginu (napr. export na inú stránku bez pluginu). Môžete implementovať save() a odstrániť render_callback.

Čo robím v tomto prípade: Ponechávam minimálny HTML kód save() A obmedzujem možnosti. V opačnom prípade sa budete musieť vysporiadať s migráciami verzií blokov skôr, ako by ste očakávali.

Možnosť 2 – Pridanie štýlov blokov (variácií štýlov) bez komplikácie používateľského rozhrania

Štýly môžete deklarovať pomocou JS (registerBlockStyle) alebo cez block.json v závislosti od vašej stratégie. Pre pokročilých blogerov je často jednoduchšie nechať používateľa vybrať si možnosť „Obrys“ alebo „Vyplnené“ bez pridania prepínača v Inšpektorovi.

Dokument: Štýly blokov.

Variant 3 – Vykresľovanie závislé od globálnej možnosti (Settings API)

Príklad: chcete mať možnosť „Farby značky“ nakonfigurovanú raz. V render()Načítajte možnosť a upravte triedy alebo štýl vloženého kódu (v jednoduchosti). Pozor: ak začnete generovať CSS kód vloženého kódu blok po bloku, môžete drasticky zväčšiť veľkosť HTML kódu na dlhých stránkach.

Kompatibilita s Divi 5 / Elementor / Avada

Kľúčový bod: Divi 5, Elementor a Avada môžu koexistovať s editorom blokov, ale obsah je možné generovať pomocou ich príslušných nástrojov na tvorbu blokov. Váš blok Gutenberg zostane použiteľný.

• v natívnom editore blokov,
• v oblastiach „Gutenberg“/„Editor blokov“, ktoré tieto témy/pluginy sprístupňujú,
• niekedy vo vyhradených moduloch (v závislosti od staviteľa).

Divi 5

Divi 5 má lepšiu interoperabilitu s blokmi, ale stále som zaznamenal problémy s globálnym CSS Divi, ktoré prepisuje štýly blokov (výška riadku, veľkosť rámčeka). Váš blok je robustný, ak:

• predponujete svoje triedy (bpca-alert),
• Vyhýbate sa príliš všeobecným selektorom.

Ak ho chcete integrovať ako „modul Divi“, môžete poskytnúť skrátený kód (záložný kód), ktorý opätovne používa rovnakú funkciu vykresľovania, ale neduplikuje logiku. Zachovajte jeden zdroj pravdy (PHP).

Elementor

Elementor umožňuje vkladať krátke kódy a v závislosti od konfigurácie aj bloky prostredníctvom widgetov WordPressu. Pre pokročilé použitie:

• navrhnúť krátky kód [bpca_alert] ktorý vyžaduje rovnakú metódu vykresľovania,
• alebo sprístupniť vyhradený widget Elementoru (ktorý sa dlhšie udržiava).

Odporúčam krátky kód ako ľahkú bránu, ak máte zmiešané publikum.

Avada (výrobca fúzií)

Avada historicky používala veľa globálneho CSS. Konkrétne test:

• predvolené okraje na div,
• štýly odkazov,
• zdedené farby.

V prípade konfliktu pridajte špecifickejšiu vrstvu CSS do src/style.css (bez toho, aby sa zapojil do vojny !important).

Kontroly po inštalácii

• vydavateľ Blok sa zobrazí a ovládacie prvky správne zmenia ukážku.
• predné Vykresľovanie HTML obsahuje bpca-alert et bpca-alert--{level}.
• Aktíva :
  • v editore: build/index.js + build/index.css naložený,
  • na prednej strane: build/style-index.css načíta sa iba vtedy, ak je blok prítomný.
• Cache Po npm run build, plugin na čistenie vyrovnávacej pamäte/CDN + hard refresh prehliadača.
• Záznamy v CSS/JS bloku sa neobjavuje „nepodarilo sa načítať zdroj“.

Rýchla diagnostická tabuľka

symptóm	Príčina pravdepodobná	overenie	Riešenie
Blok sa vo vložke nezobrazuje.	Plugin je neaktívny alebo chyba PHP pri načítaní	Správca > Rozšírenia, + debug.log	Opravte chybu, skontrolujte menný priestor/vložený súbor
Viditeľný, ale „prázdny“ blok vpredu	Dynamický blok bez render_callback efektívne alebo chyba v render()	Zobraziť zdrojový kód HTML + protokoly PHP	skontrolovať register_block_type(... render_callback ...) a hygiena
CSS chýba na front-ende	style nesprávne deklarované v block.json alebo chýbajúca zostava	Karta Sieť, súbor style-index.css	Znovu spustiť npm run build, skontrolujte cesty file:
Chyba JavaScriptu v editore	Nevyriešené závislosti / poškodená zostava	Konzola prehliadača v editore	odstrániť build/reštartujte zostavenie, skontrolujte index.asset.php
Zmeny nie sú viditeľné po zostavení	Vyrovnávacia pamäť prehliadača/CDN	Porovnanie hashov aktív	Vymazať vyrovnávaciu pamäť + tvrdé obnovenie

Ak to nefunguje

1) Najprv skontrolujte zostavenie

• build/index.asset.php Existuje? Ak chýba, WordPress nebude schopný spravovať závislosti.
• Dobre si to zvládol/a npm run build v priečinku s pluginom (nie v koreňovom adresári projektu)?

2) Skontrolujte cesty

poľa "file:./build/index.js" súvisí s block.jsonAk ste sa presťahovali block.json V podpriečinku sa všetko pokazí. Toto je bežná chyba pri reorganizácii repozitára.

3) Skontrolujte háčik

Registrácia dňa initAk uložíte súbor príliš skoro (napr. pri načítaní súboru bez hooku), môžete naraziť na funkcie, ktoré nie sú pripravené podľa poradia načítania.

4) Skontrolujte verziu PHP

Stále vidím hostingové účty, kde stránka beží na PHP 7.4/8.0, aj keď je plugin napísaný pre 8.1. Výsledok: fatálne chyby. Skontrolujte to v Nástroje > Stav stránky alebo cez phpinfo().

5) Konflikty pluginov/úryvkov kódu

„Plugin pre úryvky kódu“ môže poškodiť súbor, ak vložíte kód s chýbajúcou zátvorkou. Ak sa vaša stránka po aktivácii zrúti:

• Zakážte plugin cez FTP (premenujte priečinok),
• opravte chybu v debug.log,
• Znovu aktivovať.

Časté úskalia a chyby

Chyba	Spôsobiť	Riešenie
Skopírujte PHP kód do functions.php namiesto pluginu	Téma sa zmení, blok zmizne	Zabaľte ho ako plugin, upravte jeho verziu a čisto ho nasaďte.
Parse error: syntax error, unexpected ...	Chýbajúca bodkočiarka/zátvorka	Znovu si prečítajte rozdiel, aktivujte PHP linter, skontrolujte debug.log
Blok sa objaví, ale ovládacie prvky nereagujú	Nesprávne deklarované atribúty alebo preklepy v setAttributes	skontrolovať block.json vs attributes používané v JS
Failed to load resource sur index.js	Chýbajúca zostava, nesprávna cesta alebo súbor nie je nasadený	rozmiestniť build/ V produkčnom prostredí skontrolujte povolenia.
CSS uvoľneného bloku	Skryť, alebo style/editorStyle obrátený	Vymazať vyrovnávaciu pamäť, overiť block.json, otestujte v režime súkromného prehliadania
Zmätok medzi zásobami a filtrami	Použitie add_filter au Lieu de add_action sur init	použitie add_action( 'init', ... )
Blok „pokazený“ po aktualizácii	Pevne zakódované závislosti namiesto .asset.php	Prejsť cez file: + štandardná zostava
Priamy test v produkčnom prostredí bez zálohovania	Riziko závažnej chyby a prestojov	Riadené stagingové spracovanie, zálohovanie a nasadenie (zip/release)
Trvalé odkazy „na regeneráciu“ (vedľajší účinok)	Je to zriedkavé, ale niektoré pluginy upravujú prepisovanie pri aktivácii.	Ak sa po aktivácii vyskytne zvláštne správanie, znova uložte trvalé odkazy

Tipy na bezpečnosť, výkon a údržbu

Zabezpečenie

• Liečiť všetko Atribúty sú označené ako nespoľahlivé. Aj keď je používateľské rozhranie v administrátorskom paneli, obsah je možné vložiť cez REST alebo importovať.
• Ak do bloku pridávate koncové body REST, použite spätné volanie_permissions, nunciovia a príslušné kapacity.
• Vyhnite sa vykresľovaniu surového HTML z atribútov bez wp_kses_*.

výkon

• Dynamický blok: ponechať render() rýchle, bez ťažkých blokových dotazov.
• Ak potrebujete vykonávať dotazy (napr. CPT), použite objektovú vyrovnávaciu pamäť a vyhnite sa N+1.
• Udržujte svoj CSS minimalistický. Bloky sa opakujú: 20 upozornení na stránke = váš CSS musí zostať konzistentný.

Údržba (skutočné nasadenie)

• Nevytvárajte do produkčného prostredia. Vytvorte v CI, pošlite plugin s build/ verziované (alebo pripojené k vydaniu).
• Uzamknite verziu Node vo vývoji (nvm, volta), aby ste sa vyhli rôznym zostaveniam v závislosti od počítača.
• Sledujte vývoj v Gutenbergu: najlepším signálom zostávajú PR správy. github.com/WordPress/gutenberg.

zdroje

• @wordpress/scripts (oficiálny dokument)
• block.json / Metadáta bloku
• typ_bloku_registra()
• wp_kses_post()
• Štýly blokov
• Repo Gutenberg (sledovanie zmien)
• WordPress Core Trac (tikety, regresie)
• Podporované verzie PHP

Často kladené otázky

Prečo používať @wordpress/scripts namiesto môjho vlastného webového balíka?

Pretože zmenšujete plochu údržby. @wordpress/scripts dodržiava konvencie WordPressu (Babel, závislosti WP, generovanie) .asset.php). Webpack vytvorený na mieru sa často odchyľuje a preruší pri ďalšom dôležitom kroku.

Musím priečinok build/ uverejniť v Gite?

V prípade pluginu nasadeného na stránke áno, musíte ho dodať build/Či to commitnete alebo pripojíte k vydaniu CI, na tom nezáleží, ale produkcia by nemala závisieť od zostavenia Node.

Prečo sa štýly môjho bloku nenačítavajú na front-ende?

V 80 % prípadov: style nesprávne deklarované v block.json, nenasadená zostava alebo vyrovnávacia pamäť. Skontrolujte, či build/style-index.css existuje a je prístupný.

Dynamický blok: je to zlé pre vyrovnávaciu pamäť?

Nie nevyhnutne. HTML kód sa vykreslí pri generovaní stránky a potom sa uloží do vyrovnávacej pamäte ako všetko ostatné. Skutočný problém je, ak váš render() vytvára náročné požiadavky, požiadavky bez vyrovnávacej pamäte alebo závisí od stavu používateľa (v takom prípade fragmentujete vyrovnávaciu pamäť).

Môžem s týmto prístupom použiť InnerBlocks?

Áno. Budete musieť: (1) vyhlásiť supports.inserter v závislosti od vašich potrieb, (2) spravujte $content v render() a správne ho uniknúť (často cez do_blocks() (ak pracujete s blokovým obsahom). Robte to iba v prípade skutočnej potreby, inak znásobujete hraničné prípady.

Ako správne riadiť internacionalizáciu (i18n)?

Na strane JS použite __() a definovať textdomain v block.jsonNa strane PHP použite __()/esc_html__()Ďalej vygenerujte súbory. .po/.mo cez váš obvyklý kanál. Blok Doc i18n: Internacionalizácia v editore blokov.

Môj editor zlyhá s hlásením „Nie je možné prečítať vlastnosti nedefinovaného súboru“

Typicky: chýbajúci atribút (nesprávny názov) alebo neočakávaný typ. Skontrolujte konzistenciu. block.json ↔ JS. V režime ladenia zaznamenávať attributes v edit() a pozrite sa na skutočný stav.

Môžeme pridať REST API na napájanie bloku?

Áno, ale uistite sa, že je to bezpečné. Použite register_rest_route() s permission_callbackOverte nastavenia a spravujte funkcie. Dokument: Pridávanie vlastných koncových bodov REST API.

Ako môžem tento kód správne otestovať?

Testujem to v troch fázach:

• Jednotka/Integrácia minimálne PHP test vykresľovania (render()) s neplatnými atribútmi (neznáma úroveň, HTML v názve atď.).
• E2E vytvoriť článok, vložiť blok, publikovať, skontrolovať HTML + CSS.
• Compat aktivujte „ťažkú“ tému (Avada/Divi) na stagingu a skontrolujte, či vaše triedy nie sú prepísané.

Kde môžem sledovať zmeny, ktoré môžu ovplyvniť moje bloky?

V repozitári Gutenberg (GitHub) a na Core Trac (tréma) keď sa zmena zlúči do jadra WordPressu. Tu uvidíte zastarané verzie a zmeny API.