Filtro de intervalo (slider) do WooCommerce para atributos e campos meta

Tamanho, potência, comprimento, diagonal da tela, ano, quilometragem: dados numéricos de produtos pedem um filtro de intervalo (slider) em vez de uma longa lista de caixas de seleção. Um filtro de intervalo do WooCommerce para atributos é fácil de ativar no HUSKY, e é igualmente fácil acabar com um slider que mostra 100000 antes de 9000, divide 1,9 em dois valores ou sempre vai de 0 a 100. O motivo é quase sempre o mesmo: existem dois sliders diferentes, e eles tratam os números de maneira diferente. Este guia explica os dois, a configuração de cada um e as correções para ordem errada, decimais e intervalos vazios.

Dois sliders de intervalo: valores de atributo ou um campo meta numérico

O HUSKY pode desenhar um slider de intervalo a partir de dois tipos de dados, e a escolha determina o que o slider consegue fazer.

A diferença essencial: os termos de atributo são texto. O WordPress guarda 9000 e 100000 como nomes, não como números, então o slider de atributo só consegue percorrer uma lista de termos em uma determinada ordem. Ele nunca calcula. O slider de campo meta compara números no banco de dados, por isso lida com qualquer valor dentro de um intervalo, inclusive valores que nenhum outro produto tem.

Atributos personalizados digitados diretamente na aba Atributos de um produto, sem um atributo global por trás, não são taxonomias, e nenhum tipo de filtro consegue usá-los. Primeiro crie um atributo global em Produtos → Atributos (Products → Attributes); veja gerenciar taxonomias de produtos na documentação do WooCommerce.

Configurar um filtro de intervalo (slider) para atributos

1. Crie o atributo global, por exemplo Potência (Power), e adicione seus valores como termos: 5, 7.5, 10, 15. Atribua-os aos produtos como de costume.
2. Abra WooCommerce → Configurações → Products Filter → Estrutura (WooCommerce → Settings → Products Filter → Structure) e defina o tipo desse atributo como Controle deslizante (Slider). A extensão Slider adiciona esse tipo.
3. Clique no botão opções adicionais (additional options) (engrenagem) ao lado do atributo e defina as opções do slider:
   • Tipo (Type): double para um intervalo de/até; single para um único marcador que seleciona tudo, do primeiro valor até o marcador ("até 10 kW").
   • Passo da grade (Grid step): quais rótulos sob o slider ficam visíveis. 1 mostra todos, 2 um a cada dois, -1 oculta os rótulos entre as extremidades. Útil quando valores longos se sobrepõem.
   • Ativar recontagem dinâmica (Enable dynamic recount): remove os valores sem produtos nos resultados atuais (veja abaixo).
   • Skin do slider (Slider skin): o design deste slider.
4. Mantenha Lógica de filtragem (Logic of filtering) em OR. O slider envia todos os termos do trecho escolhido, por exemplo pa_power=5,7-5,10, e um produto precisa de apenas um deles. Com AND, o produto precisaria de todos, e nada seria encontrado.

Como um intervalo significa "os termos entre os marcadores", a ordem dos termos é toda a lógica do slider. Se 6.5 estiver depois de 8.2 na lista, um intervalo de 6 a 7 o ignora. A próxima seção corrige a ordem.

Valores do slider de atributo na ordem errada

Sintomas típicos: 100000 vem antes de 9000, 10 e 11 vêm antes de 2, valores negativos aparecem como -1, -2, -3, 0, 1, ou os marcadores pulam para frente e para trás ao arrastar. Tudo isso é ordenação de texto. A solução é dar aos termos uma ordem numérica.

O ideal: deixar o WooCommerce ordenar o atributo numericamente

Vá em Produtos → Atributos (Products → Attributes), edite o atributo e defina Ordem de classificação padrão (Default sort order) como Nome (numérico) (Name (numeric)). O WooCommerce passa a ordenar os termos pelo valor numérico de seus nomes, o que trata decimais escritos com ponto, números negativos e nomes que começam com um número, como 10 cm. Nas opções adicionais do slider, deixe Ordenar termos (Sort terms) em Padrão (Default) para que o HUSKY mantenha essa ordem. Se Cache de termos (Cache terms) estiver ativado (Avançado → Opções (Advanced → Options)), clique depois em limpar cache de termos (clear terms cache).

Para uma escala de texto, escolha Ordenação personalizada (Custom ordering) e arraste os termos para o lugar na tela Configurar termos (Configure terms) do atributo: Macio, Médio, Médio-duro, Duro. O mesmo arrastar e soltar funciona para qualquer lista numérica cuja ordem você queira controlar manualmente.

As opções próprias do HUSKY para ordenar termos

A opção Ordenar termos (Sort terms) nas opções adicionais do slider substitui a ordem padrão:

• Título (Title) usa a ordenação natural dos nomes: correta para números inteiros positivos (2 antes de 10) e para nomes como 10 cm, mas não para decimais ou números negativos.
• Numérico (Numeric.) compara o valor inteiro do slug do termo. Funciona apenas para números inteiros positivos: o slug de 6.5 é 6-5, que conta como 6, e o WordPress remove o sinal de menos inicial ao criar um slug, então -3 é ordenado como 3.

Código: ordem numérica para qualquer slider de taxonomia

Para uma taxonomia personalizada, em que o Nome (numérico) (Name (numeric)) do WooCommerce não está disponível, ordene os valores do slider por código. O filtro woof_sort_terms_before_out recebe os termos de cada filtro e o tipo do filtro:

/**
 * HUSKY: order the values of every taxonomy range slider by their number
 * (decimals with a dot and negative numbers included).
 * Child theme functions.php or a code snippets plugin.
 */
add_filter( 'woof_sort_terms_before_out', function ( $terms, $type ) {
    if ( 'slider' === $type && is_array( $terms ) ) {
        uasort( $terms, function ( $a, $b ) {
            return (float) $a['name'] <=> (float) $b['name'];
        } );
    }
    return $terms;
}, 20, 2 );

Termos sem um número no início (uma escala de texto) contam todos como 0 aqui e mantêm a ordem existente, de modo que o snippet não atrapalha esses sliders.

Decimais, vírgulas e passos irregulares em sliders de atributo

• Escreva os decimais com ponto. O slider recebe seus rótulos como uma única lista separada por vírgulas, então um termo chamado 1,9 vira dois rótulos, 1 e 9, e todas as posições seguintes apontam para o termo errado. Renomeie esses termos para 1.9. Isso não tem relação com a configuração de separador decimal da loja: os nomes dos termos são texto simples.
• As posições têm espaçamento uniforme por termo, não por valor. Os termos 1, 2, 5 e 50 recebem quatro passos iguais. Se o slider deve parecer proporcional, adicione como termos os valores intermediários que faltam.
• Um slider precisa de pelo menos dois valores. Com apenas dois termos, os marcadores só podem ficar nas duas extremidades. Com menos de dois valores restantes após a recontagem dinâmica, o slider nem é exibido.
• Só é possível escolher termos existentes. Um produto com o valor 6.5 só é encontrado se o termo 6.5 existir e estiver entre os marcadores.

Slider de intervalo para campos meta: dimensões, anos e outros números

Quando o valor é uma medida real, um slider de campo meta geralmente é a melhor ferramenta: ele compara números, aceita campos de/até e continua rápido com milhares de valores diferentes. Configuração com a extensão Meta Fields:

1. Abra a aba Metadados (Meta Data) das configurações do filtro. Informe a chave em Adicionar chave personalizada manualmente (Add Custom key by hands) ou use Obter chaves de qualquer produto pelo ID (Get keys from any product by its ID) para ver quais chaves um produto tem.
2. Defina o tipo do campo como número (number) e sua exibição como Controle deslizante (Slider). O slider não é oferecido para campos de texto ou de data. Salve.
3. Abra as opções adicionais do campo e preencha Faixa (Range) como min^max, por exemplo 10^250. Defina o Passo (Step) (0.5 funciona) e, se necessário, Prefixo (Prefix), Sufixo (Postfix) (cm), Mostrar campos (Show inputs) para caixas numéricas de/até e Usar prettify (Use prettify) para um separador de milhares.
4. Posicione o novo item de filtro na aba Estrutura (Structure) como qualquer outro.

Chaves úteis: o WooCommerce guarda as dimensões de envio e o peso de um produto como _length, _width, _height e _weight. Um campo numérico do ACF é guardado sob o nome do campo. Os detalhes sobre chaves meta estão na documentação de metadados.

O que saber sobre sliders de meta:

• O intervalo nunca é calculado. O slider mostra exatamente a Faixa (Range) que você informou; um campo vazio recorre a 0–100. Descobrir o mínimo e o máximo reais exigiria ler todos os produtos a cada visualização de página. A recontagem dinâmica decide quais filtros e valores são exibidos, não onde um slider começa e termina. Atualize a faixa quando novos produtos passarem dos limites.
• Guarde números simples com ponto como separador decimal e sem separador de milhares: 1250.5. O banco de dados lê apenas o número no início do valor, então 1,250.5 é comparado como 1 e 1250,5 como 1250.
• Anos: faixa como 1990^2026, passo 1 e Usar prettify (Use prettify) definido como Não (No); caso contrário, 2026 é exibido como 2 026.
• Variações: o meta do próprio produto é pesquisado. Se o valor existir apenas nas variações, salve-o também no produto pai ou use um atributo.

Valores decimais: woof_slider_meta_query_type

Por padrão, o slider de meta compara os valores como NUMERIC, que o MySQL trata como números inteiros. Um produto com 10.11 é então encontrado no intervalo 1–10, e 4.2, 4.4 e 4.6 contam todos como 4. Para comparar decimais, altere o tipo com o filtro woof_slider_meta_query_type:

/**
 * HUSKY: compare these meta sliders as decimal numbers.
 * Child theme functions.php or a code snippets plugin.
 */
add_filter( 'woof_slider_meta_query_type', function ( $type, $meta_key ) {
    if ( in_array( $meta_key, array( '_length', '_width', '_height', 'screen_size' ), true ) ) {
        return 'DECIMAL(10,2)'; // up to 99999999.99
    }
    return $type;
}, 10, 2 );

Em DECIMAL(M,D), M é o número total de dígitos e D os dígitos após o ponto. Escolha-os de acordo com o seu maior valor: com DECIMAL(5,3) o máximo é 99.999, e todo valor maior é tratado como 99.999.

Ocultar sliders que não se aplicam à categoria atual

• Slider de atributo: defina Ativar recontagem dinâmica (Enable dynamic recount) como Sim (Yes) nas opções adicionais dele. Os valores sem produtos na categoria atual e na seleção de filtros desaparecem e, com menos de dois valores restantes, o slider é removido. Cada valor custa uma consulta de contagem extra; portanto, em atributos com centenas de termos, observe a velocidade da página ou use um slider de meta.
• Slider de meta: com Ocultar termos vazios (Hide empty terms) definido como Sim (Yes) na aba Opções, um slider de meta que não tem produtos dentro de sua faixa nos resultados atuais não é exibido.

Um slider de atributo sem valores é removido pelo script do plugin depois que a página carrega, então seu título pode piscar por um instante. Este CSS o oculta desde o início (Aparência → Personalizar → CSS adicional (Appearance → Customize → Additional CSS), ou a folha de estilos do seu tema filho):

/* HUSKY: hide empty taxonomy sliders before the script removes them */
.woof_container_slider:has(.woof_hide_slider) {
    display: none;
}

Quando o próprio produto tem um intervalo

Um slider encontra produtos por um único valor por produto. Se um produto cobre um intervalo (adequado para alturas de 150 a 190 cm, 3 a 10 jogadores), não existe uma busca nativa de "sobreposição de intervalos". Dois modelos viáveis:

• Dois campos meta, por exemplo players_min e players_max, cada um com seu próprio slider. Um visitante que procura um jogo para 4 jogadores define o primeiro slider como 1–4 e o segundo como 4–10.
• Um atributo com um termo por valor (150, 151 ... 190), com todos os termos adequados atribuídos ao produto, e o atributo exibido como slider. Atribua os termos em massa, em vez de manualmente.

Lista de verificação

• Slider de atributo: atributo global, decimais escritos com ponto, Ordem de classificação padrão (Default sort order) definida como Nome (numérico) (Name (numeric)) ou termos arrastados para a ordem certa, Lógica de filtragem (Logic of filtering) em OR.
• Slider de meta: tipo de campo número (number), valores numéricos simples, Faixa (Range) preenchida como min^max, um tipo decimal para valores fracionários.
• Muitos valores distintos ou medidas reais: um slider de meta em vez de um atributo com centenas de termos.
• Sliders nas categorias erradas: Ativar recontagem dinâmica (Enable dynamic recount) para sliders de atributo, Ocultar termos vazios (Hide empty terms) para sliders de meta.

Se um slider ainda mostrar valores errados depois destes passos, pergunte no fórum de suporte do HUSKY com o atributo ou a chave meta, alguns valores de exemplo e um link para a página.