## 补充资源

- [WordPress 组件故事书](https://wordpress.github.io/gutenberg/?path=/docs/docs-introduction--page)
- [@wordpress/block-editor](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/)
- [@wordpress/components](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/)
- [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md)
- [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls)

# 编辑器中的区块

区块编辑器是一个React单页应用程序（SPA）。编辑器中的每个区块都是通过React组件显示的，该组件定义在客户端[注册区块](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registering-a-block-with-javascript-client-side)时所用设置对象的`edit`属性中。

区块的`Edit` React组件接收到的`props`对象包含：

- **[`attributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#attributes)：** 包含区块所有属性的对象
- **[`setAttributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#setattributes)：** 用于更新属性对象的方法
- **[`isSelected`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#isselected)：** 表示区块当前是否被选中的布尔值

WordPress提供了许多内置标准组件，可用于在编辑器中定义区块界面。这些内置组件可通过以下软件包获取：[`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) 和 [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/)。

<div class="callout">
	WordPress Gutenberg项目使用 <a href="https://wordpress.github.io/gutenberg/?path=/docs/docs-introduction--page">Storybook</a> 来记录WordPress软件包中可用的用户界面组件。
</div>

区块工具栏或设置侧边栏中的自定义设置控件也可以通过这个`Edit` React组件使用内置组件来定义，例如：

- [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md)
- [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls)

## 内置组件

[`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) 软件包包含一个通用WordPress组件库，用于为区块编辑器和WordPress仪表盘创建常见的UI元素。该软件包中最常用的一些组件包括：

- [`TextControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-textcontrol--docs)
- [`Panel`](https://wordpress.github.io/gutenberg/?path=/docs/components-panel--docs)
- [`ToggleControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-togglecontrol--docs)
- [`ExternalLink`](https://wordpress.github.io/gutenberg/?path=/docs/components-externallink--docs)

[`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/) 软件包包含一个用于区块编辑器的组件和钩子库，包括用于定义区块自定义设置控件的组件。该软件包中最常用的一些组件包括：

- [`RichText`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md)
- [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls)
- [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md)
- [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md)

<div class="callout callout-info">
	<a href="https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/"><code>@wordpress/block-editor</code></a> 软件包还提供了创建和使用独立区块编辑器的工具。
</div>

在区块编辑器中使用组件时，一个良好的工作流程是：

- 从WordPress软件包中导入组件
- 以JSX格式将组件的对应代码添加到项目中
- 大多数内置组件将用于设置[区块属性](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#using-attributes-to-store-block-data)，因此在`block.json`中定义必要的属性，并在组件中创建事件处理程序以使用`setAttributes`更新这些属性
- 根据需要调整代码以进行序列化并存储在数据库中

## 区块控制项：区块工具栏与设置侧边栏

为简化区块定制并确保一致的用户体验，系统内置了多种UI模式来辅助生成区块的编辑器预览界面。

下图详细展示了选中段落区块时的区块工具栏与设置侧边栏。

![展示选中段落区块时的区块工具栏与设置侧边栏示意图](https://developer.wordpress.org/files/2023/12/block-toolbar-settings-sidebar.png)

### 区块工具栏

当用户选中区块时，选定区块上方会显示包含多个控制按钮的工具栏。部分区块级控件会自动包含其中，您也可以自定义工具栏以添加针对特定区块类型的控件。若区块类型`Edit`函数的返回值包含`BlockControls`元素，这些控件将显示在选定区块的工具栏中。

```jsx
export default function Edit( { className, attributes: attr, setAttributes } ) {

	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } );
	};

	const onChangeAlignment = ( newAlignment ) => {
		setAttributes( {
			alignment: newAlignment === undefined ? 'none' : newAlignment,
		} );
	};

	return (
		<div { ...useBlockProps() }>
			<BlockControls>
				<ToolbarGroup>
					<AlignmentToolbar
						value={ attr.alignment }
						onChange={ onChangeAlignment }
					/>
				</ToolbarGroup>
			</BlockControls>

			<RichText
				className={ className }
				style={ { textAlign: attr.alignment } }
				tagName="p"
				onChange={ onChangeContent }
				value={ attr.content }
			/>
		</div>
	);
}
```

_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-toolbar-ab967f/src/edit.js)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-toolbar-ab967f)。_

请注意：`BlockControls`仅在区块被选中且处于可视化编辑模式时可见。在HTML编辑模式下编辑区块时不会显示`BlockControls`。

### 设置侧边栏

设置侧边栏用于显示使用频率较低的设置项或需要更多屏幕空间的设置项。该区域**仅应用于区块级设置**，并在选中区块时显示。

若设置项仅影响区块内选定的内容（如文本"加粗"功能），**请勿将其置于设置侧边栏中**，而应使用工具栏。设置侧边栏在HTML编辑模式下仍会显示，因此应仅包含区块级设置项。

与渲染工具栏类似，若在区块类型`Edit`函数的`return`值中包含`InspectorControls`组件，这些控件将显示在设置侧边栏区域。

```jsx
export default function Edit( { attributes, setAttributes } ) {
	const onChangeBGColor = ( hexColor ) => {
		setAttributes( { bg_color: hexColor } );
	};

	const onChangeTextColor = ( hexColor ) => {
		setAttributes( { text_color: hexColor } );
	};

	return (
		<div { ...useBlockProps() }>
			<InspectorControls key="setting">
				<div>
					<fieldset>
						<legend className="blocks-base-control__label">
							{ __( '背景颜色', 'block-development-examples' ) }
						</legend>
						<ColorPalette // Gutenberg标准颜色选择器元素标签
							onChange={ onChangeBGColor } // 变更事件回调函数
						/>
					</fieldset>
					<fieldset>
						<legend className="blocks-base-control__label">
							{ __( '文字颜色', 'block-development-examples' ) }
						</legend>
						<ColorPalette
							onChange={ onChangeTextColor }
						/>
					</fieldset>
				</div>
			</InspectorControls>
			<TextControl
				__nextHasNoMarginBottom
				__next40pxDefaultSize
				value={ attributes.message }
				onChange={ ( val ) => setAttributes( { message: val } ) }
				style={ {
					backgroundColor: attributes.bg_color,
					color: attributes.text_color,
				} }
			/>
		</div>
	);
}
```
_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/settings-sidebar-82c525/src/edit.js)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/settings-sidebar-82c525)。_

当选中多个同类型区块时，工具栏和侧边栏中渲染的区块控制项将同时生效。

<div class="callout callout-note">
	对于常见定制设置（包括颜色、边框、间距等），您可依赖<a href="https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#enable-ui-settings-panels-for-the-block-with-supports">区块支持功能</a>而非自定义方案。区块支持功能提供与其他核心区块功能一致的标准化UI界面。
</div>