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 块开发之旅!如果您有任何问题或需要进一步解释某些部分,请随时告诉我。