WordPress Gutenberg 交互式 API 中实现动作链式调用的实践方案

在 WordPress Gutenberg 编辑器的开发过程中，交互式 API(Interactivity API)为开发者提供了强大的前端交互能力。本文将深入探讨如何在核心查询块(core/query)的导航动作后执行自定义 JavaScript 逻辑的技术实现方案。

问题背景

在开发一个文章卡片网格布局时，我们需要在每个卡片加载后对文章摘要进行垂直对齐处理。当用户通过核心查询块的导航功能(如分页)获取新内容时，这些新加载的卡片也需要执行相同的对齐操作。

初始解决方案分析

最初考虑使用 data-wp-watch 指令来监听状态变化，但发现核心查询块本身并不维护状态，这种方法无法奏效。转而采用 data-wp-run 指令，该指令会在元素每次渲染时触发指定的回调函数。

实现方案包含三个关键部分：

1. 通过 PHP 过滤器修改块输出，添加交互式指令
2. 创建自定义存储(store)包含回调函数
3. 使用 requestAnimationFrame 确保 DOM 更新完成

优化后的完整方案

经过实践验证，发现初始方案在某些情况下不够稳定，于是开发了更完善的解决方案：

1. PHP 端处理

通过 render_block 过滤器修改核心查询块的输出：

function change_render( $block_content ) {
    $processor = \WP_HTML_Processor::create_fragment( $block_content );
    $processor->next_tag();
    // 确保块具有交互性
    if ( is_null( $processor->get_attribute( 'data-wp-interactive' ) ) {
        $processor->set_attribute( 'data-wp-interactive', 'makeiteasy/queryExtra' );
    };
    // 添加运行指令
    $processor->set_attribute( 'data-wp-run', 'makeiteasy/queryExtra::callbacks.alignExcerpts' );
    return $processor->get_updated_html();
}

2. JavaScript 存储实现

创建自定义存储并使用 React 的 useEffect 钩子：

import { store, useEffect, getElement } from '@wordpress/interactivity';

// 文章摘要对齐函数
function alignExcerpts(rootQueryElement) {
    // 实现具体的对齐逻辑
    // ...
}

// 创建存储并定义回调
store('makeiteasy/queryExtra', {
    callbacks: {
        alignExcerpts() {
            useEffect(() => {
                // 在元素渲染完成后执行
                alignExcerpts(getElement().ref);
            });
        },
    },
});

技术要点解析

1. 交互式指令的层级关系：必须先确保元素具有 data-wp-interactive 属性，才能使用其他交互式指令。

2. 渲染时机控制：使用 useEffect 比 requestAnimationFrame 更可靠，因为它与 Preact 的渲染周期深度集成，能确保在 DOM 更新完成后执行。

3. 元素引用获取：getElement().ref 提供了当前指令所在元素的直接引用，避免了复杂的 DOM 查询。

4. 模块化加载：必须通过 wp_enqueue_script_module 加载 JavaScript，以支持 ES 模块的导入语法。

实际应用建议

1. 对于类似的后续操作需求，优先考虑使用 data-wp-run 配合 useEffect 的方案。

2. 复杂的 DOM 操作应当封装为独立函数，保持回调简洁。

3. 注意处理边缘情况，如空状态或加载错误时的表现。

这种方案不仅适用于文章摘要对齐场景，也可推广到其他需要在块更新后执行自定义逻辑的用例中，展现了 WordPress Gutenberg 交互式 API 的强大扩展能力。