### 高级区块设置

设置侧边栏中的“区块”标签页可包含额外的区块选项与配置项。请注意用户可能关闭侧边栏且永不使用，不应将关键选项置于侧边栏内。

![段落区块在侧边栏中的高级设置截图](https://developer.wordpress.org/files/2022/01/advanced-settings-do.png)
**正确做法：**
首字下沉功能并非区块基础运行的必要功能，可将其作为可选配置置于区块标签页中。

### 移动端适配

尽可能在多设备、多屏幕尺寸下检验区块的视觉呈现、交互体验与功能表现。

### 支持古腾堡深色背景编辑模式

检验区块在编辑器[深色背景](/docs/how-to-guides/themes/theme-support.md#dark-backgrounds)下的视觉呈现效果。

## 示例演示

以下通过古腾堡默认区块的标注示例展示部分实践方案：

### 段落区块

编辑器最基础的构成单元。段落区块即简易输入框。

![段落区块](https://cldup.com/HVJe5bGZ8H-3000x3000.png)

#### 占位状态
- 简洁提示语“输入/选择区块”，选中区块后提示消失

#### 选中状态
- 区块工具栏：配备转换器（可切换为标题等）
- 区块工具栏：提供基础文本对齐功能
- 区块工具栏：支持行内格式设置（加粗、斜体、删除线及链接）

### 图片区块

基础图片区块。

![图片区块占位状态](https://cldup.com/w6FNywNsj1-3000x3000.png)

#### 占位状态
- 通用灰色占位区块，支持上传图片、直接拖放图片或从媒体库选取

#### 选中状态
- 区块工具栏：对齐选项（若主题支持则包含宽幅与全宽对齐）
- 区块工具栏：编辑图片（打开媒体库）
- 区块工具栏：链接按钮
- 图片上传后，下方出现标注输入框及“添加标注…”提示语：

![图片区块](https://cldup.com/6YYXstl_xX-3000x3000.png)

#### 区块设置
- 描述文本：“一图胜千言！插入单张图片”
- 提供修改替代文本、添加自定义CSS类等功能

*图片区块的未来改进方向包括取消媒体弹窗，允许用户直接在占位区选取图片。总体而言应尽量避免使用弹窗。*

### 最新文章区块

![最新文章区块](https://cldup.com/8lyAByDpy_-3000x3000.png)

#### 占位状态
插入即生效，无占位状态。默认显示最近5篇文章。

#### 选中状态
- 区块工具栏：对齐选项
- 区块工具栏：列表视图/网格视图切换功能

*注意：因无可切换的相似区块，此时区块工具栏不包含区块标识符*

#### 区块设置
- 描述文本：“展示最新文章列表”
- 提供文章排序、按分类筛选、默认显示篇数设置、发布日期显示等选项

*最新文章区块凭借完善的默认配置，插入后即可完整运作。*

## 注意事项

### 区块工具栏

按逻辑分组组织工具栏控件，避免为每个控件单独设置分组。

![对比区块工具栏合理与不合理分组的截图](https://make.wordpress.org/design/files/2021/03/docs__block-toolbar-do-dont.png)

### 区块标识

区块名称应简洁明了，方便用户在区块库中快速定位。例如命名为“YouTube”的区块直观易寻，而命名为“嵌入式视频(YouTube)”则显得冗长难觅。

在文档或界面中提及区块时，区块标题采用首字母大写格式，“区块”描述词保持小写。例如：
- 段落区块
- 最新文章区块
- 媒体与文本区块

区块应配备辨识性图标，建议使用单色设计并避免与现有区块图标重复。核心区块图标基于[Material Design图标集](https://fonts.google.com/icons)，可参考该系列或[Dashicons](https://developer.wordpress.org/resource/dashicons/)获取设计灵感。

![展示简洁区块名称的区块库截图](https://developer.wordpress.org/files/2022/01/blocks-do.png)
**建议：**
使用简练的区块名称

![展示多行长名称的区块库截图](https://developer.wordpress.org/files/2022/01/blocks-dont.png)
**避免：**
使用冗长的多行区块名称

### 区块描述

每个区块需包含功能说明，该描述将显示在设置侧边栏中。

可通过[registerBlockType函数](/docs/reference-guides/block-api/block-registration.md)的description属性添加描述。

采用“动词+主语”结构的祈使句，例如：
- 作为所有叙事的基础构建单元
- 通过内容分节帮助访客（及搜索引擎）理解内容结构
- 创建项目符号列表或编号列表

![简短区块描述示例](https://developer.wordpress.org/files/2022/01/block-descriptions-do.png)
**建议：**
使用简短明晰的区块描述

![包含品牌信息的冗长描述示例](https://developer.wordpress.org/files/2022/01/block-descriptions-dont.png)
**避免：**
使用冗长描述及品牌信息

### 占位符

若区块需用户配置后方可显示，应提供指导性占位状态。

![图库区块占位符示例](https://developer.wordpress.org/files/2022/01/placeholder-do.png)
**建议：**
提供具指导意义的占位状态

![无说明信息的炫目占位符示例](https://developer.wordpress.org/files/2022/01/placeholder-dont.png)
**避免：**
使用品牌元素且仅依赖标题传递指引

### 选中与未选中状态

未选中时，区块预览应最大程度接近前端显示效果。

选中状态下，可呈现输入框或按钮等配置选项，特别是基础操作必需的功能。

![包含行内必控功能的谷歌地图区块](https://developer.wordpress.org/files/2022/01/block-controls-do.png)
**建议：**
区块运行必需的控制元件应直接内嵌于编辑视图

![必控元件移至侧边栏的谷歌地图区块](https://developer.wordpress.org/files/2022/01/block-controls-dont.png)
**避免：**
将核心控制元件置于侧边栏，否则移动端用户或关闭侧边栏的桌面用户将无法正常操作区块

# 区块设计

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

## 最佳实践

### 区块内容区域是主要交互界面

由于区块本身代表实际显示在网站上的内容，此处的交互最符合直接操作原则，对用户也最为直观。这里应被视为添加和操作内容、调整显示效果的主要界面。交互方式有两种：

1. 区块内容区域中的占位内容可视为引导界面，帮助用户遵循指令或“填空”。例如，嵌入第三方服务内容的区块可能在占位区域包含该服务的登录控件。
2. 用户添加内容后，选中区块可显示用于调整或编辑内容的附加控件。例如，订阅区块可能显示隐藏/显示订阅者数量的控件。但这类操作应保持最小化，避免用户选中区块时引发区块尺寸与显示的剧烈变化（这可能造成困惑或困扰）。

### 区块工具栏作为次要选项设置区域

基础区块设置并非始终适合放在占位内容界面中。作为次要选择，对区块功能至关重要的选项可置于区块工具栏。区块工具栏仍保持高度情境化，且在所有屏幕尺寸下可见。需注意其图标化界面的特性，因此工具栏中的控件必须能通过图标有效传达信息。

### 按关联性分组工具栏控件

区块工具栏采用分层分段式控件分组：首段包含区块类型控件（如区块切换器、拖拽柄和移动控制器）；次段包含影响整个区块的通用与特定工具，随后是行内格式工具与“更多”菜单；可选设置的“元数据”或“其他”组可将部分工具独立分段。

![区块工具栏分段示意图](https://make.wordpress.org/design/files/2021/03/docs_block-toolbar-structure.png)

### 设置侧边栏仅用于高级三级控件

设置侧边栏在小屏/移动设备上默认隐藏，在桌面视图也可能被折叠。因此不应将区块基础操作所必需的功能置于此处。建议选择合理的默认值，将重要操作置于区块工具栏，并将设置侧边栏视为多数用户无需开启的辅助区域。

若选项超过五项，应使用分区标题帮助用户快速浏览和理解可用选项。

默认情况下每个设置侧边栏都包含“高级”分区，该区域设有“附加CSS类”字段，可用于放置高级用户控件。

## 设置状态与实时预览状态

设置状态（常称为“占位界面”）用于在展示区块实时预览前引导用户完成初始化流程。该过程收集渲染区块所需的用户信息，并通过灰色背景明确标识设置状态。并非所有区块都需要设置状态（如段落区块）。

![图片区块设置状态示例](https://make.wordpress.org/design/files/2021/03/docs__gallery-setup-state.png)

**无需**设置状态的情况：
- 能提供满足多数需求的优质默认内容
- 默认内容易于编辑和自定义

**需要**设置状态的情况：
- 缺乏适用于多数用户的明确默认状态
- 需收集与区块实时预览无直接关联的用户输入（如要求输入API密钥来渲染内容）
- 需要更多用户信息才能生成有效的默认内容

对于具有设置状态的区块，用户完成设置流程后，占位界面会被该区块的实时预览状态替代。

![图库实时预览状态示例](https://make.wordpress.org/design/files/2018/12/gallery-live-preview.png)

选中区块时可能显示附加控件用于自定义内容。例如选中图片库时，会显示删除或添加图片的控件。

![选中区块时显示附加控件的示例](https://make.wordpress.org/design/files/2018/12/gallery-additional-controls.png)

多数情况下区块设置状态仅显示一次，后续通过实时预览状态进行优化。但某些场景下需允许用户返回设置状态，例如区块内容被全部删除时，或通过区块工具栏/侧边栏的链接进入。