O WordPress é extremamente flexível, mas existe uma diferença enorme entre usar o CMS apenas como uma plataforma de posts e utilizá-lo como uma base estruturada para construir sites profissionais, portais, diretórios, catálogos, áreas de membros e aplicações de conteúdo.

É justamente nesse ponto que o Advanced Custom Fields PRO, também conhecido como ACF PRO, se torna uma das ferramentas mais importantes dentro do ecossistema WordPress.

Com ACF, você deixa de depender exclusivamente do editor padrão e passa a criar estruturas de dados personalizadas.

Em vez de colocar todas as informações dentro do conteúdo de uma página, você pode separar os dados em campos específicos.

Por exemplo, imagine uma página de imóvel.

Sem ACF, o conteúdo poderia ser escrito manualmente assim:

• Área: 120 m²
• Quartos: 3
• Banheiros: 2
• Valor: R$ 850.000
• Bairro: Jardins

Isso funciona, mas o WordPress interpreta tudo como texto.

Com ACF, cada informação pode se tornar um campo separado:

area

quartos

banheiros

preco

bairro

A partir daí, esses dados podem ser usados dinamicamente em templates, filtros, buscas, integrações, APIs e consultas personalizadas.

Esse é o verdadeiro poder do ACF.

---

O que é o Advanced Custom Fields?

O WordPress trabalha naturalmente com alguns tipos de conteúdo.

Posts.

Páginas.

Categorias.

Tags.

Usuários.

Comentários.

Custom Post Types.

Porém, muitos projetos precisam armazenar informações que não se encaixam diretamente nesses formatos.

É aí que entram os custom fields.

Custom fields são pares de chave e valor associados a um objeto do WordPress.

Um exemplo simples:

preco_imovel = 850000

Outro:

cidade = São Paulo

Ou:

quartos = 3

O WordPress já possui suporte nativo a metadados.

O problema é que gerenciar isso manualmente é pouco prático.

ACF adiciona uma interface visual completa para criação e gerenciamento desses campos.

---

Por que ACF é tão utilizado por desenvolvedores?

A principal razão é simples:

separação entre conteúdo e apresentação.

Em um site bem estruturado, o usuário responsável pelo conteúdo não deveria editar HTML ou mexer em layouts.

Ele deveria apenas preencher informações.

Por exemplo:

Nome do produto:

Notebook Ultra X

Preço:

5499

Memória:

32 GB

Processador:

Intel Core Ultra

Imagem:

produto.jpg

O template do site fica responsável por decidir como essas informações aparecem.

Essa arquitetura traz várias vantagens:

• menor risco de quebrar o layout;
• conteúdo padronizado;
• manutenção mais simples;
• maior reutilização;
• facilidade de integração;
• melhor escalabilidade.

---

Conceito fundamental: Field Group

No ACF, os campos são organizados em Field Groups.

Um Field Group é um conjunto lógico de campos.

Por exemplo:

Grupo: Informações do Imóvel

Campos:

precoareaquartosbanheirosgaragemenderecocidadeestado

Outro grupo poderia ser:

Grupo: Informações do Corretor

Campos:

nometelefonewhatsappemailfoto

Cada grupo pode ter regras específicas sobre onde será exibido.

---

Location Rules: onde os campos aparecem?

Essa é uma das partes mais importantes do ACF.

Você pode definir regras para controlar onde cada Field Group será mostrado.

Por exemplo:

Post Typeé igual aImóvel

Assim, os campos aparecem apenas ao editar imóveis.

Outra possibilidade:

Pageé igual aPágina Inicial

Ou:

User Roleé igual aEditor

Também é possível usar condições mais específicas.

Essa funcionalidade permite construir painéis administrativos muito mais organizados.

---

Criando um Custom Post Type com ACF

Uma das combinações mais comuns é:

Custom Post Type + ACF

Imagine um site de imóveis.

Você poderia criar um Custom Post Type chamado:

imovel

Cada imóvel terá:

Título.

Descrição.

Imagem destacada.

Além dos campos extras.

Por exemplo:

precoareaquartosbanheirosbairrocidadelatitudelongitude

Essa estrutura transforma o WordPress em um verdadeiro sistema de gerenciamento imobiliário.

---

Tipos de campos mais importantes no ACF

O ACF oferece muitos tipos diferentes de campos.

Conhecer a finalidade de cada um evita estruturas desnecessariamente complexas.

---

Text

Usado para texto curto.

Exemplo:

modelo_do_produto

Valor:

Galaxy Pro X

Ideal para:

• títulos complementares;
• códigos;
• nomes;
• identificadores;
• textos curtos.

---

Textarea

Ideal para textos maiores.

Exemplo:

descricao_curta

Pode ser usado para:

• observações;
• descrições;
• especificações;
• textos administrativos.

---

Number

Use quando o valor realmente é numérico.

Exemplo:

preco

idade

estoque

area

Isso é melhor do que armazenar números como texto quando você pretende ordenar, filtrar ou realizar cálculos.

---

Range

Permite criar um seletor numérico dentro de um intervalo.

Exemplo:

nivel_dificuldade

Mínimo:

1

Máximo:

10

Pode ser útil para:

• avaliações;
• prioridade;
• intensidade;
• níveis.

---

Email

Campo específico para endereços de email.

Exemplo:

email_contato

O ACF pode validar o formato do conteúdo antes de salvar.

---

URL

Ideal para links estruturados.

Exemplo:

site_oficial

Armazenar URLs em um campo específico facilita validação e reutilização.

---

Image

Um dos campos mais utilizados.

Ele permite selecionar imagens da biblioteca de mídia.

Você pode configurar o retorno como:

• ID;
• Array;
• URL.

Para projetos profissionais, normalmente ID ou Array oferecem maior flexibilidade.

---

File

Semelhante ao campo Image, mas para arquivos.

Pode ser usado para:

• PDF;
• documentos;
• catálogos;
• manuais;
• arquivos de download.

---

Select

Cria um menu suspenso.

Exemplo:

status

Opções:

disponivel : Disponívelvendido : Vendidoreservado : Reservado

Essa estrutura é muito útil porque separa o valor interno do texto exibido.

---

Checkbox

Permite selecionar várias opções.

Exemplo:

comodidades

Opções:

piscinaacademiaelevadorseguranca

Um imóvel pode ter várias dessas características simultaneamente.

---

Radio Button

Ideal quando o usuário deve escolher apenas uma opção.

Exemplo:

tipo_imovel

Opções:

CasaApartamentoCoberturaTerreno

---

True / False

Campo extremamente útil para decisões simples.

Exemplo:

destaque

Valores:

truefalse

Você pode usar isso para determinar se algo será exibido na página inicial.

---

Date Picker

Permite selecionar datas.

Exemplo:

data_evento

Muito utilizado em:

• eventos;
• reservas;
• vencimentos;
• promoções.

---

Date Time Picker

Armazena data e horário.

Exemplo:

inicio_evento

Isso permite criar sistemas mais complexos de agenda.

---

Color Picker

Permite escolher uma cor.

Pode ser útil em sistemas de personalização.

Exemplo:

cor_tema

---

Google Map / campos geográficos

Em projetos que trabalham com localização, campos geográficos podem armazenar informações como:

• endereço;
• latitude;
• longitude.

Esses valores depois podem ser utilizados em mapas ou sistemas de busca geográfica.

---

Relationship Field

Esse é um dos campos mais poderosos do ACF PRO.

Ele permite relacionar conteúdos entre si.

Imagine dois tipos de conteúdo:

filme

e

ator

Dentro de um filme, você pode criar um Relationship Field chamado:

elenco

E selecionar vários atores.

Depois, no template, você pode listar automaticamente os atores relacionados ao filme.

Isso transforma o WordPress em uma estrutura relacional muito mais avançada.

---

Post Object

É semelhante ao Relationship Field, mas normalmente usado quando a relação é mais simples.

Por exemplo:

produto_relacionado

Você pode selecionar um único post ou vários posts específicos.

---

User Field

Permite relacionar um conteúdo com usuários do WordPress.

Exemplo:

responsavel

Isso pode ser usado em:

• diretórios;
• sistemas internos;
• marketplaces;
• projetos editoriais.

---

Taxonomy Field

Permite selecionar termos de taxonomias.

Exemplo:

categoria_especial

É útil quando a estrutura do projeto mistura taxonomias e campos personalizados.

---

Repeater Field

O Repeater Field é uma das funcionalidades mais importantes do ACF PRO.

Ele permite criar grupos repetíveis de campos.

Imagine uma página de restaurante.

Você precisa cadastrar horários de funcionamento.

Em vez de criar:

segunda_aberturasegunda_fechamentoterca_aberturaterca_fechamentoquarta_aberturaquarta_fechamento

Você pode criar um repeater chamado:

horarios

E dentro dele:

diaaberturafechamento

O usuário pode adicionar quantas linhas quiser.

---

Exemplo de estrutura Repeater

horarios

Linha 1:

dia = Segundaabertura = 09:00fechamento = 18:00

Linha 2:

dia = Terçaabertura = 09:00fechamento = 18:00

Linha 3:

dia = Quartaabertura = 09:00fechamento = 17:00

Isso é muito mais escalável.

---

Como exibir um Repeater no template

Exemplo:

<?php if ( have_rows('horarios') ) : ?> <ul> <?php while ( have_rows('horarios') ) : the_row(); ?> <li> <?php the_sub_field('dia'); ?> - <?php the_sub_field('abertura'); ?> até <?php the_sub_field('fechamento'); ?> </li> <?php endwhile; ?> </ul><?php endif; ?>

O ponto importante é perceber que campos dentro do Repeater são chamados de sub fields.

Por isso usamos:

the_sub_field()

e não:

the_field()

---

Flexible Content Field

O Flexible Content é ainda mais poderoso.

Ele permite criar sistemas modulares de layout.

Imagine que você deseja criar um editor personalizado no qual o usuário pode adicionar diferentes blocos.

Por exemplo:

HeroTextoImagemGaleriaFAQCTADepoimentosVídeo

O usuário escolhe quais blocos deseja inserir e em qual ordem.

Isso é praticamente um page builder baseado em dados estruturados.

---

Exemplo de Flexible Content

Campo:

conteudo_pagina

Layouts:

herotextogaleriacta

No template:

<?php if ( have_rows('conteudo_pagina') ) : ?> <?php while ( have_rows('conteudo_pagina') ) : the_row(); ?> <?php if ( get_row_layout() === 'hero' ) : ?> <section class="hero"> <h1> <?php the_sub_field('titulo'); ?> </h1> <p> <?php the_sub_field('descricao'); ?> </p> </section> <?php elseif ( get_row_layout() === 'texto' ) : ?> <section class="texto"> <?php the_sub_field('conteudo'); ?> </section> <?php endif; ?> <?php endwhile; ?><?php endif; ?>

Essa abordagem pode substituir page builders em projetos personalizados.

---

Clone Field

O Clone Field permite reutilizar conjuntos de campos.

Imagine que vários tipos de conteúdo precisam das mesmas informações de contato.

Em vez de recriar:

telefoneemailwhatsappendereco

em vários grupos, você pode criar um Field Group reutilizável e cloná-lo.

Isso reduz duplicação e facilita manutenção.

---

Options Pages

Outra funcionalidade muito importante do ACF PRO são as Options Pages.

Nem toda informação pertence a um post específico.

Por exemplo:

• telefone da empresa;
• email;
• endereço;
• redes sociais;
• logotipo secundário;
• texto do rodapé.

Esses dados são globais.

Em vez de armazená-los em uma página qualquer, você pode criar uma página de opções no painel administrativo.

Exemplo:

Configurações do Site

Campos:

telefoneemailwhatsappinstagramfacebookendereco

Depois eles podem ser usados em qualquer template.

---

Recuperando valores de Options Page

Exemplo:

$telefone = get_field('telefone', 'option');

Ou:

the_field('telefone', 'option');

O segundo argumento:

option

indica que o valor não está associado ao post atual.

---

get_field() vs the_field()

Essa diferença é simples, mas muito importante.

the_field() imprime o valor diretamente.

Exemplo:

<?php the_field('preco'); ?>

Já get_field() retorna o valor.

Exemplo:

<?php$preco = get_field('preco');?>

Agora você pode processar a variável antes de exibir.

Por exemplo:

<?php$preco = get_field('preco');if ($preco) { echo 'R$ ' . number_format( $preco, 2, ',', '.' );}?>

Em projetos profissionais, get_field() costuma oferecer maior controle.

---

Sempre valide antes de exibir

Um erro comum é assumir que todos os campos estão preenchidos.

Evite:

<h2> <?php the_field('subtitulo'); ?></h2>

Prefira:

<?php$subtitulo = get_field('subtitulo');if ($subtitulo) :?> <h2> <?php echo esc_html($subtitulo); ?> </h2><?php endif; ?>

Assim você evita HTML vazio e melhora a segurança.

---

Sanitização e escaping

ACF facilita o gerenciamento de dados, mas não elimina a necessidade de boas práticas de segurança.

Ao exibir texto simples:

echo esc_html($valor);

Para URLs:

echo esc_url($url);

Para atributos HTML:

echo esc_attr($valor);

Para conteúdo HTML permitido:

echo wp_kses_post($conteudo);

Nunca confie automaticamente em dados apenas porque vieram do painel administrativo.

---

Estrutura correta para imagens

Se o campo de imagem retorna um array:

$imagem = get_field('imagem');

Você pode trabalhar com:

$imagem['url']$imagem['alt']$imagem['width']$imagem['height']

Mas em muitos casos é melhor trabalhar com o ID da imagem.

Exemplo:

$imagem_id = get_field('imagem');

Depois:

echo wp_get_attachment_image( $imagem_id, 'large');

Isso permite que o WordPress gere corretamente atributos responsivos como srcset.

---

Trabalhando com Query e Meta Query

Uma das maiores vantagens de armazenar dados estruturados é poder consultar esses valores.

Imagine imóveis com:

precocidadequartos

Você pode buscar apenas imóveis de São Paulo.

$args = [ 'post_type' => 'imovel', 'meta_query' => [ [ 'key' => 'cidade', 'value' => 'São Paulo', 'compare' => '=' ] ]];$query = new WP_Query($args);

---

Consulta numérica

Suponha que você queira imóveis abaixo de R$ 1.000.000.

$args = [ 'post_type' => 'imovel', 'meta_query' => [ [ 'key' => 'preco', 'value' => 1000000, 'type' => 'NUMERIC', 'compare' => '<=' ] ]];

O parâmetro:

type = NUMERIC

é extremamente importante.

Sem ele, o WordPress pode tratar os dados como texto.

---

Ordenando posts por campo ACF

Imagine que você deseja ordenar imóveis pelo preço.

$args = [ 'post_type' => 'imovel', 'meta_key' => 'preco', 'orderby' => 'meta_value_num', 'order' => 'ASC'];

Isso mostra primeiro os imóveis mais baratos.

---

Estrutura recomendada para sites imobiliários

Um projeto real poderia utilizar:

Custom Post Type:

imovel

Taxonomias:

tipocidadebairro

Campos ACF:

precoareaquartosbanheirosgaragenscondominioiptuenderecolatitudelongitudegaleriavideodestaque

Essa separação é importante.

Dados usados frequentemente para filtros podem funcionar melhor como taxonomias.

Dados específicos do item normalmente funcionam melhor como campos.

---

Não transforme tudo em ACF

Esse é um erro comum.

Só porque ACF permite criar campos personalizados não significa que tudo deveria ser um custom field.

Por exemplo:

Categoria de imóvel:

ApartamentoCasaTerreno

Pode ser melhor como taxonomia.

Por quê?

Porque taxonomias possuem estrutura nativa de arquivo, URLs e consultas.

Já algo como:

metragem

faz mais sentido como campo.

A arquitetura deve ser planejada antes da implementação.

---

ACF Blocks

Outro uso avançado do ACF é criar blocos personalizados para Gutenberg.

Você pode desenvolver blocos estruturados usando PHP e campos ACF.

Imagine um bloco:

Depoimento

Campos:

nomecargofototexto

O editor visualiza uma interface organizada.

O desenvolvedor controla completamente o HTML final.

Isso oferece uma alternativa muito interessante a blocos completamente construídos com JavaScript.

---

ACF e REST API

Campos personalizados podem ser usados em arquiteturas headless.

Por exemplo:

WordPress pode funcionar apenas como backend.

O frontend pode ser:

• React;
• Next.js;
• Vue;
• Nuxt;
• aplicativo mobile.

Nesse cenário, os dados ACF podem ser expostos via REST API.

Estrutura hipotética:

{ "title": "Apartamento Jardins", "acf": { "preco": 850000, "quartos": 3, "banheiros": 2 }}

Isso transforma o WordPress em um CMS estruturado para aplicações modernas.

---

ACF Local JSON

Para projetos profissionais, esse recurso é extremamente importante.

ACF pode salvar configurações dos Field Groups em arquivos JSON.

Normalmente:

acf-json

dentro do tema.

Isso oferece várias vantagens:

• versionamento com Git;
• sincronização entre ambientes;
• desenvolvimento em equipe;
• histórico de alterações;
• deploy mais previsível.

---

Estrutura típica

theme/│├── acf-json/│ ├── group_abc123.json│ ├── group_xyz456.json│├── functions.php├── single-imovel.php└── style.css

Quando um Field Group é alterado, o JSON pode ser atualizado automaticamente.

---

Por que Local JSON é importante?

Imagine três ambientes:

LocalStagingProduction

Sem versionamento, você pode alterar campos manualmente em cada ambiente.

Isso cria risco de inconsistência.

Com JSON, a estrutura pode acompanhar o código do projeto.

Esse é um fluxo muito mais profissional.

---

ACF e performance

ACF é poderoso, mas estruturas mal planejadas podem gerar consultas pesadas.

Um dos principais problemas acontece quando você usa grandes volumes de postmeta.

Imagine:

100.000 produtos.

Cada produto possui 40 campos.

Isso pode gerar milhões de registros na tabela:

wp_postmeta

Nesse nível de escala, consultas complexas usando meta_query podem se tornar lentas.

---

Evite Meta Query excessiva

Uma consulta com várias condições:

precocidadequartosbanheirosareatipo

pode exigir bastante do banco de dados.

Para sites muito grandes, é importante avaliar:

• taxonomias;
• índices personalizados;
• tabelas customizadas;
• mecanismos de busca externos.

ACF resolve muito bem a camada de gerenciamento de dados, mas não substitui planejamento de banco de dados.

---

Repeater também exige cuidado

Repeater é excelente, mas não deveria ser usado como banco de dados dentro de um post.

Evite armazenar milhares de linhas dentro de um Repeater.

Por exemplo:

10.000 registros de pedidos

dentro de um único post seria uma arquitetura ruim.

Repeater é melhor para estruturas relativamente pequenas.

Exemplos adequados:

• equipe;
• FAQ;
• horários;
• slides;
• características;
• etapas.