EditableTextGutenberg 无格式纯文本编辑组件完全指南【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergEditableText是 Gutenberg 块编辑器WordPress Block Editor提供的专用文本编辑组件它渲染一个可编辑文本输入但不允许任何文本格式化加粗、斜体、链接等富文本格式一律禁用。本文以 Gutenberg 仓库中 packages/block-editor/src/components/editable-text/README.md 为主线结合 index.jsx 源码与其底层RichText实现完整讲解全部属性、EditableText.Content保存机制、完整注册示例与源码级工作原理帮助你为自定义块实现纯文本输入如标题、按钮文案、短文本字段等。一、EditableText是什么在块编辑器中RichText是功能最完整的富文本组件支持加粗、斜体、链接、行内代码等格式。但很多块只需要一个纯文本输入例如按钮文字、标签文本、短标题此时使用RichText反而会让用户误以为可以加粗或加链接造成内容不一致。EditableText正是为解决这一问题而生。从源码看它是RichText的一个极薄封装// packages/block-editor/src/components/editable-text/index.jsx import { forwardRef } from wordpress/element; import RichText from ../rich-text; const EditableText forwardRef( ( props, ref ) { return RichText ref{ ref } { ...props } __unstableDisableFormats /; } );它只做了一件事把RichText渲染出来并强制传入__unstableDisableFormats禁用格式。因此它继承了RichText的编辑能力可点击、可选中、支持快捷键、支持onMerge/onReplace/onRemove等块级操作但彻底关闭了文本格式化。其官方描述为Renders an editable text input in which text formatting is not allowed.——渲染一个不允许文本格式化的可编辑文本输入。二、组件属性Properties完整说明以下是该组件支持的属性其中value与onChange为必填项其余为可选项。2.1value: String必填要编辑的字符串值。它是受控组件的当前内容与块的attributes绑定。2.2onChange( value: String ): Function必填值发生变化时被调用参数为变化后的新字符串。典型用法是回调setAttributes更新块属性onChange{ ( content ) setAttributes( { content } ) }2.3tagName: String渲染的可编辑元素标签名默认值为div。你可以改成h1、h2、p、span等任何合法 HTML 标签参考 HTML 标签名规范。例如标题类块常常使用h2使编辑区域的语义结构与最终渲染一致。2.4disableLineBreaks: Boolean可选默认false。设为true时按Enter键将不会插入换行。适合单行短文本场景如按钮文案、标签文字。在RichText底层该属性同时用于设置可编辑元素的aria-multiline无障碍属性见 packages/block-editor/src/components/rich-text/index.jsx保证辅助技术能正确感知这是单行输入。2.5placeholder: String可选字段为空时显示的占位提示文本语义与原生input/textarea的placeholder属性一致。空值时显示用户一旦输入即消失。2.6onReplace( blocks: Array ): Function可选当该可编辑实例可被给定的块数组替换时调用。典型场景是回车拆分行当用户在纯文本内回车且当前块支持拆分时编辑器可把当前块替换为多个块。blocks是用于替换的块对象数组。2.7onMerge( forward: Boolean ): Function可选当块可以合并时调用。forward为true表示与下一个块合并为false表示与上一个块合并。用户执行删除操作跨越块边界如 Backspace 删到块首时会触发。2.8onRemove( forward: Boolean ): Function可选当块可以被移除时调用。forward为true表示选区预期移动到下一个块为false表示移动到上一个块。典型场景空块中按 Backspace/Delete 移除当前块。三、EditableText.Content在save中正确保存内容EditableText.Content必须用在块的save函数中以正确输出保存到数据库的内容。它是纯静态渲染组件不包含任何编辑逻辑// packages/block-editor/src/components/editable-text/index.jsx EditableText.Content function Content( { value , tagName: Tag div, ...props } ) { return Tag { ...props }{ value }/Tag; };要点value默认为空字符串tagName默认div与编辑态组件的默认行为保持一致其余props如className、style会透传到最终的 HTML 标签上它把value作为纯文本子节点输出——不做 HTML 转义之外的任何处理这正是无格式语义的保存端落点。因为EditableText禁用了所有格式保存端无需像RichText.Content那样处理嵌套 HTML直接输出文本即可前后端行为严格一致。四、完整示例注册一个纯文本块以下示例完整取自组件文档展示了如何用EditableText注册一个文本属性为纯文本的块const { registerBlockType } wp.blocks; const { EditableText } wp.editor; registerBlockType( /* ... */, { // ... attributes: { content: { source: html, selector: .text, }, }, edit( { className, attributes, setAttributes } ) { return ( EditableText className{ className } value{ attributes.content } onChange{ ( content ) setAttributes( { content } ) } / ); }, save( { attributes } ) { return EditableText.Content value{ attributes.content } /; } } );要点拆解属性声明content使用source: htmlselector: .text从保存的 HTML 中的.text元素提取内容。由于EditableText不允许格式这里的内容必然是纯文本。edit渲染EditableText用attributes.content作为受控值onChange时通过setAttributes写回块属性。className透传便于复用块级样式类。save使用EditableText.Content输出保存内容保证编辑器输出与前端渲染一致。若想增强语义可组合使用可选属性edit( { className, attributes, setAttributes } ) { return ( EditableText tagNameh2 className{ className } value{ attributes.content } placeholder请输入标题… disableLineBreaks onChange{ ( content ) setAttributes( { content } ) } / ); },在模块化开发中更推荐从wordpress/block-editor导入import { EditableText } from wordpress/block-editor;五、源码级原理EditableText如何做到无格式5.1 禁用格式的真正机制EditableText通过向RichText传入__unstableDisableFormats实现无格式。在RichTextWrapper中该属性被解构为disableFormats见 packages/block-editor/src/components/rich-text/index.jsx随后进入格式白名单计算// packages/block-editor/src/components/rich-text/utils.jsx export function getAllowedFormats( { allowedFormats, disableFormats } ) { if ( disableFormats ) { return getAllowedFormats.EMPTY_ARRAY; } return allowedFormats; } getAllowedFormats.EMPTY_ARRAY [];当disableFormats为真时允许的格式列表被置为空数组所有格式类型format types都被排除工具栏不显示格式化按钮、粘贴的富文本格式被剥离、快捷键如 CtrlB不会生效。这比逐项列出允许的格式allowedFormats更彻底从根源上杜绝了任何格式化。同时RichText内部还有hasFormats判断const hasFormats ! adjustedAllowedFormats || adjustedAllowedFormats.length 0;格式列表为空意味着hasFormats为false格式化工具栏等相关 UI 不再渲染。5.2 与RichText、PlainText的关系三者定位不同可按下表选用组件是否允许格式换行支持典型场景RichText允许可配allowedFormats白名单支持段落、标题、列表等富文本内容EditableText禁止无格式纯文本可配disableLineBreaks短文本字段、按钮文案、单行标题PlainText禁止原生textarea无内联编辑能力支持需要多行纯文本但不需要块内编辑体验的字段特别值得注意的是PlainText与EditableText的关联在 packages/block-editor/src/components/plain-text/index.jsx 中当PlainText收到__experimentalVersion 2时其 v2 实现直接渲染EditableTextif ( __experimentalVersion 2 ) { return EditableText ref{ ref } { ...props } /; }这说明EditableText正逐步成为新一代纯文本输入的基础设施——它用 contentEditable 语义取代原生textarea在保持无格式的同时获得块编辑器原生的光标、选区、快捷键与块间合并/替换协作能力。5.3 块级操作如何工作onReplace、onMerge、onRemove三个回调并非EditableText独有而是RichText透传给块编辑上下文的能力onReplace回车拆分或粘贴转换时用新块数组替换当前块onMerge跨块删除时与相邻块合并forward决定方向onRemove空块删除时把选区移交到相邻块。这些回调由块编辑器的RichText内部事件监听器快捷键、输入事件统一驱动见 packages/block-editor/src/components/rich-text/index.jsx 附近的事件参数传递。对EditableText而言传入这些回调即可获得与RichText完全一致的块级编辑体验而无需担心格式问题。六、实战建议与注意事项保存端必须用EditableText.Content不要手写div{ value }/div替代使用Content能保证tagName默认值与编辑态一致并自动处理透传属性。单行文本务必开启disableLineBreaks按钮、标签类文本如果允许换行样式上容易出现意外折行开启后Enter不再插入换行同时aria-multiline也会被正确置为false。属性提取用source: html还是source: text由于EditableText内容为纯文本两者通常等价但若你希望保存端保留标签包裹如h2应使用source: html加selector如文档示例所示。选择组件时想清楚编辑体验需要内联编辑 无格式 →EditableText需要原生textarea行为如代码块、多行日志→PlainText需要富文本 →RichText。七、延伸阅读组件源码packages/block-editor/src/components/editable-text/index.jsx底层实现packages/block-editor/src/components/rich-text/index.jsx格式白名单计算packages/block-editor/src/components/rich-text/utils.jsx同类组件packages/block-editor/src/components/plain-text/index.jsx实际使用案例核心块库中的标题类、按钮类块大量采用禁用换行 无格式的输入模式可在 packages/block-library 中搜索disableLineBreaks查看真实用法。掌握了EditableText你就能为任意自定义块快速搭建所见即所得、但不允许格式漂移的纯文本输入体验让内容结构与样式都保持在可控范围内。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考