RichText 参考

最后更新：2026-10-17 10:55:29

RichText 是一个组件，允许开发者渲染一个 contenteditable 输入框，为用户提供将块级内容格式化为粗体、斜体、链接或其他格式选项的功能。

RichText 组件非常强大，因为它提供了在其他组件中找不到的内置功能：

管理后台和前端样式一致：可编辑容器可以设置为任何块级元素，例如 div、h2 或 p 标签。这使得您在 style.css 中应用的样式更容易在前端和管理后台生效，而无需在 editor.css 中重新编写它们。
统一的占位符文本：在用户输入内容之前，可以轻松添加已经过样式设置的占位符文本，使其与块编辑器其余部分保持一致。
控制格式选项：您可以精确指定希望 RichText 字段允许的格式选项。例如，您可以规定是否允许用户将文本设置为粗体、斜体或两者兼有。

与其他存在于组件参考部分的组件不同，RichText 单独存在，因为它仅在块编辑器中有意义，而在 WordPress 的其他区域中没有意义。

属性参考

有关要传递给 RichText 组件的可能属性列表，请查看 GitHub 上的组件文档。

使用 RichText 组件的核心区块

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

按钮 (Button)：RichText 用于输入按钮文本。
标题 (Heading)：RichText 用于输入标题文本。
引用 (Quote)：RichText 在两个地方使用，分别用于引文和出处文本。
搜索 (Search)：RichText 在两个地方使用，分别用于搜索字段上方的标签和提交按钮文本。

示例

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={ __( 'Heading...' ) } // 在用户添加任何内容之前显示此文本
            />
        );
    },

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

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

常见问题及解决方案

在使用 RichText 组件时，通常会出现一些常见问题。

HTML 格式标签显示在内容中

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

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

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

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

如果要限制允许的格式，可以在代码中使用 allowedFormats 属性进行指定，请参阅上面的示例或组件文档以获取详细信息。

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

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

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

要使更改生效，您需要在插件或主题中入队上述脚本。请参阅如何在 WordPress 中加载 JavaScript 的 JavaScript 教程。