Como criar um tema filho no WordPress

Para criar um tema filho no WordPress, adicione uma nova pasta em wp-content/themes, coloque dentro dela um arquivo style.css cujo cabeçalho Template corresponda ao nome da pasta do tema pai e ative-o. O tema filho herda os templates, os estilos e as funcionalidades do tema pai e armazena apenas as suas alterações.

Se você já editou os arquivos de um tema diretamente e depois viu a atualização seguinte apagar tudo, o tema filho é a forma de evitar que isso aconteça.

Este guia apresenta a configuração que funciona no WordPress moderno. Ele mostra como criar um tema filho clássico com o enfileiramento correto, como sobrescrever templates e funções, o que muda em temas de bloco como o Twenty Twenty-Four e os casos em que você nem precisa de um tema filho.

Por que editar o tema pai diretamente não funciona?

Quando um tema é atualizado, o WordPress substitui os arquivos dele pela nova versão, então qualquer edição feita dentro da pasta do tema é perdida. Um tema filho mantém suas alterações em uma pasta separada, que as atualizações nunca alteram. O guia de temas filhos do Theme Handbook apresenta essa abordagem como a forma de receber as atualizações do tema pai sem abrir mão das suas próprias edições. O sistema de temas se limita a dois níveis, um pai e um filho, portanto não é possível instalar um tema “neto” por cima.

Como criar um tema filho no WordPress (temas clássicos)

Um tema filho clássico precisa de uma pasta, de um style.css com o cabeçalho Template e, na maioria dos casos, de um functions.php que enfileire a folha de estilos. A estrutura é a mesma de pasta, style.css e functions.php descrita no nosso guia sobre como criar um tema WordPress responsivo com Bootstrap. A diferença é que o tema filho contém apenas o que ele altera.

wp-content/themes/
├── twentytwentyfour/
└── tt4-child/
    ├── style.css
    └── functions.php

O cabeçalho do style.css

Somente o style.css é estritamente obrigatório. A documentação da folha de estilos principal informa que todo tema precisa ter pelo menos o cabeçalho Theme Name, e um tema filho acrescenta o Template a ele.

/*
 * Theme Name:  TT4 Child
 * Template:    twentytwentyfour
 * Version:     1.0.0
 * Text Domain: tt4-child
 */

O Template recebe o nome da pasta do tema pai, e não o nome de exibição. Se os dois não forem idênticos, caractere por caractere, o WordPress não vinculará o filho ao pai.

Enfileirando folhas de estilo em vez de usar @import

Carregue os estilos do tema filho com wp_enqueue_style() no hook wp_enqueue_scripts, e não com @import. Muitos tutoriais antigos carregam os estilos do tema pai com @import no início do style.css do filho. Essa abordagem está ultrapassada:

/* Outdated: do not use */
@import url("../twentytwentyfour/style.css");

O navegador só encontra o arquivo importado depois de baixar e interpretar a folha de estilos do filho, então as duas requisições acontecem uma após a outra, e ambas bloqueiam a renderização. Além disso, o import fica fora do sistema de enfileiramento do WordPress, o que significa que o WordPress não consegue gerenciar as dependências, o versionamento nem a eliminação de duplicatas desse arquivo.

A alternativa é a wp_enqueue_style(), chamada a partir de uma função vinculada ao hook wp_enqueue_scripts. Esse mesmo hook também carrega scripts, assunto abordado no nosso artigo sobre como adicionar JavaScript personalizado a temas WordPress.

<?php
// functions.php
add_action( 'wp_enqueue_scripts', 'tt4child_enqueue_styles' );

function tt4child_enqueue_styles() {
	wp_enqueue_style(
		'tt4child-style',
		get_stylesheet_uri(), // the active (child) theme's style.css
		array(),              // $deps: handles that must load first
		'1.0.0'               // $ver: appended as a cache-busting query string
	);
}

O código de enfileiramento adequado para um tema filho depende do que o tema pai já enfileira:

Para o caso da terceira linha, use o seguinte:

function tt4child_enqueue_styles() {
	wp_enqueue_style(
		'tt4child-parent-style',
		get_parent_theme_file_uri( 'style.css' )
	);
}

Para descobrir qual caso se aplica, procure por wp_enqueue_style no functions.php do tema pai ou verifique as tags <link> de folhas de estilo no código-fonte da página. A ordem das folhas de estilo não é fixa. Ela segue as chamadas de enfileiramento, e o argumento $deps recebe um array de handles registrados que devem ser carregados antes. Para que a folha de estilos do filho seja impressa depois da do pai, passe o handle do pai em $deps, consultando o nome do handle no código do tema pai. Quando a URL da folha de estilos do filho está errada, a requisição retorna 404 e a página é renderizada apenas com o CSS do pai. Um session replay que registra as requisições de rede junto com a reprodução visual mostra a requisição com falha ao lado da página sem estilos.

Como sobrescrever templates do tema pai?

Para sobrescrever um template do tema pai, copie o arquivo (não o mova) para o mesmo caminho relativo no tema filho. Quando o WordPress percorre a hierarquia de templates, ele verifica a pasta do filho antes da do pai, portanto um arquivo com o mesmo nome no filho é o que será usado. Mover o arquivo em vez de copiá-lo altera o tema pai, e a próxima atualização o restaura de qualquer forma.

twentytwentyfour/page.php  →  copy to  →  tt4-child/page.php

A mesma regra se aplica às partes de template. Você também pode adicionar novos templates que o tema pai não possui.

Sobrescrevendo funções do tema pai

O functions.php do tema filho não substitui o do tema pai. Segundo o Handbook, o WordPress executa os dois arquivos, começando pelo do filho e passando em seguida para o do pai. Essa ordem de carregamento tem duas consequências. Funções do tema pai envolvidas em function_exists() (funções plugáveis) podem ser redefinidas no filho. Qualquer outra função do pai precisa ser desvinculada do hook ou complementada. Também não cole o código do functions.php do pai no filho: declarar os mesmos nomes de função duas vezes derruba o site com um erro fatal.

Uma função plugável no tema pai tem esta aparência:

// Parent theme
if ( ! function_exists( 'parenttheme_credit' ) ) {
	function parenttheme_credit() { /* ... */ }
}

Como o filho é executado primeiro, definir o mesmo nome no filho faz com que a versão do pai seja ignorada:

// Child theme
function parenttheme_credit() {
	echo '<p>Custom credit line</p>';
}

Se a função não for plugável, remova-a com remove_action(), usando o mesmo hook e a mesma prioridade com que ela foi registrada. Uma chamada a remove_action() colocada no nível superior do arquivo do filho é executada antes de o pai adicionar o hook dele, então ainda não há nada para remover. Execute-a a partir do after_setup_theme, que é disparado depois que os arquivos functions.php dos dois temas foram carregados:

// Parent theme
add_action( 'init', 'parenttheme_setup_extra', 20 );

// Child theme
add_action( 'after_setup_theme', function () {
	remove_action( 'init', 'parenttheme_setup_extra', 20 );
} );

O remove_filter() funciona da mesma forma para filtros. Para complementar uma função do pai em vez de substituí-la, vincule sua própria função ao mesmo hook com uma prioridade posterior. A prioridade padrão do add_action() é 10, e números maiores são executados depois:

add_action( 'parent_footer', 'tt4child_footer_extra', 20 );

Como os temas filhos funcionam em temas de bloco?

Um tema filho de um tema de bloco, como um baseado no Twenty Twenty-Four, muitas vezes precisa apenas de style.css e theme.json. A estilização fica principalmente no theme.json, por isso o Handbook observa que enfileirar o style.css costuma ser desnecessário, e muitos temas filhos de bloco nem têm um functions.php.

tt4-child/
├── style.css
├── theme.json
├── templates/
│   └── single.html
├── parts/
│   └── header.html
└── patterns/
    └── (same filename as the parent pattern).php

Para sobrescrever um template, uma parte de template ou um pattern, adicione um arquivo com o mesmo nome. No caso dos patterns, o cabeçalho Slug registrado também deve ser igual ao do pai, então copie-o do arquivo do tema pai:

<?php
/**
 * Title: Footer
 * Slug: parent-slug/pattern-name
 */
?>

Um theme.json mínimo fixa o schema e usa a versão 3, que exige o WordPress 6.6 ou posterior:

{
	"$schema": "https://schemas.wp.org/wp/6.6/theme.json",
	"version": 3,
	"styles": {
		"typography": {
			"lineHeight": "1.7"
		}
	}
}

Os arquivos theme.json do pai e do filho são combinados de acordo com regras específicas de mesclagem, com prioridade para os valores do filho. As personalizações salvas no Editor do site também ficam armazenadas no banco de dados e se sobrepõem ao tema filho no modelo de camadas do Handbook. Se um template do filho parecer estar sendo ignorado, limpe a personalização salva desse template no Editor do site.

Quando você não precisa de um tema filho

Para pequenos ajustes visuais ou recursos funcionais, você não precisa de um tema filho. Em um tema clássico, o CSS adicional do Personalizador é suficiente para algumas regras. Com um tema de bloco ativo, o CSS personalizado é feito no painel Estilos do Editor do site. Alterações funcionais, como custom post types, devem ficar em um plugin, para que continuem funcionando após uma troca de tema. Se suas alterações crescerem a ponto de o tema filho ficar difícil de gerenciar, o Handbook sugere criar um fork do tema pai e transformá-lo em um tema próprio.

Conclusão

Um tema filho se resume a uma pasta e um style.css cujo valor de Template corresponde ao nome da pasta do tema pai. Em temas clássicos, adicione um código de enfileiramento adequado ao que o tema pai carrega. Em temas de bloco, o theme.json e os arquivos de template com o mesmo nome fazem o trabalho. Comece verificando quais folhas de estilo o seu tema pai enfileira e, depois, adicione apenas os arquivos que você realmente precisa alterar.

Perguntas frequentes

Qual é a diferença entre get_template_directory_uri() e get_stylesheet_directory_uri() em um tema filho?

Quando um tema filho está ativo, get_template_directory_uri() retorna a URL do diretório do tema pai, enquanto get_stylesheet_directory_uri() retorna a URL do diretório do tema filho. Use a variante stylesheet para arquivos armazenados no filho. Desde o WordPress 4.7, get_theme_file_uri() costuma ser a melhor opção: ela retorna a cópia do arquivo no filho, se existir, e recorre ao arquivo do pai caso contrário.

Por que minhas configurações do Personalizador e as localizações de menu sumiram depois que ativei um tema filho?

O WordPress armazena as configurações do Personalizador (theme mods) separadamente para cada tema, vinculadas ao nome da pasta do tema ativo, então um tema filho começa com seu próprio conjunto vazio e não herda as do pai. Seus menus continuam existindo, mas você precisa atribuí-los novamente às localizações de menu e inserir de novo ou importar as demais configurações. As configurações do pai permanecem no banco de dados e voltam se você reativar o tema pai.

O que acontece com um arquivo de template copiado para o tema filho quando o tema pai é atualizado?

A cópia no filho permanece exatamente como você a salvou, e o WordPress continua a usá-la no lugar do arquivo atualizado do pai. Correções de bugs, patches de segurança ou alterações de marcação que o pai fizer nesse arquivo nunca chegam à sua versão sobrescrita. Após cada atualização do pai, compare os arquivos sobrescritos com as novas versões do pai e incorpore o que for necessário. Sobrescreva o menor número possível de arquivos para manter isso gerenciável.

É possível criar um tema filho para um tema de bloco sem escrever código?

Sim. O plugin oficial Create Block Theme, disponível no WordPress.org, tem a opção Create Child Theme. Ele gera um tema filho do tema de bloco ativo, como o Twenty Twenty-Four, e grava nos arquivos do filho as alterações que você fez no Editor do site. O plugin foi desenvolvido para temas de bloco, então um tema filho de um tema pai clássico ainda precisa da configuração com style.css e functions.php descrita acima.