Em 2018, o WordPress introduziu o editor Gutenberg com a versão 5.0, trazendo uma nova maneira de criar páginas e artigos usando “blocos”. No início, esses blocos eram bem básicos, mas, com o passar dos anos, eles evoluíram para oferecer mais flexibilidade e uma melhor experiência de edição.
Ainda assim, há momentos em que um bloco não faz exatamente o que você precisa. Talvez você queira remover certos recursos, adicionar novos, aplicar um estilo específico por padrão ou tornar algumas configurações mais fáceis de acessar. Em casos como esse, criar um bloco personalizado do zero pode parecer uma opção, mas, sejamos honestos, é um exagero para pequenos ajustes. Não seria mais fácil se você pudesse simplesmente modificar os blocos que já existem?
É aí que entra a API de blocos. Este artigo explica como você pode ampliar os blocos principais do WordPress usando a API de blocos, fornecendo exemplos práticos que podem ser usados em projetos reais.
Entendendo a API de blocos do WordPress
A API de blocos do WordPress é a base do editor de blocos, permitindo que os desenvolvedores criem, modifiquem e ampliem os blocos. A API oferece várias maneiras de você interagir com os blocos. Você pode:
- Modificar as configurações do bloco – Alterar atributos, valores padrão e comportamentos do bloco.
- Adicionar ou remover compatibilidades de bloco – Ativar ou desativar recursos como tipografia, cores e espaçamento.
- Inserir controles personalizados – Adicionar novas opções dentro do painel de configurações do bloco.
- Criar variações de blocos – Crie versões pré-configuradas de blocos existentes para acelerar a criação de conteúdo.
Cada bloco no WordPress, seja ele um parágrafo, imagem ou botão, é definido por um conjunto de atributos e configurações armazenados em um arquivo block.json. Esse arquivo contém metadados sobre o bloco, inclusive o nome, a categoria, os atributos padrão e os recursos que ele suporta.
O WordPress permite que você modifique esses valores usando PHP ou JavaScript, mas este artigo explica como usar hooks de filtro na API de Blocos. Isso garante que suas modificações sejam registradas no servidor sem a necessidade de carregar arquivos JavaScript adicionais.
Por exemplo, se você quiser ativar ou desativar determinados recursos de um bloco, a melhor maneira de fazer isso é usar o filtro register_block_type_args no PHP. Esse método permite que você ajuste as configurações do bloco dinamicamente sem modificar diretamente o arquivo block.json.
Modificando as compatibilidades de blocos
Os blocos do WordPress vêm com suportes predefinidos, que controlam as opções do editor. Alguns blocos, como o bloco de Imagem (core/image), têm filtros duotone ativados por padrão, permitindo que os usuários apliquem sobreposições de cores.
No entanto, o bloco Mídia e Texto (core/media-text) não oferece suporte ao duotone por padrão, mesmo permitindo a inserção de uma imagem. Isso significa que, embora seja possível aplicar um filtro duotone a um bloco de Imagem isolado, não é possível fazer o mesmo quando a imagem está dentro de um bloco de Mídia e Texto.
Como o bloco de Mídia e Texto pode conter uma imagem, faz sentido ativar os filtros duotone. Podemos fazer isso modificando o array supports e especificando o seletor CSS correto para que o filtro seja aplicado adequadamente. Para ativar esse suporte, usamos o filtro register_block_type_args em PHP.
Adicione o seguinte código ao arquivo functions.php do seu tema:
function enable_duotone_for_media_text_block($args, $block_type) {
// Only modify the Media & Text block
if ( 'core/media-text' === $block_type ) {
$args['supports'] ??= [];
$args['supports']['filter'] ??= [];
$args['supports']['filter']['duotone'] = true;
$args['selectors'] ??= [];
$args['selectors']['filter'] ??= [];
$args['selectors']['filter']['duotone'] = '.wp-block-media-text .wp-block-media-text__media';
}
return $args;
}
add_filter('register_block_type_args', 'enable_duotone_for_media_text_block', 10, 2);O código acima ativa o filtro duotone dentro do array supports e define o seletor CSS correto para aplicar o efeito duotone às imagens dentro do Bloco Mídia e Texto. A função add_filter() usa 10 como a prioridade (quando o filtro é executado) e 2 para especificar o número de argumentos passados ($args, $block_type).
Após salvar o arquivo e recarregar o editor do WordPress, você deverá ver os controles do Duotone disponíveis na seção Filtros.
Ativar o filtro duotone para o bloco Mídia e Texto usando register_block_type_args é uma forma eficaz de modificar o comportamento do bloco de forma dinâmica. No entanto, o WordPress oferece outro método para ajustar as configurações de blocos: sobrescrever os metadados do bloco usando block_type_metadata.
Ambas as abordagens permitem personalizar blocos, mas atuam em momentos diferentes do processo de registro do bloco.
Por exemplo, digamos que você queira ajustar o bloco Parágrafo (core/paragraph) de modo que ele suporte apenas ajustes de margem e desative o preenchimento. Uma maneira de fazer isso é usar register_block_type_args:
function modify_paragraph_spacing_args($args, $block_type) {
if ($block_type === 'core/paragraph') {
$args['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $args;
}
add_filter('register_block_type_args', 'modify_paragraph_spacing_args', 10, 2);Esse método funciona bem na maioria dos casos. No entanto, como a modificação ocorre após o bloco já ter sido registrado, ela pode ser sobrescrita por outros plugins ou temas que alterem o mesmo bloco posteriormente.
Uma abordagem mais estruturada nesse caso poderia ser substituir os metadados do bloco diretamente usando block_type_metadata:
function mytheme_modify_paragraph_spacing($metadata) {
if ($metadata['name'] === 'core/paragraph') {
$metadata['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $metadata;
}
add_filter('block_type_metadata', 'mytheme_modify_paragraph_spacing');Nenhuma das duas abordagens é intrinsecamente melhor do que a outra — tudo depende de quando você deseja modificar o bloco e de quão persistente deseja que essa alteração seja.
Registro de estilos de bloco
Muitos blocos do WordPress já vêm com estilos predefinidos que o usuário pode aplicar diretamente no editor. Um bom exemplo é o bloco Imagem (core/image), que inclui o estilo Rounded por padrão. No entanto, o raio aplicado nesse estilo costuma ser exagerado, fazendo com que a imagem fique mais oval do que visualmente refinada.
Em vez de ajustar manualmente o raio da borda para cada imagem, uma abordagem melhor é personalizar o estilo arredondado de modo que ele aplique um raio de canto mais refinado, talvez adicionando uma sombra sutil para um visual moderno. Assim, os usuários podem aplicar um estilo profissional com apenas um clique, sem precisar modificar configurações toda vez.
Vamos usar o estilo Rounded no bloco Imagem e personalizá-lo para que os cantos sejam ligeiramente arredondados em vez de excessivamente curvados, e uma sutil sombra de caixa seja adicionada para dar uma aparência mais refinada.
Como o editor de blocos permite o registro e o cancelamento do registro de estilos de blocos, podemos remover o estilo Rounded padrão e substituí-lo por uma versão personalizada.
Veja como fazer isso:
function modify_image_block_rounded_style() {
// Remove the default "Rounded" style
unregister_block_style( 'core/image', 'rounded' );
// Register a new "Rounded" style with custom CSS
register_block_style(
'core/image',
array(
'name' => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'inline_style' => '
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjust this value */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Optional shadow */
}
',
)
);
}
add_action( 'init', 'modify_image_block_rounded_style' );O código substitui o estilo padrão excessivamente arredondado por uma versão refinada que aplica border-radius: 20px; para cantos mais suaves e box-shadow para uma elevação sutil.
Usando um arquivo CSS externo em vez de inline_style
Embora o estilo inline funcione bem para estilos simples, ele não é ideal para manutenção. A melhor prática é definir o estilo em um arquivo CSS externo e carregá-lo com o WordPress.
Para fazer isso, crie um novo arquivo CSS, por exemplo, custom-block-styles.css, e adicione o seguinte:
/* Custom Rounded Image Block Style */
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjusted rounded corners */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Subtle shadow */
}Enfileire esse arquivo CSS no functions.php:
function enqueue_custom_block_styles() {
wp_enqueue_style(
'custom-block-styles',
get_template_directory_uri() . '/css/custom-block-styles.css',
array(),
'1.0'
);
}
add_action('wp_enqueue_scripts', 'enqueue_custom_block_styles');
add_action('enqueue_block_editor_assets', 'enqueue_custom_block_styles');Agora, em vez de usar o estilo em linha, você pode registrar o estilo sem incorporar o CSS diretamente no PHP:
register_block_style(
'core/image',
array(
'name' => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'style_handle' => 'custom-block-styles'
)
);Dessa forma, você pode modificar estilos sem tocar no PHP.
Registrando variações de bloco
As variações de bloco permitem que você crie versões predefinidas de um bloco com configurações personalizadas, facilitando aos usuários a aplicação de designs consistentes com um único clique. Em vez de modificar manualmente as configurações de um bloco a cada vez, uma variação permite que você insira um bloco que já tenha os atributos, estilos ou configurações corretos aplicados.
Alguns blocos principais do WordPress realmente funcionam dessa forma. O bloco Embed não é um bloco único – é um conjunto de variações para diferentes plataformas, como YouTube, Twitter e Spotify. O bloco Row e o bloco Stack também são apenas variações do bloco Group, cada um com diferentes configurações de layout.
Essa abordagem mantém as coisas modulares, permitindo que o WordPress forneça experiências personalizadas enquanto usa uma estrutura subjacente compartilhada.
Criando uma variação de Depoimento para o bloco de Citação (Quote)
Embora o WordPress não tenha um bloco de Depoimento dedicado, o bloco de Citação (core/quote) pode ser adaptado para essa finalidade. Em vez de fazer com que os usuários adicionem manualmente uma imagem, alinhem o texto e formatem tudo, podemos definir uma variação de Depoimento para o bloco de Citação.
Essa variação inclui automaticamente um bloco de Imagem, um bloco de Citação e dois blocos de Parágrafo para o nome da pessoa e a empresa. Isso garante que cada depoimento siga o mesmo formato estruturado sem exigir ajustes extras.
Para registrar uma variação de bloco no WordPress, usamos registerBlockVariation() em JavaScript. Como as variações de bloco são tratadas no lado do cliente, precisamos carregar um arquivo JavaScript que registre nossa variação personalizada de Depoimento.
Para implementar isso, crie um arquivo JavaScript (como custom-block-variations.js) que defina a variação de Depoimento para o bloco de Citação. Você pode criar esse arquivo no diretório assets/js/ do seu tema e adicionar o seguinte código:
wp.domReady(() => {
wp.blocks.registerBlockVariation(
'core/quote',
{
name: 'testimonial',
title: 'Testimonial',
description: 'A variation of the Quote block for testimonials.',
category: 'text',
attributes: {
className: 'is-style-testimonial',
},
innerBlocks: [
['core/image', { align: 'center', width: 100, height: 100 }],
['core/quote'],
['core/paragraph', { placeholder: 'Name', align: 'center', fontSize: 'medium', className: 'testimonial-name' }],
['core/paragraph', { placeholder: 'Company / Role', align: 'center', fontSize: 'small', className: 'testimonial-company' }]
],
scope: ['inserter'],
}
);
// Inject inline styles for the editor preview
const style = document.createElement('style');
style.innerHTML = `
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial p {
margin-bottom: 12px;
font-size: 1.1em;
}
.wp-block-quote.is-style-testimonial cite {
font-weight: bold;
display: block;
margin-top: 10px;
color: #0073aa;
}
.wp-block-quote.is-style-testimonial .wp-block-image {
display: flex;
justify-content: center;
margin: 0 auto 12px;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
`;
document.head.appendChild(style);
});No código acima, registerBlockVariation() define a variação de Depoimento (Testimonial) do bloco de Citação (Quote), pré-carregando um bloco de Imagem, um bloco de Citação e dois blocos de Parágrafo para o nome da pessoa e a empresa. O bloco de Imagem é centralizado com 100×100 pixels para manter uniformidade nas fotos de perfil, enquanto o bloco de Citação permanece inalterado como texto do depoimento.
Uma classe personalizada (is-style-testimonial) é aplicada para estilização, fornecendo ao bloco um fundo claro, sombra sutil e texto centralizado. A borda esquerda padrão é removida, e a imagem mantém sua proporção com cantos levemente arredondados para um visual mais refinado.
Em seguida, como o arquivo JavaScript precisa ser carregado dentro do editor de blocos, devemos enfileirá-lo (enqueue) no functions.php.
function enqueue_custom_block_variations() {
wp_enqueue_script(
'custom-block-variations',
get_template_directory_uri() . '/assets/js/custom-block-variations.js',
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
filemtime( get_template_directory() . '/assets/js/custom-block-variations.js' ),
true
);
}
add_action( 'enqueue_block_editor_assets', 'enqueue_custom_block_variations' );Isso garante que a variação de bloco de Depoimento apareça dentro do editor de blocos.
Embora o código JavaScript assegure que o bloco apareça corretamente no editor, também precisamos aplicar os estilos no frontend para que os depoimentos sejam exibidos corretamente quando publicados. Adicione o seguinte código ao functions.php:
function register_testimonial_block_style() {
register_block_style(
'core/quote',
array(
'name' => 'testimonial',
'label' => __( 'Testimonial', 'your-text-domain' ),
'inline_style' => '
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
',
)
);
}
add_action( 'init', 'register_testimonial_block_style' );Agora, sempre que um usuário inserir um bloco de depoimento, ele já incluirá os campos de imagem, citação, nome e empresa, todos pré-formatados e estilizados corretamente. Isso elimina a necessidade de ajustes manuais, garantindo que todos os depoimentos sigam a mesma estrutura limpa e profissional.
Em vez de forçar os usuários a criar depoimentos do zero, essa variação de bloco oferece um fluxo de trabalho simplificado que aprimora a criação de conteúdo e mantém a consistência do design do site.
Caso de uso avançado: Combinando as APIs de Supports e Styles para criar botões com identidade visual da marca
Agora que você já sabe o que cada API faz e como funciona, que tal ir um pouco além? Em vez de usar a API de Supports ou a de Styles separadamente, podemos combiná-las para resolver um problema comum: manter a consistência visual do design ao mesmo tempo em que damos ao usuário uma forma estruturada de aplicar os estilos corretos.
Vamos considerar um cenário real: uma empresa quer que todos os botões do seu site sigam regras rígidas da identidade visual. Eles não querem que os usuários escolham cores aleatórias, alterem o espaçamento ou usem tipografias diferentes. No entanto, querem manter certa flexibilidade — permitindo que os usuários escolham entre dois estilos de botão pré-aprovados:
-
Botão Primário — O principal call-to-action, com fundo sólido e estilo marcante.
-
Botão Secundário — Um botão mais discreto, com borda e aparência menos destacada, ideal para ações secundárias.
Para fazer isso, precisamos:
- Usar a API Styles para definir os dois estilos de botão.
- Usar a API Supports para remover configurações desnecessárias, garantindo que os usuários não substituam manualmente a marca alterando as cores, o espaçamento ou a tipografia.
Combinando as duas APIs, permitimos escolhas estruturadas e, ao mesmo tempo, evitamos que os usuários quebrem o sistema de design.
Etapa 1: Definindo estilos personalizados para botões
Comece adicionando o seguinte código ao arquivo functions.php:
function register_custom_button_styles() {
register_block_style(
'core/button',
array(
'name' => 'primary-button',
'label' => __( 'Primary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-primary-button .wp-block-button__link {
background-color: #4D4D4D;
color: #ffffff;
padding: 12px 24px;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: 2px 2px 6px rgba(0, 0, 0, 0.1);
}
',
)
);
register_block_style(
'core/button',
array(
'name' => 'secondary-button',
'label' => __( 'Secondary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-secondary-button .wp-block-button__link {
background-color: transparent;
color: #4D4D4D;
padding: 12px 24px;
border: 1px solid #4D4D4D;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: none;
}
',
)
);
}
add_action( 'init', 'register_custom_button_styles' );Agora, ao inserir um bloco de Botão, os usuários verão as opções Botão Primário e Botão Secundário como estilos disponíveis.
O botão principal tem um fundo cinza escuro sólido, enquanto o botão secundário tem um fundo transparente com uma borda. Ambos mantêm padding, bordas arredondadas e estilização de fonte consistentes — garantindo uma aparência profissional em todo o site.
Etapa 2: Restringindo a personalização dos botões
Embora os estilos dos botões estejam agora predefinidos, os usuários ainda podem substituí-los manualmente usando as configurações do editor de blocos do WordPress. Se eles alterarem as cores, o preenchimento ou a tipografia, os botões poderão não corresponder mais às diretrizes da marca.
Podemos usar a API de suporte para desativar essas opções de personalização, evitando que os usuários façam alterações não intencionais. Adicione isso a functions.php:
function restrict_button_customization($args, $block_type) {
if ($block_type === 'core/button') {
// Disable specific color settings (text, background, link)
$args['supports']['color'] = [
'text' => false,
'background' => false,
'link' => false,
];
// Disable typography settings (font size, font weight, line height)
$args['supports']['typography'] = false;
// Disable spacing settings (padding, margin)
$args['supports']['spacing'] = false;
}
return $args;
}
add_filter('register_block_type_args', 'restrict_button_customization', 10, 2);Com isso em vigor:
- Os usuários não podem alterar as cores dos botões, portanto, todos os botões devem aderir ao esquema de cores da marca.
- Os controles de tipografia são removidos, mantendo a formatação do texto consistente.
- Os ajustes de espaçamento são desativados, impedindo que os usuários modifiquem o preenchimento e as margens.
Agora, em vez de permitir que os usuários criem uma mistura aleatória de estilos de botão, eles simplesmente escolherão entre os estilos primário e secundário, mantendo o design profissional e estruturado.
Resumo
Este artigo abordou apenas a superfície do que é possível com a personalização de blocos no WordPress. A plataforma oferece uma ampla variedade de APIs que facilitam a extensão e a customização de blocos, permitindo que desenvolvedores adaptem a experiência do editor sem perder a estrutura nem a facilidade de uso.
Se você quer dominar a personalização de blocos, há muito mais a explorar. Consulte a documentação oficial para desenvolvedores WordPress, participe de WordCamps e encontros e continue aprendendo com ótimos recursos, como o blog da Kinsta, onde regularmente detalhamos conceitos avançados do WordPress.
Claro, contar com uma hospedagem confiável torna todo esse processo de testes e experimentações muito mais tranquilo. Seja para experimentar novas modificações em blocos ou para administrar um site de alto tráfego, a Kinsta garante desempenho, segurança e escalabilidade. Na verdade, fomos recentemente classificados como o número 1 em hospedagem de WordPress pelo G2, graças a mais de 930 avaliações de clientes.
Isso diz muito por si só: você pode confiar na Kinsta para potencializar sua experiência com WordPress.
