Criar bloco personalizado do Gutenberg – Parte 6: barras de ferramentas
Neste post vamos aprender como adicionar as barras de ferramentas do WordPress ao nosso bloco, ou seja, para alinhamento e alinhamento de blocos. Também aprenderemos a adicionar nossas próprias barras de ferramentas com nossos próprios botões para fazer ações personalizadas.
Adicionando barras de ferramentas
Para adicionar algo à barra de ferramentas do nosso bloco, precisaremos envolver o que queremos dentro de um componente chamado BlockControls
(de wp.blockEditor
). Dentro deste componente, podemos adicionar um dos componentes do WordPress para as barras de ferramentas padrão que conhecemos de outros blocos (por exemplo, alinhamento) ou podemos adicionar nossa própria barra de ferramentas.
Por padrão, um bloco terá uma barra de ferramentas contendo apenas o ícone do bloco (para a funcionalidade Transformar em) e o menu do bloco para, por exemplo, remover o bloco. Não podemos removê-los, mas podemos adicionar nossos próprios botões e barras de ferramentas entre eles.
No entanto, alguns componentes do WordPress adicionarão suas próprias barras de ferramentas. A partir de agora, nosso bloco mostra uma barra de ferramentas para formatação de texto que vem do RichText
componente que adicionamos.
Adicionando uma barra de ferramentas de alinhamento de bloco
A barra de ferramentas de alinhamento de blocos existe em praticamente todos os tipos de blocos do WordPress, então vamos adicioná-la ao nosso bloco também. Nos bastidores existe um componente BlockAlignmentToolbar
que poderíamos adicionar, mas não recomendo. Usá-lo requer que você manipule manualmente as classes para alinhamento de blocos e certifique-se de que o bloco estenda sua largura no editor ao escolher “Wide Width" ou “Full Width”. Felizmente, o WordPress tornou muito fácil implementá-lo, totalmente automático.
PS: O tema ativo deve ter adicionado suporte de tema ativamente para esses dois alinhamentos de blocos. Você pode adicionar suporte para isso usando add_theme_support('align-wide')
o after_setup_theme
hook.
Podemos adicionar uma nova propriedade à nossa configuração de objeto em registerBlockType()
, chamada supports
. Existem alguns outros recursos, mas o que nos interessa aqui é align
. Podemos definir align
para true
adicionar todos os alinhamentos possíveis ou fornecer uma matriz de quais alinhamentos permitimos para nosso bloco.
O que nos dá isso no editor:
Se você quiser, por exemplo, impedir que alguém use Wide Width ou Full Width, você pode fornecer um array e excluir esses dois. Os nomes dos alinhamentos de blocos são os seguintes: left
, right
, center
, wide
e full
.
supports: {
align: ['left', 'right', 'center']
},
Precisa de alinhamento padrão?
Por padrão, o bloco não recebe alinhamento de bloco. Se você quiser, pode definir um padrão criando um atributo com a chave align
, defina o tipo string
e defina o padrão lá. O WordPress conectará automaticamente este atributo ao alinhamento do bloco.
attributes: {
align: {
type: 'string',
default: 'center'
}
},
supports: {
align: true
},
Com isso sempre que um novo bloco do nosso tipo é criado, o alinhamento do bloco padrão é centralizado.
Bloquear bagunça de estilo de alinhamento? Não é nossa culpa
Nota: O estilo de bloco padrão do WordPress atrapalhará o fluxo do conteúdo do seu post ao usar o alinhamento de bloco esquerdo e direito. A mesma coisa acontece com outros tipos de blocos do WordPress e não é um problema exclusivo do nosso bloco. Isso é causado pela adição de float ao elemento, que recolhe o elemento pai. Acredite, eu tentei construir o bloco para evitar esse problema. A única coisa que descobri estar funcionando corretamente sem mexer com os outros alinhamentos de blocos é adicionar estilo ao editor e ajustar o estilo flutuante.
Independentemente disso, o WordPress facilitou bastante a implementação do alinhamento de blocos. Agora vamos ver outras barras de ferramentas que podemos usar.
Adicionando uma barra de ferramentas de alinhamento de texto
Se você preferir a barra de ferramentas para alinhamento de texto, você pode fazer isso em vez de alinhamento de bloco – nesta barra de ferramentas temos apenas alinhamento à esquerda, centralizado e à direita. Na verdade, você pode usar alinhamento de texto e alinhamento de bloco juntos – eles funcionam separadamente. Para não confundir os usuários, você pode, por exemplo, apenas adicionar suporte para alinhamento de bloco de largura e largura total e usar a barra de ferramentas de alinhamento de texto para controlar o alinhamento à esquerda, ao centro ou à direita. Ao fazer isso, você evita o problema mencionado acima com o fluxo de blocos no editor. Cabe a você como você quer que seu bloco funcione.
O WordPress tem um componente para gerar a barra de ferramentas de alinhamento de texto, mas não há manipulação automática de adicionar as classes corretas para realmente alinhar o conteúdo – tanto dentro do editor quanto no frontend (até onde eu encontrei, pelo menos!). Precisamos adicionar e atualizar manualmente um atributo para o alinhamento do texto.
Adicionando BlockControls
eAlignmentToolbar
Vamos finalmente adicionar BlockControls
à nossa edit
função para nossa saída na barra de ferramentas. O componente para alinhamento de texto é AlignmentToolbar
de wp.blockEditor
package.
Observe que excluí o conteúdo de tudo o que criamos na InspectorControls
etapa anterior para encurtar o código.
Na linha intermediária #37
a #42
está todo o conteúdo da nossa barra de ferramentas (além do alinhamento do bloco adicionado automaticamente pela supports
propriedade e a formatação do texto adicionada pelos nossos RichText
componentes). Usamos BlockControls
para acessar a barra de ferramentas, e dentro adicionamos o AlignmentToolbar
componente.
Como já fizemos várias vezes com entradas, fornecemos uma value
prop para mostrar o valor salvo e uma onChange
prop para atualizar nosso atributo para o AlignmentToolbar
componente. O atributo que usaremos para armazenar o alinhamento de texto escolhido é definido como textAlignment
e deve ser type string
. Como de costume, você pode fornecer um default
para garantir que os blocos recém-criados obtenham um alinhamento padrão.
Para garantir que o bloco produza as informações de alinhamento e também seja estilizado corretamente (para que realmente vejamos o alinhamento do texto mudar) tanto no editor quanto no frontend, precisamos configurar manualmente a classe correta no div de encapsulamento. Em ambos edit
e save
defino uma variável que verifica se attributes.textAlignment
está definida. Se for, eu construo o nome da classe seguindo os padrões do WordPress para alinhamentos de texto, que é “has-text-align-(left|center|right)”. Com esta classe, o WordPress aplicará seu estilo em nosso bloco e garantirá que nosso bloco seja alinhado visualmente corretamente, tanto no editor quanto no frontend.
Adicionando barras de ferramentas personalizadas com nossos próprios botões
Você também pode adicionar seus próprios botões na barra de ferramentas para fazer o que quiser ao clicar neles. Para fazer isso você vai querer adicionar o componente Toolbar
e dentro deste elemento adicionar um IconButton
(ambos no wp.components
pacote). Tudo dentro BlockControls
, claro.
Nota: De acordo com o changelog do WordPress Gutenberg IconButton
é preterido em favor do uso de arquivos Button
. No entanto, não consigo fazer com que um ícone apareça usando o Button
componente, não importa o que eu faça, mesmo que ele deva suportá-lo. Então a partir de agora eu vou usar IconButton
.
Obviamente, você pode combinar vários componentes da barra de ferramentas dentro do BlockControls
. Com o código abaixo, adicionamos a barra de ferramentas de alinhamento de texto e nossa barra de ferramentas personalizada com um botão depois.
O componente IconButton aceita um ícone de painel do WordPress ou um SVG para o prop icon
. Podemos fornecer alguns outros adereços como className
e label
(aparecerá na dica de ferramenta ao passar o mouse sobre o botão). O prop em que estamos mais interessados é obviamente o onClick
prop que dispara quando o botão é clicado. Aqui podemos fornecer uma função e basicamente fazer o que quisermos. As possibilidades são infinitas e depende do que você quer fazer. No código acima eu simplesmente console log algo quando o botão é clicado. À medida que progredirmos nesta série de tutoriais, você provavelmente terá algumas ideias de como fazer com que seu botão personalizado faça o que você deseja que ele faça.
Isto é o que fizemos até agora. Na próxima etapa da série, começaremos a analisar coisas mais avançadas e aprenderemos como criar nossos próprios componentes para utilizar o estado e outros benefícios.