WooCommerce HPOS批量订单操作钩子及9.3.3版本兼容咨询

问题根源 #

全新安装的WooCommerce 9.3.3默认启用HPOS（高性能订单存储），HPOS的订单列表页面采用独立的钩子体系，传统的bulk_actions-edit-shop_order钩子仅适配基于Post类型的传统订单存储模式。

升级到9.3.3后代码仍能生效，是因为升级过程中WooCommerce会保留原有订单存储设置（默认不强制切换到HPOS），此时订单仍以Post类型存储，旧钩子自然能继续工作。

HPOS模式下的正确钩子 #

HPOS订单列表页面的批量动作注册钩子为：bulk_actions-woocommerce_page_wc-orders

注册自定义批量动作的基础代码 #

add_filter( 'bulk_actions-woocommerce_page_wc-orders', 'register_custom_bulk_action' );
function register_custom_bulk_action( $bulk_actions ) {
    $bulk_actions['action_1'] = __( 'action 1', 'woocommerce' );
    $bulk_actions['action_2'] = __( 'action 2', 'woocommerce' );
    return $bulk_actions;
}

完整批量动作实现（含处理逻辑） #

仅注册动作无法完成实际操作，需搭配对应的处理钩子handle_bulk_actions-woocommerce_page_wc-orders执行业务逻辑，同时兼容两种存储模式的代码示例如下：

// 注册批量动作（兼容HPOS和传统模式）
add_filter( 'bulk_actions-edit-shop_order', 'register_custom_bulk_action' );
add_filter( 'bulk_actions-woocommerce_page_wc-orders', 'register_custom_bulk_action' );

function register_custom_bulk_action( $bulk_actions ) {
    $bulk_actions['action_1'] = __( 'action 1', 'woocommerce' );
    $bulk_actions['action_2'] = __( 'action 2', 'woocommerce' );
    return $bulk_actions;
}

// 处理批量动作（兼容HPOS和传统模式）
add_action( 'handle_bulk_actions-edit-shop_order', 'custom_bulk_action_handler', 10, 3 );
add_action( 'handle_bulk_actions-woocommerce_page_wc-orders', 'custom_bulk_action_handler', 10, 3 );

function custom_bulk_action_handler( $redirect_to, $action, $order_ids ) {
    // 过滤非自定义动作
    if ( ! in_array( $action, [ 'action_1', 'action_2' ] ) ) {
        return $redirect_to;
    }

    foreach ( $order_ids as $order_id ) {
        $order = wc_get_order( $order_id );
        if ( ! $order ) continue;

        // 根据动作类型执行对应操作
        switch ( $action ) {
            case 'action_1':
                // 示例：更新订单为处理中状态
                $order->update_status( 'processing' );
                break;
            case 'action_2':
                // 示例：添加自定义订单备注
                $order->add_order_note( '执行了自定义批量动作2' );
                break;
        }
        $order->save();
    }

    // 添加操作结果反馈参数
    $redirect_to = add_query_arg(
        [
            'custom_bulk_success' => 1,
            'processed_count' => count( $order_ids ),
            'action_type' => $action
        ],
        $redirect_to
    );

    return $redirect_to;
}

验证当前存储模式 #

可在WooCommerce后台设置 > 高级 > 订单存储中查看当前使用的存储模式，确认是否启用HPOS。

结论 #

这并非WooCommerce的内部bug，而是HPOS模式与传统订单存储模式使用了不同的页面钩子体系，只需针对对应模式替换钩子，或通过兼容代码同时支持两种模式即可解决问题。

内容的提问来源于stack exchange，提问作者ali noori