@wordpress/scripts és create-block

Gutenberg-blokkot modern JavaScripttel (JSX, ESNext) írsz, a böngésző viszont ezt közvetlenül nem futtatja. Két WordPress-csomag oldja meg a ráépülő munkát. A @wordpress/create-block létrehozza a bővítmény vázát, a @wordpress/scripts pedig a fordítást végzi. Neked nem kell webpacket, Babelt vagy ESLintet beállítanod.

Mit kell hozzá telepíteni

• Node.js. A hivatalos fejlesztői környezeti útmutató az Active LTS verziót ajánlja, és egy verziókezelőt (például nvm) is. A create-block referenciája szerint legalább a 22.13.0 verzió kell.
• Egy helyi WordPress. A generált bővítményt kézzel kell a WordPress plugins/ mappájába tenni, és aktiválni. A WordPress projekt a wp-env használatát ajánlja a Gutenberg-fejlesztéshez.

Blokk létrehozása

A legrövidebb út, ha megadod a slugot:

Terminál

npx @wordpress/create-block@latest todo-list
cd todo-list
npm start

A slug lesz a mappa neve, a bővítmény neve és a blokk belső neve is. A többi beállítás alapértéket kap.

Slug nélkül interaktív módban indul, és megkérdezi a szükséges adatokat (slug, cím, névtér és társaik):

Terminál

npx @wordpress/create-block@latest

Gyakori kapcsolók

Kapcsoló	Mit csinál
--namespace <érték>	A blokk névtere. Alapértelmezetten create-block, a blokk neve névtér/slug.
--title <érték>	A blokk és a bővítmény megjelenő neve.
--short-description <érték>	Rövid leírás.
--category <név>	A blokk kategóriája.
--textdomain <érték>	A fordítások szövegtartománya. Alapértelmezetten a slug.
--variant <név>	A sablon egy változata. A --variant dynamic dinamikus blokkot ad.
--template <név>	A sablon: standard (alap), es5, npm-csomag neve vagy helyi mappa.
--target-dir <mappa>	A kimeneti mappa. Alapértelmezetten a slug.
--no-plugin	Csak a blokk fájljait hozza létre az aktuális mappába, bővítmény nélkül.
--wp-scripts / --no-wp-scripts	A @wordpress/scripts használatának be- és kikapcsolása.
--wp-env	@wordpress/env beállítást és hozzá egy szkriptet ad, a Dockerre épülő helyi WordPresshez.

Például egyedi névtérrel és dinamikus blokkal:

Terminál

npx @wordpress/create-block@latest my-block --namespace=my-plugin --variant=dynamic

Ez a my-plugin/my-block nevű blokkot hozza létre. Ha később névteret cserélnél, írd át a name mezőt a block.json fájlban.

A létrejövő mappaszerkezet

A Block Editor Handbook szerint a bővítmény így néz ki:

Mappaszerkezet

todo-list/
├── todo-list.php     a bővítmény fő fájlja, itt van a blokk szerveroldali regisztrációja
├── package.json
├── src/
│   ├── block.json
│   ├── index.js
│   ├── edit.js
│   ├── save.js
│   ├── style.scss
│   ├── editor.scss
│   ├── render.php    csak dinamikus blokknál
│   └── view.js
└── build/            a src/ fordított kimenete

A fájlok szerepe:

• src/block.json: a blokk metaadatai (név, attribútumok, támogatások), és megmondja, mely fájlokat használja.
• src/index.js: a szerkesztő belépési pontja, itt hívódik a registerBlockType.
• src/edit.js: a blokk szerkesztőbeli felülete (React-komponens).
• src/save.js: a statikus HTML, ami az adatbázisba mentődik.
• src/style.scss: stílus a szerkesztőben és a nyilvános oldalon is.
• src/editor.scss: stílus csak a szerkesztőben.
• src/render.php: a dinamikus blokk kimenetét adja a nyilvános oldalon.
• src/view.js: a nyilvános oldalon betöltődő JavaScript.
• build/: a wp-scripts fordítja a src/ tartalmából, és a WordPress ezeket a fájlokat tölti be.

npm-szkriptek

A create-block ezeket a szkripteket írja a package.json fájlba, és npm run <név> paranccsal futtatod őket:

Parancs	Mit csinál
npm start	Fejlesztői build figyelővel: a mentett változtatásra újrafordít, a hibákat a konzolban mutatja.
npm run build	Egyszeri, optimalizált éles build.
npm run format	Formázza a kódot.
npm run lint:js	JavaScript-ellenőrzés.
npm run lint:css	CSS-ellenőrzés.
npm run packages-update	Frissíti a @wordpress/* függőségeket.
npm run plugin-zip	Telepíthető bővítmény-zip készítése.

A lint- és formázóparancsok hátteréről az ESLint, Prettier és Stylelint cikk szól.

Fejlesztés közben indítsd el az npm start parancsot, és hagyd futni. Telepítés vagy kiadás előtt futtass npm run build parancsot.

Mit fordít a wp-scripts

A build és a start alapból a src mappában keres block.json fájlokat (almappákban is). A bennük megadott editorScript, script és viewScript JavaScript-fájlokból lesz belépési pont. Ha nincs block.json, a src/index.js (vagy .jsx, .ts, .tsx) az alap. A kimenet alapból a build mappába kerül.

Az index.css csak a szerkesztő stílusa, a style-index.css a nyilvános oldalé és a szerkesztőé is. A forrás- és kimeneti mappa a --source-path és --output-path kapcsolóval módosítható.

A block.json szerepe

A block.json a blokk egyetlen leírása, amit a PHP és a JavaScript is olvas. A kézikönyv a blokkok regisztrálásának kanonikus módjaként ajánlja. Előnyei:

• a blokk eszközeit (szkript, stílus) csak akkor tölti be, ha a blokk szerepel az oldalon;
• a Block Directoryban megjelenő bővítmény minden blokkjához kell block.json;
• a séma fájllal a szerkesztő súgót, automatikus kiegészítést és ellenőrzést ad.

A fájlutak file: előtagot kapnak, és a block.json-hoz képest relatívak:

src/block.json

{
  "apiVersion": 3,
  "name": "create-block/todo-list",
  "title": "Todo List",
  "textdomain": "todo-list",
  "editorScript": "file:./index.js",
  "render": "file:./render.php"
}

A name kötelező, névtér/blokknév alakban. A render (WordPress 6.1 óta) a dinamikus blokk PHP-fájlja. A fenti példa a mezők szemléltetésére rövidített, a generált fájl ennél több mezőt tartalmaz.

Regisztráció PHP-ból

A blokkot a bővítmény fő PHP-fájljában, az init horogra kötve regisztrálod. A register_block_type() a build mappa block.json fájlját olvassa, nem a src mappáét:

todo-list.php

function todo_list_register_block() {
    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'todo_list_register_block' );

Több blokkhoz a WordPress 6.8 óta a wp_register_block_types_from_metadata_collection() az ajánlott. Ehhez a wp-scripts build-blocks-manifest (vagy a build --blocks-manifest kapcsolója) egyetlen PHP-fájlba gyűjti a blokkok metaadatait:

todo-list.php

function my_plugin_register_blocks() {
    wp_register_block_types_from_metadata_collection(
        __DIR__ . '/build',
        __DIR__ . '/build/blocks-manifest.php'
    );
}
add_action( 'init', 'my_plugin_register_blocks' );

Mire figyelj

• A WordPress a build mappa fájlait tölti be, ezért a kiadott bővítménybe a fordított kimenetnek is be kell kerülnie. Az npm run plugin-zip zipbe csomagolja a bővítményt.
• Ha a témád vagy a teljes oldalad asseteit Vite építi, az a blokk-bővítménytől független: a blokk fordítását a wp-scripts végzi.

Hasznos linkek

• create-block referencia
• @wordpress/scripts referencia
• Get started with create-block
• Block metadata (block.json)
• Registration of a block
• File structure of a block