Como adicionar configurações de cores ao seu bloco Gutenberg personalizado

Este post se aprofundará em como adicionar configurações de cores ao seu bloco WordPress Gutenberg personalizado. Aprenderemos como adicionar o mesmo componente de configurações de cores, que apresenta a escolha de cores da paleta e cores personalizadas, como muitos dos blocos padrão do WordPress usam.

Isto é o que adicionaremos ao nosso bloco personalizado:

Ao usar os componentes do Gutenberg, podemos facilmente implementar esta paleta/seção de cores em nosso próprio bloco personalizado. Você pode definir as configurações de cor para afetar qualquer cor desejada; fundo, cor do texto, cor da borda ou qualquer outra coisa. Você também pode adicionar quantas configurações de cores desejar dentro deste painel.

Antes de mergulharmos no código, há algumas coisas que você precisa estar ciente. Não pule para o código, pois a próxima seção explicará muito por que o código precisa fazer isso como faz.

O que você precisa saber primeiro

Os componentes para implementar as configurações de paleta/cor são PanelColorSettingse withColorsdo wp.blockEditorpacote. O componente withColorsé chamado de componente de ordem superior e precisa ser implementado de forma um pouco diferente do que simplesmente gerar um componente normal. Entrarei em um pouco mais de detalhes mais adiante. Mas primeiro precisamos estar cientes do básico sobre como o Gutenberg lida com as configurações de cores de bloco.

Como os blocos Gutenberg lidam com as configurações de cores

Existem certas regras sobre como o Gutenberg lida com as configurações de cores em blocos. Se você já estilizou um tema compatível com Gutenberg antes, provavelmente já está familiarizado com essas regras. Nós vamos passar por eles rapidamente, no entanto, porque temos que lidar com isso em nosso código de bloco.

• Quando uma cor de paleta é escolhida, o elemento do bloco de nós receberá uma classe de um determinado padrão. A classe começa com ” has-“, e depois vem o slug da paleta. O final depende de qual elemento a cor deve afetar. Para cor de texto termina com ” -color“. Para cor de fundo, termina com ” -background-color“. Como exemplo, um bloco com a cor da paleta “vermelho" escolhida como cor de fundo receberá a classe ” has-red-background-color“.
• Quando uma cor personalizada é escolhida (no seletor de cores), o elemento do bloco de nó obterá um estilo embutido com o código hexadecimal. Por exemplo, uma cor personalizada #DD0000 escolhida para a cor de fundo receberá o atributo ” style="background-color: #DD0000;“.

Quando implementarmos as configurações de cores para o nosso bloco, precisaremos implementar a classe e o estilo inline corretos. Faremos isso no final deste tutorial.

Como trabalhar comwithColors

Como mencionado anteriormente withColors, é um componente de ordem superior. O que isso basicamente significa que é um componente que recebe um componente e retorna um novo componente. No componente retornado, obtemos props úteis do componente de ordem superior. Simplificando, usaremos withColorspara retornar nosso próprio componente para nosso bloco personalizado. Nosso componente de bloco obtém os adereços necessários para trabalhar com cores do withColors.

O componente withColorslida com o estado e muitas funcionalidades para trabalhar com cores. E temos muita automação nesse processo. Isso é muito útil para descobrir se a cor escolhida é uma cor de paleta (precisamos adicionar uma classe) ou uma cor personalizada (precisamos adicionar um estilo embutido). withColorssimplificar muito o processo de armazenamento da cor escolhida, seja ela qual for, nos atributos do nosso bloco. Falando em atributos..

Atributos ewithColors

Obviamente seu bloco precisa de atributos para armazenar a cor escolhida. Para se beneficiar da automação do withColor para armazenar a cor correta, você precisa definir dois atributos para cada configuração de cor. Um para armazenar o slug da cor da paleta e outro para armazenar o código hexadecimal. Existem algumas regras embora.

Digamos que você queira adicionar uma configuração de cor para a cor do texto do bloco – então você decide definir um atributo apropriadamente chamado ” textColor“. Você precisará então definir outro atributo no padrão ” customYourOriginalAttribute“. Neste exemplo, o segundo atributo precisará ser nomeado ” customTextColor“. Lembre-se do camelCase (capitalização) aqui. Seguir este padrão withColorsirá automaticamente:

• Se uma cor de paleta foi escolhida, o atributo ” textColor” conterá o slug da paleta.
• Se uma cor personalizada foi escolhida, ” customTextColor” será preenchido com o código hexadecimal.

Esses dois trabalham em conjunto. Se uma cor personalizada for escolhida, textColorserá automaticamente undefinede vice-versa.

E, finalmente, uma última coisa a lembrar: você não precisará usar setAttributes()para atualizar seus atributos de cor! Os adereços fornecidos withColorsincluem uma função que atualiza automaticamente seus atributos para você. Tudo que você precisa fazer é passar esta função para o onChangeevento para o PanelColorSettingscomponente, e seus atributos serão atualizados automaticamente.

Ok, é hora de ver tudo isso na prática!

Implementando configurações de cores em um bloco personalizado

Para começar, tenho um bloco personalizado bastante inútil que não faz nada além de exibir um texto codificado. Isso apenas facilita a separação do que precisamos codificar para adicionar configurações de cores. Eu tenho uma série de tutoriais sobre como criar seus próprios blocos personalizados se você estiver interessado em aprender mais.

Nota: estou escrevendo todo o código em ES6/ESNext. Isso inclui funções de seta que requerem cuidados especiais na configuração do seu Babel/webpack. Se você estiver recebendo erros em alguns dos códigos abaixo, siga meu guia sobre como configurar o Webpack e o Babel para ES6/ESNext ou ajuste o código para não usar “sintaxes experimentais”.

Este é o meu bloco personalizado básico antes de fazer qualquer coisa com as configurações de cores:

É bem básico. Observe que a editfunção está simplesmente se referindo a um componente separado, BlockWithColorSettings, em vez de escrevê-lo embutido. Isso facilita a implementação withColorsposterior.

Ok, hora de implementar as configurações de cores em nosso bloco! Como exemplo, quero configurar a cor do texto.

Adicionando atributos

Como mencionado anteriormente, precisamos definir dois atributos para cada configuração de cor. E precisamos ter um cuidado extra em sua nomenclatura. Eu quero adicionar um atributo de cor de texto, então estou nomeando o atributo textColor. O que significa que também adicionarei um atributo customTextColor. Ambos devem ser do tipo string.

Nossos atributos estão prontos para armazenar a configuração de cor do texto do bloco. Agora é hora de implementar withColorse PanelColorSettings.

ImplementaçãowithColors

Como mencionado anteriormente withColors, é um componente de ordem superior que deve receber um componente para retornar. Obviamente, queremos que ele retorne nosso componente de edição, BlockWithColorSettings. Mas como parâmetro para withColorsnós fornecemos um objeto.

No objeto passado withColorsprecisamos dizer withColorsqual atributo queremos usar para armazenar a cor e que tipo de elemento ele irá colorir (no nosso caso text color, que significa a regra CSS “color”). Informar sobre a regra CSS garante que os nomes das classes retornados estejam corretos. Como esta é a cor do texto, queremos nomes de classe como “has–color”.

Primeiro alguma desestruturação no topo. withColorsreside no wp.blockEditorpacote.

const { withColors } = wp.blockEditor;

Vamos mudar a editfunção para:

Com este código nosso componente BlockWithColorSettingsreceberá alguns adereços adicionais:

• props.textColor: É um objeto que consiste em todas as informações sobre a cor escolhida. Se uma cor de paleta foi escolhida, ela armazenará propriedades para código hexadecimal, slug de paleta, nome de classe e muito mais. Se uma cor personalizada foi escolhida, o objeto conterá o código hexadecimal. O código hexadecimal é sempre encontrado na propriedade color. E o nome da classe, (somente se for escolhida a cor da paleta) será definido na propriedade class.
• props.setTextColor: Uma função que atualizará nossos atributos para nós. Fornecemos isso para o onChangeevento das configurações de cores, como veremos mais adiante. A função atualizará os atributos textColore. customTextColorComo seguimos as regras de nomenclatura, ele será atualizado automaticamente, customTextColormesmo que nunca tenhamos fornecido esse nome de atributo.

Observe que a função “set” fornecida como prop seguirá a regra: ” setYourAttributeName“. Como fornecemos textColor, a função é denominada setTextColor. Se, em vez disso, nomeamos nosso atributo awesomeColore fornecemos isso no withColorsobjeto, a função set seria nomeada setAwesomeColor().

ImplementaçãoPanelColorSettings

A próxima etapa é implementar a seção Inspetor real. Para fazer isso, adicionamos PanelColorSettingsdentro de um InspectorControlscomponente. Como o React requer que tudo esteja dentro de um nó raiz, também usamos Fragment(from wp.elements) para envolver tudo dentro.

Primeiro alguma desestruturação no topo do arquivo:

const { Fragment } = wp.element;
const { InspectorControls, PanelColorSettings, withColors } = wp.blockEditor;

E atualizamos nosso BlockWithColorSettingscomponente para algo assim:

Como você pode ver na linha #2, desestruturamos os adereços recebidos de withColors, textColore setTextColor. Tenha em mente que props.textColoré o objeto recebido de withColors, e props.attributes.textColoré o atributo. No entanto, não precisamos nos referir ao atributo.

Como adereços para o componente PanelColorSettings, podemos fornecer um título para a seção (título na caixa recolhível no Inspector). O importante aqui é o prop colorSettingsonde precisamos fornecer uma matriz de objetos de configuração de cores. Para cada configuração de cor (atualmente temos apenas uma), precisamos fornecer algumas propriedades. A propriedade valueespera o código hexadecimal escolhido no momento (mesmo que uma cor de paleta tenha sido escolhida). Isso é fornecido para nós no textColorprop, dentro da propriedade color. Para a onChangepropriedade, simplesmente fornecemos a função “set” fornecida por withColors, setTextColor. E finalmente devemos dar um labelpara que o usuário saiba qual elemento essa cor afetará. Ele aparecerá logo acima da área de escolha de uma cor.

É assim que nosso componente aparece no editor Gutenberg agora:

Agora está atualizando com sucesso nossos atributos ao escolher as cores. Você pode ver que ele lembra sua escolha de cor ao salvar a postagem.

No entanto, nada acontece visualmente quando você altera as cores. A escolha da cor é armazenada nos atributos, mas nenhuma mudança de cor acontece no editor, nem na visualização do post. Isso ocorre porque precisamos adicionar código para as classes e estilos do bloco. Precisamos fazer isso tanto para a editfunção (que é para o editor) quanto para a savefunção (frontend). Esse é o próximo passo.

Manipulando classes e estilos embutidos emedit

Precisamos construir a classe de nó do bloco e os atributos de estilo de acordo com a configuração de cor escolhida. Felizmente withColors, temos alguma automação nisso. Lembre-se que props.textColoré um objeto que contém todas as informações que precisamos, incluindo o nome da classe.

Poderíamos fazer algo assim:

Na linha #20, aplicamos a classe crítica e o estilo inline ao nó raiz do nosso bloco. Antes disso, construímos a classe e o atributo de estilo inline verificando o props.textColorobjeto.

Após essa alteração, seu bloco personalizado agora deve estar totalmente funcional no editor. Sempre que você mudar de cor, o bloco mudará a cor do texto. Incrível! A etapa final é fazer isso savetambém para a função, para que possamos obter essas classes e estilos no frontend também.

Manipulando classes e estilos embutidos emsave

O conceito de construir a classe e os estilos embutidos e aplicá-los ao nó raiz é o mesmo saveno edit. Mas há uma diferença crucial. Em savenão temos os adereços fornecidos pelo withColors. E não podemos adicionar componentes de ordem superior à savefunção. Então na savefunção todas as informações que temos são os atributos.

É uma boa regra geral evitar codificar nomes de classe “tem-“. E se o WordPress decidir mudar essa regra no futuro? Felizmente, temos uma função que pode nos ajudar a gerar os nomes de classe apropriados para nós: getColorClassName().

Antes que esqueçamos, vamos desestruturar. Também está no wp.blockEditorpacote.

const { InspectorControls, PanelColorSettings, withColors, getColorClassName } = wp.blockEditor;

Usar a getColorClassName()função requer dois parâmetros. Primeiro uma string para a regra CSS. Como nossa configuração de cor é para a cor do texto, fornecemos ‘ color‘. Isso diz à função que ela deve retornar um nome de classe de “tem-algo-cor” e não “tem-algo-cor de fundo” por exemplo. Como segundo parâmetro, precisamos fornecer o valor do atributo.

O atributo style é construído simplesmente definindo “color” para o valor do atributo customTextColor, se estiver definido.

E, claro, não se esqueça de aplicar a classe e o estilo no nó raiz do seu bloco; como na linha #12.

PS: Se você estiver testando seu bloco no editor enquanto escreve este código, agora receberá um erro de bloco. Isso acontece porque agora alteramos a saída da savefunção e tudo o que você salvou anteriormente está em conflito. Você terá que remover o bloco e adicioná-lo novamente.

Após essa alteração, seu bloco agora deve aplicar corretamente a cor de texto escolhida no frontend também.

E é isso! Você agora implementou com sucesso as configurações de cores para o seu bloco. Se você estiver interessado em adicionar várias configurações de cores (não apenas a cor do texto), continue lendo.

Uma nota sobre várias configurações de cores

Até agora você deve ser capaz de implementar várias configurações de cores. Você pode querer adicionar configurações para cor de fundo, cor do texto, cor da borda ou qualquer outra coisa para o seu bloco. Nesta seção, farei uma rápida visão geral do que precisamos fazer para implementar várias configurações de cores.

Vamos supor que eu queira adicionar cor de fundo ao meu bloco também.

Primeiro eu preciso definir um novo atributo chamado backgroundColor. Eu defino outro atributo customBackgroundColortambém.

Na editfunção eu mudo o objeto fornecido withColorscomo tal:

withColors({textColor: 'color', backgroundColor: 'background-color'})

Isso informa withColorsque meu textColoratributo é para a regra CSS ” color” (para cor do texto), e o atributo backgroundColoré para a regra CSS ” background-color“. withColorsreconhecerá e atualizará automaticamente os atributos customTextColore também.customBackgroundColor

No PanelColorSettingscomponente, forneço outro objeto ao array para o prop colorSettings. Igual a:

Com isso, você deve obter duas configurações de cores separadas dentro da caixa Inspetor para configurações de cores.

A última etapa é construir os nomes e estilos de classe apropriados em ambos edite save. Este é um passo bem simples, pois está apenas construindo uma string ou objeto de estilo corretamente. Lembre-se de que o nome da sua classe deve suportar várias classes de cores (por exemplo, se a cor do texto e a cor de fundo foram escolhidas). Basta adicionar um espaço entre cada nome de classe.

PS: Se você precisar lidar com muitos nomes de classe para o seu bloco, poderá se beneficiar da instalação do classnamespacote. Praticamente todos os componentes do Gutenberg usam essa biblioteca para combinar nomes de classe mais facilmente.

Conclusão e código completo

Agora você deve ter aprendido como implementar configurações de cores em seu bloco personalizado. Espero que isso tenha sido de alguma utilidade para você! Eu tive que adicionar esse recurso ao meu projeto e realmente não consegui encontrar nenhuma informação ou boa documentação. Então esse é o resultado de consolidar tudo o que aprendi sobre esse tema, depois de muita tentativa e erro.

Aqui está o código final, ao todo, para o exemplo de bloco personalizado com configuração de cor do texto: