Gutenberg 块设计指南从内容区到工具栏、侧栏与设置状态的最佳实践【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本篇指南以 Gutenberg 项目的官方块设计文档 docs/explanations/user-interface/block-design.md 为核心骨架结合仓库内 Paragraph、Image、Latest Posts 等核心块的block.json元数据与源码实现系统讲解在设计一个新块Block时应遵循的界面层级、交互状态与命名规范。读完本篇你将掌握内容区优先、工具栏其次、侧栏兜底的三级界面原则理解 Setup state设置状态与 live preview state实时预览状态的取舍标准并能依据可落地的 Dos and Donts 清单为块命名、撰写描述、配置占位符与高级设置。为什么需要块设计规范块是 Gutenberg 编辑器的基本构成单元用户在编辑器中插入、操作、配置块的方式直接决定了他们对编辑器的第一印象。一个设计良好的块应当遵循直接操作direct manipulation原则用户希望所见即所得不希望为了完成基础操作而在多层界面之间来回切换。本文总结的规范正是围绕这一目标展开的其核心主张可以用一句话概括内容区是块的主界面块工具栏是次要界面设置侧栏只放三级、高级的配置项。下文将逐一展开这三层界面的定位、约束与适用场景并结合仓库内真实块实现进行印证。主界面块的内容区优先块在站点上最终呈现的内容就是它与用户交互的第一界面。由于块本身代表了即将出现在站点上的实际内容在这里交互最贴近直接操作原则对用户也最直观。内容区的交互有两种形式占位内容作为操作向导。内容区中的占位符Placeholder可以理解为引导用户完成一组指令或填空的界面。例如一个嵌入第三方服务内容的块可以在占位符内直接提供登录该服务的控件。选中块后揭示额外控件。用户添加内容后选中块可以显示用于调整或编辑内容的额外控件。例如一个订阅Signup块在被选中后可以显示显示/隐藏订阅人数的开关。但这种揭示应当保持最小化避免选中块时剧烈改变其尺寸和外观——这会令用户感到迷失或厌烦。这一原则在仓库的 Paragraph 块中有直观体现。查看其编辑器实现 packages/block-library/src/paragraph/edit.jsx当段落内容为空时RichText组件会渲染占位文本Type / to choose a block输入/以选择块并在选中后消失placeholder{ placeholder || __( Type / to choose a block ) }>BlockControls groupblock ParagraphRTLControl direction{ direction } setDirection{ ( newDirection ) setAttributes( { direction: newDirection } ) } / /BlockControls从文档描述可以推断工具栏分组是层级化的段内可以再细分但不要为每一个控件单独开一段——这是 Dos and Donts 中明确强调的一点。三级界面设置侧栏只放高级、三级控件设置侧栏Settings Sidebar在移动/小屏幕上默认不可见在桌面视图下也可能被折叠。因此任何块基础操作所必需的内容都不能依赖侧栏。设计要点包括选好默认值为块提供合理的默认状态让大多数用户无需打开侧栏重要操作放工具栏把关键动作前置到内容区或工具栏把侧栏当作大多数用户无需打开的存在。当选项超过少数几个时应在侧栏中使用分区和标题sections and headers便于用户快速扫描和理解可用选项。此外每个设置侧栏默认自带一个Advanced高级区域其中包含Additional CSS Class附加 CSS 类字段应利用该区域存放面向进阶用户的控件。Paragraph 块正是一个范例其block.json中声明的dropCap首字下沉属性是一个布尔开关默认false它被放置在Block标签页的排版分区中属于可选配置而非基础操作所需attributes: { content: { type: rich-text, source: rich-text, selector: p, role: content }, dropCap: { type: boolean, default: false } }对应源码 packages/block-library/src/paragraph/edit.jsx 中DropCapControl仅在块被选中时才渲染isSingleSelected 并通过ToggleControl切换帮助文本会根据文本对齐情况动态变化Not available for aligned text. / Showing large initial letter. 等。这正是侧栏存放非必要配置原则的落地实现。设置状态 vs. 实时预览状态设置状态Setup state有时被称为占位符Placeholder用于在展示块的实时预览状态之前引导用户完成一个初始流程。设置过程从用户处收集渲染块所需的信息。块的设置状态以灰色背景标示为用户提供清晰的视觉区分。并非所有块都有设置状态——例如 Paragraph 块就没有。关于设置状态的使用文档给出了明确的双向标准不需要设置状态如果你可以在块中提供满足大多数人需求的良好默认内容且该默认内容易于编辑和自定义。应该使用设置状态如果不存在对大多数用户都适用的明确默认状态你需要收集与块实时预览没有一一对应关系的输入例如需要用户输入 API 密钥来渲染内容你需要从用户处获取更多信息才能渲染出有用的默认内容。对于有设置状态的块用户完成设置流程后占位符即被替换为该块的实时预览状态。当块被选中时可以揭示额外控件来自定义块内容——例如 Image Gallery 被选中时会显示移除/添加图片的控件。大多数情况下块的设置状态只展示一次之后通过实时预览状态完成进一步自定义。但在某些场景下允许用户返回设置状态是可取的——例如当块的全部内容被删除时或通过块工具栏/侧栏中的链接返回。仓库中的 Placeholder 组件Gutenberg 仓库为这一状态提供了统一的组件基础packages/components/src/placeholder/README.md 中的Placeholder组件用法如下import { Placeholder } from wordpress/components; import { more } from wordpress/icons; const MyPlaceholder () Placeholder icon{ more } labelPlaceholder /;该组件支持的关键 Props 包括Prop类型说明classNamestring设置到容器 div 上的类名iconstring\|Function\|Component\|null若提供则在标签旁渲染一个图标instructionsstring占位符的使用说明文字labelstring占位符的标题noticesReactNode已渲染的通知列表previewReactNode在占位符内渲染的预览withIllustrationboolean是否输出占位符插图Image 块是这一模式的完整示例。查看其编辑器实现 packages/block-library/src/image/edit.jsx未选中图片时渲染的是Placeholder/MediaPlaceholder提供上传图片、直接拖放图片、从媒体库选择图片等操作入口选中并上传图片后则切换到富文本标题输入figcaption等实时预览控件。这也与文档中占位符消失、出现 Write caption… 标题输入框的描述一致。Dos and Donts可落地的设计检查清单块工具栏按逻辑分段分组工具栏控件应归入逻辑分段不要为每个控件单独开一段。过多的分段会让工具栏变得碎片化、难以扫描。块标识简短、清晰、可检索块应有一个简洁、简短的名字让用户能轻松在块库中找到它。名为YouTube的块易找易理解而命名为Embedded Video (YouTube)则会更难被找到。在文档或 UI 中引用块时块标题用 Title Case首字母大写block 描述词用小写例如Paragraph blockLatest Posts blockMedia Text block块的命名规范在注册层面同样重要。参考 docs/reference-guides/block-api/block-registration.md块名必须遵循namespace/block-name结构只包含小写字母数字和短横线且以字母开头。这个名字会被持久化到每篇使用该块的文章内容中!-- wp:my-plugin/book --事后无法轻易更改因此选择命名空间要格外谨慎使用你的插件/主题真实名称避免editorial/、block/、create-block/这类过于通用的名字。块的图标块应有一个可识别的图标理想情况下使用单一颜色并避免与已有块使用相同图标。核心块的图标基于 Material Design Icons可以参考该图标集或 Dashicons 获取风格灵感。在注册 API 中图标既可以是 Dashicons 名称字符串也可以是自定义 SVG 元素甚至可以是带background/foreground配色的对象形式见 block-registration.md 中的icon属性说明。块描述一句话动宾结构每个块都应包含一个清晰说明块功能的描述该描述会显示在设置侧栏中。添加方式是在registerBlockType函数中使用description属性参见 block-registration.md 中的description配置说明。描述应采用单个祈使句 动作 对象格式。例如Start with the basic building block of all narrative.Paragraph 块的描述见 paragraph/block.jsonInsert an image to make a visual statement.Image 块的描述见 image/block.jsonDisplay a list of your most recent posts.Latest Posts 块的描述见 latest-posts/block.json避免冗长描述和品牌营销式措辞。占位符要有指导性如果你的块要求用户在显示前配置某些选项应提供有指导性的占位符状态。反面教材是使用强烈的、令人分心的颜色且没有操作说明仅靠标题传达信息。好的占位符应当告诉用户下一步该做什么如上传图片 / 从媒体库选择。选中与未选中状态未选中时块应尽可能以贴近前端输出的方式预览其内容。选中时块可以浮出额外选项如输入框或按钮以便直接配置块——尤其是当这些选项对基础操作必要时。核心原则是对块操作至关重要的控件直接放在块编辑视图内而不是放进侧栏——否则移动端用户或已折叠侧栏的桌面用户会看到看起来无法工作的块。高级块设置谨慎放置设置侧栏的Block标签页可以包含额外的块选项与配置。但要记住用户可以收起侧栏并且再也不用它因此不应把关键选项放进侧栏。Drop Cap首字下沉这类非基础功能放在 Block 标签页作为可选配置是可以接受的。考虑移动端在尽可能多的设备和屏幕尺寸上检查块的外观、手感和工作方式。移动端没有悬停、屏幕更窄工具栏与占位符的可用性尤其要验证。支持编辑器深色背景方案检查块在编辑器深色背景下的表现。Gutenberg 编辑器支持深色配色方案参见 docs/how-to-guides/themes/theme-support.md 中的深色背景说明块的颜色、边框与占位符在深色模式下必须保持可读。示例从核心块反推设计范式为演示以上实践文档对三个默认 Gutenberg 块做了逐点批注仓库中对应的block.json与源码可交叉验证。Paragraph 块最基础的输入单元Paragraph 是编辑器中最基础的单元——一个简单的输入字段。占位符显示Type / to choose a block输入/以选择块的简单占位文本选中块后消失见上文 edit.jsx 中RichText的placeholder逻辑。选中状态块工具栏有块切换器可转换为标题等块类型块工具栏基础文本对齐块工具栏行内格式选项——加粗、斜体、删除线和链接。元数据佐证其 block.json 声明category: text、description: Start with the basic building block of all narrative.、keywords: [text]并开放了对齐wide/full、颜色、间距、排版字号、行高、文本对齐、文本列、文本缩进等的supports配置。所有基础交互均发生在内容区与工具栏设置侧栏仅承担 Drop Cap 等非必要配置。Image 块设置状态的标准范例基础图片块。占位符一个通用灰色占位块提供上传图片、直接拖放图片到其上、或从媒体库选择图片三种入口。选中状态块工具栏对齐包括主题支持时的宽幅wide与全宽full块工具栏编辑图片Edit Image打开媒体库块工具栏链接按钮图片上传后图片下方出现标题输入框占位文本为Write caption…。块设置描述为 Insert an image to make a visual statement.当前仓库中的实际描述文案提供更换/添加替代文本alt text、添加附加 CSS 类等选项。其 block.json 声明了url、alt、caption、lightbox、width/height、aspectRatio、focalPoint等属性以及align: [left, center, right, wide, full]等支持项。文档中提到的 Image 块未来改进方向是去掉媒体模态框media modal改为让用户直接从占位符中选择图片。一般性原则是尽量避免模态框。Latest Posts 块优秀默认值的正面教材占位符没有占位符——因为它插入后立即可用。默认插入状态显示最近 5 篇文章。选中状态块工具栏对齐块工具栏列表视图或网格视图的选择选项。值得注意的是由于没有相近的块可以转换此例中块工具栏不包含块切换器Block Chip。块设置描述为 Display a list of your most recent posts.与 latest-posts/block.json 一致提供文章排序、按分类筛选列表、更改默认显示文章数、显示文章日期等选项。Latest Posts 之所以插入即完全可用正是因为它自带良好的默认值——这恰好呼应了前文不需要设置状态的第一个判定条件。结语把设计决策写进block.json与组件实现块设计并非玄学而是一系列可以在实现阶段落地的具体决策默认值优先先在block.json的attributes中为每个属性设计合理默认值让块插入即可用界面层级排序内容区含占位符承载基础交互 → 块工具栏承载图标可表达的关键操作 → 设置侧栏只放高级可选配置命名与描述块名简短、命名空间谨慎唯一、描述使用祈使句动宾结构参考 block-registration.md 的title、description、icon、keywords配置设置状态按需启用仅在无合理默认值或需要收集预览无关输入时使用并用灰色背景与Placeholder组件packages/components/src/placeholder/README.md实现全设备验证检查移动端可用性与编辑器深色模式下的可读性。对于块开发者来说最有效的学习方式是把 Paragraph、Image、Latest Posts 这三个核心块当作活文档在 packages/block-library/src/paragraph/、packages/block-library/src/image/ 与 packages/block-library/src/latest-posts/ 中对照阅读block.json元数据、edit.jsx编辑器实现与save.jsx前端输出即可把本文的设计规范与真实生产代码一一对应起来。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考