富文本组件参考指南

富文本组件允许开发者渲染具有内容可编辑功能的输入区域，为用户提供格式化区块内容的选项，包括加粗、斜体、添加链接或其他格式设置。

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

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

与组件参考部分的其他组件不同，富文本组件独立存在，因为它仅适用于区块编辑器环境，不适用于WordPress的其他场景。

属性参数说明

如需查看富文本组件支持的完整属性列表，请查阅GitHub上的组件文档。

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

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

按钮区块：通过富文本组件输入按钮文字
标题区块：通过富文本组件输入标题文字
引用区块：两处使用富文本组件，分别用于引文内容和出处标注
搜索区块：两处使用富文本组件，分别用于搜索框标签和提交按钮文字

代码示例

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属性进行配置（详见前文示例或组件文档）。

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

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

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

实际应用时，需通过插件或主题队列加载上述脚本。具体方法请参考WordPress中加载JavaScript的JavaScript教程。

4.9 KiB Raw Permalink Blame History Unescape Escape