WordPress Gutenberg Block Cheatsheet (Nâng cao)

Dưới đây là WordPress Gutenberg Block Cheatsheet (Nâng cao) – dành cho lập trình viên muốn phát triển block tùy chỉnh chuyên nghiệp bằng JavaScript (React), kết hợp với PHP để mở rộng trình soạn thảo của WordPress.

---

1. Cấu trúc thư mục block cơ bản

📋 Copymy-plugin/
├── blocks/
│   └── my-block/
│       ├── block.json
│       ├── index.js
│       ├── edit.js
│       ├── save.js
├── my-plugin.php

---

2. Đăng ký block với block.json

📋 Copy{
  "apiVersion": 2,
  "name": "myplugin/my-block",
  "title": "My Custom Block",
  "category": "widgets",
  "icon": "smiley",
  "description": "Một block tùy chỉnh.",
  "attributes": {
    "content": {
      "type": "string",
      "source": "html",
      "selector": "p"
    }
  },
  "editorScript": "file:./index.js"
}

---

3. Đăng ký script trong plugin PHP

📋 Copyadd_action('init', function () {
    register_block_type(__DIR__ . '/blocks/my-block');
});

Block sẽ tự động đọc block.json và tải file index.js

---

4. File index.js – nhập edit & save

📋 Copyimport { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import Save from './save';

registerBlockType('myplugin/my-block', {
  edit: Edit,
  save: Save,
});

---

5. File edit.js – giao diện trong editor

📋 Copyimport { useBlockProps, RichText } from '@wordpress/block-editor';

export default function Edit({ attributes, setAttributes }) {
  return (
    <div {...useBlockProps()}>
      <RichText
        tagName="p"
        value={attributes.content}
        onChange={(content) => setAttributes({ content })}
        placeholder="Nhập nội dung..."
      />
    </div>
  );
}

---

6. File save.js – nội dung được lưu ra frontend

📋 Copyimport { useBlockProps, RichText } from '@wordpress/block-editor';

export default function Save({ attributes }) {
  return (
    <div {...useBlockProps.save()}>
      <RichText.Content tagName="p" value={attributes.content} />
    </div>
  );
}

---

7. Các loại attribute thường dùng

Loại	Mô tả
type	'string', 'number', 'boolean', 'array', 'object'
source	'html', 'text', 'attribute'
selector	Chọn phần tử trong DOM
attribute	Đọc attribute cụ thể (class, href, etc.)

---

8. Hook và component phổ biến

Hook	Mô tả
useBlockProps()	Thêm class và thuộc tính mặc định
useSelect()	Lấy dữ liệu từ store
useDispatch()	Gửi hành động tới store
useEffect(), useState()	React hooks thường dùng

Component	Mô tả
RichText	Trường soạn thảo nội dung
InspectorControls	Sidebar tuỳ chọn
MediaUpload, ColorPicker	Chọn ảnh, màu
PanelBody, TextControl, ToggleControl	UI components

---

9. Thêm sidebar tuỳ chỉnh

📋 Copyimport { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, TextControl } from '@wordpress/components';

<InspectorControls>
  <PanelBody title="Tùy chọn">
    <TextControl
      label="Tiêu đề phụ"
      value={attributes.subtitle}
      onChange={(val) => setAttributes({ subtitle: val })}
    />
  </PanelBody>
</InspectorControls>

---

10. Thêm style block

a) CSS trong block

📋 Copy"style": "file:./style.css",
"editorStyle": "file:./editor.css"

Tự động được load vào frontend hoặc editor tương ứng.

b) Dynamic style trong JS

📋 Copy<div style={{ backgroundColor: attributes.bgColor }}>

---

11. Block động (dynamic block)

📋 Copyregister_block_type('myplugin/dynamic-block', [
    'render_callback' => 'my_dynamic_block_render'
]);

function my_dynamic_block_render($attributes, $content) {
    return '<div class="my-block">Nội dung render bằng PHP: ' . esc_html($attributes['text']) . '</div>';
}

Block này sẽ render từ PHP khi load ra frontend (không dùng save.js)

---

12. Dùng wp-env để phát triển

📋 Copywp-env start

Cấu hình file .wp-env.json để dễ dàng test block trên site WordPress local.

---

13. Biên dịch JavaScript với @wordpress/scripts

Cài đặt:

📋 Copynpm install @wordpress/scripts --save-dev

Thêm vào package.json:

📋 Copy"scripts": {
  "build": "wp-scripts build",
  "start": "wp-scripts start"
}

Chạy:

📋 Copynpm run start

Tự động compile block cho môi trường phát triển.

---

14. Tối ưu phân phối block

• Dùng viewScript, script, editorStyle, style trong block.json để chia nhỏ JS/CSS
• Tránh inline CSS lớn trong save.js
• Sử dụng wp_enqueue_block_style() nếu cần đăng ký style ngoài block

---

15. Công cụ & tài nguyên

• Block Editor Handbook
• @wordpress/components
• create-block
• @wordpress/scripts