O conjunto padrão de botões de formatação no editor do WordPress é familiar para todos: negrito, itálico, listas, citações. Mas quando precisa de inserir regularmente um botão de uma cor específica, um bloco de aviso ou uma legenda de imagem numa moldura com a identidade da marca, a rotina instala-se em força. Sempre o mesmo: mudar para o modo de texto, escrever style="", copiar classes de uma cábula. Um botão ficou azul, outro azul-claro. Um bloco com sombra, outro sem.

O problema não é a ausência de ferramentas, mas o facto de o menu suspenso «Formatos» no TinyMCE estar oculto por predefinição. E mesmo que o ative, está vazio: o WordPress não sabe de que estilos precisa. Mas pode adicioná-los lá.

Existem três abordagens: através de código no functions.php, através de um plugin com um construtor visual e através do mecanismo nativo do editor de blocos register_block_style(). Todas funcionam e cobrem cenários diferentes: desde o controlo manual sobre cada píxel até «clicou e aplicou».

💡 Resumo rápido:

• Ativamos o menu suspenso «Formatos» no editor clássico com o filtro mce_buttons_1 e preenchemo-lo com os nossos próprios estilos através de tiny_mce_before_init, com o código passo a passo incluído.
• Criamos o editor-style.css para pré-visualização ao vivo diretamente no editor: um botão parece um botão mesmo antes da publicação.
• Instalamos o TinyMCE Custom Styles, um construtor visual de formatos sem mexer em código, com ficheiros CSS gerados automaticamente.
• Vemos o caminho nativo para o Gutenberg: registar variações de blocos através de register_block_style(), ligar estilos através de theme.json ou wp_add_inline_style().

O que são estilos personalizados e porque precisa deles

Um estilo personalizado é uma predefinição de CSS que aplica a um fragmento selecionado através do menu suspenso do editor. Em vez de envolver um parágrafo em <span style="..."> pela centésima vez, escolhe «Destaque» no menu «Formatos» e obtém um realce amarelo com cantos arredondados. Um clique.

Três razões para configurar isto uma vez e esquecer:

• Consistência. Todos os botões, avisos e legendas têm o mesmo aspeto de publicação para publicação. O design não se desvia.
• Rapidez. O editor não mexe no CSS nem copia classes mágicas do bloco de notas, basta premir um botão.
• Segurança. Ninguém sobrescreve acidentalmente a marcação através de estilos inline no modo de texto.

Cenários típicos: botão de call-to-action (theme-button), bloco «Importante» com ícone e borda colorida, lista com marcas de verificação, legenda de imagem com estilo de marca, realce de código dentro de um parágrafo.

Método 1: Código, através do functions.php e editor-style.css

O caminho para quem não tem medo de abrir o functions.php uma vez. Resultado: o menu suspenso «Formatos» aparece na barra de ferramentas do TinyMCE e lá dentro estão os seus próprios estilos. Dez linhas de PHP, um ficheiro CSS, zero plugins desnecessários.

Passo 1. Ativar o botão «Formatos»

Por predefinição, a lista suspensa de formatos styleselect está oculta. Este filtro devolve-a à primeira linha do editor. Coloque o código no functions.php do tema ativo ou, mais corretamente, no tema filho:

1
function myprefix_mce_buttons_1( $buttons ) {
2
    array_unshift( $buttons, 'styleselect' );
3
    return $buttons;
4
}
5
add_filter( 'mce_buttons_1', 'myprefix_mce_buttons_1' );

O hook mce_buttons_1 adiciona o botão à primeira linha da barra de ferramentas. Se preferir a segunda ou terceira, use mce_buttons_2 ou mce_buttons_3.

Guardou o functions.php, abriu qualquer artigo, apareceu um menu suspenso «Formatos» na linha superior, à esquerda. Ainda vazio, para já.

Passo 2. Registar os seus próprios estilos

Agora vamos preencher o menu com formatos reais. Adicione um segundo filtro ao mesmo functions.php:

1
function myprefix_add_format_styles( $init_array ) {
2
    $style_formats = array(
3
        array(
4
            'title'    => __( 'Theme Button', 'text-domain' ),
5
            'selector' => 'a',
6
            'classes'  => 'theme-button',
7
        ),
8
        array(
9
            'title'    => __( 'Highlight', 'text-domain' ),
10
            'inline'   => 'span',
11
            'classes'  => 'text-highlight',
12
        ),
13
    );
14
    $init_array['style_formats'] = json_encode( $style_formats );
15
    return $init_array;
16
}
17
add_filter( 'tiny_mce_before_init', 'myprefix_add_format_styles' );

O que significam os parâmetros de cada elemento:

• title, o nome que o editor verá no menu suspenso.
• selector, a tag HTML à qual o estilo é aplicado. 'a' significa que «Botão do Tema» só funcionará em links.
• inline, envolve o texto selecionado numa tag (normalmente span) com a classe especificada. Perfeito para realçar uma palavra ou frase dentro de um parágrafo.
• classes, classe CSS (ou classes separadas por espaço) adicionada ao elemento.

Adicione os seus próprios itens ao array seguindo o mesmo modelo. A lista completa de parâmetros aceites está na documentação do TinyMCE em developer.wordpress.org.

Passo 3. Escrever CSS para o frontend

O menu está preenchido, mas o navegador ainda não sabe qual é o aspeto do .theme-button. Adicione CSS à folha de estilos do tema (ou tema filho):

1
.theme-button {
2
    display: inline-block;
3
    padding: 10px 15px;
4
    color: #fff;
5
    background: #1796c6;
6
    text-decoration: none;
7
}
8
.theme-button:hover {
9
    text-decoration: none;
10
    opacity: 0.8;
11
}
12
.text-highlight {
13
    background: #FFFF00;
14
}

Depois de guardar, o botão fica com estilo no frontend. Mas no admin, o editor ainda não o mostra.

Passo 4. Adicionar editor-style.css para pré-visualização no editor

Para mostrar os estilos diretamente no editor visual antes da publicação, precisa de um ficheiro editor-style.css separado. O WordPress pode carregá-lo:

1
function myprefix_theme_add_editor_styles() {
2
    add_editor_style( 'editor-style.css' );
3
}
4
add_action( 'init', 'myprefix_theme_add_editor_styles' );

Crie um ficheiro editor-style.css na raiz do tema e copie para lá o CSS do passo 3. Se estiver a trabalhar com o tema de outra pessoa, crie este ficheiro no tema filho: o WordPress verificará primeiro o tema filho e, encontrando lá o editor-style.css, carregá-lo-á em vez do do tema pai.

Resultado: texto selecionado, escolhi «Highlight», o realce amarelo fica imediatamente visível no editor. Cliquei num link, escolhi «Theme Button», e este transforma-se num botão azul.

Método 2: Plugin TinyMCE Custom Styles, sem mexer em código

Se não quiser mexer no functions.php, mas precisar de estilos, existe um plugin pronto. Faz o mesmo através de uma interface visual no painel de administração.

Instale e ative o TinyMCE Custom Styles. Em junho de 2026, o plugin contava com mais de 8.000 instalações ativas e suporta o bloco clássico do Gutenberg a partir da versão 1.1.1. A atualização mais recente (v1.1.5, junho de 2024) fechou vulnerabilidades. O autor, Tim Reeves, está abertamente à procura de um sucessor, mas a base de código é estável: o plugin não depende de recursos externos e não mexe na base de dados para além da sua própria tabela de opções.

O plugin aparece na lista geral de plugins instalados. Certifique-se de que está ativo antes de prosseguir para a configuração.

Após a ativação, vá a Settings → TinyMCE Custom Styles. O primeiro ecrã oferece a escolha de onde guardar os ficheiros CSS. Recomendo a terceira opção: criar uma pasta separada (por exemplo tinymce-styles) em wp-content/uploads. Isto protegerá os estilos ao atualizar o tema ou o próprio plugin. Clique em «Save Settings».

O primeiro ecrã mostra três opções de localização para o CSS. Escolha a terceira e defina um nome de pasta, por exemplo tinymce-styles.

Desça a página e clique em «Add New Style». Abrir-se-á um construtor onde define:

• Title, o nome no menu suspenso (por exemplo «Large Blue Button»).
• Type, baseado em seletor (aplica-se a uma tag específica), inline (envolve em span) ou block.
• Classes e propriedades CSS, diretamente na interface, sem ficheiros.

Depois de guardar as definições, clique em «Add New Style» no final da página. Abrir-se-á um construtor com campos para título, tipo e propriedades CSS.

Guarde, abra qualquer artigo e localize o menu suspenso «Formats» na segunda linha da barra de ferramentas. O novo estilo já está lá. Seleccione o texto, escolha-o e é aplicado de imediato.

A vantagem do plugin: os ficheiros CSS (editor-style.css e editor-style-shared.css) são criados automaticamente na pasta seleccionada. Obtém-nos via FTP, edita num editor prático e volta a carregá-los, sem uma única alteração ao functions.php.

Método 3: register_block_style(), via nativa para o Gutenberg

Os dois métodos anteriores funcionam no editor clássico TinyMCE e no seu bloco Clássico dentro do Gutenberg. Mas se vive exclusivamente no editor de blocos, há um caminho mais direto: register_block_style().

Esta função regista uma variação de estilo para um bloco específico, botão, título, citação, grupo. A variação aparece no painel lateral do bloco e o editor aplica-a com um clique.

Exemplo: vamos adicionar uma variação «Fancy» a um botão com fundo amarelo e cantos arredondados:

1
function myprefix_register_block_styles() {
2
    register_block_style(
3
        'core/button',
4
        array(
5
            'name'  => 'fancy',
6
            'label' => __( 'Fancy', 'text-domain' ),
7
        )
8
    );
9
}
10
add_action( 'init', 'myprefix_register_block_styles' );

O CSS é ligado através do theme.json (para temas de blocos modernos) ou através de wp_add_inline_style():

1
.is-style-fancy .wp-block-button__link {
2
    background-color: #f0c040;
3
    color: #fff;
4
    border: none;
5
    border-radius: 15px;
6
    padding: 10px 20px;
7
}

Esta abordagem não depende do TinyMCE e funciona nativamente no Gutenberg. Para temas com theme.json (todos os temas de blocos modernos), os estilos podem ser descritos diretamente na secção styles.blocks, sem uma única linha de PHP.

⁉️🤔 Perguntas frequentes

Os formatos não aparecem no editor. O que está errado?

Primeiro, vá a Settings → Advanced Editor Tools e certifique-se de que o botão «Formats» não foi removido da barra de ferramentas. O AET interceta o controlo das linhas de botões e o seu filtro mce_buttons_1 pode ser ignorado até que adicione explicitamente o botão através da interface do plugin. Verifique também se o filtro mce_buttons_1 está registado e devolve um array com o elemento 'styleselect'. Limpe a cache do navegador e a cache do servidor; muitas vezes o problema está apenas aí.

Posso associar um estilo a vários seletores ao mesmo tempo?

Sim. Em vez da string 'selector' => 'a', passe um array: 'selector' => 'a, button, span'. O TinyMCE aplicará o estilo à primeira tag pai correspondente da lista. Na prática, isto é útil quando um estilo visual deve funcionar tanto em links como em botões <button>. A ordem no array é importante: se o texto selecionado estiver dentro de um link aninhado num div e os seletores especificarem 'div, a', o estilo será aplicado ao div, não ao a. Coloque os seletores mais específicos primeiro.

Qual é a diferença entre editor-style.css e editor-style-shared.css?

O plugin TinyMCE Custom Styles cria dois ficheiros. O editor-style.css carrega apenas no editor TinyMCE. O editor-style-shared.css carrega tanto no editor como no frontend; os estilos deste ficheiro são visíveis para os visitantes do site. Se um estilo for necessário apenas para conveniência de edição, coloque-o no editor-style.css. Se o estilo deve funcionar no site, coloque-o no editor-style-shared.css. Com a abordagem manual, o análogo do ficheiro partilhado é a folha de estilos principal do tema, e o editor-style.css (um ficheiro separado registado através de add_editor_style()) afeta apenas a pré-visualização dentro do TinyMCE.

É obrigatório criar um tema filho para estas edições?

Não, o código também funciona no functions.php do tema principal. Mas na próxima atualização do tema, todas as edições serão sobrescritas. A regra é simples: qualquer personalização através do functions.php vai para um tema filho; isto é um seguro contra a perda de alterações. Se ainda não tem um tema filho, crie-o em dez minutos seguindo o guia de temas filho: dois ficheiros, style.css com um cabeçalho e functions.php com a importação dos estilos do tema pai, e os seus formatos personalizados sobreviverão a qualquer atualização.

O plugin não é atualizado desde 2024. Devo instalá-lo?

Em junho de 2026, o plugin TinyMCE Custom Styles permanece no catálogo do WordPress.org com mais de 8.000 instalações ativas. O autor está abertamente à procura de um sucessor, mas a base de código não está abandonada: a última atualização (v1.1.5, junho de 2024) fechou vulnerabilidades. Há risco, mas é gerível: o plugin não depende de bibliotecas externas e não mexe profundamente na base de dados. Se no futuro o plugin deixar de ser atualizado, pode sempre transferir os estilos para o método manual (passos 1 a 4 acima) sem perder o CSS. Existe uma alternativa com desenvolvimento ativo, o Advanced Editor Tools (AET) da Automattic, mas a sua opção «Create CSS classes menu» frequentemente polui o menu com classes desnecessárias. O TinyMCE Custom Styles dá controlo manual sobre cada elemento, por isso não são concorrentes, mas sim complementares.

Código, plugin ou blocos: o que escolher para o seu cenário

A escolha resume-se a duas perguntas: em que editor trabalha e se está disposto a abrir o functions.php uma vez.

Se trabalha no editor clássico ou no bloco Clássico do Gutenberg e não tem medo de código, escolha o método 1. Dez linhas de PHP, um ficheiro CSS, controlo total.

Se quer um construtor visual de formatos sem mexer em código e com geração automática de CSS, instale o TinyMCE Custom Styles. Lembre-se do risco de suporte a longo prazo, mas, à data de hoje, o plugin cumpre o que promete.

Se vive no editor de blocos, domine o register_block_style(). Esta via é nativa do Gutenberg, não depende do TinyMCE e é suportada pelo núcleo do WordPress.

Em qualquer um dos três cenários, obtém o principal: formatação com um clique em vez de cópia manual de classes e estilos inline. E isso é uma ou duas horas de tempo poupado por mês em qualquer site com publicação regular.