Instalou um tema, afinou o site, ajustou cores e fontes, adicionou alguns templates personalizados. Depois, chega uma atualização do tema e apaga tudo. Parece-lhe familiar?

Um tema filho no WordPress é o mecanismo que separa as suas personalizações do código do programador. Altera o que quiser e o tema principal é atualizado sem consequências. Parece magia, mas por detrás disto está apenas uma linha no style.css.

Neste guia, do conceito a um tema filho funcional: porque precisa de um, como criá-lo manualmente, como enfileirar estilos e o functions.php, e o que fazer se algo correr mal. Sem palha, com snippets testados.

💡 Visão geral rápida:

• Crie uma pasta de tema filho em /wp-content/themes/, qualquer nome funciona, por exemplo mytheme-child
• Adicione o style.css com um cabeçalho de tema e uma linha Template: a apontar para a pasta do tema principal
• Enfileire os estilos do tema principal através do functions.php, usando a função wp_enqueue_style() no hook wp_enqueue_scripts
• Copie qualquer ficheiro de template do tema principal para o tema filho e edite-o sem receio de atualizações
• Tudo o resto (functions.php, campos personalizados, novos templates) pode ser estendido sem tocar no tema principal

O que é um tema filho do WordPress

Um tema filho é um tema do WordPress que herda todas as funcionalidades, estilos e templates de outro tema. Aquele do qual herda é chamado de tema principal. Um tema filho, por si só, pode consistir apenas num único ficheiro style.css e ainda assim funcionar plenamente.

O mecanismo de herança é simples. Quando o WordPress carrega uma página, procura primeiro o ficheiro de template necessário no tema filho. Se o encontrar, usa esse ficheiro. Se não o encontrar, vai buscar o ficheiro ao tema principal. É por isso que pode substituir apenas o que quer alterar, e tudo o resto virá automaticamente do tema principal.

O elemento chave sem o qual um tema filho não pode existir é a linha Template: no cabeçalho do style.css. Esta aponta para o nome da pasta do tema principal (por exemplo, twentytwentyfour) e cria a relação pai-filho. A linha deve corresponder exatamente ao nome da pasta do tema principal, incluindo maiúsculas e minúsculas.

O tema principal pode ser QUALQUER tema WordPress instalado, desde o padrão Twenty Twenty-Five até um tema comercial como o Total ou o Kadence. O tema filho "pede emprestados" os seus ficheiros e funções, mas não os copia fisicamente.

Porque precisa de um tema filho: 4 razões

Podia ignorar tudo isto e editar o tema principal diretamente. Muitas pessoas fazem-no. Mas eis o que acontece a seguir.

Atualizações seguras

O programador do tema principal lança uma atualização e você instala-a. Se editou os ficheiros do tema principal diretamente, todas as alterações são apagadas. Um tema filho guarda as suas personalizações em separado: atualizar o tema principal não lhes toca. Obtém tanto a versão atualizada do tema (com correções de segurança) como as suas personalizações preservadas.

Experimentação isolada

Quer experimentar uma nova estrutura de template ou um hack de CSS não convencional? Num tema filho, pode experimentar livremente. Se algo correr mal, desative o tema filho e o site volta ao tema principal no seu estado original.

Base de código limpa

Um tema filho contém apenas as suas alterações. Alguns templates, o functions.php com hooks, o style.css com substituições. Sem mistura de código original com as suas edições. Quando precisar de corrigir algo seis meses depois, não estará a escavar o código de outra pessoa à procura do seu.

Arranque rápido de desenvolvimento

Um tema filho é a sandbox perfeita para aprender desenvolvimento de temas WordPress. Não escreve um tema de raiz (isso leva centenas de horas), mas faz alterações direcionadas a um tema que já funciona. A documentação oficial de temas filho do WordPress recomenda exatamente esta abordagem para programadores iniciantes.

Quais são as desvantagens dos temas filho

Também há desvantagens. Não são críticas, mas conhecê-las antecipadamente ajuda.

Conhecimentos básicos de código necessários

Configurar um tema filho envolve HTML, CSS e algum PHP. Se nunca abriu um editor de código, terá de aprender o básico. A boa notícia: para tarefas típicas (enfileirar estilos, adicionar um hook), o código já está escrito; basta copiá-lo e substituir os seus próprios valores.

Migração de definições do Personalizador

Alguns temas vinculam as definições do Personalizador (cores, fontes, layout) ao nome do tema ativo. Ao mudar para um tema filho, estas definições "desaparecem". Não se perdem; permanecem na base de dados, vinculadas ao nome do tema principal. A solução: antes de ativar o tema filho, exporte as definições do Personalizador (muitos temas, como o Total, fornecem uma ferramenta de importação/exportação integrada) ou transfira-as manualmente após a ativação.

Dependência do tema principal

Um tema filho sem o seu tema principal é apenas uma pasta com ficheiros. Se decidir mudar completamente de tema, precisará de criar um novo tema filho de raiz. As funções incorporadas no functions.php do tema filho podem estar vinculadas a hooks específicos de um determinado tema principal e também precisarão de ser adaptadas.

Como criar um tema filho manualmente

O caminho mais direto, sem plugins, usando apenas as suas mãos. Precisará de acesso aos ficheiros do seu site (FTP, o gestor de ficheiros do seu alojamento ou cPanel) e de um editor de texto.

Passo 1. Criar a pasta do tema filho

Abra o diretório de temas do WordPress: /wp-content/themes/. Crie uma nova pasta. Qualquer nome funciona, mas a convenção é adicionar o sufixo -child ao nome do tema principal: por exemplo, para twentytwentyfive, a pasta filha seria twentytwentyfive-child.

Para trabalhar com ficheiros via FTP, o FileZilla funciona bem. Através do alojamento, use o gestor de ficheiros integrado no cPanel ou no seu painel de alojamento.

Passo 2. Criar o style.css com o cabeçalho do tema

Na pasta do tema filho, crie um ficheiro chamado style.css. Este é o único ficheiro obrigatório. Cole o cabeçalho do tema:

1
/*
2
Theme Name:   Twenty Twenty-Five Child
3
Theme URI:    https://example.com/
4
Description:  Child theme for Twenty Twenty-Five
5
Author:       Your Name
6
Template:     twentytwentyfive
7
Version:      1.0.0
8
*/

A linha Template: é a que liga o tema filho ao tema principal. O valor deve corresponder EXATAMENTE ao nome da pasta do tema principal. Para o Twenty Twenty-Five, a pasta chama-se twentytwentyfive, por isso é exatamente isso que escreve. Um erro de digitação ou uma maiúscula/minúscula errada significa que o tema não será reconhecido como tema filho.

Passo 3. Enfileirar os estilos do tema principal

Neste ponto, o tema filho já funciona; pode ativá-lo em Aparência → Temas. Mas o site aparecerá sem estilos porque o seu style.css ainda está vazio (exceto o cabeçalho).

Crie um ficheiro chamado functions.php na pasta do tema filho e adicione o código para enfileirar os estilos do tema principal:

1
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue_styles' );
2
 
3
function my_theme_enqueue_styles() {
4
    $theme   = wp_get_theme( 'twentytwentyfive' );
5
    $version = $theme->get( 'Version' );
6
 
7
    wp_enqueue_style(
8
        'parent-style',
9
        get_template_directory_uri() . '/style.css',
10
        array(),
11
        $version
12
    );
13
}

Este código obtém dinamicamente a versão do tema principal e adiciona-a como parâmetro ao URL da folha de estilos. Quando o tema é atualizado, a versão muda, o navegador limpa a cache e os utilizadores veem os estilos atuais sem problemas de CSS.

Substitua twentytwentyfive pelo nome do seu tema principal. Use wp_get_theme() em vez de um número de versão fixo; isto protege-o de problemas de cache nas atualizações.

Passo 4. Ativar o tema filho

No painel de administração do WordPress: Aparência → Temas → encontre o seu tema filho recém-criado → Ativar. A aparência do site não mudará; isto é normal. Está no tema filho e ele funciona.

Como personalizar um tema filho

O tema está ativado; agora é a personalização. Eis o que pode e deve fazer.

Adicionar os seus próprios estilos

Escreva todas as suas regras de CSS NO ficheiro style.css do tema filho, após a secção do cabeçalho. Elas substituirão automaticamente os estilos do tema principal com a mesma especificidade. Se quiser mudar a cor dos títulos, escreva a regra no style.css filho e ela será aplicada.

Editar ficheiros de template

Quer mudar a estrutura do single.php ou do footer.php? Copie o ficheiro desejado do tema principal para a pasta do tema filho, preservando a mesma estrutura de subpastas (por exemplo, /template-parts/). Edite a cópia no tema filho; quando o WordPress carregar, usará a sua versão em vez da original do tema principal.

Detalhe importante: só pode copiar FICHEIROS DE TEMPLATE (os localizados na pasta raiz do tema e na pasta template-parts/). Os ficheiros de subpastas como inc/, functions/ e classes/ não são copiados desta forma. Para modificar a lógica desses ficheiros, use hooks e filtros do WordPress.

Estender através do functions.php

O functions.php do tema filho carrega ANTES do tema principal. Isto significa que pode:

• Adicionar novas funções sem tocar no functions.php do tema principal;
• Substituir funções do tema principal apenas se estas estiverem encapsuladas em if ( ! function_exists() );
• Adicionar novos hooks e filtros para alterar o comportamento do tema principal ou do próprio WordPress.

Exemplo: permitir uploads de SVG através do functions.php filho:

1
function my_child_allow_svg( $mimes ) {
2
    $mimes['svg'] = 'image/svg+xml';
3
    return $mimes;
4
}
5
add_filter( 'upload_mimes', 'my_child_allow_svg' );

Nunca copie TODO o functions.php do tema principal para o tema filho. Isto causará um erro fatal devido a funções redeclaradas. O functions.php filho estende o do tema principal; não o substitui.

Adicionar novos ficheiros de template

Um tema filho pode conter templates que não existem no tema principal. Por exemplo, pode criar template-full-width.php para páginas sem barra lateral, e o WordPress detetá-lo-á no tema filho e oferecê-lo-á como opção ao editar uma página.

Ferramentas e editores de texto

Qualquer editor serve para código de tema filho, mas o realce de sintaxe facilita as coisas. Aqui estão algumas opções:

• VS Code: gratuito, com extensões para PHP e WordPress;
• Notepad++: um editor leve para Windows que lida com CSS/PHP/JS;
• Sublime Text: rápido e minimalista, pago após o período de teste.

Para aceder a ficheiros via FTP, use o cliente FTP FileZilla. Para utilizadores de alojamento, o gestor de ficheiros integrado do cPanel é perfeitamente adequado para criar alguns ficheiros.

Erros comuns e como corrigi-los

Ao longo de anos a trabalhar com temas filho, compilámos uma lista dos obstáculos mais frequentes.

"O tema filho não é reconhecido." Quase sempre, isto é um erro na linha Template:. Verifique se o nome da pasta do tema principal corresponde caráter por caráter, incluindo maiúsculas/minúsculas e hífenes. TwentyTwentyFive e twentytwentyfive são nomes diferentes.

"O site mostra HTML simples sem estilos." O tema filho está ativado, mas os estilos não estão enfileirados. Adicione wp_enqueue_style() no functions.php do tema filho (ver Passo 3).

"Erro fatal de PHP após a ativação." Muito provavelmente, copiou o functions.php do tema principal para o tema filho e agora as funções estão declaradas duas vezes. Remova as duplicações do functions.php filho; mantenha apenas AS SUAS funções.

"As definições do Personalizador desapareceram." Estão vinculadas ao nome do tema. Mude temporariamente de volta para o tema principal, exporte as definições (através de um plugin ou da ferramenta integrada do tema) e, em seguida, ative o tema filho e importe-as.

"Atualizar o tema principal quebrou o layout." O programador alterou a estrutura HTML de um template que copiou para o tema filho. A sua cópia é agora incompatível com os novos estilos. Solução: compare o novo template do tema principal com a sua cópia e adapte as alterações.

Vídeo passo a passo (EN) sobre como criar um tema filho: desde a criação da pasta até à ativação final e configuração de estilos. Canal WPEstate, 2025, claro e sem enchimento.

⁉️🤔 Perguntas frequentes

Tenho de criar um tema filho para cada site WordPress?

Não. Se não está a editar ficheiros de tema nem a adicionar código personalizado, não precisa de um tema filho. Mas se alguma vez abriu o editor de temas no painel de administração, adicionou CSS em CSS Adicional e planeia modificar templates, crie um tema filho. Demora 10 minutos agora e poupa horas na próxima atualização.

O que acontece se eu apagar o tema principal, mas mantiver o tema filho?

O site irá falhar com um erro crítico. Um tema filho sem o seu tema principal não funciona; não contém um conjunto completo de ficheiros e herda tudo do tema principal. Antes de apagar o tema principal, apague (ou desative) primeiro o tema filho e ative um tema diferente.

Posso criar um tema "neto", um filho de um filho?

Não. O WordPress suporta apenas um nível de herança: pai → filho. Para personalizações complexas que não cabem num único tema filho, a abordagem correta é bifurcar o tema e criar um tema principal completo, ou mover a lógica para um plugin separado.

Um tema filho funciona com temas de blocos (FSE, Edição Completa do Site)?

Sim, mas o mecanismo difere ligeiramente. Nos temas de blocos, o theme.json do tema filho é fundido com o do tema principal, em vez de o substituir. Os templates e as partes de template são substituídos da mesma forma: criando um ficheiro com o mesmo nome no tema filho. Mais detalhes estão na documentação oficial dos Recursos para Programadores em wordpress.org.

Como transfiro personalizações já feitas no tema principal para o tema filho?

Identifique o que alterou: CSS, templates ou functions.php. Copie as regras de CSS para o style.css filho. Para templates modificados, copie os ficheiros para o tema filho e mantenha as suas edições lá. Transfira o código do functions.php do tema principal seletivamente: apenas as suas funções, não o ficheiro inteiro. Após a transferência, remova as suas edições do tema principal; caso contrário, serão perdidas na próxima atualização.

Deve criar um tema filho agora mesmo

Se leu até aqui, a resposta é provavelmente sim. Um tema filho não complica o site nem o torna mais lento. Ele separa o seu código do código do programador do tema. É como comentar código: a princípio parece desnecessário, mas um mês depois salva-o.

Para quem edita um tema pela primeira vez: comece com uma sandbox. Um servidor local (LocalWP, XAMPP) ou um site de testes no seu alojamento. Crie um tema filho seguindo os passos acima, adicione algumas regras de CSS, copie um template. Quando vir que tudo funciona, repita no seu site ativo.

A questão não é se precisa de um tema filho. A questão é quando se lembrará dele: antes da atualização do tema ou depois de as suas personalizações terem desaparecido.