Criar bloco personalizado do Gutenberg – Parte 3: adereços e componentes do WordPress

A etapa anterior desta série de tutoriais passou por como registrar um bloco personalizado, tanto em Javascript quanto em PHP. Nesta etapa, aprenderemos como usar os componentes do WordPress para adicionar diferentes tipos de campos e configurações.

Para utilizar os componentes do WordPress em nosso bloco, precisamos primeiro conhecer os adereços.

Adereços

Props é um recurso importante no React e é basicamente uma maneira de passar variáveis ​​ou funções para outros componentes. Se você não está familiarizado com os adereços do React, você pode ler o tutorial oficial do React sobre isso.

O WordPress fornece alguns adereços para as funções edite em. Dentro dessas props temos acesso a coisas críticas, como atributos e um método para atualizar nossos atributos. Veremos os atributos em detalhes na próxima etapa! save``registerBlockType()

Até agora, em nosso bloco, escrevemos a função for edite saveassim:

Você deve se acostumar a adicionar o parâmetro propsa editand save, assim:

Agora você tem acesso total à variável propse tudo que ela contém de dentro edite save. Se você estiver curioso, pode adicionar um console.log(props);na editfunção antes da returninstrução. Você deve ver quais adereços estão disponíveis no depurador do console.

Usando os componentes do WordPress

Como mencionado anteriormente, temos acesso a uma enorme biblioteca de componentes e funções úteis dentro do pacote global wp. Você encontrará componentes prontos para uso para qualquer tipo de componente relacionado a entrada que você possa imaginar. Os exemplos incluem entradas de texto, entradas de rich text, menus suspensos, alternância, caixas de seleção, botões em estilos diferentes, carregador de mídia e seletores de cores. Existem também funções e componentes para funcionalidades mais avançadas. Como consultar o WordPress por conteúdo (postagens, categorias, etc.) com funções integradas ou buscar com a API REST.

É mais fácil e recomendado usar os componentes de interface do usuário do WordPress. Isso é para garantir que o design e a funcionalidade sejam o mais simplificados possível para não confundir ou incomodar os usuários.

Mas, infelizmente, no momento em que escrevo isso, a documentação de Gutenberg é muito escassa. Eu encontrei a melhor maneira de aprender sobre o que existe dentro do wppacote e como os componentes funcionam, na verdade, olhando em seu repositório oficial do Github do Gutenberg. Alguns dos pacotes (pastas) têm um texto leia-me que oferece um pouco de documentação. Dê uma olhada no leia-me para um botão ou a alternância, por exemplo.

O repositório do Github deve corresponder ao que está dentro do wppacote (dependendo de qual versão você possui e de qual branch você está procurando no Github). Isso significa que cada pasta que você vê no diretório raiz packagesdo Github reside no wppacote global. Como exemplo, lembre-se de que a função que usamos na etapa anterior, registerBlockType(), estava dentro wp.blocksde, o que significa que você encontrará o código-fonte dessa função exportado dentro de packages/blocks/.

Como desenvolvi vários blocos personalizados do Gutenberg e pesquisei bastante no repositório do Github, descobri que existem alguns pacotes que contêm a funcionalidade mais comum usada para criar blocos personalizados. Vou incluí-los abaixo.

Para uma visão mais completa dos componentes disponíveis, recomendo baixar meu eBook gratuito cobrindo os componentes disponíveis em Gutenberg! Ele contém os componentes mais comuns e úteis com documentação sobre props e exemplos de código:

Uma visão geral rápida dos pacotes mais comuns que você usará para blocos

Obviamente há muito mais disponível, mas o abaixo é o mais comum para o desenvolvimento de blocos. Usaremos a maioria, se não todos, nesta série de tutoriais. Sempre que você quiser usar um componente, você precisa saber em qual pacote ele está.

wp.components

Você encontrará a maioria dos componentes de entrada da interface do usuário dentro do wp.components. Exemplos são diferentes entradas de texto, seleção, caixas de seleção, botões de opção, componentes arrastáveis, botões, seletor de cores, seletor de data e assim por diante. Você também encontrará componentes de interface do usuário que podem ser usados ​​para a barra de ferramentas do bloco e o conteúdo da barra lateral de configurações (chamadas InspectorControls) no editor.

Confira as pastas no repositório do Github.

wp.blockEditor e wp.editor

Nesses dois pacotes, você encontrará componentes úteis para rich text, manipulação de imagens/carregador de mídia e componentes para adicionar barras de ferramentas ou painéis personalizados do Inspetor (barra lateral).

No final desta série, veremos a construção de blocos dinâmicos nos quais usaremos PHP para renderizar a saída do bloco e, para isso, usaremos um componente de wp.editor.

Pelo que entendi, a maioria dos componentes começou nos wp.editorprimeiros dias de Gutenberg, mas especialmente após o WordPress 5.3, muitos deles foram movidos para o wp.blockEditor. Se você usar um componente em wp.editorque o WordPress planeja migrar para wp.blockEditorele, não falhará a partir de agora, mas no depurador do console, você receberá avisos de que ele foi preterido e que você deve mudar para wp.blockEditorquando puder. E reversivelmente, se você estiver seguindo esta série com uma versão mais antiga do WordPress por algum motivo, poderá encontrar erros ao chamar componentes que wp.blockEditorainda não foram movidos.

wp.element

Dentro wp.elementvocê encontrará componentes que correspondem aos componentes React. Por exemplo Component(que corresponde a React.Component) e Fragment( React.Fragment). Nós os usaremos quando começarmos a dividir nosso código em componentes separados.

wp.i18n

Como o nome indica, o wp.i18npacote contém funções para lidar com a tradução. Ele contém as mesmas funções de tradução que conhecemos no PHP; por exemplo __()e _e(). Veremos isso em detalhes em <<<>>>> quando aprendermos como traduzir nosso bloco.

wp.data

O wp.datapacote é para consultar o WordPress para dados fora do editor. Existem componentes para despachar mensagens withSelecte selectque usaremos posteriormente nesta série para consultar postagens dentro de nosso bloco.

wp.compose

O pacote anterior e wp.composesão para construção de blocos mais avançada. Dentro deste pacote, encontraremos componentes e funções para criar os chamados componentes de ordem superior. Componentes de ordem superior é uma técnica de padrão no React para reutilizar componentes e lógica, e usaremos isso em combinação com wp.datapara consultar postagens.

Chega de conversa – como você usa alguns desses componentes na prática?

Como mencionado anteriormente; para usar os componentes do WordPress você precisa saber onde eles estão. Espero que minha visão geral acima combinada com o repositório do Github dê uma ideia de onde obtê-los.

Não se esqueça de que você sempre pode adicionar qualquer tag HTML normal, como div, span, títulos e assim por diante. Apenas lembre-se de seguir as diretrizes do React em atributos. Por exemplo class, é uma palavra-chave reservada no React (para criar componentes baseados em classe), portanto, se você deseja adicionar uma classe a um elemento HTML, precisa usar className.

Nota: Durante o desenvolvimento, não se esqueça de iniciar npm run starta compilação do seu código.

Como um exemplo simples, vamos experimentar alguns componentes para ver como eles se parecem. Nós os desestruturamos de seus pacotes correspondentes e os utilizamos em nossa editfunção.

Isso, por exemplo, resultará em nosso bloco assim no editor.

Você notará que receberá mensagens de erro no Console ao digitá-las e que não salvará o que você digitar ao atualizar a postagem (e atualizar). Isso ocorre porque nos faltam props nos componentes que são a conexão com os atributos, onde todos os dados do nosso bloco são armazenados. As props são responsáveis ​​por passar os valores salvos e funções responsáveis ​​por atualizar nossos atributos quando algo é alterado em nossas entradas. Isso é o que faremos na próxima etapa, onde finalmente começaremos a escrever algum código de verdade.