区块设计

以下是设计新区块的最佳实践，包含相关建议以及对现有区块的详细描述，用以说明我们创建区块的方法。

最佳实践

区块的主要界面是区块的内容区域

由于区块本身代表了将在网站上实际显示的内容，在此处的交互最贴近直接操作原则，对用户而言也最为直观。应将其视为添加和操作内容以及调整内容显示方式的主要界面。这里有两种交互方式：

1. 区块内容区域中的占位符内容可以被视为一种指南或界面，引导用户按照一组说明操作或“填空”。例如，嵌入第三方服务内容的区块可能会在占位符中包含用于登录该服务的控件。
2. 用户添加内容后，选中区块可以显示额外的控件来调整或编辑该内容。例如，一个注册区块可能会显示一个用于隐藏/显示订阅者数量的控件。但是，这种做法应尽量精简，以避免在用户选中区块时极大地改变区块的大小和显示效果（这可能会让用户感到困惑或厌烦）。

区块工具栏是放置必需选项和控件的次要位置

基本区块设置在占位符/内容界面中并不总是合理的。作为次要选择，对区块功能至关重要的选项可以放在区块工具栏中。区块工具栏仍然具有很强的上下文关联性，并且在所有屏幕尺寸上都可见。区块工具栏的一个显著限制是它基于图标的界面，因此放置在区块工具栏中的任何控件都需要能够通过单个图标或图标组来有效地传达。

将区块工具栏中相关的控件分组放置

区块工具栏按层次将控件分组为多个区段。第一个区段包含区块类型控件，例如区块切换器、拖动手柄和移动控件。第二组包含影响整个区块的通用和特定区块工具，随后是内联格式设置和“更多”菜单。还可以选择使用“Meta”或“其他”分组，将某些工具单独放在自己的区段中。

设置侧边栏应仅用于高级的第三层级控件

设置侧边栏在小屏幕/移动设备屏幕上默认不显示，在桌面视图中也可能处于折叠状态。因此，对于区块基本操作所必需的任何功能，都不应依赖于设置侧边栏。请选择良好的默认值，将重要操作放在区块工具栏中提供，并将设置侧边栏视为大多数用户无需打开的内容。

此外，如果选项较多，请在设置侧边栏中使用分区和标题，以便用户能够轻松浏览和理解可用的选项。

每个设置侧边栏默认都带有一个“高级”部分。此区域包含一个“附加 CSS 类”字段，应用于存放其他高级用户控件。

设置状态与实时预览状态

设置状态（有时也称为“占位符”）可用于在显示区块的实时预览状态之前，引导用户完成一个初始流程。设置过程会从用户那里收集渲染区块所需的信息。区块的设置状态以灰色背景标识，以便为用户提供清晰的区分。并非所有区块都有设置状态——例如，段落区块就没有。

在以下情况下，设置状态并非必需：

• 您可以在区块中提供能满足大多数人需求的良好默认内容。
• 该默认内容易于编辑和自定义。

在以下情况下，请使用设置状态：

• 没有适用于大多数用户的明确默认状态。
• 您需要收集用户输入的信息，而这些信息与区块的实时预览没有一一对应的关系（例如，您需要用户输入 API 密钥来渲染内容）。
• 您需要从用户那里获取更多信息，才能渲染出有用的默认内容。

对于确实具有设置状态的区块，一旦用户完成设置流程，占位符就会被该区块的实时预览状态所取代。

当选中区块时，可能会显示额外的控件来自定义区块的内容。例如，当选中图库时，它会显示删除或添加图片的控件。

在大多数情况下，区块的设置状态只显示一次，之后的进一步自定义通过实时预览状态完成。但是，在某些情况下，可能需要允许用户返回设置状态——例如，当所有区块内容都已被删除时，或者通过区块工具栏或侧边栏中的链接返回。

应做与不应做的事

区块工具栏

将工具栏控件按逻辑区段进行分组。不要为每个控件单独添加一个区段。

区块标识

区块应该有一个直截了当的简短名称，以便用户能够在区块库中轻松找到它。名为“YouTube”的区块很容易找到和理解。而同一个区块如果命名为“嵌入式视频（YouTube）”，就会不够清晰，也更难在区块库中找到。

在文档或界面中引用区块时，区块名称请使用标题式大写（title case），而描述词“区块”使用小写。例如：

• Paragraph block
• Latest Posts block
• Media & Text block

区块应该有一个标识性图标，最好使用单一颜色。尽量避免使用与现有区块相同的图标。核心区块图标基于 Material Design Icons。可以参考该图标集，或参考 Dashicons 以获取样式灵感。

正确做法：
使用简洁的区块名称。

错误做法：
避免使用冗长的、多行的区块名称。

区块描述

每个区块都应包含一段描述，清楚地说明区块的功能。该描述将显示在设置侧边栏中。

您可以通过 registerBlockType 函数中的 description 属性来添加描述。

请坚持使用单个祈使句，采用“动作 + 对象”的格式。示例：

• 从一切叙事的基本构建单元开始。
• 引入新的章节并组织内容，帮助访问者（以及搜索引擎）理解内容的结构。
• 创建项目符号列表或编号列表。

正确做法：
使用简短、简单的区块描述。

错误做法：
避免使用冗长的描述和品牌信息。

占位符

如果您的区块需要用户先配置一些选项才能显示，您应该提供一个具有指导性的占位符状态。

正确做法：
提供具有指导性的占位符状态。

错误做法：
避免使用品牌信息，以及仅依靠标题来传达说明。

选中和未选中状态

未选中时，您的区块应尽可能贴近前端输出的效果来预览其内容。

选中时，您的区块可以显示额外的选项，例如输入字段或按钮，以便直接配置区块，尤其是当这些选项对于基本操作必不可少时。

正确做法：
对于区块操作必不可少的控件，请直接在区块编辑视图中提供。

不要：
不要将对区块正常运作必不可少的控件放在侧边栏中，否则对于移动设备用户或已关闭侧边栏的桌面用户来说，该区块会显得无法使用。

区块高级设置

设置侧边栏的“区块”标签页可以包含额外的区块选项和配置。请记住，用户可能会关闭侧边栏并且从不使用它。你不应将关键选项放在侧边栏中。

要：
由于首字下沉（Drop Cap）功能并非区块基本操作所必需，你可以将其作为可选配置放入“区块”标签页。

考虑移动设备

请在尽可能多的设备和屏幕尺寸上检查你的区块的外观、感受和运行方式。

支持 Gutenberg 编辑器的深色背景配色方案

在编辑器中检查你的区块在深色背景下的外观。

示例

为了演示其中一些实践做法，下面提供了几个带有注释的默认 Gutenberg 区块示例：

段落

编辑器中最基本的单元。段落区块是一个简单的输入字段。

占位符

• 简单的占位符文本，显示为“键入 / 以选择区块”。当区块被选中时，该占位符会消失。

选中状态

• 区块工具栏：具有一个切换器，可将段落转换为标题等。
• 区块工具栏：提供基本的文本对齐方式
• 区块工具栏：提供行内格式化选项：加粗、斜体、删除线和链接

图片

基本的图片区块。

占位符

• 一个通用的灰色占位区块，提供上传图片、直接将图片拖放到该区块上，或从媒体库中选取图片的选项。

选中状态

• 区块工具栏：对齐方式，如果主题支持，还包括宽对齐和全宽对齐。
• 区块工具栏：编辑图片，用于打开媒体库
• 区块工具栏：链接按钮
• 当上传图片后，图片下方会出现一个说明文字输入字段，其占位符文本为“撰写说明文字……”：

区块设置

• 描述为：“一图胜千言！插入单张图片。”
• 提供更改或添加替代文本（alt text）以及添加额外自定义 CSS 类的选项。

图片区块未来的改进可能包括移除媒体模态框，改为让用户直接在占位符本身上选择图片。一般来说，请尽量避免使用模态框。

最新文章

占位符

没有占位符，因为它在插入后即可立即工作。默认的插入状态会显示最近 5 篇文章。

选中状态

• 区块工具栏：对齐方式
• 区块工具栏：用于选择列表视图或网格视图的选项

请注意，在这种情况下区块工具栏不包含 Block Chip（区块标识），因为没有可切换到的类似区块。

区块设置

• 描述为：“显示您的最新文章列表。”
• 提供文章排序、按分类筛选列表、更改默认显示的文章数量以及显示文章日期的选项。

最新文章区块一经插入即可完全正常使用，因为它自带了良好的默认设置。