# 富文本组件参考指南

富文本组件允许开发者渲染具有[内容可编辑功能](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content)的输入区域，为用户提供格式化区块内容的选项，包括加粗、斜体、添加链接或其他格式设置。

该组件功能极其强大，具备其他组件所没有的内置功能：

-   **管理界面与前端样式一致性**：可编辑容器可设置为任何块级元素，如`div`、`h2`或`p`标签。这使得在style.css中定义的样式能同时适配前端和管理界面，无需在editor.css中重复编写。
-   **一体化占位文本**：在用户输入内容前，可轻松添加已预设样式的占位文本，与区块编辑器的整体风格保持统一。
-   **格式控制权限**：可精确指定富文本字段允许的格式选项。例如，可设置是否允许用户使用加粗、斜体或两者兼用。

与[组件参考](/packages/components/README.md)部分的其他组件不同，富文本组件独立存在，因为它仅适用于区块编辑器环境，不适用于WordPress的其他场景。

## 属性参数说明

如需查看富文本组件支持的完整属性列表，请[查阅GitHub上的组件文档](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md)。

## 使用富文本组件的核心区块

以下核心区块均使用了富文本组件。每个区块对应的JavaScript编辑函数（下方链接）可作为开发自定义区块时的最佳实践参考：

-   **[按钮区块](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/button/edit.js)**：通过富文本组件输入按钮文字
-   **[标题区块](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/heading/edit.js)**：通过富文本组件输入标题文字
-   **[引用区块](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/quote/edit.js)**：两处使用富文本组件，分别用于引文内容和出处标注
-   **[搜索区块](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/search/edit.js)**：两处使用富文本组件，分别用于搜索框标签和提交按钮文字

## 代码示例

```jsx
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText } from '@wordpress/block-editor';

registerBlockType( /* ... */, {
	// ...

	attributes: {
		content: {
			type: 'string',
			source: 'html',
			selector: 'h2',
		},
	},

	edit( { attributes, setAttributes } ) {
		const blockProps = useBlockProps();

		return (
			<RichText
				{ ...blockProps }
				tagName="h2" // 此处的标签决定管理界面的可编辑元素及最终输出元素
				value={ attributes.content } // 现有内容（来自数据库或属性默认值）
				allowedFormats={ [ 'core/bold', 'core/italic' ] } // 仅允许内容设置为加粗/斜体，禁用其他格式选项
				onChange={ ( content ) => setAttributes( { content } ) } // 将更新内容存储为区块属性
				placeholder={ __( '输入标题...' ) } // 用户添加内容前显示的提示文本
			/>
		);
	},

	save( { attributes } ) {
		const blockProps = useBlockProps.save();

		return <RichText.Content { ...blockProps } tagName="h2" value={ attributes.content } />; // 将<h2>编辑器添加的内容...</h2>保存至数据库供前端显示
	}
} );
```

## 常见问题与解决方案

使用富文本组件时，常会遇到以下几类问题：

### HTML格式标签在内容中可见

若文本格式相关的HTML标签（如`<strong>`或`em>`）被转义并在网站前端显示，这通常源于保存函数的问题。请确保代码采用`<RichText.Content tagName="h2" value={ heading } />`（JSX语法）形式，而非直接使用`<h2>{ heading }</h2>`输出值。

### 仍显示不需要的格式选项

在继续操作前，请先评估使用富文本组件的必要性。是否使用基础的`input`或`textarea`元素更为合适？若无需任何格式功能，这些HTML标签可能是更优选择。

若仍需使用富文本组件，可通过指定`withoutInteractiveFormatting`属性来禁用所有格式选项。

若需限制允许的格式类型，可在代码中通过`allowedFormats`属性进行配置（详见前文示例或[组件文档](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md#allowedformats-array)）。

### 在编辑器中禁用特定格式类型

富文本组件使用格式来显示行内元素（例如段落区块中的图片）。若仅需在编辑器中禁用某格式，可使用`unregisterFormatType`函数。例如禁用行内图片格式：

```
wp.richText.unregisterFormatType( 'core/image' );
```

实际应用时，需通过插件或主题队列加载上述脚本。具体方法请参考[WordPress中加载JavaScript](https://developer.wordpress.org/block-editor/how-to-guides/javascript/loading-javascript/)的JavaScript教程。