Análise aprofundada dos campos de checkout personalizados do WooCommerce: guia de desenvolvimento completo.

Visão Geral do Sistema de Campos de Pagamento do WooCommerce

A página de pagamento do WooCommerce é um ponto crítico no processo de compras online, pois é onde as informações do cliente são coletadas. A flexibilidade e a escalabilidade desse sistema se devem, em grande parte, ao seu sistema de campos modular. Esse sistema organiza todos os itens que o usuário precisa preencher – como nome, endereço, contato, etc. – em um array multidimensional e estruturado. Esse array não apenas define as etiquetas e os tipos dos campos, mas também controla a ordem em que eles são exibidos, a obrigatoriedade de preenchimento, as regras de validação e as classes CSS aplicadas a eles.

O núcleo de todo o sistema é… class-wc-checkout.php O arquivo, bem como o seu conteúdo… WC_Checkout Classe. Todos os campos são agrupados em alguns “conjuntos de campos” principais, de acordo com sua função; os mais utilizados são… billing(Campo do fatura)shipping(Campo de entrega) e order(Campos como observações do pedido, etc.) Cada conjunto de campos é, em si, um array que contém as definições de vários campos. Compreender essa estrutura hierárquica é o primeiro passo para realizar qualquer operação personalizada, pois todas as modificações são feitas em torno desse array geral de campos. Os desenvolvedores não precisam modificar os arquivos principais diretamente, mas sim intervir no processo através de uma série de ações e ganchos de filtro cuidadosamente projetados. Isso garante a sustentabilidade das funcionalidades personalizadas e a compatibilidade com futuras versões do sistema.

Use os ganchos internos para adicionar e modificar campos.

O WooCommerce oferece um sistema de ganchos (Hooks) poderoso e fácil de usar, que permite que os desenvolvedores adicionem, removam, alterem ou consultem os campos de pagamento de forma segura. Esta é a prática padrão para desenvolvimentos personalizados, evitando os problemas de manutenção decorrentes da modificação direta dos arquivos de templates principais.

Leitura recomendada Guia Prático para Otimização de Desempenho de Sites de Comércio Eletrônico com WooCommerce e Desenvolvimento de Plugins Avançados。

Como adicionar novos campos a um formulário de pagamento?

Para adicionar um novo campo à página de pagamento, como um botão de seleção que permita que o cliente escolha o “tipo de cabeçalho da fatura”, você precisa usar: woocommerce_checkout_fields Filtro. Este filtro transmite um array completo de campos de pagamento para a função desenvolvida, permitindo que você acesse qualquer conjunto de campos (por exemplo,...). billingAdicione uma nova entrada no (…)

Hospedagem para sites WordPress da UltraHost

Garantia de reembolso em 30 dias, largura de banda ilimitada e banco de dados, proteção contra DDoS gratuita; desconto de 50% na compra de 3 anos (planos de 4 TB a 10 TB).

página de acesso

function add_invoice_title_field( $checkout_fields ) {
    $checkout_fields['billing']['billing_invoice_type'] = array(
        'type' => 'select',
        'label' => '发票抬头',
        'required' => true,
        'options' => array(
            'personal' => '个人',
            'company' => '单位'
        ),
        'class' => array('form-row-wide'),
        'priority' => 21, // 紧跟在“公司名称”字段之后
    );
    return $checkout_fields;
}
add_filter( 'woocommerce_checkout_fields', 'add_invoice_title_field' );

O código acima cria uma caixa de seleção suspensa (drop-down) na área dos campos de fatura. Cada definição de campo é um array associado, no qual… type, label, required Os pares de chave-valor determinam o comportamento e a aparência de um campo.priority Os parâmetros são de extrema importância, pois controlam a ordem de exibição desse campo no formulário. Quanto menor o número, maior a posição que ele ocupa.

Modificar ou excluir as propriedades de um campo existente

As necessidades do negócio podem exigir a alteração dos campos padrão. Por exemplo, em algumas regiões, pode ser necessário tornar o campo “Código Postal” opcional ou ocultar o campo “Estado/Província”. Isso também é realizado através de operações específicas. woocommerce_checkout_fields Isso é realizado através de um array de filtros.

function adjust_default_fields( $fields ) {
    // 将账单邮编字段设为非必填
    $fields['billing']['billing_postcode']['required'] = false;

// 完全移除账单州/省字段
    unset( $fields['billing']['billing_state'] );

// 更改邮箱字段的占位符文本
    $fields['billing']['billing_email']['placeholder'] = '用于接收订单确认信';

return $fields;
}
add_filter( 'woocommerce_checkout_fields', 'adjust_default_fields' );

Através de unset() Uma função pode excluir completamente um campo de um objeto. Na maioria dos casos, isso é feito ao substituir (ou “overriding”) o valor correspondente de um atributo em um array. required, label, class) para modificar o comportamento dos campos.

Validação de campos e persistência de dados

Exibir os campos no frontend é apenas o primeiro passo. Para garantir a qualidade dos dados, é necessário verificar as informações inseridas pelo usuário e salvar de forma confiável os dados que passarem na verificação no pedido. Esse processo é dividido em duas etapas: a verificação imediata no frontend (opcional, mas que melhora a experiência do usuário) e a verificação no backend no momento do envio (obrigatória).

Leitura recomendada Guia definitivo para otimizar o desempenho de sites de comércio eletrónico do WooCommerce: de configuração a cache, tudo explicado。

Implementar a lógica de validação no lado backend.

Quando o usuário clica no botão “Efetuar Pedido”, o WooCommerce executa o processo de verificação para concluir a compra. Os desenvolvedores podem aproveitar essa funcionalidade para... woocommerce_checkout_process Use os ganchos de ação (action hooks) para inserir regras de validação personalizadas. Se a validação falhar, é necessário chamar a função correspondente. wc_add_notice() A função exibe uma mensagem de erro para o usuário e impede a criação do pedido.

function validate_custom_fields_during_checkout() {
    // 检查自定义的“发票抬头”字段
    if ( isset( $_POST['billing_invoice_type'] ) && $_POST['billing_invoice_type'] == 'company' ) {
        // 如果选择了“单位”发票，则检查是否填写了公司名称
        if ( empty( $_POST['billing_company'] ) ) {
            wc_add_notice( '选择“单位”发票抬头时，必须填写公司名称。', 'error' );
        }
    }

// 验证一个自定义的文本字段，确保其格式
    if ( ! empty( $_POST['billing_custom_id'] ) && ! preg_match( '/^CUSTd{6}$/', $_POST['billing_custom_id'] ) ) {
        wc_add_notice( '客户编号格式错误，应为 CUST 后接6位数字。', 'error' );
    }
}
add_action( 'woocommerce_checkout_process', 'validate_custom_fields_during_checkout' );

Salve o valor do campo nos metadados do pedido.

Após a verificação ser bem-sucedida, o próximo passo é salvar permanentemente os valores dos campos personalizados durante a criação do pedido. Isso é feito através de… woocommerce_checkout_update_order_meta O hook de ação foi concluído. Esse hook é acionado após a criação do pedido e transmite o ID do pedido. Você deve usar o recurso disponível no WordPress para isso. update_post_meta() Função que armazena os dados do formulário como informações do pedido.

function save_custom_checkout_field_data( $order_id ) {
    // 保存发票类型
    if ( ! empty( $_POST['billing_invoice_type'] ) ) {
        update_post_meta( $order_id, '_billing_invoice_type', sanitize_text_field( $_POST['billing_invoice_type'] ) );
    }

// 保存客户编号
    if ( ! empty( $_POST['billing_custom_id'] ) ) {
        update_post_meta( $order_id, '_billing_custom_id', sanitize_text_field( $_POST['billing_custom_id'] ) );
    }
}
add_action( 'woocommerce_checkout_update_order_meta', 'save_custom_checkout_field_data' );

Ao armazenar dados, use nomes de chaves com um prefixo que contém um sublinhado (por exemplo: _nome_da_chave). _billing_invoice_typeÉ um acordo que visa impedir a exibição desse campo na caixa de metadados “Campos Personalizados” da página de edição de pedidos em segundo plano, evitando erros por parte dos administradores. É essencial utilizá-lo. sanitize_text_field() Funções como essas são utilizadas para limpar os dados, a fim de prevenir riscos de segurança.

hospedagem compartilhada da hosting.com

Alto desempenho com CPUs AMD EPYC, armazenamento SSD NVMe e LiteSpeed, suporte interno especializado 24 horas por dia, 7 dias por semana, medidas de segurança avançadas, incluindo SSL, força bruta, malware e proteção contra DDoS, economia de até 73%

página de acesso

Exibir dados personalizados na interface relacionada aos pedidos.

Após salvar os dados, é geralmente necessário exibi-los em vários locais, incluindo: 1) a interface de gerenciamento de pedidos no backend do WordPress; 2) a página de detalhes do pedido no “Meu Conta” do usuário no frontend; 3) os e-mails de pedido enviados aos clientes e administradores. Isso garante a integridade e a transparência das informações da transação.

Integrar campos personalizados na página de detalhes do pedido no backend

Para que os administradores possam visualizar facilmente as informações preenchidas pelos clientes no backend, você precisa exibir os metadados dos pedidos salvos na página de edição do pedido. Isso pode ser feito utilizando… woocommerce_admin_order_data_after_billing_address e woocommerce_admin_order_data_after_shipping_address Esses “ganchos” permitem inserir conteúdo após as informações existentes.

function display_custom_order_meta_in_admin( $order ) {
    $invoice_type = get_post_meta( $order->get_id(), '_billing_invoice_type', true );
    if ( $invoice_type ) {
        $display_type = ( $invoice_type == 'company' ) ? '单位' : '个人';
        echo '<p><strong>Tipo de cabeçalho da fatura:</strong> '`. esc_html($display_type)`.'</p>';
    }

$custom_id = get_post_meta( $order-&gt;get_id(), '_billing_custom_id', true );
    if ( $custom_id ) {
        echo '<p><strong>Número do cliente:</strong> '`. esc_html($custom_id)`.'</p>';
    }
}
add_action( 'woocommerce_admin_order_data_after_billing_address', 'display_custom_order_meta_in_admin' );

Exibir dados na interface do usuário e em mensagens de e-mail.

Para que os clientes também possam ver as informações que forneceram, você precisará modificar o modelo da tela de pedidos no front-end e o conteúdo dos e-mails. Para a página de detalhes do pedido, você pode usar… woocommerce_order_details_after_order_table Gancho. No caso de e-mails, é necessário utilizá-lo. woocommerce_email_order_meta_keys O filtro informa ao sistema de e-mail as chaves de metadados personalizadas, fazendo com que elas sejam automaticamente incluídas no conteúdo das mensagens.

Leitura recomendada Dominando o desenvolvimento de plug-ins do WordPress: Criando módulos de funções personalizadas eficientes a partir do zero。

// 在前台“查看订单”页面显示
function display_custom_data_in_order_view( $order ) {
    $custom_id = get_post_meta( $order->get_id(), '_billing_custom_id', true );
    if ( $custom_id ) {
        echo '<h2>Informações adicionais</h2><table class="shop_table custom-info"><tbody><tr><th>Número do cliente:</th><td>'`. esc_html($custom_id)`.'</td></tr></tbody></table>';
    }
}
add_action( 'woocommerce_order_details_after_order_table', 'display_custom_data_in_order_view' );

// 将自定义字段加入订单邮件
function add_custom_field_to_emails( $keys ) {
    $keys[] = '_billing_custom_id'; // 这个键对应的值会被加入到邮件中
    $keys[] = '_billing_invoice_type';
    return $keys;
}
add_filter( 'woocommerce_email_order_meta_keys', 'add_custom_field_to_emails' );

resumos

Personalizar os campos de pagamento do WooCommerce é um processo de desenvolvimento completo que abrange desde a exibição na interface até o armazenamento dos dados. O ponto central é entender e utilizar de forma flexível o sistema de ganchos (hooks) fornecido pelo WooCommerce. woocommerce_checkout_fields Use filtros para definir e modificar a estrutura dos campos; através disso… woocommerce_checkout_process A ação implementa a lógica de validação necessária; com a ajuda de… woocommerce_checkout_update_order_meta As ações permitem a persistência de dados válidos; por fim, são utilizados vários ganchos (hooks) relacionados à exibição (como…) woocommerce_admin_order_data_after_billing_address e woocommerce_email_order_meta_keysOs dados devem ser exibidos no backend, no frontend e em e-mails. Seguindo esse padrão, os desenvolvedores podem criar uma experiência de pagamento robusta, estável e alinhada às necessidades do negócio, garantindo ao mesmo tempo a manutenibilidade do código e a segurança das atualizações.

Perguntas frequentes Perguntas frequentes

É possível adicionar regras de validação para campos personalizados, como permitir que sejam inseridos apenas números?

Sim, conforme descrito na seção “Validação de Campos e Persistência de Dados” deste artigo, você pode… woocommerce_checkout_process Você pode escrever qualquer lógica de validação em PHP dentro da função de callback do gancho. Por exemplo, use-a para verificar os dados recebidos. is_numeric() Função ou expressão regular preg_match() Verifique se o valor do campo é um número puro. Se a validação falhar, chame… wc_add_notice() Basta exibir o erro.

Hospedagem Compartilhada InterServer

Hospedagem compartilhada $2.50 USD por mês, primeiro mês $0.1 USD código promocional tryinterserver, 461 scripts de aplicativos em nuvem, instalação com um clique.

página de acesso

Como fazer com que um campo personalizado seja exibido apenas para determinados métodos de entrega?

Isso requer a combinação de lógica de decisão baseada em condições. Você pode verificar o método de entrega atual no carrinho de compras ou na sessão do usuário dentro da função que adiciona ou modifica os campos. Por exemplo, use… WC()->session->get('chosen_shipping_methods') Obtenha o ID do método de entrega selecionado. Se não atender aos requisitos, outro método pode ser utilizado. unset() Remova esse campo do array de campos, ou adicione uma classe CSS específica (por exemplo,...). hidden) É exibido/ocultado dinamicamente em conjunto com o JavaScript.

Eu modifiquei os campos, mas a página de pagamento não mudou. Qual pode ser a razão?

Primeiramente, confira se o seu código personalizado está sendo executado corretamente (por exemplo, no tema que você está utilizando). functions.php O arquivo não possui erros de sintaxe. Em seguida, verifique a lógica do código para garantir que você esteja modificando os nomes das chaves do array de campos corretamente (por exemplo…). billing no entanto shippingEm seguida, limpe todos os caches possíveis, incluindo o cache de objetos, o cache de páginas e o cache do navegador. Por fim, tente alternar para o tema padrão (como o Storefront) e desative outros plugins para eliminar possíveis conflitos.

Os dados dos campos personalizados salvos podem ser utilizados em buscas de pedidos subsequentes ou em análises de relatórios?

Sim, mas podem ser necessários passos adicionais. Como os dados são armazenados como Post Meta de pedidos, você pode recuperá-los através das funcionalidades de consulta de metadados do WordPress. Para realizar buscas na lista de pedidos no backend do WooCommerce, você pode precisar usar um plugin que suporte a busca em campos personalizados ou escrever código para expandir as funcionalidades de busca padrão. Quanto à geração de relatórios, plugins avançados para relatórios geralmente oferecem opções para incluir os metadados dos pedidos nas dimensões de filtragem e exibição. A exportação dos dados dos campos para um formato CSV também depende de se o ferramenta de exportação suporta a seleção de colunas de metadados personalizadas.