90 lines
4.9 KiB
Markdown
90 lines
4.9 KiB
Markdown
# 富文本组件参考指南
|
||
|
||
富文本组件允许开发者渲染具有[内容可编辑功能](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教程。 |