WordPress 6.9 全新协作模式：区块级批注（Notes）功能

WordPress 6.9 引入了一个名为批注（英文为：Notes）​的全新协作功能，它本质上是一个集成在区块编辑器中的评论系统，允许用户（如管理员、编辑、作者）在特定的内容块上留下基于上下文的反馈，以便进行讨论，跟踪更改并解决问题，所有操作都在编辑器内完成。

谁可以使用批注？

因为批注只能在文章编辑器内创建或查看，所以用户必须对该文章具有 edit_post 能力才能使用，所以这意味着默认情况下：

• 管理员和编辑者可以查看所有文章上的所有批注。
• 作者和贡献者可以查看他们自己创作的文章的所有批注。
• 订阅者无法查看任何批注。

为自定义文章类型启用批注功能

默认情况下 post和 page 这些内置的文章类型默认启用了批注功能，但也可以为任何自定义文章类型启用。

在注册文章类型时启用（推荐）：通过调用 register_post_type() 函数时设置支持：

register_post_type( 'book', array(
	'label' => 'Books',
	'public' => true,
	'show_in_rest' => true,
	'supports' => array(
		'title',
		'editor' => array( 'notes' => true ),
		'author',
	),
) );

为已注册的文章类型启用：如果自定义文章类型已经注册，可以通过以下代码添加对批注的支持：

add_action( 'init', function() {
    $supports = get_all_post_type_supports( 'my-post-type' );
    $editor_supports = array( 'notes' => true );

    // `add_post_type_support()` 会覆盖功能的子属性，因此必须显式合并。
    if (
        is_array( $supports['editor'] ) &&
        isset( $supports['editor'][0] ) &&
        is_array( $supports['editor'][0] )
    ) {
        $editor_supports = array_merge( $editor_supports, $supports['editor'][0] );
    }

    add_post_type_support( 'my-post-type', 'editor', $editor_supports );
} );

补充说明：由于批注是编辑器的一个子功能，目前需要手动合并设置，WordPress 官方正在优化此流程，未来添加支持的代码将简化为：

add_post_type_support( 'my-post-type', 'editor', array(
    'notes' => true,
) );

以编程方式访问批注

在底层，批注是作为特殊评论类型存储在 wp_comments 表中的 WP_Comment对象，可以使用标准的评论 API 并通过指定评论类型 note 来访问它们：

例如，以下代码就是查询指定文章 ID 的所有批注：

$notes = get_comments( 
	array(
		'post_id' => $post_id,
		'type'    => 'note',
	)
);

也可以使用 REST API 查询批注：

$request = new WP_REST_Request( 'GET', '/wp/v2/comments' );
$request->set_param( 'post', $post_id );
$request->set_param( 'type', 'note' );
$response = rest_get_server()->dispatch( $request );
if ( ! is_wp_error( $response ) ) {
    $notes = $response->get_data();
    foreach ( $notes as $note ) {
        // 根据需要处理每个批注
    }
}

批注状态

当向一个区块添加批注时：

• 初始为“开放”状态，也就是 comment_status 为 0（即 hold）。
• 解决后，comment_status 变为 1（即 approve）。
• 被删除，状态变为 trash，若 EMPTY_TRASH_DAYS设置为 0，则立即永久删除。

以下代码片段将获取指定文章所有未解决的批注：

$notes = get_comments(
    array(
        'post_id' => $post_id,
        'type'    => 'note',
        'status'  => 'hold'
    )
);

注意必须显示将评论类型设置为 note 才能获取到批注，比如下面代码只会返回评论，批注会被自动排除：

// 只会返回评论，批注会被自动排除。
$comments = get_comments( array ( 'post_id' => $post_id ) );

邮件通知

当其他用户向文章添加批注时，文章作者将收到一封通知邮件，告知有批注添加到文章中，这个通知功能默认是启用的，可以在站点级别的 设置 > 讨论​ 中的 当有人发布批注时发送电子邮件通知我​ 选项进行控制。

开发者也可以使用现有的评论过滤器 notify_post_author 来控制通知，例如只发送关于页面批注的通知，而不发送关于文章批注的通知：

add_filter( 'notify_post_author', function( $notify, $comment_id ) {
    if ( 'note' !== get_comment_type( $comment_id ) ) {
        return $notify;
    }

    $comment = get_comment( $comment_id );
    if ( 'page' === get_post_type( $comment->comment_post_ID ) ) {
        return true;
    }

    return false;
}, 10, 2 );

其他事项

批注权限：如前所述，只有能够编辑给定文章的用户才能添加批注。因为批注是内部/授权用户功能，和评论发布的相关的限制（如防刷屏和防重复功能）并不会不适用于批注，此外，pre_comment_approved过滤器也不会应用于批注。

批注如何连接到区块：顶级的批注通过元数据属性链接到区块，意思是当向区块添加新的批注时，批注 ID 会以 noteId 作为 key 存储在区块属性的 metadata 中，而回复作为子项链接到顶级批注（其父项设置为顶级批注）。

未来展望（WordPress 7.0）

以下增强功能已在规划中：

• 片段批注 – 在区块的一部分或跨区块上进行批注的能力。
• “@”提及​ – 在文章中提及另一位用户，他们将收到通知。
• 改进的通知​ – 控制通知频率，例如接收所有新批注的每日摘要。
• 改进宽屏浮动布局 – 将浮动部分移至编辑器框架和侧边栏之间
• 精简模式​ – 批注显示为图标和头像，位于区块旁边，点击时展开。
• 在编辑器中更广泛的可用性，包括在模板中使用批注。
• 实时协作。

总结

WordPress 6.9 的批注功能通过复用评论表结构和集成块编辑器元数据，实现了轻量级、上下文相关的协作体验，它解决了内容审阅过程中反馈分散的问题，该功能标志着WordPress向内置协作平台演进的关键一步，为后续实时协作等高级功能奠定了基础。