¿Cómo personalizar los campos de la página de pago mediante los ganchos de WooCommerce?

Comprender la arquitectura de los campos de pago en WooCommerce

Antes de comenzar a personalizar cualquier elemento, es de vital importancia comprender en profundidad la estructura interna de los campos de pago. La página de pago de WooCommerce no es un diseño estático, sino que se genera dinámicamente a partir de una serie de grupos lógicos y un conjunto de campos que pueden ser filtrados. Este enfoque permite a los desarrolladores tener un control total, desde el nivel general hasta los detalles más específicos.

Los campos relacionados con el proceso de pago se organizan principalmente en cuatro grupos principales: Facturación (billing), Envío (shipping), Cuenta (account) y Pedido (order). Cada grupo cuenta con sus propios filtros específicos para realizar selecciones o ajustes en los datos correspondientes. woocommerce_billing_fields Se utiliza para manejar específicamente los campos de las facturas, lo que permite a los desarrolladores realizar operaciones más detalladas sin necesidad de acceder a todo el array de campos.

En detalle, cada campo es un array asociado que contiene múltiples atributos. Estos atributos determinan cómo se presenta y se comporta el campo en la interfaz de usuario ( frontend). Los atributos clave incluyen: type(Definir tipos de entrada, como `text`, `select`, `checkbox`).label(Letras de visualización para los campos)placeholder(El texto de sugerencia dentro del cuadro de entrada)required(Valor booleano que indica si el campo es obligatorio o no).class(Un array de clases CSS para controlar los estilos de diseño, por ejemplo…) form-row-first (Haz que ocupe la mitad izquierda de la anchura) y también… priority(Los números determinan el orden en que se muestran los campos dentro del mismo grupo; cuanto menor el valor, más hacia adelante aparece el campo). Comprender estos atributos es la base para realizar cualquier personalización efectiva.

Lecturas recomendadas Guía práctica de WooCommerce: Cómo construir un sitio web de comercio electrónico profesional desde cero。

Utilizar los filtros principales para agregar, eliminar o modificar campos.

La operación personalizada más importante consiste en modificar el array de campos mediante los ganchos (hooks) de los filtros. Estos ganchos son una extensión de la arquitectura de plugins de WordPress y WooCommerce, que permiten que tu código interrumpa y modifique los datos antes de que sean utilizados.

Servidor de WordPress de UltaHost

Garantía de reembolso en 30 días, ancho de banda ilimitado y bases de datos, protección gratuita contra ataques DDoS; descuento del 50% al comprar por 3 años (versiones de 4 TB y 5 TB).

página de acceso

Modificar las propiedades de un campo existente.

Uno de los requisitos más comunes es modificar la configuración de los campos predeterminados, como cambiar las etiquetas, los placeholders, o convertir un campo de obligatorio a opcional. Esto se puede lograr accediendo a los atributos específicos del arreglo de campos y reasignándoles los valores deseados.

woocommerce_checkout_fields Es el filtro principal que se utiliza para procesar esta tarea. El siguiente ejemplo demuestra cómo modificar los campos de código postal y de notas del pedido:

add_filter( 'woocommerce_checkout_fields', 'modify_default_checkout_fields' );
function modify_default_checkout_fields( $fields ) {
    // 将账单邮编字段改为非必填，并更新标签和占位符
    $fields['billing']['billing_postcode']['required'] = false;
    $fields['billing']['billing_postcode']['label'] = '邮政编码 / 邮编';
    $fields['billing']['billing_postcode']['placeholder'] = '可选填';

// 为订单备注字段添加更明确的提示
    $fields['order']['order_comments']['placeholder'] = '如需指定配送时间或包装要求，请在此注明。';

// 移除配送电话字段（如果不需要）
    unset( $fields['shipping']['shipping_phone'] );

return $fields;
}

Añadir un campo completamente nuevo a la página de pago.

Además de las modificaciones, agregar nuevos campos de negocio (como “Número de Identificación Fiscal de la Empresa” o “Mensaje del Regalo”) es otra solicitud muy frecuente. La esencia de agregar campos es incorporar información a grupos específicos (como…). billingInsertar un nuevo par de clave-valor en el array.

add_filter( 'woocommerce_checkout_fields', 'add_new_custom_field' );
function add_new_custom_field( $fields ) {
    // 在账单分组中添加一个“公司税号”字段
    $fields['billing']['billing_vat_number'] = array(
        'type' => 'text',
        'label' => __('公司税号 (VAT)', 'your-text-domain'),
        'placeholder' => __('请输入您的增值税号', 'your-text-domain'),
        'required' => true, // 根据业务需求设定
        'class' => array('form-row-wide'), // 占满整行
        'clear' => true, // 在该字段后换行
        'priority' => 35, // 调整显示位置，例如放在城市字段之后
    );

// 在订单分组中添加一个“礼品贺卡留言”字段
    $fields['order']['gift_card_message'] = array(
        'type' => 'textarea',
        'label' => __('礼品贺卡留言', 'your-text-domain'),
        'placeholder' => __('我们将把这段祝福写在贺卡上。', 'your-text-domain'),
        'required' => false,
        'class' => array('form-row-wide'),
        'priority' => 25,
    );

return $fields;
}

Procesamiento de la validación y almacenamiento de datos de los campos

Los campos adicionados en la parte frontal ( frontend) deben estar en coordinación con el proceso de procesamiento de datos en la parte posterior ( backend); de lo contrario, la información introducida por los usuarios se perderá. Esto implica dos pasos clave: la validación de datos y el almacenamiento permanente de estos datos.

Lecturas recomendadas Análisis en profundidad de WooCommerce: cómo construir tu sitio web de comercio electrónico profesional desde cero.。

Implementar la validación de campos en el lado del servidor

Para garantizar la validez y la seguridad de los datos, es necesario verificar los campos personalizados que los usuarios envían desde el lado del servidor. WooCommerce ofrece herramientas para ello. woocommerce_checkout_process El “gancho de acción” (action hook) se activa antes de que el proceso de pago procese los datos.

En la función de callback de este gancho, puedes realizar las comprobaciones necesarias. $_POST El valor del campo correspondiente en la variable superglobal. Si el valor no cumple con los requisitos (por ejemplo, un campo obligatorio está vacío o tiene un formato incorrecto), puedes utilizar… wc_add_notice() La función muestra un mensaje de error al usuario, lo que impide que el pedido avance al siguiente paso de su procesamiento.

add_action( 'woocommerce_checkout_process', 'validate_custom_checkout_field' );
function validate_custom_checkout_field() {
    // 验证“公司税号”字段是否已填写（假设其为必填）
    if ( ! empty( $_POST['billing_vat_number'] ) ) {
        // 可以在此添加更复杂的格式验证逻辑
        $vat_number = sanitize_text_field( $_POST['billing_vat_number'] );
        if ( strlen( $vat_number ) < 10 ) {
            wc_add_notice( __( '公司税号格式不正确，长度应不少于10位。', 'your-text-domain' ), 'error' );
        }
    } else {
        // 如果字段被标记为required但未填写，则报错
        // 注意：此处的逻辑应与前端字段的`required`属性设置保持一致
        // wc_add_notice( __( '请填写公司税号。', 'your-text-domain' ), 'error' );
    }
}

Guardar los valores de los campos personalizados en el pedido.

Los datos verificados deben ser almacenados de manera permanente. Esto se suele lograr mediante… woocommerce_checkout_update_order_meta Se utiliza un “gancho de acción” (action hook) para completar este proceso. Este gancho se activa después de la creación del pedido y antes del pago, y constituye el lugar estándar para guardar los metadatos a nivel de pedido (Custom Order Meta).

hosting.com Alojamiento compartido

Alto rendimiento con CPU AMD EPYC, almacenamiento SSD NVMe y LiteSpeed, asistencia interna de expertos 24 horas al día, 7 días a la semana, medidas de seguridad avanzadas como SSL, fuerza bruta, protección contra malware y DDoS, ahorro de hasta 73%.

página de acceso

add_action( 'woocommerce_checkout_update_order_meta', 'save_custom_checkout_field_to_order' );
function save_custom_checkout_field_to_order( $order_id ) {
    // 保存公司税号
    if ( isset( $_POST['billing_vat_number'] ) && ! empty( $_POST['billing_vat_number'] ) ) {
        // 清理数据后保存
        update_post_meta( $order_id, '_billing_vat_number', sanitize_text_field( $_POST['billing_vat_number'] ) );
    }

// 保存礼品留言
    if ( isset( $_POST['gift_card_message'] ) && ! empty( $_POST['gift_card_message'] ) ) {
        update_post_meta( $order_id, '_gift_card_message', sanitize_textarea_field( $_POST['gift_card_message'] ) );
    }
}

Tras guardarlos, estos datos se almacenarán en la base de datos como metadatos de los pedidos (Post Meta). Puedes acceder a ellos en la página de detalles del pedido en el backend, en los archivos de exportación de pedidos o a través de llamadas a API.

Aplicaciones avanzadas y mejores prácticas

Una vez que hayas dominado las operaciones básicas, algunas técnicas avanzadas y buenas prácticas pueden ayudarte a crear soluciones personalizadas más robustas, fáciles de usar y de alto rendimiento.

Implementar la visualización de la lógica condicional de los campos

En ciertas situaciones, la visualización o no de un campo depende del valor de otros campos. Por ejemplo, el campo “Número de Orden de Compra” solo se muestra cuando el usuario elige la opción “Compras Corporativas”. Esto se logra principalmente mediante JavaScript en el lado del cliente (generalmente utilizando jQuery) para manipular dinámicamente el DOM.

Lecturas recomendadas ¿Cómo personalizar un tema para WordPress que sea potente y atractivo visualmente?。

Necesitas escribir un script que monitorice los cambios en el campo de origen (por ejemplo, un cuadro de selección) y, en función del valor seleccionado, muestre u oculte el elemento que envuelve el campo de destino. Además, para garantizar la coherencia de los datos, se recomienda incluir juicios condicionales en la lógica de validación del lado del servidor.

Mostrar datos en el backend y en la gestión de correos electrónicos.

Para que el propietario del negocio pueda ver los datos guardados, es necesario mostrar estos campos personalizados en la página de detalles del pedido en el backend de WordPress. Puedes utilizar esta funcionalidad para ello. woocommerce_admin_order_data_after_billing_address o woocommerce_admin_order_data_after_shipping_address Utiliza ganchos de acción (action hooks) para generar y mostrar información.

Alojamiento compartido InterServer

Alojamiento compartido $2.50 USD al mes , primer mes $0.1 USD código promocional tryinterserver, 461 scripts de aplicaciones en la nube, instalación en un clic.

página de acceso

add_action( 'woocommerce_admin_order_data_after_billing_address', 'display_custom_field_on_admin_order', 10, 1 );
function display_custom_field_on_admin_order( $order ) {
    $vat_number = $order->get_meta( '_billing_vat_number' );
    if ( $vat_number ) {
        echo '<p><strong>'\n' . __( 'Número de impuesto de la empresa:', 'your-text-domain' ) . '</strong> '`. esc_html($vat_number)`.'</p>';
    }
}

De la misma manera, también puedes utilizar ganchos de filtro (filter hooks) para… woocommerce_email_order_meta_fieldsAñada los campos personalizados al correo de confirmación del pedido que se envía a los clientes o administradores.

Sugerencias de rendimiento y organización del código

将所有的结账字段自定义代码集中管理，例如放在一个独立的PHP文件中，或者封装在一个类中，以提高可维护性。避免在钩子回调函数中执行重型数据库查询或远程API调用。对于需要条件判断的逻辑，尽量使用早期返回（early return）来减少不必要的处理。始终遵循安全准则：对输入进行清理（sanitization），对输出进行转义（escaping）。

resúmenes

Personalizar los campos de la página de pago a través del sistema de ganchos (hooks) de WooCommerce implica un proceso completo que comienza con la comprensión de la arquitectura del sistema, continúa con el uso de filtros para modificar los datos, y finaliza con la validación y almacenamiento de estos datos mediante ganchos de acción. Este enfoque evita la modificación directa de los archivos de plantillas principales, lo que garantiza la compatibilidad y la facilidad de mantenimiento del código a lo largo de las actualizaciones. Ya sea que se trate de ajustes simples en los elementos de la página o de la adición de campos condicionales y el procesamiento de datos más complejo, este flujo de trabajo basado en ganchos ofrece soluciones potentes y flexibles. Al dominar estas habilidades, podrá crear experiencias de pago altamente personalizadas, fluidas y seguras para cualquier tienda en línea, lo que a su vez mejorará directamente la eficiencia de las conversiones comerciales y la satisfacción de los clientes.

FAQ Preguntas más frecuentes

¿Cómo se ajusta el estilo de los campos personalizados?

El estilo de los campos personalizados se controla principalmente a través de CSS. WooCommerce genera un envoltorio HTML para cada campo que incluye una clase CSS específica. Puedes utilizar estas clases, por ejemplo, las clases generadas por el ID del campo (como…). #billing_vat_number_field), clases de diseño (como…) .form-row-wide) o clases de estado de validación (por ejemplo, .woocommerce-validatedEs necesario escribir las reglas CSS en el archivo de estilo del tema front-end. Para requisitos de estilo más complejos, podría ser necesario agregar clases CSS personalizadas a los campos correspondientes. class En el array de atributos.

¿Por qué mis campos personalizados no se muestran en la página de pago?

Por favor, siga los siguientes pasos para realizar la investigación: En primer lugar, asegúrese de que el código PHP que añade los campos haya sido correctamente implementado en el tema de la actividad. functions.php El problema puede estar en un archivo o un complemento personalizado, y no hay errores de sintaxis que provoquen la interrupción de la ejecución de PHP. En segundo lugar, verifica la lógica del código para asegurarte de que estás modificando el grupo de campos correcto. $fields[‘billing’]Y, finalmente, devolvió el resultado correcto. $fields Un array. Luego, borra todo el caché que pueda existir, incluido el caché de objetos de WordPress, el caché de páginas y el caché del navegador. Finalmente, verifica si hay otros plugins o código de temas que han sobrescrito tus modificaciones con una prioridad más alta.

¿Cómo mostrar los valores de los campos personalizados en la vista de pedidos de la cuenta del usuario?

Para mostrar los valores de los campos en los detalles del pedido de la página “Mi Cuenta”, necesitas utilizar… woocommerce_order_details_after_order_table Acción de gancho (para la vista del cliente) o woocommerce_order_item_meta_end Espere a que se active el hook. En la función de callback, obtenga el objeto del pedido actual y luego utilícelo. get_meta() Método para recuperar los metadatos de los pedidos almacenados y generar una salida segura.

add_action( 'woocommerce_order_details_after_order_table', 'display_custom_field_in_customer_view', 10, 1 );
function display_custom_field_in_customer_view( $order ) {
    $custom_value = $order->get_meta( '_your_field_key' );
    if ( $custom_value ) {
        echo '<section class="custom-field-display"><h2>Información personalizada</h2><p>'`. esc_html($custom_value)`.'</p></section>';
    }
}

¿Cómo se debe configurar el atributo `priority` de un campo?

priority Los atributos controlan el orden de disposición vertical de los campos dentro del mismo grupo. En WooCommerce, el prioridad por defecto de los campos suele ser un múltiplo de 10. Puede consultar los valores por defecto al imprimir un array de campos y luego establecer sus propios valores según sus necesidades. Por ejemplo, si desea que un campo se coloque entre “Línea de dirección 1” y “Línea de dirección 2”, puede asignarle una prioridad numérica intermedia, como 55. Cuanto menor sea el valor, más arriba aparecerá el campo en el formulario. Una configuración adecuada puede optimizar el flujo lógico de relleno del formulario.