12 KiB
setValues 函数
setValues 函数用于更新绑定区块源的所有值。它接收一个包含以下属性的 object 作为参数：
bindings返回特定源的绑定对象。该对象必须以属性作为键，值可以是string或包含参数的object。此对象包含一个newValue属性，用于存储用户的输入。clientId返回一个string，表示当前区块的客户端 ID。context返回一个object，表示当前区块的上下文，定义在usesContext属性中。关于区块上下文的更多信息。dispatch返回一个object，包含存储的操作创建器。关于 dispatch 的更多信息。select返回一个object，包含给定存储的选择器。更多信息请参阅文档。
编辑器注册核心示例
核心中有几个示例可供参考：
注销源
**注意：**自 WordPress 6.7 起。
unregisterBlockBindingsSource 通过提供名称注销一个区块绑定源。
import { unregisterBlockBindingsSource } from '@wordpress/blocks';
unregisterBlockBindingsSource( 'plugin/my-custom-source' );
获取所有源
**注意：**自 WordPress 6.7 起。
getBlockBindingsSources 返回所有已注册的区块绑定源。
import { getBlockBindingsSources } from '@wordpress/blocks';
const registeredSources = getBlockBindingsSources();
获取特定源
**注意：**自 WordPress 6.7 起。
getBlockBindingsSource 通过名称返回特定的区块绑定源。
import { getBlockBindingsSource } from '@wordpress/blocks';
const blockBindingsSource = getBlockBindingsSource( 'plugin/my-custom-source' );
区块绑定工具
**注意：**自 WordPress 6.7 起。
useBlockBindingUtils 是一个包含两个辅助函数的钩子，允许开发者轻松编辑 metadata.bindings 属性。
它接受一个 clientId 字符串作为参数，如果未设置，函数将使用上下文中的当前区块客户端 ID。
示例：
import { useBlockBindingsUtils } from '@wordpress/block-editor';
const { updateBlockBindings } = useBlockBindingsUtils('my-block-client-id-12345');
...
updateBlockBindings
updateBlockBindings 的工作方式类似于 updateBlockAttributes，可用于创建、更新或删除特定连接。
import { useBlockBindingsUtils } from '@wordpress/block-editor';
const { updateBlockBindings } = useBlockBindingsUtils();
function updateBlockBindingsURLSource( url ) {
updateBlockBindings({
url: {
source: 'myplugin/new-source',
}
})
}
// 从 url 属性中移除绑定。
function removeBlockBindingsURLSource() {
updateBlockBindings( { url: undefined } );
}
removeAllBlockBindings
removeAllBlockBindings 将通过移除 metadata.bindings 属性来删除区块中的所有现有连接。
import { useBlockBindingsUtils } from '@wordpress/block-editor';
const { removeAllBlockBindings } = useBlockBindingsUtils();
function clearBlockBindings() {
removeAllBlockBindings();
}
服务器注册核心示例
核心代码库中有几个可用作参考的示例：
编辑器注册
注意： 自WordPress 6.7起支持
客户端编辑器注册允许定义绑定区块在获取值或编辑值时的行为。
注册自定义源的函数是 registerBlockBindingsSource( args )：
args：包含以下结构的对象：name：具有唯一性且机器可读名称的字符串label：自定义源的人类可读名称字符串。若已在服务器端定义，服务器标签将被此标签覆盖，此时不建议在此重复定义（可选）usesContext：自定义源可能需要的区块上下文数组。若已在服务器端定义，则不应在此重复定义（可选）getValues：从源获取值的函数（可选）setValues：允许更新与源连接值的函数（可选）canUserEditValue：判断用户是否可以编辑值的函数。默认情况下用户无法编辑（可选）
此示例将在编辑器中显示自定义文章元数据日期，若不存在则显示当前日期。用户可以编辑日期值。（注意：此示例未将用户输入格式化为日期——仅用于教学目的）
import {
registerBlockBindingsSource,
} from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
import { store as coreDataStore } from '@wordpress/core-data';
registerBlockBindingsSource( {
name: 'wpmovies/visualization-date',
label: __( '观影日期', 'custom-bindings' ), // 可跳过标签定义，因已在前面示例的服务器端定义
usesContext: [ 'postType' ], // 可跳过postId定义，因已在前面示例的服务器端定义
getValues( { select, context } ) {
let wpMoviesVisualizationDate;
const { getEditedEntityRecord } = select( coreDataStore );
if ( context?.postType && context?.postId ) {
wpMoviesVisualizationDate = getEditedEntityRecord(
'postType',
context?.postType,
context?.postId
).meta?.wp_movies_visualization_date;
}
if ( wpMoviesVisualizationDate ) {
return {
content: wpMoviesVisualizationDate,
};
}
return {
content: new Date().toLocaleDateString( 'zh-CN' ),
};
},
setValues( { select, dispatch, context, bindings } ) {
dispatch( coreDataStore ).editEntityRecord(
'postType',
context?.postType,
context?.postId,
{
meta: {
wp_movies_visualization_date: bindings?.content?.newValue,
},
}
);
},
canUserEditValue( { select, context } ) {
return true;
},
} );
getValues函数
getValues函数在区块加载时从源获取值。它接收包含以下属性的对象作为参数：
bindings返回特定源的绑定对象。必须以属性为键，值可以是字符串或带参数的对象clientId返回当前区块客户端ID的字符串context返回在usesContext属性中定义的当前区块上下文对象。关于区块上下文的更多信息select返回给定存储库选择器的对象。详细文档
该函数必须返回具有以下结构的对象：
{ '区块属性': 值 }
数据绑定
区块绑定 API 允许您将动态数据"绑定"到区块的属性上，这些数据最终会反映在输出到前端浏览器的 HTML 标记中。
例如，可以将图片区块的 url 属性连接到从外部 API 返回随机图片的函数。
<!-- wp:image {
"metadata":{
"bindings":{
"url":{
"source":"my-plugin/get-random-images"
}
}
}
} -->
兼容区块及其属性
目前并非所有区块属性都支持数据绑定。虽然正在努力提升兼容性，但当前支持的列表如下：
| 支持区块 | 支持属性 |
|---|---|
| 段落 | content |
| 标题 | content |
| 图片 | id, url, title, alt |
| 按钮 | text, url, linkTarget, rel |
注册自定义数据源
注册数据源需要至少定义 name（名称）、label（标签）和 callback（回调函数），该函数从数据源获取值并传递给区块属性。
数据源注册后，任何支持的区块都可以通过配置 metadata.bindings 属性来读取该数据源的值。
注册可以通过 PHP 在服务器端完成，也可以通过 JavaScript 在编辑器端完成，两者可以共存。
服务器端注册定义的标签将被编辑器端定义的标签覆盖。
服务器端注册
服务器端注册允许应用一个回调函数，该函数将在前端为绑定属性执行。
注册自定义数据源的函数是 register_block_bindings_source($name, $args)：
name：string，设置自定义数据源的唯一 ID。args：array，包含：label：string，自定义数据源的可读名称。uses_context：array，传递给回调函数的区块上下文（可选）。get_value_callback：function，在绑定区块的渲染函数中运行。它接受三个参数：source_args、block_instance和attribute_name。此值可以通过block_bindings_source_value过滤器进行修改。
注意，register_block_bindings_source() 应通过附加到 init 钩子的处理程序调用。
以下是一个示例：
add_action(
'init',
function () {
register_block_bindings_source(
'wpmovies/visualization-date',
array(
'label' => __( 'Visualization Date', 'custom-bindings' ),
'get_value_callback' => function ( array $source_args, $block_instance ) {
$post_id = $block_instance->context['postId'];
if ( isset( $source_args['key'] ) ) {
return get_post_meta( $post_id, $source_args['key'], true );
}
},
'uses_context' => array( 'postId' ),
)
);
}
);
此示例需要注册一个 post_meta，并且可以使用过滤器返回默认的 $visualization_date 值，该值将在下一个标题中显示。
add_action(
'init',
function () {
register_meta(
'post',
'wp_movies_visualization_date',
array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'label' => __( 'Movie visualization date', 'custom-bindings' ),
)
);
}
);
区块绑定数据源值过滤器
**注意：**自 WordPress 6.7 起。
get_value_callback 返回的值可以通过 block_bindings_source_value 过滤器进行修改。
该过滤器具有以下参数：
value：要过滤的值。name：数据源的名称。source_args：包含数据源参数的array。block_instance：区块实例对象。attribute_name：属性名称。
示例：
function wpmovies_format_visualization_date( $value, $name ) {
// 防止此过滤器应用于其他数据源。
if ( $name !== 'wpmovies/visualization-date' ) {
return $value;
}
if ( ! $value ) {
return date( 'm/d/Y' );
}
return date( 'm/d/Y', strtotime( $value ) );
}
add_filter( 'block_bindings_source_value', 'wpmovies_format_visualization_date', 10, 2 );