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

默认情况下，该按钮会显示在每个富文本工具栏中（如图片说明、按钮、段落等）。您可以通过使用[数据API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data)，仅针对特定类型的区块显示该按钮。

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

```js
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` 组件将按钮直接添加到工具栏。

```js
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`](/packages/rich-text/README.md#registerformattype)
-   组件：[`RichTextToolbarButton`](/packages/block-editor/README.md#richtexttoolbarbutton)
-   RichText：[`applyFormat`](/packages/rich-text/README.md#applyformat)
-   RichText：[`removeFormat`](/packages/rich-text/README.md#removeformat)
-   RichText：[`toggleFormat`](/packages/rich-text/README.md#toggleformat)

## 结论

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

从 [block-development-examples](https://github.com/WordPress/block-development-examples) 仓库下载 [format-api 示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/format-api-f14b86)。

# 格式化工具栏 API

## 概述

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

![格式化 API 工具栏动态示例](https://developer.wordpress.org/files/2021/12/format-api-example.gif)

在 WordPress 术语中，_格式_是指具有[文本级语义的 HTML 标签](https://www.w3.org/TR/html5/textlevel-semantics.html#text-level-semantics-usage-summary)，用于为文本选区赋予特殊含义。例如，本教程中要挂钩到格式工具栏的按钮将使用 `<samp>` HTML 标签包裹特定文本选区。

## 开始之前

本指南假设您已熟悉 WordPress 插件及其 JavaScript 加载方式，如需复习请参阅[插件手册](https://developer.wordpress.org/plugins/)或 [JavaScript 教程](/docs/getting-started/fundamentals/javascript-in-the-block-editor.md)。

您需要准备：

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

您可参考[完整的 format-api 示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/format-api-f14b86)进行设置。

## 分步指南

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

### 步骤 1：注册新格式

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

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

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

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

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

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

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

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

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

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

```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,
} );
```

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

![含自定义按钮的工具栏](https://developer.wordpress.org/files/2021/12/format-api-toolbar.png)

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

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

### 步骤 3：点击时应用格式

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

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

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

```js
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 来定位元素并按需设置样式。