Pular para o conteúdo

useBlockProps

Por padrão, Gutenberg precisa criar um wrapper em torno dos blocos para torná-los interativos no editor. Isso pode ser problemático para alguns tipos de bloco, como contêineres ou colunas, pois a marcação será diferente entre o editor e o frontend. O hook useBlockProps permite marcar um elemento dentro do modelo do bloco como elemento raiz, criando assim paridade de marcação entre o editor e o frontend.

Uso

Basta adicionar o atributo useBlockProps ao elemento raiz do seu bloco.

PHP
<div useBlockProps class="my-class">
  <!--
  This element will be rendered
  as the root element of your block
  in Gutenberg.
  -->
</div>

Blockstudio combinará automaticamente as classes e os atributos do editor (classes de alinhamento etc.) com os definidos nos modelos de bloco. get_block_wrapper_attributes é usado internamente para isso.

O filtro blockstudio/blocks/components/use_block_props/render é aplicado ao wrapper tanto no frontend quanto na renderização do editor. Assim, classes adicionadas por um tema ou por uma integração por instância aparecem tanto na tela do editor quanto na marcação salva do frontend.

Saída:

HTML
<div class="my-class wp-block-your-block-name alignright">
</div>

Considerações

Blockstudio impede a navegação por links dentro do editor de blocos, incluindo target="_blank", cliques com modificadores, cliques com o botão do meio e ativação pelo teclado. Os eventos de clique ainda chegam a Gutenberg, então os cliques comuns selecionam o bloco. RichText continua editável. Isso se aplica com ou sem useBlockProps, inclusive quando uma âncora é usada como elemento raiz do bloco.

Os links no frontend e os comandos do menu de contexto do navegador não mudam. Não é preciso remover links dos modelos nem criar uma ramificação com base em $isEditor.

Elemento raiz

Como só pode haver um elemento raiz em um modelo de bloco, ao usar useBlockProps, o modelo do bloco precisa ter um único elemento raiz. Por exemplo, o seguinte não funcionará, e Gutenberg criará um wrapper em torno do modelo.

PHP
<div useBlockProps>
  First root element.
</div>
<span>
  Second root element.
</span>

Da mesma forma, useBlockProps só pode ser usado uma vez por modelo de bloco.

Sinal @

Blockstudio converte o modelo do bloco em código React válido dentro de Gutenberg usando html-react-parser. Isso implica que o caractere @ não pode ser usado no nome de um atributo HTML.

Bibliotecas como Alpine.js usam os caracteres @ para definir diretivas em elementos HTML.

PHP
<button useBlockProps @click="console.log('hi')">
  Click me
</button>

Dentro de Gutenberg, esse atributo @click será removido do elemento. (Ele continuará funcionando no frontend, é claro.)

Para contornar esse problema, você pode usar a sintaxe alternativa fornecida por Alpine.js.

PHP
<button useBlockProps x-on:click="console.log('hi')">
  Click me
</button>

O exemplo acima funcionará dentro de Gutenberg e no frontend.

Classes do corpo da tela

Quando assets.reset.enabled está ativo, Blockstudio também copia as classes sanitizadas retornadas pelo filtro body_class de WordPress para a tela do editor de blocos. Isso mantém seletores do tema, como .brand-a .site-card, funcionando nos dois lugares.

Filtre a lista final de classes quando o editor precisar de um conjunto mais restrito:

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

Esse filtro controla apenas as classes copiadas para a tela do editor. Ele não altera as classes body do frontend.