9.2 KiB
补充资源
编辑器中的区块
区块编辑器是一个React单页应用程序（SPA）。编辑器中的每个区块都是通过React组件显示的，该组件定义在客户端注册区块时所用设置对象的edit属性中。
区块的Edit React组件接收到的props对象包含：
attributes： 包含区块所有属性的对象setAttributes： 用于更新属性对象的方法isSelected： 表示区块当前是否被选中的布尔值
WordPress提供了许多内置标准组件，可用于在编辑器中定义区块界面。这些内置组件可通过以下软件包获取：@wordpress/components 和 @wordpress/block-editor。
区块工具栏或设置侧边栏中的自定义设置控件也可以通过这个Edit React组件使用内置组件来定义，例如：
内置组件
@wordpress/components 软件包包含一个通用WordPress组件库，用于为区块编辑器和WordPress仪表盘创建常见的UI元素。该软件包中最常用的一些组件包括：
@wordpress/block-editor 软件包包含一个用于区块编辑器的组件和钩子库，包括用于定义区块自定义设置控件的组件。该软件包中最常用的一些组件包括：
@wordpress/block-editor 软件包还提供了创建和使用独立区块编辑器的工具。
在区块编辑器中使用组件时，一个良好的工作流程是：
- 从WordPress软件包中导入组件
- 以JSX格式将组件的对应代码添加到项目中
- 大多数内置组件将用于设置区块属性，因此在
block.json中定义必要的属性，并在组件中创建事件处理程序以使用setAttributes更新这些属性 - 根据需要调整代码以进行序列化并存储在数据库中
区块控制项：区块工具栏与设置侧边栏
为简化区块定制并确保一致的用户体验，系统内置了多种UI模式来辅助生成区块的编辑器预览界面。
下图详细展示了选中段落区块时的区块工具栏与设置侧边栏。
区块工具栏
当用户选中区块时，选定区块上方会显示包含多个控制按钮的工具栏。部分区块级控件会自动包含其中，您也可以自定义工具栏以添加针对特定区块类型的控件。若区块类型Edit函数的返回值包含BlockControls元素，这些控件将显示在选定区块的工具栏中。
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>
);
}
请注意：BlockControls仅在区块被选中且处于可视化编辑模式时可见。在HTML编辑模式下编辑区块时不会显示BlockControls。
设置侧边栏
设置侧边栏用于显示使用频率较低的设置项或需要更多屏幕空间的设置项。该区域仅应用于区块级设置，并在选中区块时显示。
若设置项仅影响区块内选定的内容（如文本"加粗"功能），请勿将其置于设置侧边栏中，而应使用工具栏。设置侧边栏在HTML编辑模式下仍会显示，因此应仅包含区块级设置项。
与渲染工具栏类似，若在区块类型Edit函数的return值中包含InspectorControls组件，这些控件将显示在设置侧边栏区域。
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>
);
}
当选中多个同类型区块时，工具栏和侧边栏中渲染的区块控制项将同时生效。