WordPress Gutenberg 编辑器格式工具栏 API 开发指南

最新推荐文章于 2025-06-04 09:00:12 发布

平樱玫Duncan

最新推荐文章于 2025-06-04 09:00:12 发布

阅读量294

点赞数 5

本文链接：https://blog.youkuaiyun.com/gitblog_00626/article/details/148415065

版权

WordPress Gutenberg 编辑器格式工具栏 API 开发指南

gutenberg The Block Editor project for WordPress and beyond. Plugin is available from the official repository. 项目地址: https://gitcode.com/gh_mirrors/gu/gutenberg

概述

在 WordPress Gutenberg 编辑器中，格式工具栏 API 允许开发者向富文本编辑器的工具栏添加自定义按钮，这些按钮可以对选中的文本应用特定的格式。本文将详细介绍如何利用这个强大的 API 来扩展编辑器的功能。

核心概念

什么是格式？

在 WordPress 中，格式指的是具有文本级语义的 HTML 标签，用于为选中的文本赋予特殊含义。例如：

<strong> 表示重要文本
<em> 表示强调文本
<samp> 表示计算机代码输出示例

格式工具栏 API 的作用

通过这个 API，开发者可以：

注册新的文本格式类型
向工具栏添加自定义按钮
控制按钮的显示逻辑
定义格式应用的行为

开发准备

在开始之前，请确保：

已搭建 WordPress 开发环境
已创建并激活一个基础插件
配置好 JavaScript 构建环境（如 webpack）
熟悉 React 和 WordPress 组件系统

实战教程

第一步：注册新格式类型

首先需要注册一个新的格式类型，这是整个流程的基础：

import { registerFormatType } from '@wordpress/rich-text';

registerFormatType( 'my-plugin/sample-format', {
    title: '示例输出',  // 格式的名称
    tagName: 'samp',   // 使用的HTML标签
    className: null,   // 可选的CSS类名
});

这段代码注册了一个使用 <samp> 标签的格式类型。注册后，可以通过以下方式验证是否成功：

wp.data.select( 'core/rich-text' ).getFormatTypes();

第二步：添加工具栏按钮

注册格式后，需要为其添加可视化按钮：

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

const FormatButton = ( props ) => (
    <RichTextToolbarButton
        icon="editor-code"  // 使用WordPress Dashicon
        title="示例输出"
        onClick={ () => console.log('点击按钮') }
    />
);

// 更新注册代码，添加edit属性
registerFormatType( 'my-plugin/sample-format', {
    title: '示例输出',
    tagName: 'samp',
    className: null,
    edit: FormatButton,
});

构建并刷新后，在段落块中选择文本，应该能看到新增的按钮。

第三步：实现格式切换功能

现在让按钮真正发挥作用：

import { toggleFormat } from '@wordpress/rich-text';

const FormatButton = ({ isActive, onChange, value }) => (
    <RichTextToolbarButton
        icon="editor-code"
        title="示例输出"
        onClick={ () => {
            onChange(
                toggleFormat(value, {
                    type: 'my-plugin/sample-format'
                })
            );
        }}
        isActive={ isActive }
    />
);

关键点说明：

toggleFormat 自动处理格式的添加/移除
isActive 属性控制按钮的激活状态
value 和 onChange 来自富文本组件的props

第四步：条件显示按钮（进阶）

默认情况下按钮会出现在所有富文本工具栏中，可以通过以下方式限制显示范围：

import { useSelect } from '@wordpress/data';

const ConditionalButton = (props) => {
    const selectedBlock = useSelect( select => 
        select('core/block-editor').getSelectedBlock()
    );
    
    if (selectedBlock?.name !== 'core/paragraph') {
        return null;
    }
    
    return <FormatButton {...props} />;
};

第五步：在工具栏直接显示按钮（非下拉菜单）

如果需要按钮直接显示在主工具栏中：

import { BlockControls } from '@wordpress/block-editor';
import { ToolbarGroup, ToolbarButton } from '@wordpress/components';

const ToolbarButton = (props) => (
    <BlockControls>
        <ToolbarGroup>
            <ToolbarButton
                icon="editor-code"
                title="示例输出"
                onClick={ /* 同前 */ }
                isActive={ props.isActive }
            />
        </ToolbarGroup>
    </BlockControls>
);