如何在Gutenberg块生成的WooCommerce结账表单中添加ACF自定义字段

当WooCommerce结账页面切换为Gutenberg块（WooCommerce Blocks）后，传统的woocommerce_checkout_fields等钩子不再生效，需要针对Blocks的专属机制来实现ACF字段嵌入。以下是可行的解决方案：

核心思路 #

WooCommerce Blocks提供了一套独立的钩子来扩展结账表单，我们需要：

1. 注册自定义字段到Blocks的订单属性系统
2. 在结账表单的指定位置渲染ACF字段
3. 将字段值保存到订单并关联ACF数据

具体实现步骤 #

1. 先在ACF Pro中创建订单关联字段 #

在ACF后台创建一个字段组，设置位置规则为“等于 WooCommerce 订单”，添加你需要的字段（比如文本框、下拉选单等），记录字段的字段键（例如custom_checkout_field）。

2. 注册字段到WooCommerce Blocks #

将自定义字段注册到Blocks的订单属性，让系统识别这个字段：

add_filter( 'woocommerce_blocks_checkout_block_register_order_attributes', 'acf_register_checkout_field' );
function acf_register_checkout_field( $attributes ) {
    $attributes['custom_acf_field'] = array(
        'type'     => 'string', // 根据ACF字段类型调整，比如boolean、integer
        'default'  => '',
        'validate' => function( $value ) {
            // 可选：添加字段验证逻辑
            if ( empty( $value ) ) {
                throw new \WC_Data_Exception( 'field_empty', '请填写此字段', 400 );
            }
            return $value;
        },
    );
    return $attributes;
}

3. 在结账表单中渲染ACF字段 #

使用Blocks的位置钩子，将ACF字段插入到结账表单的合适位置（比如账单地址后、配送地址前等）：

add_action( 'woocommerce_blocks_checkout_billing_address_after', 'acf_render_checkout_field' );
function acf_render_checkout_field() {
    $field_key = 'custom_checkout_field'; // 替换为你的ACF字段键
    $field = get_field_object( $field_key );
    
    if ( ! $field ) return;
    
    // 获取当前结账会话中的字段值（如果有）
    $current_value = WC()->checkout->get_value( 'custom_acf_field' );
    ?>
    <div class="woocommerce-form-row woocommerce-form-row--wide form-row form-row-wide">
        <label for="custom_acf_field">
            <?php echo esc_html( $field['label'] ); ?>
            <?php if ( $field['required'] ) : ?>
                <span class="required">*</span>
            <?php endif; ?>
        </label>
        <!-- 根据ACF字段类型调整输入控件 -->
        <?php if ( $field['type'] === 'text' ) : ?>
            <input 
                type="text" 
                id="custom_acf_field" 
                name="custom_acf_field" 
                value="<?php echo esc_attr( $current_value ); ?>" 
                <?php echo $field['required'] ? 'required' : ''; ?>
                class="input-text"
            />
        <?php elseif ( $field['type'] === 'select' ) : ?>
            <select 
                id="custom_acf_field" 
                name="custom_acf_field" 
                <?php echo $field['required'] ? 'required' : ''; ?>
                class="select"
            >
                <option value="">请选择</option>
                <?php foreach ( $field['choices'] as $value => $label ) : ?>
                    <option value="<?php echo esc_attr( $value ); ?>" <?php selected( $current_value, $value ); ?>>
                        <?php echo esc_html( $label ); ?>
                    </option>
                <?php endforeach; ?>
            </select>
        <?php endif; ?>
        
        <?php if ( ! empty( $field['instructions'] ) ) : ?>
            <p class="description"><?php echo esc_html( $field['instructions'] ); ?></p>
        <?php endif; ?>
    </div>
    <?php
}

4. 保存字段值到订单 #

将用户提交的字段值保存到订单元数据，并同步到ACF字段：

add_action( 'woocommerce_checkout_create_order', 'acf_save_checkout_field_to_order' );
function acf_save_checkout_field_to_order( $order ) {
    if ( isset( $_POST['custom_acf_field'] ) ) {
        $field_value = sanitize_text_field( $_POST['custom_acf_field'] );
        // 保存到WooCommerce订单元数据
        $order->update_meta_data( '_custom_acf_field', $field_value );
        // 同步到ACF字段（关联到订单ID）
        update_field( 'custom_checkout_field', $field_value, $order->get_id() );
    }
}

常见问题说明 #

• 为什么自定义Gutenberg块无法嵌入结账表单？
  WooCommerce Checkout Block是一个封装的复合块，内部表单结构无法通过添加独立块嵌入，必须使用官方提供的钩子来插入内容。
• 直接在页面添加ACF字段为什么不行？
  页面级的ACF字段只能渲染在结账块的外部区域，无法插入表单内部的流程节点中。

内容的提问来源于stack exchange，提问作者Asif Reza