Campos Personalizados no WordPress: Custom Fields, Metaboxes e ACF

Os campos personalizados são um dos recursos mais versáteis do WordPress, permitindo enriquecer qualquer tipo de conteúdo com metadados além dos campos padrão de título e editor. Com eles, você pode adicionar informações como preço de um produto, depoimentos, galerias, datas de eventos, avaliações e praticamente qualquer dado estruturado que seu projeto exigir. Este guia completo cobre desde o uso dos custom fields nativos, passando pela criação de metaboxes manuais, até o poderoso plugin Advanced Custom Fields (ACF) – a ferramenta mais adotada por desenvolvedores para gerenciar campos personalizados no ecossistema WordPress.

O que são Custom Fields no WordPress?

Todo post, página ou conteúdo personalizado no WordPress possui uma tabela no banco de dados chamada wp_postmeta. Essa tabela armazena pares chave-valor associados ao post – são os custom fields nativos. Por padrão, o WordPress exibe uma interface simples de custom fields na tela de edição (ativável pelo menu "Opções de Tela"), onde é possível adicionar chaves e valores manualmente.

Para recuperar um valor no template, utiliza-se a função get_post_meta():

<?php $preco = get_post_meta( get_the_ID(), 'preco', true ); ?>
<p>Preço: R$ <?php echo esc_html( $preco ); ?></p>

O terceiro parâmetro true retorna um único valor (string); se omitido ou false, retorna um array com todos os valores daquela chave. Custom fields nativos são funcionais, mas a interface é rudimentar e não oferece validação, máscaras ou campos visuais como seletores de data ou upload de imagem.

Criando Metaboxes personalizadas manualmente

Para oferecer uma experiência de edição mais amigável, você pode criar metaboxes usando o hook add_meta_box() dentro de uma função registrada em add_action( 'add_meta_boxes', 'sua_funcao' ). Cada metabox é renderizada com HTML próprio e os dados são salvos no hook save_post.

function meu_campo_meta_box() {
    add_meta_box(
        'meu_campo',
        'Preço do Produto',
        'meu_campo_html',
        'post',
        'normal',
        'high'
    );
}
add_action( 'add_meta_boxes', 'meu_campo_meta_box' );

function meu_campo_html( $post ) {
    $valor = get_post_meta( $post->ID, 'preco', true );
    echo '<label for="preco">Preço:</label> ';
    echo '<input type="text" id="preco" name="preco" value="' . esc_attr( $valor ) . '" />';
}

function salvar_meu_campo( $post_id ) {
    if ( isset( $_POST['preco'] ) ) {
        update_post_meta( $post_id, 'preco', sanitize_text_field( $_POST['preco'] ) );
    }
}
add_action( 'save_post', 'salvar_meu_campo' );

Embora funcional, esse método exige repetição de código para cada campo, tratamento de segurança, sanitização e validação. Em projetos com muitos campos, o trabalho se torna excessivo e propenso a erros. É nesse cenário que o ACF se destaca.

Advanced Custom Fields (ACF): produtividade e flexibilidade

O Advanced Custom Fields (ACF) é um plugin que permite criar grupos de campos personalizados por meio de uma interface visual dentro do admin do WordPress. Você define os campos, seus tipos, regras de exibição (em que tipos de post, páginas, categorias ou até mesmo em opções do tema) e exporta as configurações como PHP ou JSON para versionamento.

Principais vantagens do ACF em relação aos métodos manuais:

• Interface drag-and-drop para criar e organizar campos
• Mais de 30 tipos de campo nativos (texto, imagem, galeria, repetidor, flexível, relacionamento, etc.)
• Condições de exibição lógicas (mostrar grupo apenas em posts de uma categoria específica, por exemplo)
• Funções simples como get_field() e the_field() para exibir os valores
• Suporte a blocos Gutenberg, widgets e páginas de opções
• Integração completa com tipos de post personalizados e temas personalizados

Para instalar, basta baixar o plugin do repositório oficial ou incluí-lo via Composer. A versão gratuita já atende a maioria dos casos; a versão PRO adiciona campos como repetidor, flexível, galeria e a página de opções.

Principais tipos de campo do ACF

O ACF oferece dezenas de tipos de campo. Abaixo os mais utilizados no dia a dia do desenvolvimento WordPress:

• Texto / Textarea / WYSIWYG – campos de texto livre, recomendados para descrições, biografias, conteúdo formatado.
• Imagem / Galeria – upload de uma ou várias imagens com retorno de ID, URL ou objeto completo.
• Repetidor (Repeater) – permite criar listas repetíveis de subcampos, como slides de um carrossel ou membros da equipe.
• Campo Flexível (Flexible Content) – construtor de layouts dinâmicos onde o editor escolhe entre blocos pré-definidos (heróis, chamadas, depoimentos, etc.).
• Relacionamento (Relationship / Post Object) – vincula posts entre si, útil para selecionar posts relacionados, produtos ou depoimentos.
• Escolha (Select / Radio / Checkbox) – opções pré-definidas, ideal para categorias de produtos ou status.
• Data / Cor / Arquivo / Google Maps – campos especializados com interfaces otimizadas.

Cada tipo possui configurações específicas de formatação, valor padrão, instruções e validação. A documentação oficial do ACF detalha cada um com exemplos.

Exibindo valores de campos ACF no template

A função get_field( 'nome_do_campo' ) retorna o valor do campo, podendo ser uma string, array, objeto ou número dependendo do tipo. Já the_field( 'nome_do_campo' ) exibe o valor diretamente.

<?php 
// Exibir um campo de texto
$preco = get_field( 'preco' );
if ( $preco ) {
    echo '<p class="preco">R$ ' . esc_html( $preco ) . '</p>';
}
?>

Para campos repetidores, use o loop have_rows() e the_row():

<?php if ( have_rows( 'equipe' ) ) : ?>
    <ul class="equipe">
    <?php while ( have_rows( 'equipe' ) ) : the_row(); 
        $nome = get_sub_field( 'nome' );
        $foto = get_sub_field( 'foto' );
    ?>
        <li>
            <img src="<?php echo esc_url( $foto['url'] ); ?>" alt="<?php echo esc_attr( $nome ); ?>" />
            <h3><?php echo esc_html( $nome ); ?></h3>
        </li>
    <?php endwhile; ?>
    </ul>
<?php endif; ?>

Já o campo flexível permite criar páginas modulares com blocos escolhidos pelo editor. Basta percorrer as linhas com have_rows('conteudo_flexivel') e usar get_row_layout() para identificar cada layout.

Se você estiver utilizando ACF em conjunto com temas personalizados, poderá criar estruturas modulares completas sem perder desempenho. ACF também se integra perfeitamente com tipos de post personalizados, permitindo que cada post type tenha seu próprio conjunto de campos na tela de edição.

Boas práticas ao trabalhar com campos personalizados

Para manter projetos organizados e com boa performance, siga estas recomendações:

• Prefixo nas chaves: utilize um prefixo único (meuprojeto_preco) para evitar conflitos com outros plugins ou temas.
• Evite excesso de campos: centenas de campos por post podem impactar consultas ao banco. ACF tem boa performance, mas planeje com moderação.
• Exporte as configurações: commite os arquivos JSON ou PHP gerados pelo ACF para manter o versionamento e facilitar deploys.
• Use transients ou cache: se campos são usados em consultas pesadas, considere cachear os valores.
• Documente os campos: utilize o campo "Instruções" do ACF para orientar editores e mantenha uma planilha com a descrição de cada chave.
• Prefira ACF para projetos complexos: se o número de campos for superior a 5 e houver necessidade de interface amigável, ACF economiza horas de desenvolvimento.

Continue aprofundando seus conhecimentos no desenvolvimento WordPress com nossos guias completos sobre o ecossistema.

Perguntas Frequentes (FAQ)

Qual a diferença entre Custom Fields nativos e ACF?

Custom fields nativos são pares chave-valor simples sem interface amigável para o usuário. ACF oferece interface visual, validação, dezenas de tipos de campo e exportação de configurações, agilizando o desenvolvimento.

Preciso instalar o plugin ACF para usar campos personalizados?

Não, você pode usar as funções nativas get_post_meta() e add_meta_box() para criar campos manuais. O ACF é uma ferramenta que simplifica e acelera o processo em projetos mais complexos.

O ACF pode ser usado em temas personalizados?

Sim, o ACF é muito utilizado em temas personalizados para adicionar opções modulares e flexíveis sem escrever HTML repetitivo para cada campo.

Como exibir um campo ACF no PHP?

Use get_field('nome_do_campo') para retornar o valor e the_field() para exibi-lo diretamente. Para campos repetidores, utilize have_rows() e the_row().

ACF deixa o site lento?

O ACF é bem otimizado. O impacto na performance é mínimo quando usado com moderação. Evite campos repetidores com centenas de linhas sem paginação e utilize cache quando necessário.

Preciso comprar a versão PRO do ACF?

A versão gratuita já cobre campos essenciais como texto, imagem, seletor de posts, data, etc. A PRO adiciona repetidor, campo flexível, galeria e página de opções, recomendados para projetos institucionais e e-commerce.