HUSKY - WooCommerce Product Filter Professional

Filtrar produtos do WooCommerce por campo ACF: tipos, configuração e correções

Você pode filtrar produtos do WooCommerce por valores de campos ACF com o HUSKY, mas somente quando o campo guarda seu valor de uma forma que uma consulta ao banco de dados consiga comparar. Campos de valor único (Select, Radio Button, True / False, Number, Text, Date Picker) funcionam bem. Campos Checkbox e campos Select com Selecionar múltiplos valores (Select Multiple) ativado ou nunca aparecem no filtro ou mostram opções que sempre encontram 0 produtos. A seguir, como o HUSKY lê os dados do ACF, quais tipos de campo funcionam, como configurar cada um e o que fazer com campos de múltiplos valores.

Duas formas de o HUSKY ler campos ACF

O ACF salva cada campo como um metadado comum do produto: uma linha na tabela wp_postmeta, sob o Nome do campo (Field Name), contendo o valor salvo. O HUSKY tem duas extensões nativas que filtram por essas linhas. Ambas são extensões de sistema, sempre ativas, então não há nada para ligar.

  • A extensão ACF (Campos ACF (ACF fields)) encontra seus grupos de campos do ACF automaticamente e lista os campos Select, Radio Button e True / False deles na aba Estrutura (Structure) como Rótulo do campo (Título do grupo) (Field label (Group title)). Defina a lista suspensa ao lado de um campo como Sim (Yes), salve, e o campo estará no filtro. Outros tipos de campo nem são listados. Os detalhes estão na página da extensão ACF.
  • A aba Metadados (extensão Filtro meta (Meta filter)) funciona com qualquer chave meta, do ACF ou não. Você mesmo adiciona a chave e escolhe como ela é exibida: Controle deslizante (Slider), Busca por texto (Search by text), Caixa de seleção (Checkbox), Lista suspensa (Drop-down), Lista suspensa múltipla (Multi Drop-down) ou Seletor de data (Datepicker), e que tipo de dado ela contém: número (number), texto (string) ou data (date). Veja filtrar por campos meta.

A extensão ACF é mais rápida de configurar, mas tem três regras que explicam a maioria dos relatos de "o campo não aparece" e de "0 produtos":

  1. O grupo de campos deve ser atribuído por tipo de conteúdo. O HUSKY só reconhece grupos cujas regras de Localização (Location) contenham Tipo de post é igual a Produto (Post Type is equal to Product). Um grupo exibido apenas por uma regra como categoria de produto é ignorado, e seus campos nunca chegam à aba Estrutura (Structure).
  2. O valor de cada opção deve coincidir com seu rótulo. No ACF, uma opção escrita como xl : Extra large salva xl no produto, mas a extensão ACF procura pelo rótulo, Extra large, e não encontra nada. Opções escritas com uma única palavra por linha (valor e rótulo iguais), ou que diferem apenas em maiúsculas e minúsculas, como red : Red, funcionam. Rótulos que contêm aspas nunca coincidem.
  3. Selecionar múltiplos valores deve estar desativado. Um campo Select com Selecionar múltiplos valores (Select Multiple) ativado continua sendo listado, mas não encontra produtos, pelo motivo explicado abaixo.

Se um campo quebra uma dessas regras, filtre-o pela aba Metadados (Meta Data), onde você controla a chave e os valores exatos.

Quais tipos de campo ACF podem ser filtrados

Tipo de campo ACFO que é salvo no produtoComo filtrar no HUSKY
Select (único), Radio ButtonO valor de uma opçãoExtensão ACF, ou Metadados Lista suspensa (Drop-down) / Lista suspensa múltipla (Multi Drop-down)
Button GroupO valor de uma opçãoMetadados Lista suspensa (Drop-down) / Lista suspensa múltipla (Multi Drop-down)
True / False1 ou 0Extensão ACF, ou Metadados Caixa de seleção (Checkbox)
Number, RangeUm númeroMetadados Controle deslizante (Slider), tipo número (number)
Text, Email, URLUma stringMetadados Busca por texto (Search by text), ou Lista suspensa (Drop-down) com os valores listados
Date PickerUma data como 20250131 (Ymd)Metadados Seletor de data (Datepicker) mais um hook (veja abaixo)
Checkbox, Select com Selecionar múltiplos valores (Select Multiple), Relationship / Post Object / Taxonomy com múltiplos valoresUm array serializadoNão com uma comparação normal; veja as duas saídas abaixo
Repeater, Flexible ContentLinhas numeradas como specs_0_widthNão é filtrável como um único campo

Campos dentro de um campo Group são salvos como groupname_fieldname e filtram de acordo com o próprio tipo. Um Date Time Picker salva um texto como 2025-01-31 14:00:00, que o filtro Datepicker não consegue comparar.

Por que campos checkbox e de seleção múltipla não encontram nada

Quando um campo pode conter vários valores, o ACF os empacota em uma única string no formato serializado do PHP. Um carro com ar-condicionado e bancos aquecidos recebe uma linha meta como esta:

a:2:{i:0;s:2:"ac";i:1;s:12:"heated_seats";}

A extensão ACF e as exibições Lista suspensa, Lista suspensa múltipla e Caixa de seleção pedem ao banco de dados as linhas em que o valor é igual à opção selecionada. ac não é igual a essa string inteira, então o resultado é 0. Desativar Selecionar múltiplos valores (Select Multiple) no ACF não repara os produtos existentes: os valores deles permanecem serializados até que cada produto seja salvo novamente com um único valor.

Configurar um campo ACF na aba Metadados

  1. Encontre a chave meta real. É o Nome do campo (Field Name) no ACF (por exemplo, body_type), não o rótulo. Na aba Metadados (Meta Data), Obter chaves de qualquer produto pelo ID (Get keys from any product by its ID) lista todas as chaves de um produto. Cada campo ACF aparece duas vezes: body_type guarda o valor, _body_type guarda a referência interna do campo no ACF. Use a chave sem o sublinhado. As chaves diferenciam maiúsculas de minúsculas e nunca contêm espaços ou colchetes.
  2. Adicione a chave com Adicionar chave personalizada manualmente (Add Custom key by hands) ou a partir da lista, informe um título e escolha a exibição e o tipo. Para valores de texto, escolha texto (string). Com número (number), o MySQL converte textos como Coupe em 0 antes de comparar, e o filtro retorna todos os produtos que têm a chave, o que parece "o filtro não faz nada".
  3. Liste as opções para Lista suspensa (Drop-down) e Lista suspensa múltipla (Multi Drop-down). Um campo meta é texto livre, então o HUSKY não consegue montar a lista de valores sozinho; você a escreve, separada por vírgulas. Use título^valor quando o título visível for diferente do valor salvo. Para as opções do ACF coupe : Coupe e suv : SUV / Crossover, fica assim:
    Coupe^coupe,SUV / Crossover^suv
    A parte depois de ^ deve ser exatamente o que o ACF salvou, o valor da opção, e não o rótulo.
  4. Salve, abra a aba Estrutura (Structure), defina o novo item como Sim (Yes), arraste-o para o lugar e salve de novo. O ícone de engrenagem ao lado dele contém as opções próprias da exibição, por exemplo Opção de busca (Search option) e Valor da busca (Search value) para uma Caixa de seleção, ou Condição de busca por texto (Text search conditional) (LIKE ou EXACT) para Busca por texto (Search by text).

Uma Caixa de seleção (Checkbox) é uma única caixa para uma chave. Ela encontra produtos cujo valor é 1 (campos True / False), outro Valor da busca (Search value) como yes ou, com Opção de busca (Search option) definida como O valor existe (Value exists), todos os produtos que têm o campo preenchido.

Se um valor salvo contiver uma vírgula, altere o separador de todas as listas Lista suspensa e Lista suspensa múltipla e depois reescreva as listas com |:

/*
 * HUSKY: separate meta filter options with | instead of a comma.
 * Child theme functions.php or a code snippets plugin.
 * Example list afterwards: Wood, oak|Wood, pine|Metal
 */
add_filter( 'woof_meta_options_separator', function ( $separator ) {
    return '|';
} );

Campos Number e Range pertencem a um Controle deslizante (Slider); faixas, passos e decimais são tratados em filtros de intervalo para atributos e campos meta.

Filtrar por um campo de data do ACF

O filtro Datepicker compara timestamps Unix por padrão, enquanto o Date Picker do ACF salva datas como 20250131. O hook woof_meta_use_acf_dateformat faz o filtro converter as datas escolhidas para o mesmo formato antes de pesquisar:

/*
 * HUSKY: Datepicker meta filters search ACF Date Picker values (Ymd).
 * Child theme functions.php or a code snippets plugin.
 */
add_filter( 'woof_meta_use_acf_dateformat', '__return_true' );

Adicione a chave do ACF na aba Metadados (Meta Data) com a exibição Seletor de data (Datepicker) e mantenha o tipo em número (number): as datas convertidas são comparadas como números, e o tipo data (date) não produz datas utilizáveis aqui. O hook se aplica a todos os filtros Datepicker do site, então todos eles precisam apontar para campos Date Picker do ACF. Para um período de validade (de / até), adicione os campos de início e de fim como dois filtros separados.

Campos checkbox e de seleção múltipla: duas saídas

Recomendado: mover os valores para uma taxonomia

Dados com vários valores por produto são exatamente para o que as taxonomias existem. Com uma taxonomia, você tem uma caixa de seleção para cada valor, contagens, lógica AND ou OR entre os valores selecionados e suporte ao modo Turbo, o que um campo meta não oferece. Você não precisa abrir mão do ACF para a edição:

  1. Crie uma taxonomia de produto, por exemplo Equipamentos (Equipment), como uma taxonomia personalizada ou como um atributo global em Produtos → Atributos (Products → Attributes).
  2. No ACF, substitua o campo Checkbox por um campo Taxonomia (Taxonomy) que aponte para ela, com Salvar termos (Save Terms) e Carregar termos (Load Terms) ativados. O ACF então atribui os termos escolhidos ao produto, em vez de guardar um array.
  3. Os produtos recebem seus termos quando são salvos novamente; em um catálogo grande, faça isso em massa. A taxonomia então aparece na aba Estrutura (Structure) do HUSKY como qualquer outra.

Manter o campo: pesquisar dentro do array armazenado

Se o campo precisa continuar como está, a comparação pode ser alterada. O snippet abaixo transforma a condição "é igual" do HUSKY, para as chaves listadas, em uma busca LIKE pelo valor entre aspas, de modo que ac vira LIKE '%"ac"%' e corresponde ao elemento dentro da string serializada, mas não a ac_rear. Ele também corrige as contagens das opções.

/*
 * HUSKY: Drop-down / Multi Drop-down meta filters for ACF Checkbox
 * and Select Multiple fields (values stored as serialized arrays).
 * Child theme functions.php or a code snippets plugin.
 */
function my_husky_serialized_keys() {
    return array( 'equipment' ); // ACF field names
}

function my_husky_match_serialized( $meta_query ) {
    if ( ! is_array( $meta_query ) ) {
        return $meta_query;
    }
    foreach ( $meta_query as $i => $clause ) {
        if ( ! is_array( $clause ) ) {
            continue;
        }
        if ( isset( $clause['key'], $clause['value'], $clause['compare'] )
            && '=' === $clause['compare']
            && is_scalar( $clause['value'] )
            && in_array( $clause['key'], my_husky_serialized_keys(), true ) ) {
            $meta_query[ $i ]['compare'] = 'LIKE';
            $meta_query[ $i ]['value']   = '"' . $clause['value'] . '"';
            $meta_query[ $i ]['type']    = 'CHAR';
        } else {
            $meta_query[ $i ] = my_husky_match_serialized( $clause );
        }
    }
    return $meta_query;
}

// Products found by the filter
add_filter( 'woof_get_meta_query', 'my_husky_match_serialized', 100 );

// Counts next to the options (Show count + Dynamic recount)
add_filter( 'woof_dynamic_count_attr', function ( $args ) {
    if ( isset( $args['meta_query'] ) ) {
        $args['meta_query'] = my_husky_match_serialized( $args['meta_query'] );
    }
    return $args;
}, 100 );

Depois, adicione equipment na aba Metadados (Meta Data) como Lista suspensa (Drop-down) ou Lista suspensa múltipla (Multi Drop-down), tipo texto (string), com os valores das opções do ACF depois de ^, por exemplo Air conditioning^ac,Heated seats^heated_seats. Conheça os limites: uma Lista suspensa múltipla encontra produtos que têm qualquer um dos valores selecionados, não todos eles; uma busca LIKE '%…%' não consegue usar um índice do banco de dados e fica mais lenta em catálogos grandes; e o snippet não se aplica no modo Turbo. Mais sobre o hook na página woof_get_meta_query.

Variações, modo Turbo e grades de produtos personalizadas

  • Valores nas variações não são pesquisados. A consulta da loja retorna produtos pai e verifica o meta do próprio pai. Os atributos funcionam para variações porque o pai carrega todos os termos de suas variações; valores meta, não. Coloque o valor no produto pai.
  • O modo Turbo filtra no navegador a partir de seu próprio arquivo de dados, que inclui apenas as chaves adicionadas na aba Metadados (Meta Data). Campos exibidos pela extensão ACF e hooks PHP, como os snippets acima, não são usados ali. Veja solução de problemas do modo Turbo.
  • A URL muda, mas todos os produtos continuam aparecendo. Nesse caso o problema não é o campo: a grade do construtor de páginas ou o template personalizado executa sua própria consulta e ignora todos os filtros. A solução está em a URL do filtro muda, mas os produtos não são filtrados.

Se o filtro ACF ainda não encontra produtos

  • Verifique o que realmente está salvo. No phpMyAdmin ou em uma ferramenta semelhante, execute SELECT meta_key, meta_value FROM wp_postmeta WHERE post_id = 123 com o ID de um produto (e o prefixo das suas tabelas). Um valor que começa com a: é um array serializado; uma chave diferente da esperada significa que o ACF salva sob outro nome.
  • Aba Metadados (Meta Data): a chave sem o sublinhado inicial, com as mesmas maiúsculas e minúsculas; tipo texto (string) para textos; o valor da opção salvo depois de ^.
  • Para a extensão ACF: a localização do grupo é Tipo de post é igual a Produto (Post Type is equal to Product), os valores das opções coincidem com seus rótulos, Selecionar múltiplos valores (Select Multiple) está desativado e os produtos foram salvos novamente depois da alteração.
  • O valor está no produto pai, não nas variações.
  • Um filtro de taxonomia funciona na mesma página. Se não funcionar, corrija primeiro a grade de produtos.

Se tudo estiver certo e o filtro ainda não encontrar nada, abra um tópico no fórum de suporte do HUSKY com o tipo e as configurações do campo, a chave meta e um exemplo do valor salvo, e vamos analisar.