13 KiB
补充资源
第三步：使用文章元数据
您可以通过多种方式使用上一步存储的文章元数据。
在 PHP 中使用文章元数据
第一个示例使用文章元字段的值，并将其包裹在 H4 标签中附加到文章内容的末尾。
function myguten_content_filter( $content ) {
$value = get_post_meta( get_the_ID(), 'myguten_meta_block_field', true );
if ( $value ) {
return sprintf( "%s <h4> %s </h4>", $content, esc_html( $value ) );
} else {
return $content;
}
}
add_filter( 'the_content', 'myguten_content_filter' );
在区块中使用文章元数据
您也可以在其他区块中使用文章元数据。在此示例中，数据会在每个段落区块渲染时（即显示给用户时）加载到其末尾。您可以根据需要将其替换为任何核心或自定义区块类型。
在 PHP 中，使用 register_block_type 函数设置区块渲染时的回调，以包含元值。
function myguten_render_paragraph( $block_attributes, $content ) {
$value = get_post_meta( get_the_ID(), 'myguten_meta_block_field', true );
// 输出前检查值是否已设置
if ( $value ) {
return sprintf( "%s (%s)", $content, esc_html( $value ) );
} else {
return $content;
}
}
register_block_type( 'core/paragraph', array(
'api_version' => 3,
'render_callback' => 'myguten_render_paragraph',
) );
第四步：使用区块模板（可选）
使用元区块的一个问题是作者很容易忘记添加，因为它需要添加到每篇文章中。您可以通过使用区块模板来解决这个问题。区块模板是按文章类型预定义的区块项列表。模板允许您为文章类型指定默认的初始状态。
在此示例中，您将使用模板自动在文章顶部插入元区块。
将以下代码添加到 myguten-meta-block.php 文件中：
function myguten_register_template() {
$post_type_object = get_post_type_object( 'post' );
$post_type_object->template = array(
array( 'myguten/meta-block' ),
);
}
add_action( 'init', 'myguten_register_template' );
您还可以在数组中添加其他区块类型，包括占位符，甚至可以将文章锁定为一组特定的区块。模板是控制编辑体验的强大工具，更多信息请参阅上面链接的文档。
总结
本指南展示了如何使用区块读取和写入文章元数据。以下部分介绍了与现有元框的向后兼容性。
向后兼容性
测试、转换和维护现有元框
在将元框转换为区块之前，可以先测试元框是否与区块编辑器兼容，并明确标记。
如果某个元框与区块编辑器不兼容，且无法更新以使其正常工作，下一步是在元框声明中添加 __block_editor_compatible_meta_box 参数：
add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
null, 'normal', 'high',
array(
'__block_editor_compatible_meta_box' => false,
)
);
WordPress 不会显示该元框，而是会显示一条消息，说明它与区块编辑器不兼容，并包含指向经典编辑器插件的链接。默认情况下，__block_editor_compatible_meta_box 为 true。
将元框转换为区块后，可以声明其存在以保持向后兼容性：
add_meta_box( 'my-meta-box', 'My Meta Box', 'my_meta_box_callback',
null, 'normal', 'high',
array(
'__back_compat_meta_box' => true,
)
);
当使用区块编辑器时，此元框将不再显示在元框区域中，因为它现在仅用于向后兼容。在经典编辑器中，它将像以前一样显示。
元数据框数据收集
在每次区块编辑器页面加载时，我们会注册一个用于收集元数据框数据的操作，以判断某个区域是否为空。收集元数据框数据后，原始全局状态将被重置。
详见 register_and_do_post_meta_boxes。
该操作将遍历 post.php 用于注册元数据框的函数和钩子，包括 add_meta_boxes、add_meta_boxes_{$post->post_type} 和 do_meta_boxes。
元数据框会经过过滤，移除所有核心元数据框、标准自定义分类法元数据框，以及任何声明仅用于向后兼容的元数据框。
随后检查该特定类型元数据框的每个位置是否处于活动状态。若非空则存储值为 true，若为空则存储值为 false。这些元数据框位置数据随后会通过编辑器 Redux 存储库在 INITIALIZE_META_BOX_STATE 中分发。
理想情况下，这可以在编辑器实例化时完成，从而简化流程。但在 admin_enqueue_scripts（即调用 initializeEditor() 的阶段）之前无法获知元数据框状态。除非我们将 initializeEditor() 移至页脚或 admin_head 之后的某个阶段执行，否则目前只能如此处理。随着编辑器引导机制的最新改进，现在可能已具备可行性。需使用 ACF 进行测试验证。
Redux 与 React 元数据框管理
渲染区块编辑器时，元数据框会被渲染到隐藏的 #metaboxes 容器中。
Redux 存储库默认将所有元数据框设为非活动状态。当接收到 INITIALIZE_META_BOX_STATE 时，存储库会将活动元数据框区域的 isActive 标志更新为 true。随后 React 将检查 Redux 传递给 MetaBox 组件的新属性。若该 MetaBox 处于活动状态，则会渲染 MetaBoxArea 组件而非空内容。MetaBox 组件是协调 MetaBoxArea 与 Redux 存储库的容器组件。若无活动元数据框，则保持默认状态。由于所有核心元数据框已被移除，这将成为默认行为。
MetaBoxArea 组件
组件渲染时会存储元数据框容器的引用，并从预取位置获取元数据框的 HTML 内容。
文章更新时，仅会提交处于活动状态的元数据框区域，以避免不必要的请求。元数据框提交不会创建额外修订版本。任何活动元数据框在触发 REQUEST_POST_UPDATE 时都会激活 Redux 操作（参见 editor/effects.js）。REQUEST_META_BOX_UPDATES 操作会将该元数据框状态设为 isUpdating。isUpdating 属性将传递至 MetaBoxArea 并触发表单提交。
当元数据框区域保存时，我们会显示更新遮罩层，防止用户在保存过程中修改表单值。
示例保存地址形如：
example.org/wp-admin/post.php?post=1&action=edit&meta-box-loader=1
该地址通过 _wpMetaBoxUrl 全局变量自动传递给 React。
此页面模拟 post.php 的文章表单，提交时会触发所有常规钩子和操作，并具备正确的全局状态以正常执行所有 PHP 元数据框逻辑，无需修改现有代码。提交成功后，React 会触发 handleMetaBoxReload 来移除更新遮罩。
常见兼容性问题
大多数 PHP 元数据框在区块编辑器中应能继续工作，但包含高级功能的元数据框可能会出现异常。以下是元数据框在区块编辑器中可能无法正常工作的常见原因：
- 依赖针对旧编辑器文章标题、内容字段及其他元数据框选择器的插件
- 依赖 TinyMCE API 的插件（区块编辑器中不再存在单一 TinyMCE 实例）
- 在“提交”或“保存”时更新 DOM 的插件
另请注意：若插件触发输出 PHP 警告或通知，将导致 HTML 文档类型（<!DOCTYPE html>）输出异常，从而使浏览器启用“怪异模式”（当浏览器无法识别文档类型时激活的兼容模式）。区块编辑器不适用于此模式，但可能看似正常运行。若遇到元数据框覆盖编辑器等布局问题，请检查网页源代码确认文档类型声明是否为页面首行内容。JavaScript 控制台也会显示相关警告提示。
元数据框
概述
在区块编辑器出现之前，自定义元数据框被用于扩展编辑器功能。现在有了新的扩展方式，既赋予开发者更多能力，又为内容创作者带来更佳体验。建议将旧版自定义元数据框迁移至以下新方法之一，为编辑器用户创造更统一连贯的体验。
区块编辑器确实支持大多数现有元数据框，详见下文向后兼容性说明。
若您需要在编辑器外部处理文章元数据，请参阅侧边栏教程。
使用区块存储元数据
通常区块会将属性值存储在序列化的区块HTML中。但您也可以创建将属性值保存为文章元数据的区块，这样就能在模板的任何位置通过编程方式访问这些数据。
本指南将演示如何创建能够提示用户输入单个值，并将其保存为文章元数据的区块。
准备工作
本指南假设您已熟悉WordPress插件、文章元数据和基础JavaScript。建议先学习JavaScript入门教程打好基础。
虽然本指南将逐步创建基础区块，但推荐通过创建区块教程来更深入理解自定义区块的开发流程。
您需要准备：
- WordPress开发环境
- 已激活并可编辑的基础插件
- 配置好构建和队列加载的JavaScript环境
您可参考完整的元数据区块示例来搭建开发环境。
分步指南
步骤1：注册元字段
文章元字段是用于存储文章扩展数据的WordPress对象。使用前需先注册新元字段。详见文章元数据管理文档。
注册字段时请注意show_in_rest参数，这能确保数据被包含在REST API中（区块编辑器通过该API加载和保存元数据）。更多信息请参阅register_post_meta函数说明。
此外，文章类型需支持custom-fields才能使register_post_meta函数正常工作。
将以下代码添加到PHP插件中以注册字段：
<?php
// 注册自定义元标签字段
function myguten_register_post_meta() {
register_post_meta( 'post', 'myguten_meta_block_field', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
) );
}
add_action( 'init', 'myguten_register_post_meta' );
步骤2：添加元数据区块
完成上一步的元字段注册后，接下来创建用于向用户显示字段值的新区块。
区块可通过useEntityProp钩子获取或修改元数据值。
将以下代码添加到JavaScript src/index.js：
import { registerBlockType } from '@wordpress/blocks';
import { TextControl } from '@wordpress/components';
import { useSelect } from '@wordpress/data';
import { useEntityProp } from '@wordpress/core-data';
import { useBlockProps } from '@wordpress/block-editor';
registerBlockType( 'myguten/meta-block', {
edit: ( { setAttributes, attributes } ) => {
const blockProps = useBlockProps();
const postType = useSelect(
( select ) => select( 'core/editor' ).getCurrentPostType(),
[]
);
const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta' );
const metaFieldValue = meta[ 'myguten_meta_block_field' ];
const updateMetaValue = ( newValue ) => {
setMeta( { ...meta, myguten_meta_block_field: newValue } );
};
return (
<div { ...blockProps }>
<TextControl
__nextHasNoMarginBottom
__next40pxDefaultSize
label="元数据区块字段"
value={ metaFieldValue }
onChange={ updateMetaValue }
/>
</div>
);
},
// 不保存信息至区块
// 数据通过钩子保存至文章元数据
save: () => {
return null;
},
} );
创建文章并添加元数据区块即可验证功能。您将看到可输入值的字段。当保存文章（草稿或已发布）时，文章元数据值也会同步保存。可通过保存后重新加载草稿来验证——重新加载后表单仍将保留输入内容。
您还可以检查数据库表wp_postmeta，确认新文章ID包含新字段数据。
故障排除：请确保在每次修改后重新构建代码（您更新了步骤1的PHP代码，且JavaScript文件已正确加入队列）。检查构建输出和开发者控制台是否有错误信息。