Gutenberg区块开发：如何基于`Inspector Controls`实现高级的自定义设置面板，并利用`create-block`工具？

Gutenberg 区块开发：基于 Inspector Controls 实现高级自定义设置面板

各位开发者，大家好！今天我们来深入探讨 Gutenberg 区块开发中一个至关重要的部分：如何利用 Inspector Controls 实现高级的自定义设置面板，并结合 create-block 工具来提升开发效率。

Inspector Controls 是 Gutenberg 编辑器提供的一个强大的 API，允许我们在区块的侧边栏中创建自定义的设置面板，从而让用户可以灵活地配置区块的行为和外观。 结合 create-block 工具，我们可以快速搭建区块的开发环境，并专注于实现自定义设置面板的逻辑。

下面，我们将逐步讲解如何使用 Inspector Controls 创建高级设置面板，并结合 create-block 工具的使用。

1. 使用 create-block 创建区块

首先，我们需要使用 create-block 工具创建一个新的 Gutenberg 区块。 确保你已经安装了 Node.js 和 npm。

npx @wordpress/create-block my-advanced-block
cd my-advanced-block
npm install
npm start

这条命令会创建一个名为 my-advanced-block 的区块，并启动开发服务器。 create-block 会自动生成必要的代码结构，包括：

• src/index.js: 区块的入口文件，负责注册区块。
• src/edit.js: 定义区块在编辑器中的呈现方式。
• src/save.js: 定义区块在前端的呈现方式。
• src/style.scss: 区块在编辑器和前端共享的样式。
• src/editor.scss: 区块在编辑器中独有的样式。
• block.json: 区块的元数据定义文件，包含了区块的名称、描述、属性等信息。

2. 理解 block.json

block.json 文件是区块的核心配置文件。 我们需要在这里定义区块的属性，这些属性将会在 Inspector Controls 中作为设置项呈现给用户。

例如，我们想创建一个可以自定义标题、内容和背景颜色的区块。 block.json 文件可以这样定义：

{
    "apiVersion": 2,
    "name": "my-advanced-block/my-block",
    "title": "My Advanced Block",
    "category": "common",
    "icon": "smiley",
    "description": "A block with advanced customization options.",
    "supports": {
        "html": false
    },
    "attributes": {
        "title": {
            "type": "string",
            "default": "My Awesome Title"
        },
        "content": {
            "type": "string",
            "default": "This is the content of my block."
        },
        "backgroundColor": {
            "type": "string",
            "default": "#ffffff"
        }
    },
    "textdomain": "my-advanced-block",
    "editorScript": "file:./build/index.js",
    "editorStyle": "file:./build/index.css",
    "style": "file:./build/style-index.css"
}

在这个 block.json 文件中，我们定义了三个属性：

• title: 字符串类型，默认值为 "My Awesome Title"。
• content: 字符串类型，默认值为 "This is the content of my block."。
• backgroundColor: 字符串类型，默认值为 "#ffffff"。

3. 在 edit.js 中使用 Inspector Controls

现在，我们需要在 edit.js 文件中使用 Inspector Controls 组件来创建自定义设置面板。

首先，我们需要导入必要的组件：

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

• __: 用于国际化字符串。
• useBlockProps: 用于生成区块的 props，包括类名等。
• InspectorControls: 用于在侧边栏中添加自定义设置面板。
• PanelBody: 用于将设置项分组。
• TextControl: 用于输入文本。
• ColorPicker: 用于选择颜色。

然后，在 edit 函数中，我们可以这样使用 InspectorControls：

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

export default function Edit( { attributes, setAttributes } ) {
    const { title, content, backgroundColor } = attributes;

    const onChangeTitle = ( newTitle ) => {
        setAttributes( { title: newTitle } );
    };

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

    const onChangeBackgroundColor = ( newBackgroundColor ) => {
        setAttributes( { backgroundColor: newBackgroundColor } );
    };

    return (
        <>
            <InspectorControls>
                <PanelBody title={ __( 'Block Settings', 'my-advanced-block' ) }>
                    <TextControl
                        label={ __( 'Title', 'my-advanced-block' ) }
                        value={ title }
                        onChange={ onChangeTitle }
                    />
                    <TextControl
                        label={ __( 'Content', 'my-advanced-block' ) }
                        value={ content }
                        onChange={ onChangeContent }
                        help={ __( 'Enter the content of the block.', 'my-advanced-block' ) }
                    />
                    <ColorPicker
                        label={ __( 'Background Color', 'my-advanced-block' ) }
                        color={ backgroundColor }
                        onChangeComplete={ ( value ) => onChangeBackgroundColor( value.hex ) }
                    />
                </PanelBody>
            </InspectorControls>
            <div { ...useBlockProps( {
                style: { backgroundColor: backgroundColor }
            } ) }>
                <h2>{ title }</h2>
                <p>{ content }</p>
            </div>
        </>
    );
}

在这个例子中，我们在 InspectorControls 中添加了一个 PanelBody，并在 PanelBody 中添加了三个设置项：

• TextControl 用于设置标题。
• TextControl 用于设置内容。
• ColorPicker 用于设置背景颜色。

每个设置项都通过 onChange 属性绑定了一个函数，该函数负责更新区块的属性。 setAttributes 函数用于更新区块的属性，并触发区块的重新渲染。

同时，我们在区块的 div 元素中使用了 useBlockProps 函数，并将 backgroundColor 属性应用到 style 属性中。 这样，区块的背景颜色就会根据用户的设置而改变。

4. 在 save.js 中使用属性

save.js 文件定义了区块在前端的呈现方式。 我们需要在这里使用区块的属性来生成 HTML 代码。

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

export default function save( { attributes } ) {
    const { title, content, backgroundColor } = attributes;

    return (
        <div { ...useBlockProps.save( {
            style: { backgroundColor: backgroundColor }
        } ) }>
            <h2>{ title }</h2>
            <p>{ content }</p>
        </div>
    );
}

在这个例子中，我们使用了 useBlockProps.save 函数来生成区块的 props，并将 backgroundColor 属性应用到 style 属性中。 这样，区块在前端的背景颜色也会根据用户的设置而改变。

5. 高级自定义设置面板

除了基本的文本输入和颜色选择，我们还可以使用 Inspector Controls 创建更高级的自定义设置面板。 例如，我们可以添加一个下拉菜单，让用户选择不同的字体大小。

首先，我们需要在 block.json 文件中添加一个新的属性：

{
    "apiVersion": 2,
    "name": "my-advanced-block/my-block",
    "title": "My Advanced Block",
    "category": "common",
    "icon": "smiley",
    "description": "A block with advanced customization options.",
    "supports": {
        "html": false
    },
    "attributes": {
        "title": {
            "type": "string",
            "default": "My Awesome Title"
        },
        "content": {
            "type": "string",
            "default": "This is the content of my block."
        },
        "backgroundColor": {
            "type": "string",
            "default": "#ffffff"
        },
        "fontSize": {
            "type": "string",
            "default": "medium"
        }
    },
    "textdomain": "my-advanced-block",
    "editorScript": "file:./build/index.js",
    "editorStyle": "file:./build/index.css",
    "style": "file:./build/style-index.css"
}

然后，在 edit.js 文件中，我们可以使用 SelectControl 组件来创建一个下拉菜单：

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

export default function Edit( { attributes, setAttributes } ) {
    const { title, content, backgroundColor, fontSize } = attributes;

    const onChangeTitle = ( newTitle ) => {
        setAttributes( { title: newTitle } );
    };

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

    const onChangeBackgroundColor = ( newBackgroundColor ) => {
        setAttributes( { backgroundColor: newBackgroundColor } );
    };

    const onChangeFontSize = ( newFontSize ) => {
        setAttributes( { fontSize: newFontSize } );
    };

    const fontSizes = [
        { label: __( 'Small', 'my-advanced-block' ), value: 'small' },
        { label: __( 'Medium', 'my-advanced-block' ), value: 'medium' },
        { label: __( 'Large', 'my-advanced-block' ), value: 'large' },
    ];

    return (
        <>
            <InspectorControls>
                <PanelBody title={ __( 'Block Settings', 'my-advanced-block' ) }>
                    <TextControl
                        label={ __( 'Title', 'my-advanced-block' ) }
                        value={ title }
                        onChange={ onChangeTitle }
                    />
                    <TextControl
                        label={ __( 'Content', 'my-advanced-block' ) }
                        value={ content }
                        onChange={ onChangeContent }
                        help={ __( 'Enter the content of the block.', 'my-advanced-block' ) }
                    />
                    <ColorPicker
                        label={ __( 'Background Color', 'my-advanced-block' ) }
                        color={ backgroundColor }
                        onChangeComplete={ ( value ) => onChangeBackgroundColor( value.hex ) }
                    />
                    <SelectControl
                        label={ __( 'Font Size', 'my-advanced-block' ) }
                        value={ fontSize }
                        options={ fontSizes }
                        onChange={ onChangeFontSize }
                    />
                </PanelBody>
            </InspectorControls>
            <div { ...useBlockProps( {
                style: {
                    backgroundColor: backgroundColor,
                    fontSize: fontSize === 'small' ? '12px' : fontSize === 'medium' ? '16px' : '20px'
                }
            } ) }>
                <h2>{ title }</h2>
                <p>{ content }</p>
            </div>
        </>
    );
}

在这个例子中，我们使用了 SelectControl 组件来创建一个下拉菜单，其中包含了三个选项：small、medium 和 large。 options 属性用于指定下拉菜单的选项，value 属性用于指定当前选中的选项，onChange 属性用于绑定一个函数，该函数负责更新区块的属性。

同时，我们在区块的 div 元素中使用了 fontSize 属性来设置字体大小。 我们使用了三元运算符来根据 fontSize 属性的值设置不同的字体大小。

最后，我们需要在 save.js 文件中使用 fontSize 属性来设置字体大小：

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

export default function save( { attributes } ) {
    const { title, content, backgroundColor, fontSize } = attributes;

    return (
        <div { ...useBlockProps.save( {
            style: {
                backgroundColor: backgroundColor,
                fontSize: fontSize === 'small' ? '12px' : fontSize === 'medium' ? '16px' : '20px'
            }
        } ) }>
            <h2>{ title }</h2>
            <p>{ content }</p>
        </div>
    );
}

6. 表格总结常用组件

组件名称	描述	常用属性
InspectorControls	用于在侧边栏中添加自定义设置面板。	无
PanelBody	用于将设置项分组。	title: 面板的标题，initialOpen: 是否默认展开
TextControl	用于输入文本。	label: 标签，value: 当前值，onChange: 值改变时的回调函数，help: 帮助文本
ColorPicker	用于选择颜色。	label: 标签，color: 当前颜色，onChangeComplete: 颜色选择完成时的回调函数
SelectControl	用于创建下拉菜单。	label: 标签，value: 当前值，options: 选项数组，onChange: 值改变时的回调函数
RangeControl	用于选择一个范围内的值。	label: 标签，value: 当前值，onChange: 值改变时的回调函数，min: 最小值，max: 最大值，step: 步长
ToggleControl	用于切换开关状态。	label: 标签，checked: 是否选中，onChange: 值改变时的回调函数
RadioControl	用于创建单选按钮组。	label: 标签，value: 当前值，options: 选项数组，onChange: 值改变时的回调函数
CheckboxControl	用于创建复选框。	label: 标签，checked: 是否选中，onChange: 值改变时的回调函数
Button	用于创建按钮。	isPrimary: 是否是主要按钮，isSecondary: 是否是次要按钮，onClick: 点击事件的回调函数
ExternalLink	用于创建外部链接。	href: 链接地址，children: 链接文本
TextareaControl	用于创建多行文本输入框。	label: 标签，value: 当前值，onChange: 值改变时的回调函数，help: 帮助文本

7. 代码优化与最佳实践

在实际开发中，我们需要注意代码的优化和最佳实践，以提高代码的可读性和可维护性。

• 代码复用: 将常用的设置项封装成自定义组件，以便在不同的区块中复用。
• 状态管理: 对于复杂的设置面板，可以使用 Redux 或 Context API 来管理状态。
• 代码注释: 添加详细的代码注释，方便其他开发者理解代码。
• 错误处理: 添加适当的错误处理机制，防止程序崩溃。
• 国际化: 使用 __() 函数对字符串进行国际化处理，以便支持多种语言。

8. 调试技巧

在开发过程中，我们经常需要调试代码。 以下是一些常用的调试技巧：

• 使用 console.log(): 在代码中添加 console.log() 语句，输出变量的值。
• 使用浏览器的开发者工具: 使用浏览器的开发者工具来查看 JavaScript 代码的执行过程和变量的值。
• 使用 Gutenberg 的调试模式: 在 WordPress 的 wp-config.php 文件中设置 WP_DEBUG 为 true，可以开启 Gutenberg 的调试模式，从而查看更多的调试信息。
• 使用 @wordpress/scripts 的 start 命令: npm start 命令会自动监听文件变化并重新编译，方便我们快速调试代码。

9. 进阶技巧

• 使用 ServerSideRender 组件: 对于需要动态生成 HTML 代码的区块，可以使用 ServerSideRender 组件将渲染任务交给服务器处理。
• 使用 Meta Box 集成: 可以使用 Meta Box 等插件来创建更复杂的自定义字段，并将这些字段集成到 Gutenberg 区块中。
• 自定义控件: 可以通过实现自定义的 React 组件来创建完全定制化的控件。

尾声：总结要点和启发

我们学习了如何使用 Inspector Controls 创建高级自定义设置面板，并结合 create-block 工具来提升开发效率。理解 block.json 的作用，合理使用各种组件，以及遵循代码优化和最佳实践，可以帮助你构建更加强大和灵活的 Gutenberg 区块。掌握这些技巧，你就可以构建出更加强大的 Gutenberg 区块，满足各种各样的需求。