如何向 WooCommerce 结账阻止添加额外的字段

此功能需要 WooCommerce 8.9.0 或更高版本。

WooCommerce 结账阻止提供了一个强大的 API，供开发者在结账过程中从客户处收集额外的信息。 无论您需要收集特殊的送货说明、公司信息还是营销偏好，额外的结账字段都可以轻松扩展您的商店功能。

在本指南中，我们将逐步介绍如何向您的结账表单添加您自己的额外字段，并提供您可以立即实现的实用示例。

快速开始

要添加额外的结账字段，您将使用 woocommerce_register_additional_checkout_field() 函数。 应该在 woocommerce_init 操作之后调用此函数，以确保 WooCommerce 已完全加载。

以下是基本结构：

add_action( 'woocommerce_init', function() {
    if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
        return;
    }
    
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'your-namespace/field-name',
            'label'    => __( 'Your Field Label', 'your-text-domain'),
            'location' => 'contact', // or 'address' or 'order'
            'type'     => 'text',    // or 'select' or 'checkbox'
            'required' => false,
        )
    );
});

字段位置：您的字段显示的位置

您可以将额外的字段放置在三个不同的位置：

联系方式 (contact)

这些字段显示在结账表单的顶部，位于电子邮件字段旁边。 保存在此处的数据将成为客户帐户的一部分，并在他们的“帐户详情”部分可见。

示例：

woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/marketing-opt-in',
        'label'    => __('Subscribe to our newsletter?', 'your-text-domain'),
        'location' => 'contact',
        'type'     => 'checkbox',
    )
);

地址 (address)

这些字段显示在收货地址和账单地址表单中。 它们同时保存到客户和订单，因此回头客无需再次填写。

示例：

woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/delivery-instructions',
        'label'    => __('Special delivery instructions', 'your-text-domain'),
        'location' => 'address',
        'type'     => 'text',
    )
);

订单信息 (order)

此位置的字段会显示在单独的“订单信息”块中，并且仅保存到订单，而不会保存到客户的帐户。非常适合用于特定于订单的详细信息，这些信息不需要在未来的购买中被记住。

示例：

woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/gift-message',
        'label'    => __('Gift message', 'your-text-domain'),
        'location' => 'order',
        'type'     => 'text',
    )
);

支持的字段类型

API 支持三种字段类型：

文本字段

非常适合收集简短的文本输入：

woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/company-vat',
        'label'    => __('VAT Number', 'your-text-domain'),
        'location' => 'address',
        'type'     => 'text',
        'required' => true,
    )
);

下拉菜单

非常适合预定义的选项：

woocommerce_register_additional_checkout_field(
    array(
        'id'       => 'my-plugin/preferred-delivery-time',
        'label'    => __('Preferred delivery time', 'your-text-domain'),
        'location' => 'order',
        'type'     => 'select',
        'options'  => array(
            array(
                'value' => 'morning',
                'label' => __('Morning (9AM - 12PM)', 'your-text-domain')
            ),
            array(
                'value' => 'afternoon',
                'label' => __('Afternoon (12PM - 5PM)', 'your-text-domain')
            ),
            array(
                'value' => 'evening',
                'label' => __('Evening (5PM - 8PM)', 'your-text-domain')
            ),
        ),
    )
);

复选框

非常适合用于“是/否”问题或选择加入：

woocommerce_register_additional_checkout_field(
    array(
        'id'           => 'my-plugin/age-verification',
        'label'        => __('I confirm I am over 18 years old', 'your-text-domain'),
        'location'     => 'contact',
        'type'         => 'checkbox',
        'required'     => true,
        'error_message' => __('You must be over 18 to place this order.', 'your-text-domain'),
    )
);

添加字段属性

您可以使用 HTML 属性来增强您的字段，以获得更好的用户体验： 示例：

woocommerce_register_additional_checkout_field(
    array(
        'id'         => 'my-plugin/phone-number',
        'label'      => __('Alternative phone number', 'your-text-domain'),
        'location'   => 'contact',
        'type'       => 'text',
        'attributes' => array(
            'autocomplete' => 'tel',
            'pattern'      => '[0-9]{10}',
            'title'        => __('Please enter a 10-digit phone number', 'your-text-domain'),
            'placeholder'  => '1234567890',
        ),
    )
);

验证和清理

为了确保您在自定义字段中输入的数据是有效且安全的，您可以添加自定义的验证和清理函数。

add_action( 'woocommerce_init', function() {
    woocommerce_register_additional_checkout_field(
        array(
            'id'                => 'my-plugin/business-email',
            'label'             => __('Business Email', 'your-text-domain'),
            'location'          => 'contact',
            'type'              => 'text',
            'required'          => true,
            'sanitize_callback' => function( $value ) {
                return sanitize_email( $value );
            },
            'validate_callback' => function( $value ) {
                if ( ! is_email( $value ) ) {
                    return new WP_Error( 
                        'invalid_business_email', 
                        __('Please enter a valid business email address.', 'your-text-domain') 
                    );
                }
            },
        )
    );
});

验证

您还可以使用 WordPress 动作钩子进行验证：

add_action( 'woocommerce_validate_additional_field', function( $errors, $field_key, $field_value ) {
    if ( 'my-plugin/business-email' === $field_key ) {
        if ( ! is_email( $field_value ) ) {
            $errors->add( 'invalid_business_email', __('Please enter a valid email address.', 'your-text-domain') );
        }
    }
}, 10, 3 );

访问字段值

结账后，您可以使用辅助方法检索字段值：

use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\Domain\Services\CheckoutFields;

$checkout_fields = Package::container()->get( CheckoutFields::class );
$order = wc_get_order( $order_id );

// 获取特定字段值
$business_email = $checkout_fields->get_field_from_object( 
    'my-plugin/business-email', 
    $order, 
    'other' // 使用 'billing' 或 'shipping' 获取地址字段
);

// 获取所有附加字段
$all_fields = $checkout_fields->get_all_fields_from_object( $order, 'other' );

完整示例

add_action( 'woocommerce_init', function() {
    if ( ! function_exists( 'woocommerce_register_additional_checkout_field' ) ) {
        return;
    }

    // 公司信息
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'my-business-store/company-size',
            'label'    => __('公司规模', 'your-text-domain'),
            'location' => '位置',
            'type'     => 'select',
            'required' => true,
            'options'  => array(
                array( 'value' => '1-10', 'label' => __('1-10名员工', 'your-text-domain') ),
                array( 'value' => '11-50', 'label' => __('11-50名员工', 'your-text-domain') ),
                array( 'value' => '51-200', 'label' => __('51-200名员工', 'your-text-domain') ),
                array( 'value' => '200+', 'label' => __('200名以上员工', 'your-text-domain') ),
            ),
        )
    );

    // 送货偏好
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'my-business-store/requires-appointment',
            'label'    => __('送货是否需要预约', 'your-text-domain'),
            'location' => '地址',
            'type'     => '复选框',
        )
    );

    // 订单相关的备注
    woocommerce_register_additional_checkout_field(
        array(
            'id'       => 'my-business-store/po-number',
            'label'    => __('订单号', 'your-text-domain'),
            'location' => '订单',
            'type'     => 'text',
        )
    );
});

下一步

现在，您已经为在您的 WooCommerce 商店中使用结账块添加额外的结账字段奠定了基础。

API 提供了强大的基础，用于自定义您的结账体验，同时保持与 WooCommerce 的基于块的结账系统的兼容性。 从简单的字段开始，并随着需求的增长，逐渐添加更复杂的验证和条件逻辑。