Ao construir uma loja online, a experiência do cliente no processo de pagamento é de extrema importância. O formulário de pagamento padrão do WooCommerce pode não atender a todas as necessidades do negócio, como a coleta do endereço da empresa para a emissão de faturas, mensagens de aniversário ou especificações personalizadas para o envio dos produtos. Nesses casos, os campos de pagamento personalizados se tornam uma ferramenta de extensão muito útil. Eles não apenas aumentam o nível de personalização da experiência do usuário, mas também permitem que o lojista colete dados essenciais para a melhoria dos serviços e das estratégias de marketing.
Através do sistema de ganchos (hooks) do WordPress e da vasta API fornecida pelo WooCommerce, os desenvolvedores podem adicionar com relativa facilidade diferentes tipos de campos, como caixas de texto, menus suspensos, caixas de seleção e caixas de seleção múltipla, em vários locais da página de pagamento (após as áreas de “Endereço da Fatura” e “Endereço de Entrega”, ou até mesmo criar blocos completamente novos). Todo esse processo não se limita apenas à exibição no lado front-end; o mais importante é o fluxo de processamento de dados no lado back-end: como garantir que os dados inseridos pelo usuário sejam salvos de forma correta e segura no pedido, e como exibi-los de forma clara na interface de gerenciamento do backend, na página do perfil do usuário e nos e-mails de notificação do pedido.
Método de implementação de campos de pagamento personalizados
O WooCommerce disponibiliza dois grandes tipos de ganchos (hooks) para o processamento dos campos de pagamento:woocommerce_checkout_fields e woocommerce_checkout_update_order_metaO primeiro é usado para definir e renderizar os campos, enquanto o segundo é usado para salvar os dados desses campos.
Leitura recomendada Desenvolvimento de plugins para WordPress: Do básico ao avançado: Um guia passo a passo para criar suas próprias funcionalidades exclusivas。
Usar ganchos para adicionar campos
O passo mais crucial é… woocommerce_checkout_fields O gancho do filtro adiciona os campos personalizados ao array de campos de pagamento. Essa estrutura do array é clara, permitindo que você organize os campos de forma organizada, especialmente no contexto de uma “fatura”.billing“Entrega”shipping“Observações do pedido”orderJá existem partições como essas, e é possível até criar partições personalizadas.custom）。
O exemplo de código abaixo mostra como adicionar um campo de texto para o “Código de Imposto da Empresa” e um botão de seleção (“Necessita de Fatura?”) na parte inferior da área de informações do “Contas”.
/**
* 在结账页面添加自定义字段
*/
add_filter( 'woocommerce_checkout_fields', 'custom_add_checkout_fields' );
function custom_add_checkout_fields( $fields ) {
// 在“账单”字段组中添加一个“公司税号”文本字段
$fields['billing']['billing_vat_number'] = array(
'label' => __( '公司税号 / VAT Number', 'your-text-domain' ),
'placeholder' => _x( '请输入您的公司税号', 'placeholder', 'your-text-domain' ),
'required' => false, // 非必填
'class' => array( 'form-row-wide' ), // 宽度样式
'clear' => true, // 清除浮动
'priority' => 25, // 显示顺序，数字越小越靠前
);
// 在“账单”字段组中添加一个“是否需要发票”单选框
$fields['billing']['billing_invoice_needed'] = array(
'type' => 'radio',
'label' => __( '是否需要纸质发票？', 'your-text-domain' ),
'required' => true,
'class' => array( 'form-row-wide' ),
'clear' => true,
'priority' => 30,
'options' => array(
'yes' => __( '是，需要纸质发票', 'your-text-domain' ),
'no' => __( '否，不需要', 'your-text-domain' )
)
);
return $fields;
}Verificar e salvar os dados dos campos.
Após adicionar os campos, é necessário garantir que os dados inseridos pelo usuário sejam salvos nos metadados correspondentes do pedido. Isso é feito através de… woocommerce_checkout_update_order_meta Isso é realizado através de “ganchos de ação” (action hooks). Quando o usuário envia um pedido, o WooCommerce aciona esse gancho, e nós podemos capturar e salvar os valores dos campos personalizados nesse momento.
/**
* 保存自定义结账字段的值到订单元数据
*/
add_action( 'woocommerce_checkout_update_order_meta', 'custom_save_checkout_fields' );
function custom_save_checkout_fields( $order_id ) {
if ( ! empty( $_POST['billing_vat_number'] ) ) {
// 使用 sanitize_text_field 进行清洁处理，防止恶意代码
update_post_meta( $order_id, '_billing_vat_number', sanitize_text_field( $_POST['billing_vat_number'] ) );
}
if ( ! empty( $_POST['billing_invoice_needed'] ) ) {
update_post_meta( $order_id, '_billing_invoice_needed', sanitize_text_field( $_POST['billing_invoice_needed'] ) );
}
}Exibir os dados dos campos no backend e nos e-mails.
Apenas salvar os dados não é suficiente; os lojistas precisam ter acesso a essas informações na gestão dos pedidos em segundo plano, e os clientes também devem conseguir ver o que preencheram no e-mail de confirmação do pedido e na página “Meu Conta”.
Exibir na página de edição de pedidos em segundo plano.
É possível fazer isso. woocommerce_admin_order_data_after_billing_address Semelhante a esses “ganchos” (hook functions), o valor dos campos personalizados é exibido após as colunas “Endereço da Fatura” ou “Endereço de Entrega” na página de detalhes do pedido no backend.
Leitura recomendada Guia de Início para Desenvolvimento de Plugins para WordPress: Construa sua Primeira Extensão de Funcionalidade do Zero。
/**
* Exibir campos personalizados na página de detalhes do pedido de backend
*/
add_action( 'woocommerce_admin_order_data_after_billing_address', 'custom_display_admin_order_meta', 10, 1 );
função custom_display_admin_order_meta( $order ) {
$vat_number = $order->get_meta( '_billing_vat_number' );
$invoice_needed = $order->get_meta( '_billing_invoice_neededed' );
if ( $vat_number ) {
echo '<p><strong>'\n' . __( 'Número de identificação fiscal da empresa:', 'your-text-domain' ) . '</strong> '`. esc_html($vat_number).`'</p>';
}
se ( $invoice_needed ) {
$display_text = ( $invoice_neededed == 'yes' ) ? __( 'yes', 'your-text-domain' ) : __( 'no', 'your-text-domain' ) ;
echo '<p><strong>'\n' . __( 'Necessário uma fatura em papel:', 'your-text-domain' ) . '</strong> '`. esc_html($display_text).`'</p>';
}
}Mostrar no e-mail de confirmação do pedido e na página de agradecimento.
Para que os clientes também possam ver essas informações, precisamos adicioná-las aos e-mails de pedido e à página de confirmação do pedido (agradecimento). woocommerce_email_order_meta_keys Os filtros podem adicionar automaticamente as chaves de metadados especificadas a todos os e-mails de notificação. Ao mesmo tempo, é possível utilizar… woocommerce_order_details_after_order_table Os ganchos de ação (action hooks) podem ser exibidos nas detalhes do pedido na interface do usuário.
/**
* Adicionar campos personalizados aos e-mails de pedidos
*/
add_filter( 'woocommerce_email_order_meta_keys', 'custom_add_order_meta_to_email' );
função custom_add_order_meta_to_email( $keys ) {
$keys[] = '_billing_vat_number'; function
$keys[] = '_billing_invoice_neededed'; // O e-mail será formatado como uma chave, muitas vezes exigindo mais embelezamento
return $keys;
}
/**
* Exibir campos personalizados nos detalhes do pedido de front-end (página de agradecimento, minha conta - detalhes do pedido)
*/
add_action( 'woocommerce_order_details_after_order_table', 'custom_display_order_data_frontend', 10, 1 );
função custom_display_order_data_frontend( $order ) {
$vat_number = $order->get_meta( '_billing_vat_number' );
if ( $vat_number ) {
echo '<h2>'\n' . __( 'Informações adicionais', 'your-text-domain' ) . '</h2>'; echo '
echo '<table class="shop_table shop_table_responsive additional_info">'; echo '
echo '<tr><th>'\n' . __( 'Número de identificação fiscal da empresa:', 'your-text-domain' ) . '</th><td>'`. esc_html($vat_number).`'</td></tr>'; echo '
echo '</table>';
}
}Aplicações Avançadas e Lógica de Condições de Campos
Além da adição de campos básicos, interações mais complexas podem melhorar significativamente a experiência do usuário, como a exibição condicional de campos e a validação com base em valores existentes.
Implementar a exibição condicional de campos
Usando JavaScript/jQuery, você pode exibir ou ocultar dinamicamente um campo com base no valor de outro campo (como um país, um estado ou uma opção de seleção). Por exemplo, apenas quando o usuário selecionar “Necessito de nota fiscal em papel”, uma área de texto com “Observações para o envio da nota fiscal” será exibida.
Para implementar essa funcionalidade, é necessário adicionar lógica ao arquivo JavaScript do tema, ou utilizar outros métodos apropriados. wp_enqueue_script Coloque o script na fila de espera e monitore as alterações nos campos na página de pagamento, controlando o estado de exibição dos campos-alvo.
Adicionar validação personalizada a um campo
Embora o WooCommerce tenha funcionalidades integradas para marcar campos como “obrigatórios”,required (\n=> true) para verificar, mas às vezes você precisa de regras de validação mais complexas, como um formato específico para o número de identificação fiscal. Isso pode ser feito através de woocommerce_checkout_process Use os ganchos de ação (action hooks) para adicionar lógica de validação personalizada.
/**
* 在结账过程中验证自定义字段
*/
add_action( 'woocommerce_checkout_process', 'custom_validate_checkout_fields' );
function custom_validate_checkout_fields() {
// 如果“公司税号”字段不为空，则检查其格式（示例：假设是15位数字）
if ( ! empty( $_POST['billing_vat_number'] ) && ! preg_match( '/^d{15}$/', $_POST['billing_vat_number'] ) ) {
wc_add_notice( __( '错误：公司税号格式不正确，应为15位数字。', 'your-text-domain' ), 'error' );
}
}Otimização de desempenho e melhores práticas
Ao adicionar muitos campos personalizados a um site ou ao não gerenciá-los de forma adequada, isso pode afetar a velocidade de carregamento da página de pagamento e a experiência do usuário.
Leitura recomendada Guia Avançado de Desenvolvimento para Dominar os Campos Personalizados do WooCommerce: Desde a Criação até a Exibição。
Otimização do carregamento e da renderização dos campos
- Carregamento seletivo de scripts: Carregue apenas os scripts JavaScript necessários para os campos que são exibidos condicionalmente na página de pagamento.
- Definir prioridades de forma razoável: use isso.
priorityOrganize os campos de acordo com os parâmetros de forma racional para evitar reorganizações desnecessárias no layout. - Simplificado:
classArray: Adicione apenas as classes de estilo necessárias, como…form-row-wideouform-row-first。
Segurança e limpeza de dados
- Sempre limpe e verifique o conteúdo antes de salvá-lo.
update_post_meta) e exibição (echoAntes de usar os dados dos usuários, é essencial garantir que…sanitize_text_field(),esc_html(),wp_kses_post()Funções como essas são essenciais para evitar ataques de tipo Cross-Site Scripting (XSS). - Use os tipos de dados corretos: para números ou dados em formatos específicos, considere a utilização dos tipos de dados apropriados.
sanitize_key()Ou use expressões regulares personalizadas para realizar a validação e a limpeza dos dados.
resumos
Personalizar os campos de pagamento do WooCommerce é uma funcionalidade poderosa, que facilita a troca de informações entre lojistas e clientes nos momentos críticos de uma transação. woocommerce_checkout_fields \nDefinir o campo front-end do gancho e, em seguida, utilizá-lo. woocommerce_checkout_update_order_meta Os “ganchos” (hooks) são utilizados para salvar os dados de forma segura, e em seguida, esses dados são exibidos no backend, por e-mail e no frontend dos usuários através de vários ganchos de gerenciamento e filtros de e-mail. Todo esse processo constitui um ciclo completo de processamento de dados. Ao dominar esses métodos fundamentais, e combiná-los com técnicas avançadas como a exibição condicional de informações e a validação personalizada, os desenvolvedores podem criar processos de pagamento altamente personalizados, amigáveis ao usuário e seguros em termos de proteção de dados. Isso permite atender a uma variedade de necessidades de comércio eletrônico, aumentando a profissionalidade da loja e a satisfação dos clientes.
Perguntas frequentes Perguntas frequentes
Onde os dados dos campos personalizados são salvos?
Os dados dos campos personalizados são salvos como “metadados do pedido”. Quando utilizado… update_post_meta( $order_id, ‘_field_key’, $value ); Ao salvar, os dados serão armazenados no WordPress. wp_postmeta Nos bancos de dados, as tabelas que se relacionam com os pedidos (um tipo de artigo personalizado) são… post_id Associação. O nome da chave geralmente começa com um underline (_), indicando que se trata de metadados ocultos.
Como fazer com que os campos personalizados também sejam salvos na conta do usuário durante o processo de registro?
Se você permitir a criação de uma conta durante o checkout e desejar que campos como o “Nome da empresa” também sejam salvos como informações do usuário, será necessário atualizar os metadados do usuário ao mesmo tempo que os metadados do pedido. Para isso, você pode usar update_user_meta( $customer_id, ‘billing_company’, $value );Atenção: Geralmente, é necessário obter o ID correto do usuário no contexto do registro ou login do mesmo.
Por que meus campos personalizados não estão sendo exibidos corretamente no e-mail?
Se o valor do campo não for exibido no e-mail, a causa mais comum é esquecer de incluí-lo na mensagem. woocommerce_email_order_meta_keys O filtro adiciona os nomes das suas chaves às variáveis do e-mail. Além disso, o modelo de e-mail pode não conter a parte responsável pela exibição de metadados personalizados. Certifique-se de que os nomes das suas chaves de campo foram corretamente adicionados ao array do filtro e de que o modelo de e-mail (como…) esteja configurado corretamente. email-order-details.phpSuporta a exibição de metadados gerais.
É possível adicionar blocos de campos em diferentes posições na página de pagamento?
Claro. Além dos valores padrão… billing、shipping、order Para agrupar os itens, você pode… woocommerce_checkout_fields Crie um novo grupo no filtro, por exemplo: custom_sectionEntão, use… woocommerce_checkout_after_customer_details ou woocommerce_before_order_notes Ganchos de ação, em combinação… do_action(‘woocommerce_checkout_’ . $section); Você pode renderizar os campos desse novo grupo em qualquer posição da página que desejar. Isso requer um certo conhecimento da estrutura do modelo de pagamento do WooCommerce.
O que vem a seguir, o que vem a seguir?
Leitura ampliada e conhecimento prático
Os seguintes estão relacionados ao tópico deste artigo e são adequados para uma leitura mais aprofundada. Geralmente, é melhor priorizar o artigo que está mais próximo do seu problema atual e, em seguida, expandir gradualmente para os tópicos adjacentes.
- Desenvolvimento de plugins para WordPress: Do básico ao avançado: Construa o seu primeiro plugin personalizado
- Dominando o desenvolvimento de plugins para o WordPress do zero: Criando funcionalidades exclusivas e gerando lucros de forma eficiente
- O desenvolvimento de plugins do WordPress é um processo que vai do zero ao um, para o sistema de gerenciamento de conteúdo mais popular do mundo.
- Guia de desenvolvimento do WooCommerce: construir um site de comércio eletrónico profissional do zero
- Introdução ao desenvolvimento de plugins para o WordPress do zero: Funcionalidades, padrões e melhores práticas explicados em detalhes
Português do Brasil