2025-10-22 01:40:18 +08:00

7.8 KiB

Raw Permalink Blame History

步骤4：仅对特定区块显示按钮（可选）

默认情况下，该按钮会显示在每个富文本工具栏中（如图片说明、按钮、段落等）。您可以通过使用数据API，仅针对特定类型的区块显示该按钮。

以下示例仅对段落区块显示按钮：

import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
import { RichTextToolbarButton } from '@wordpress/block-editor';
import { useSelect } from '@wordpress/data';

function ConditionalButton( { isActive, onChange, value } ) {
	const selectedBlock = useSelect( ( select ) => {
		return select( 'core/block-editor' ).getSelectedBlock();
	}, [] );

	if ( selectedBlock && selectedBlock.name !== 'core/paragraph' ) {
		return null;
	}

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

registerFormatType( 'my-custom-format/sample-output', {
	title: '示例输出',
	tagName: 'samp',
	className: null,
	edit: ConditionalButton,
} );

步骤5：在下拉菜单外添加按钮（可选）

使用 RichTextToolbarButton 组件时，按钮会被添加到默认的下拉菜单中。您可以通过使用 BlockControls 组件将按钮直接添加到工具栏。

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

const MyCustomButton = ( { isActive, onChange, value } ) => {
	return (
		<BlockControls>
			<ToolbarGroup>
				<ToolbarButton
					icon="editor-code"
					title="示例输出"
					onClick={ () => {
						onChange(
							toggleFormat( value, {
								type: 'my-custom-format/sample-output',
							} )
						);
					} }
					isActive={ isActive }
				/>
			</ToolbarGroup>
		</BlockControls>
	);
};

registerFormatType( 'my-custom-format/sample-output', {
	title: '示例输出',
	tagName: 'samp',
	className: null,
	edit: MyCustomButton,
} );

故障排除

如果遇到错误：

请再次确认是否已先运行 npm run build。
确认构建过程中没有语法错误或其他问题。
确认JavaScript已在编辑器中加载。
检查控制台是否有错误消息。

其他资源

本指南中使用的参考文档：

RichText：registerFormatType
组件：RichTextToolbarButton
RichText：applyFormat
RichText：removeFormat
RichText：toggleFormat

结论

本指南向您展示了如何在工具栏中添加按钮，并将其格式应用于选定的文本。请尝试使用它，并在下一个插件中探索更多可能性。

从 block-development-examples 仓库下载 format-api 示例。

格式化工具栏 API

概述

格式化 API 使开发者能够向格式化工具栏添加自定义按钮，并将特定_格式_应用于文本选区。加粗按钮就是格式化工具栏中标准按钮的一个示例。

在 WordPress 术语中，_格式_是指具有文本级语义的 HTML 标签，用于为文本选区赋予特殊含义。例如，本教程中要挂钩到格式工具栏的按钮将使用 <samp> HTML 标签包裹特定文本选区。

开始之前

本指南假设您已熟悉 WordPress 插件及其 JavaScript 加载方式，如需复习请参阅插件手册或 JavaScript 教程。

您需要准备：

WordPress 开发环境
已激活并配置就绪的最小化插件
用于构建和入队的 JavaScript 设置

您可参考完整的 format-api 示例进行设置。

分步指南

本指南将引用 src/index.js 作为进行更改的 JavaScript 文件。每步完成后，运行 npm run build 会生成 build/index.js，该文件随后将加载到文章编辑器界面。

步骤 1：注册新格式

第一步是注册新格式，在 src/index.js 中添加以下内容：

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

registerFormatType( 'my-custom-format/sample-output', {
	title: '示例输出',
	tagName: 'samp',
	className: null,
} );

可用格式类型列表由 core/rich-text 存储库维护。您可查询存储库以确认自定义格式现已可用。

在浏览器控制台中运行以下代码进行验证：

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

这将返回包含格式类型的数组，其中包括您自定义的格式。

步骤 2：向工具栏添加按钮

格式就绪后，下一步是通过为 edit 属性注册组件来向 UI 添加按钮。

使用 RichTextToolbarButton 组件，更新 src/index.js：

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

const MyCustomButton = ( props ) => {
	return (
		<RichTextToolbarButton
			icon="editor-code"
			title="示例输出"
			onClick={ () => {
				console.log( '切换格式' );
			} }
		/>
	);
};

registerFormatType( 'my-custom-format/sample-output', {
	title: '示例输出',
	tagName: 'samp',
	className: null,
	edit: MyCustomButton,
} );

检查功能是否正常：构建并重新加载后，选择任意包含文本的区块（例如段落区块）。确认新按钮已添加到格式工具栏。

点击按钮并在控制台中查看 "toggle format" 消息。

如果未看到按钮或消息，请仔细检查是否正确构建和加载了 JavaScript，并查看控制台是否有错误信息。

步骤 3：点击时应用格式

接下来是更新按钮，在点击时应用格式。

在本示例中，<samp> 标签格式是二元的——文本选区要么具有该标签，要么没有，因此我们可以使用 RichText 包中的 toggleFormat 方法。

更新 src/index.js，修改 onClick 操作：

import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
import { RichTextToolbarButton } from '@wordpress/block-editor';

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

registerFormatType( 'my-custom-format/sample-output', {
	title: '示例输出',
	tagName: 'samp',
	className: null,
	edit: MyCustomButton,
} );

验证功能：先构建并重新加载，然后选择文本并点击按钮。浏览器可能会以不同于周围文本的方式显示该选区。

您也可以通过切换到 HTML 视图（代码编辑器 Ctrl+Shift+Alt+M）来确认，查看被 <samp> HTML 标签包裹的文本选区。

注册时使用 className 选项可向标签添加自定义类。您可以使用该类配合自定义 CSS 来定位元素并按需设置样式。

7.8 KiB Raw Permalink Blame History Unescape Escape