Como exibir valores de campos personalizados no WordPress (guia 2026)

Campos Personalizados (Custom Fields), técnicamente conhecidos como Post Meta, são a funcionalidade que transforma o WordPress dé uma plataforma simples de blog num poderoso Sistema de Gestão de Conteúdos (CMS). Permitem atribuir qualquer informação extra a um post, como “Classificação do Filme”, “Preço do Produto”, “Data do Evento” ou “ID do Vídeo Relacionado”.

Neste guia completo para programadores (Edição 2026), não vamos apenas aprender a exibir campos. Vamos entender a arquitetura da Metadata API, aprender a escrever consultas eficientes e descobrir quando não usar campos personalizados.

#1. Metadata API: Fundamentos (crud)

O WordPress oferecé um conjunto de funções para gerir metadados, conhecido como CRUD (Create, Read, Update, Delete).

#Obter dados: Get_post_meta()

Está é a função mais usada.

// Sintaxe
$valor = get_post_meta( $post_id, $chave, $single );

• $post_id: ID do Post (use get_the_ID() dentro do loop).
• $chave: O nome do campo na base de dados (ex: ‘preco_produto’).
• $single:
  • true: Retorna um valor único (string/int).
  • false (padrão): Retorna um array de valores. Está é uma armadilha comum!

Exemplo:

$preco = get_post_meta( get_the_ID(), 'preco_produto', true );
if ( $preco ) {
    echo 'Preço: ' . esc_html( $preco ) . ' €';
}

#Guardar é atualizar: Update_post_meta()

Está função é inteligente: sé o campo não existir, cria-o. Se existir, atualiza-o.

update_post_meta( $post_id, 'preco_produto', '99.00' );

Se guardar um array, o WordPress irá serializá-lo automáticamente:

$dados = ['cor' => 'vermelho', 'tamanho' => 'XL'];
update_post_meta( $post_id, 'variantes', $dados );
// Guardado na BD como: a:2:{s:3:"cor";s:8:"vermelho"...}

#Apagar: Delete_post_meta()

delete_post_meta( $post_id, 'preco_produto' );

#2. Armadilha de desempenho: Arrays e serialização

Por padrão, get_post_meta() com $single = false retorna um array dé arrays, o que é pouco intuitivo.

Se tiver um campo “cor” com o valor “azul”:

$val = get_post_meta( $id, 'cor', false );
// Retorna: Array ( [0] => "azul" )

Portanto, em 99% dos casos, usamos $single = true.

#O problema da serialização

O WordPress serializa automáticamenté arrays é objetos PHP na base de dados. Isto é conveniente, MAS: Não pode pesquisar ou ordenar eficientemente por dados serializados em SQL.

Se guardar dados como ['idade' => 25, 'cidade' => 'Lisboa'] num único campo meta, uma consulta SQL à procura de “pessoas de Lisboa” teria de usar um LIKE %Lisboa% lento, o que mata o desempenho em grandes bases de dados.

Regra de Ouro: Se precisar de pesquisar ou ordenar por algo (ORDER BY), guarde-o num campo meta separado, não dentro dé um array.

#3. Meta query: Filtrar posts por campos

O verdadeiro poder manifesta-se em WP_Query. Podé obter posts com base nos valores dos seus campos.

#Consulta simples (obter produtos mais caros que 100€)

$args = [
    'post_type'  => 'produto',
    'meta_query' => [
        [
            'key'     => 'preco',
            'value'   => 100,
            'compare' => '>',
            'type'    => 'NUMERIC' // Importante para ordenação numérica correta!
        ]
    ]
];
$query = new WP_Query( $args );

#Relações complexas (preço > 100 e cor = vermelho)

$args = [
    'post_type'  => 'produto',
    'meta_query' => [
        'relation' => 'AND', // ou 'OR'
        [
            'key'     => 'preco',
            'value'   => 100,
            'compare' => '>',
            'type'    => 'NUMERIC'
        ],
        [
            'key'     => 'cor',
            'value'   => 'vermelho'
        ]
    ]
];

Aviso de Desempenho: Pedidos meta_query geram JOINs para a tabela wp_postmeta. CADA critério adicional é outro JOIN. Com milhões de posts, isto pode ser extremamente lento. Sé o seu site estiver lento, verifique se está a abusar de meta_query. Nesses casos, considere tabelas de base de dados personalizadas.

#4. Exibir dados: ACF vs PHP puro

O plugin Advanced Custom Fields (ACF) é o padrão da indústria. Simplifica a criação de UI para campos no painel dé administração.

#ACF (método fácil)

$preco = get_field('preco'); // Faz automáticamente get_post_meta

#PHP puro (para puristas e desempenho)

Se não quiser dependência de plugins, pode criar uma metabox manualmente usando add_meta_box(), mas requer código significativo (formulário HTML, nonce, guardar save_post).

Em 2026, uma abordagem híbrida é comum: use ACF para criar campos (UI), mas obtenha-os via get_post_meta() no código se quiser “pureza” e evitar a sobrecarga da API do ACF em casos simples.

#5. Campos meta ocultos (prefixo underscore)

Já notou qué alguns campos não aparecem na lista “Campos Personalizados” no editor de posts? Isso acontece quando o nome da chave começa com um sublinhado _.

• preço -> Visível para o útilizador na UI padrão.
• _preco -> Oculto (Protegido).

Plugins como Yoast SEO ou WooCommerce usam _ (ex: _yoast_wpseo_title) para qué o útilizador não estrague esses dados manualmente. Como programador, também deve usar está convenção para dados do sistema.

#6. Segurança: Sanitização e escaping

Está é a secção mais importante. Nunca confie em dados, mesmo da base de dados.

#Ao guardar (sanitize)

Antes de colocar dados na base de dados (update_post_meta), limpe-os.

$novo_preco = sanitize_text_field( $_POST['preco'] );
update_post_meta( $post_id, 'preco', $novo_preco );

Outras funções úteis: sanitize_email(), absint() (para inteiros).

#Ao exibir (escape)

Antes de enviar dados para o navegador (echo), garanta que não contêm JS malicioso (XSS).

// MAU
echo get_post_meta($id, 'url', true);

// BOM
echo esc_url( get_post_meta($id, 'url', true) );

// TEXTO
echo esc_html( get_post_meta($id, 'cidade', true) );

// ATRIBUTOS HTML
echo '<div class="' . esc_attr( $classe ) . '">';

#7. Campos personalizados na era Gutenberg (fse)

Em 2026, ao usar o Block Editor (Gutenberg), surgé a questão: Onde guardar dados? Em atributos de bloco ou post meta?

• Atributos de Bloco: Guardados no conteúdo do post (HTML). Rápido de ler ao renderizar, mas impossível de consultar em SQL (não pode fazer “mostrar posts com um bloco que tem cor vermelha”).
• Post Meta: Guardados na tabela wp_postmeta. Mais lento (requer consulta separada), mas permite filtragem é ordenação (ex: em arquivos).

Melhor Prática: Sé os dados dizem respeito à aparência dé um elemento específico na página -> Atributo de Bloco. Sé os dados descrevem o post inteiro e quer filtrar por eles -> Post Meta.

Também pode combinar ambos: Um Bloco Gutenberg pode guardar os seus atributos em Post Meta para que fiquem acessíveis a WP_Query.

#Resumo

A função get_post_meta() é apenas a ponta do iceberg. Para ser um programador WordPress consciente em 2026:

1. Entenda a diferença entre $single=true e false.
2. Evite serializar dados pelos quais precisa de pesquisar.
3. Cuidado com o desempenho de meta_query (índices da base de dados).
4. Use sempre (SEMPRE) funções de escaping (esc_html, esc_url).
5. Escolha sabiamente entré atributos de bloco e campos meta.