Como adicionar estilos de bloco personalizados aos blocos do WordPress Gutenberg

Um recurso um pouco menos conhecido no Gutenberg é a opção de configurar estilos diferentes para blocos. Você pode registrar tantos estilos diferentes em qualquer tipo de bloco para dar ao mesmo bloco designs diferentes. Estilos possíveis para blocos são exibidos como uma seção no lado direito do editor. Cada estilo recebe sua própria visualização. Se você estiver manipulando estilos corretamente, alternar entre estilos deve atualizar imediatamente o design dentro do editor, bem como no frontend.

A documentação do WordPress para esse recurso não é tão completa e informativa quanto poderia ser. Então, neste post, vamos dar uma olhada detalhada em como você pode adicionar seus estilos de bloco personalizados e como você deve lidar com o estilo deles.

A forma como este recurso funciona é que sempre que o Gutenberg detecta que um tipo de bloco registrou no mínimo um estilo, a caixa "Estilos" aparecerá automaticamente no lado direito do editor. Dentro dela o editor pode escolher entre o estilo padrão ou qualquer estilo de bloco que foi adicionado.

Em versões anteriores (pelo menos antes do WordPress 5.3), registrar um estilo personalizado exigia que você também registrasse o estilo padrão (“sem estilo"). Felizmente, isso foi corrigido nas versões mais recentes do WordPress, então agora você só precisa registrar seus estilos personalizados e o WordPress adicionará o estilo padrão automaticamente.

Você pode registrar estilos de bloco personalizados de duas maneiras; com PHP ou com Javascript. Vamos dar uma olhada em ambos. Mas primeiro alguns a-ha’s sobre como lidar com seus estilos.

Uma nota sobre estilos de enfileiramento para Gutenberg

Pode haver alguma confusão sobre como e onde adicionar seus estilos (arquivos CSS); apenas para o editor, para o frontend ou uma folha de estilo para ambos. Um dos principais objetivos do editor Gutenberg é garantir que você possa visualizar corretamente a aparência do conteúdo do seu post, dentro do editor. Portanto, é recomendável que você certifique-se de que seus estilos personalizados sejam aplicados no editor e também no frontend.

Como você lida com isso realmente depende do seu projeto e da configuração da folha de estilo existente. Se você estiver desenvolvendo um tema completo, provavelmente já incluiu estilo de bloco dentro de sua folha de estilo frontend. Você pode considerar adicionar uma folha de estilo separada que enfileirará apenas para o editor. Mas isso pode ser difícil de manter se você adicionar muitos estilos diferentes. Você teria que atualizar seus estilos em dois lugares e garantir que seus resultados sejam os mesmos. A solução para isso seria manter uma folha de estilo que você enfileira para o editor e o frontend. Mas então seu frontend precisaria carregar pelo menos duas folhas de estilo separadas e isso pode não ser o ideal.

Outra solução é usar, por exemplo, SCSS ou LESS e configurar de @importstal forma que você só precise escrever seus estilos de bloco uma vez, e é aplicado tanto ao editor quanto ao frontend. Como você verá abaixo ao usar o PHP para registrar estilos de blocos personalizados, você ainda tem outra opção; para adicionar estilos embutidos. Esses estilos serão aplicados no editor e no frontend. No frontend, eles serão adicionados pelo WordPress como uma linha personalizada <style type="text/css">...</style>dentro do cabeçalho.

Seja como for que você decida resolvê-lo, saiba que existem alguns novos ganchos para estilos de registro (e scripts) para o Gutenberg. Se você deseja enfileirar uma folha de estilo para frontend e editor, use o gancho enqueue_block_assets. Se você quiser adicionar uma folha de estilo apenas para o editor, coloque-a na fila dentro do gancho enqueue_block_editor_assets.

Como aplicar estilo aos estilos de bloco personalizados

Estilos de bloco personalizados serão adicionados como uma classe de um determinado padrão na tag HTML mais externa do bloco.

A classe CSS para estilos de bloco é adicionada na forma de ” is-style-<stylename>“. Se você, por exemplo, nomear seu estilo ” outline“, o bloco receberá a classe ” is-style-outline“.

No entanto, você pode perceber que o editor Gutenberg, em alguns casos, substituirá seu estilo. Eu recomendo prefixar o estilo do seu editor com o seletor editor-styles-wrapperpara garantir que seus estilos “vençam”. Lembre-se de que essa classe não existe no frontend, portanto, para estar seguro, talvez seja necessário adicionar dois seletores, assim (se você estiver usando a mesma folha de estilo para o editor e o frontend):

.is-style-colored-bottom-border, 
.editor-styles-wrapper .is-style-colored-bottom-border { 
    border-bottom: 2px solid purple;
}

Adicionando estilos de bloco personalizados com PHP

Para adicionar um tipo de bloco personalizado usando PHP, usamos a função [register_block_style](https://developer.wordpress.org/reference/functions/register_block_style/)(). A documentação infelizmente está sem informações em qual hook devemos usar, mas tive sorte com o hook init.

Você precisa saber o nome do namespace Gutenberg do seu tipo de bloco para adicionar um estilo personalizado a ele. Todos os blocos padrão do WordPress têm o namespace ” core” seguido por um /e uma versão slug de seu nome. Por exemplo, o nome de Gutenberg para o bloco de parágrafo padrão é core/paragraph.

O registro de um estilo de bloco personalizado é feito em sua forma mais simples, assim:

O código acima adiciona um estilo de bloco personalizado ao tipo de bloco Heading, o que resultaria na classe is-style-colored-bottom-borderem qualquer Heading que tenha escolhido esse estilo.

Esta função fornece dois métodos para adicionar seu CSS (se você não o adicionou de outra forma); fornecendo CSS inline como uma string ou fornecendo um identificador de folha de estilo registrado que o WordPress enfileirará para você, se necessário.

Se você deseja adicionar estilo inline (lembre-se, isso afetará o editor e o frontend), adicione o elemento ‘ inline_style‘ à chamada da função e escreva o CSS completo como uma string como seu valor:

Se você preferir fazer a função enfileirar uma folha de estilo, forneça seu identificador para o elemento ‘ style_handle‘.

Ajuste a localização da sua folha de estilo para se adequar ao seu projeto. A folha de estilo será aplicada ao editor e ao frontend, mas desta vez o frontend fará uma solicitação separada para incluir esta folha de estilo. Este método não é recomendado se você estiver adicionando vários estilos de bloco. O frontend ficará significativamente mais lento ao solicitar um monte de folhas de estilo separadas.

Adicionando estilos de bloco personalizados com Javascript

Se você preferir adicionar seus estilos de bloco usando Javascript, isso é tão fácil quanto com PHP.

Você precisará enfileirar um arquivo Javascript no gancho apenas do editor: enqueue_block_editor_assets. Seu script provavelmente não precisará de nenhuma dependência, mas eu prefiro adicionar pelo menos ‘ wp-blocks‘ como dependência.

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks']
    );
});

Ajuste o nome do arquivo e o local para se adequar ao seu projeto.

Em seu arquivo Javascript, você usa a função registerBlockStyle()dentro do wp.blocksobjeto para registrar estilos de bloco personalizados. Adicionar o mesmo estilo de bloco que fizemos no PHP acima ficaria assim:

wp.blocks.registerBlockStyle('core/heading', {
    name: 'colored-bottom-border',
    label: 'Colored bottom border'
});

E é isso! Mole-mole.

Cancelando o registro de estilos de bloco

Assim como você pode registrar um estilo de bloco, um estilo de bloco também pode ser desregistrado. Talvez você queira remover alguns dos estilos de bloco padrão do WordPress? Assim como no registro de estilos de bloco, você também pode cancelar o registro de estilos de bloco com PHP ou Javascript. Mas a escolha entre esses dois métodos não é mais uma escolha de preferência.

Você não pode cancelar o registro de um bloco com PHP se ele foi registrado com Javascript e vice-versa. Portanto, você precisa descobrir como o estilo que deseja remover foi registrado e combiná-lo com PHP ou Javascript. Eu acredito que todos os estilos de bloco do WordPress são adicionados com Javascript (não me cite sobre isso!). Portanto, se você quiser remover alguns deles, precisará seguir a rota do Javascript.

Cancelar o registro de um estilo de bloco com PHP é feito chamando a função unregister_block_style(), fornecendo o tipo de bloco e o nome do estilo que você deseja remover. Por exemplo, cancelar o registro do estilo adicionado acima neste post (assumindo que foi registrado com PHP) ficaria assim:

add_action('init', function() {
    unregister_block_style('core/heading', 'colored-bottom-border');
});

Cancelar o registro de um estilo de bloco com Javascript é feito de forma semelhante com a função unregisterBlockStyle()dentro do wp.blocksobjeto. No entanto, com o Javascript, há uma questão de qual script deve ser executado primeiro, e você pode encontrar problemas quando seu script é executado antes do registro. Para resolver isso, usamos o equivalente do Gutenberg ao “document ready” do jQuery (jQuery(document).ready(function() { ... });), e também adicionamos outra dependência ao seu script.

Vamos começar adicionando uma nova dependência de script em seu arquivo Javascript enfileirado para ‘ wp-edit-post‘:

add_action('enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'myguten-script', 
        get_template_directory_uri(). '/assets/js/myguten.js', 
        ['wp-blocks', 'wp-edit-post']
    );
});

E dentro do seu arquivo Javascript, coloque sua chamada de função unregister dentro wp.domReady(function() { ... })de, assim:

wp.domReady(function() {
    wp.blocks.unregisterBlockStyle('core/quote', 'large');
});

Como o código acima mostra, com Javascript agora podemos remover o estilo “Large” do WordPress no bloco Quote. Se você tentasse fazer o mesmo com PHP, não funcionaria.

Uma nota lateral sobre como cancelar o registro de estilos de bloco

Você pode notar que, embora tenha removido com sucesso qualquer estilo de bloco personalizado em um bloco, a caixa "Estilos" no editor não desaparecerá. Ele permanece apenas com a opção “Default” dentro dele. Se você deseja remover completamente a caixa “Estilos” para não confundir os editores, você pode simplesmente cancelar o registro do estilo padrão também (por exemplo, wp.blocks.unregisterBlockStyle('core/quote', 'large')). Isso removerá totalmente a caixa "Estilos" do editor Gutenberg.