1. 介绍

Gutenberg 是 WordPress 的新编辑器,它使用”块”作为内容的基本构建单元。本教程将指导您完成创建自定义 Gutenberg 块的过程。

2. 准备工作

2.1 环境设置

确保您有以下环境:

• WordPress 5.0 或更高版本
• Node.js 和 npm
• 代码编辑器 (如 VS Code)

2.2 创建插件结构

在 WordPress 的 wp-content/plugins 目录下创建一个新文件夹,例如 my-gutenberg-block。

3. 基本文件结构

创建以下文件:

my-gutenberg-block/
├── my-gutenberg-block.php
├── src/
│   └── index.js
├── build/
├── package.json
└── webpack.config.js

4. 设置 package.json

在插件根目录运行:

npm init -y

然后安装必要的依赖:

npm install @wordpress/scripts --save-dev

修改 package.json,添加构建脚本:

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

5. 编写插件主文件

在 my-gutenberg-block.php 中:

<?php
/**
 * Plugin Name: My Gutenberg Block
 * Description: A custom Gutenberg block
 * Version: 1.0.0
 * Author: Your Name
 */

function my_gutenberg_block_init() {
    register_block_type_from_metadata( __DIR__ );
}
add_action( 'init', 'my_gutenberg_block_init' );

6. 创建块

6.1 编写 JavaScript

在 src/index.js 中:

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText } from '@wordpress/block-editor';

registerBlockType( 'my-gutenberg-block/hello-world', {
    title: 'Hello World',
    icon: 'smiley',
    category: 'common',
    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'p',
        },
    },
    edit: ( props ) => {
        const { attributes: { content }, setAttributes } = props;
        const blockProps = useBlockProps();

        const onChangeContent = ( newContent ) => {
            setAttributes( { content: newContent } );
        };

        return (
            <RichText
                { ...blockProps }
                tagName="p"
                onChange={ onChangeContent }
                value={ content }
                placeholder={ 'Enter your text here...' }
            />
        );
    },
    save: ( props ) => {
        const blockProps = useBlockProps.save();
        return (
            <RichText.Content
                { ...blockProps }
                tagName="p"
                value={ props.attributes.content }
            />
        );
    },
} );

6.2 创建 block.json

在插件根目录创建 block.json:

{
    "apiVersion": 2,
    "name": "my-gutenberg-block/hello-world",
    "title": "Hello World",
    "category": "common",
    "icon": "smiley",
    "description": "A custom Gutenberg block",
    "supports": {
        "html": false
    },
    "textdomain": "my-gutenberg-block",
    "editorScript": "file:./build/index.js"
}

7. 构建块

运行以下命令来构建您的块:

npm run build

8. 测试您的块

激活您的插件,然后在 Gutenberg 编辑器中查找您的新块。

9. 高级主题

9.1 添加样式

创建 src/editor.scss 和 src/style.scss 文件来分别为编辑器和前端添加样式。

9.2 使用 InspectorControls

您可以添加侧边栏控件:

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

// 在 edit 函数中:
<>
    <InspectorControls>
        <PanelBody title="Block Settings">
            <TextControl
                label="Background Color"
                value={ backgroundColor }
                onChange={ ( newColor ) => setAttributes( { backgroundColor: newColor } ) }
            />
        </PanelBody>
    </InspectorControls>
    {/* 您的主要编辑组件 */}
</>

9.3 使用 withColors 高阶组件

为您的块添加颜色支持:

import { withColors } from '@wordpress/block-editor';

let Edit = ( props ) => {
    // 您的编辑组件
};

Edit = withColors( 'backgroundColor', 'textColor' )( Edit );

9.4 添加块变体

您可以为您的块创建变体:

registerBlockType( 'my-gutenberg-block/hello-world', {
    // ... 其他配置
    variations: [
        {
            name: 'blue',
            title: 'Blue Hello World',
            attributes: { backgroundColor: 'blue', textColor: 'white' },
        },
        {
            name: 'red',
            title: 'Red Hello World',
            attributes: { backgroundColor: 'red', textColor: 'white' },
        },
    ],
} );

10. 结论

这个教程涵盖了 Gutenberg 块开发的基础知识。随着您的深入学习,您可以探索更多高级主题,如创建动态块、使用 ServerSideRender 组件、创建块模式等。

记住,Gutenberg 开发是一个不断发展的领域,保持关注 WordPress 开发者博客和文档以获取最新信息是很重要的。

希望这个教程能帮助您开始 Gutenberg 块开发之旅!如果您有任何问题或需要进一步解释某些部分,请随时告诉我。