格式工具栏 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: 'Sample output',
	tagName: 'samp',
	className: null,
} );

可用格式类型的列表保存在 core/rich-text 存储中。您可以查询该存储以确认您的自定义格式现已可用。

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

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

它将返回一个包含格式类型的数组，其中也包括您自己的格式。

Step 2: Add a button to the toolbar

With the format available, the next step is to add a button to the UI by registering a component for the edit property.

Using the RichTextToolbarButton component, update src/index.js:

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

const MyCustomButton = ( props ) => {
	return (
		<RichTextToolbarButton
			icon="editor-code"
			title="Sample output"
			onClick={ () => {
				console.log( 'toggle format' );
			} }
		/>
	);
};

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

Let's check that everything is working as expected. Build and reload and then select any block containing text like for example the paragraph block. Confirm the new button was added to the format toolbar.

Toolbar with custom button

Click the button and check the console.log for the "toggle format" message.

If you do not see the button or message, double check you are building and loading the JavaScript properly; and check the console.log for any errors.

Step 3: Apply a format when clicked

Next is to update the button to apply a format when clicked.

For our example, the <samp> tag format is binary - either a text selection has the tag or not, so we can use the toggleFormat method from the RichText package.

Update src/index.js changing the onClick action:

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

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

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

Confirm it is working: first build and reload, then make a text selection and click the button. Your browser will likely display that selection differently than the surrounding text.

You can also confirm by switching to HTML view (Code editor Ctrl+Shift+Alt+M) and see the text selection wrapped with <samp> HTML tags.

Use the className option when registering to add your own custom class to the tag. You can use that class and custom CSS to target that element and style as you wish.

Step 4: Show the button only for specific blocks (Optional)

By default, the button is rendered on every rich text toolbar (image captions, buttons, paragraphs, etc). You can render the button only on blocks of a certain type by using the data API.

Here is an example that only shows the button for Paragraph blocks:

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="Sample output"
			onClick={ () => {
				onChange(
					toggleFormat( value, {
						type: 'my-custom-format/sample-output',
					} )
				);
			} }
			isActive={ isActive }
		/>
	);
}

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

Step 5: Add a button outside of the dropdown (Optional)

Using the RichTextToolbarButton component, the button is added to the default dropdown menu. You can add the button directly to the toolbar by using the BlockControls component.

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="Sample output"
					onClick={ () => {
						onChange(
							toggleFormat( value, {
								type: 'my-custom-format/sample-output',
							} )
						);
					} }
					isActive={ isActive }
				/>
			</ToolbarGroup>
		</BlockControls>
	);
};

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

故障排除

如果遇到错误：

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

其他资源

本指南使用的参考文档：

RichText：registerFormatType
Components：RichTextToolbarButton
RichText：applyFormat
RichText：removeFormat
RichText：toggleFormat

总结

本指南展示了如何向工具栏添加按钮，并使其对选定文本应用格式。请尝试使用，看看您能在下一个插件中用它构建什么功能。

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

这篇文档对你有帮助吗？