# RichText 参考

RichText 是一个允许开发者渲染 [`contenteditable` 输入框](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content)的组件，为用户提供格式化块级内容的选项，例如加粗、斜体、添加链接或其他格式。

RichText 组件功能极其强大，因为它提供了其他组件不具备的内置功能：

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

与[组件参考](/packages/components/README)部分中的其他组件不同，RichText 单独存在，因为它仅在区块编辑器中有意义，而不适用于 WordPress 的其他区域。

## 属性参考

如需了解可传递给 RichText 组件的属性列表，[请查看 GitHub 上的组件文档](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md)。

## 使用 RichText 组件的核心区块

有许多核心区块使用了 RichText 组件。下面为每个区块链接的 JavaScript 编辑函数，可作为创建自定义区块时的最佳实践参考。

-   **[按钮](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/button/edit.js):** RichText 用于输入按钮文本。
-   **[标题](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/heading/edit.js):** RichText 用于输入标题文本。
-   **[引用](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/quote/edit.js):** RichText 用于两个地方，分别用于引文和出处文本。
-   **[搜索](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/search/edit.js):** RichText 用于两个地方，分别用于搜索字段上方的标签和提交按钮文本。

## Example



```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" // The tag here is the element output and editable in the admin
				value={ attributes.content } // Any existing content, either from the database or an attribute default
				allowedFormats={ [ 'core/bold', 'core/italic' ] } // Allow the content to be made bold or italic, but do not allow other formatting options
				onChange={ ( content ) => setAttributes( { content } ) } // Store updated content as a block attribute
				placeholder={ __( 'Heading...' ) } // Display this text before any content has been added by the user
			/>
		);
	},

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

		return <RichText.Content { ...blockProps } tagName="h2" value={ attributes.content } />; // Saves <h2>Content added in the editor...</h2> to the database for frontend display
	}
} );
```

## 常见问题与解决方案

使用 RichText 组件时，常会出现一些典型问题。

### HTML 格式标签在内容中显示

如果文本格式化所用的 HTML 标签（如 `<strong>` 或 `<em>`）被转义并在网站前端显示，这很可能是保存函数的问题。请确保在保存函数中使用类似 `<RichText.Content tagName="h2" value={ heading } />`（JSX）的代码，而不是简单地用 `<h2>{ heading }</h2>` 输出值。

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

在继续之前，请考虑使用 RichText 组件是否完全合理。使用基本的 `input` 或 `textarea` 元素是否更好？如果您认为不应允许任何格式，这些 HTML 标签可能更合适。

如果您仍想使用 RichText，可以通过指定 `withoutInteractiveFormatting` 属性来消除所有格式选项。

如果您想限制允许的格式，可以在代码中指定 `allowedFormats` 属性，详情请参见上面的示例或[组件文档](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md#allowedformats-array)。

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

RichText 组件使用格式来显示内联元素，例如段落块内的图像。如果您只想在编辑器中禁用某种格式，可以使用 `unregisterFormatType` 函数。例如，要禁用内联图像，请使用：

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

要应用此更改，您需要在插件或主题中排队加载上述脚本。有关如何在 WordPress 中加载 JavaScript，请参阅 JavaScript 教程：[如何在 WordPress 中加载 JavaScript](https://developer.wordpress.org/block-editor/how-to-guides/javascript/loading-javascript/)。