O Gutenberg evoluiu e se tornou um editor avançado e altamente personalizável. Além de seus robustos recursos prontos para uso, os desenvolvedores WordPress agora podem aproveitar um rico conjunto de APIs para integrar recursos personalizados em seus sites com facilidade. Essa extensibilidade permite um nível impressionante de desenvolvimento sob medida, possibilitando criar experiências on-line altamente personalizadas e ricas em recursos.
Este artigo explora dois recursos de desenvolvimento WordPress menos conhecidos, porém poderosos: Variações de Estilo (Style Variations) e Variações de Bloco (Block Variations).
Embora sua utilidade possa parecer pouco evidente no início, você vai se surpreender com o quanto eles podem ser úteis e como um pequeno investimento de tempo permitirá integrá-los perfeitamente ao seu fluxo de trabalho.
Você terá uma compreensão prática do que eles são e de como usá-los por meio de um projeto do mundo real. Você pode implementar esse projeto em seu site WordPress simplesmente copiando e colando o código deste tutorial e, eventualmente, adicionando personalizações.
Antes de começarmos o projeto, vamos revisar rapidamente os pré-requisitos:
- Ambiente de desenvolvimento local do WordPress: qualquer um serve, mas recomendamos fortemente o DevKinsta, a suíte de desenvolvimento local da Kinsta. Ela é fácil de usar e oferece diversas configurações e ferramentas para criar e gerenciar rapidamente um site WordPress local.
- Node.js e npm: são essenciais, pois o editor de blocos é construído com React e requer um processo de build.
- Habilidades básicas de desenvolvimento de frontend: será útil que você tenha um conhecimento básico de Node.js, JavaScript (com React), PHP e CSS.
Embora esse projeto não seja muito complexo, você deve estar preparado para escrever algum código. O código completo também está disponível no GitHub.
Vamos começar!
Estilos de bloco vs Variações de bloco
Estilos de bloco e Variações de bloco são dois recursos poderosos do WordPress para desenvolvedores. Embora seus nomes pareçam bastante semelhantes, eles diferem em termos de finalidade e uso.
Os Estilos de bloco, também conhecidos como variações de estilo, são conjuntos predefinidos de estilos CSS que permitem que você altere a aparência de um bloco com um único clique. Depois de registrar um estilo de bloco, um botão aparece na barra lateral do bloco para atribuir um conjunto de estilos pré-criados ao bloco. Você pode ativar e desativar os estilos e visualizar o bloco no editor em tempo real.
As variações de estilo não alteram os atributos do bloco. Elas modificam apenas a aparência de um bloco, atribuindo uma classe CSS ao elemento envolvente do bloco.
As variações de bloco são uma ferramenta mais poderosa porque permitem que você crie uma versão pré-configurada de um bloco com atributos e blocos internos. Elas também aparecem no inseridor de blocos do editor. Essencialmente, uma variação de bloco aparece para o usuário como se fosse um bloco autônomo, completamente independente do bloco sobre o qual foi criado.
As variações de bloco permitem a personalização da aparência, das configurações iniciais e da estrutura de um bloco.
Com tudo isso em mente, vamos utilizar essas ferramentas para levar os blocos do Gutenberg ao próximo nível!
Um efeito Polaroid animado em um bloco de Imagem nativo
Agora, analisaremos no nosso projeto! Vamos estender o bloco de imagem nativo (core Image block) com um plugin Gutenberg para:
- Implementar uma variação de estilo Polaroid: os usuários podem aplicar um efeito Polaroid encantador às suas imagens com um único clique na barra lateral de configurações do bloco.
- Adicionar uma Animação de Hover: Aprimoraremos as imagens no estilo Polaroid com uma sutil animação ao passar o mouse.
- Criar uma variação do bloco “Animated Polaroid”: Isso permitirá que os usuários insiram rapidamente imagens Polaroid pré-configuradas com um efeito de foco diretamente do inseridor de blocos.
Pronto para começar? Vamos configurar o nosso plugin!
Configuração do ambiente
Antes de começarmos, precisamos configurar um ambiente de desenvolvimento WordPress com o Node.js. Presumimos que você já tenha instalado seu ambiente local de desenvolvimento WordPress e as versões mais recentes do Node.js e do npm. Se você precisar de ajuda, confira nosso tutorial sobre como criar um plugin Gutenberg para adicionar funcionalidade ao editor de blocos.
Etapa 1 – Criar a estrutura básica do plugin
Para este tutorial, chamaremos nosso plugin de Image Hacker.
Navegue até o diretório plugins e crie uma nova pasta image-hacker. Dentro dessa pasta, crie um novo arquivo image-hacker.php (o arquivo principal do plugin) e uma subpasta src, onde você desenvolverá os recursos do plugin.
Esta é a estrutura básica do seu plugin:
/wp-content/plugins/
└── /image-hacker/
├── image-hacker.php
└── /src/Etapa 2 – Criar o código PHP
Em seguida, você precisa garantir que o WordPress reconheça seu plugin. Para fazer isso, adicione o seguinte código em image-hacker.php:
<?php
/**
* Plugin Name: Image Hacker
* Description: Adds new features to the core Image block
* Version: 1.0.0
* Author: Your Name
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: image-hacker
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly.
}Etapa 3 – Inicializar o npm e instalar as dependências
Abra sua ferramenta de linha de comando favorita e navegue até o diretório do seu plugin. Uma vez lá, execute o seguinte comando:
npm init -yEsse comando inicializa um novo arquivo package.json, que inclui as dependências e os scripts do seu projeto.
Em seguida, você precisa instalar os scripts do WordPress e as ferramentas de build, como webpack e Babel:
npm install @wordpress/plugins @wordpress/scripts --save-devEsse comando adiciona uma pasta node_modules com dependências do Node e um arquivo package-lock.json. A imagem abaixo mostra a estrutura atual do seu projeto no Visual Studio Code:
Em seguida, abra o arquivo package.json e atualize a propriedade scripts da seguinte forma:
{
"name": "image-hacker",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"devDependencies": {
"@wordpress/plugins": "^7.25.0",
"@wordpress/scripts": "^30.18.0"
}
}Observe que as versões de devDependencies podem ser diferentes das mencionadas acima e dependem das versões reais instaladas em seu ambiente.
Etapa 4 – Criar os arquivos-fonte do plugin
O próximo passo é criar os arquivos-fonte do plugin. Acesse a pasta src e adicione os seguintes arquivos:
index.jsstyle.scsseditor.scss
Agora, a estrutura do plugin deve ter a seguinte aparência:
/wp-content/plugins/
└── /image-hacker/
├── /node-modules/
├── image-hacker.php
├── package.json
├── package-lock.json
└── /src/
├── index.js
├── style.scss
└── editor.scssAgora, abra o painel de controle do WordPress e navegue até a tela Plugins. Encontre o plugin Image Hacker e ative-o.
Etapa 5 – Incluir ativos (assets) no arquivo do plugin
Em seguida, você precisa incluir os ativos do plugin no arquivo principal do plugin. Adicione o seguinte no image-hacker.php:
/**
* Enqueue block editor assets.
*/
function image_hacker_enqueue_editor_assets() {
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
// Enqueue the script with our modifications
wp_enqueue_script(
'image-hacker-script',
plugins_url( 'build/index.js', __FILE__ ),
array( 'wp-plugins', 'wp-edit-post' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/index.js' )
);
// Enqueue the editor-only styles
wp_enqueue_style(
'image-hacker-editor-style',
plugins_url( 'build/editor.css', __FILE__ ),
[],
filemtime( plugin_dir_path( __FILE__ ) . 'build/editor.css' )
);
}
add_action( 'enqueue_block_editor_assets', 'image_hacker_enqueue_editor_assets' );
/**
* Enqueue frontend and editor assets.
*/
function image_hacker_enqueue_assets() {
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
// Enqueue styles for both frontend and editor
wp_enqueue_style(
'image-hacker-style',
plugins_url( 'build/style-index.css', __FILE__ ),
[],
filemtime( plugin_dir_path( __FILE__ ) . 'build/style-index.css' )
);
}
add_action( 'enqueue_block_assets', 'image_hacker_enqueue_assets' );O que este código faz:
- O hook
enqueue_block_editor_assetscarrega o scriptindex.jse o arquivoeditor.cssapenas no - O hook
enqueue_block_assetscarrega o arquivostyle.cssno editor e no frontend.
Observe que esse código inclui os ativos .js e .css localizados na pasta /build/ do plugin. Isso significa que, para fazer isso funcionar, você precisa executar o Comando build em sua ferramenta de linha de comando:
npm run buildObserve também que, quando você importar um arquivo chamado style.scss para index.js, o arquivo CSS compilado não se chamará style.css, mas sim style-index.css.
Registrar o estilo do bloco
Você concluiu a configuração do seu ambiente de desenvolvimento. Agora, você pode passar para a parte interessante do projeto e registrar sua variação de estilo para o bloco de imagem.
Existem várias maneiras de registrar estilos de bloco, e a escolha depende dos seus objetivos e preferências. Seguiremos a abordagem em JavaScript. Abra seu arquivo /src/index.js e cole o seguinte código:
// Import the function to register block styles.
import { registerBlockStyle } from '@wordpress/blocks';
// Import the function to run code only when the DOM is ready.
import domReady from '@wordpress/dom-ready';
// This line tells the build process to include and compile our SCSS file.
import './style.scss';
/**
* Use domReady to run code only when the DOM is ready.
*/
domReady(() => {
// Register our new style variation for the core image block.
registerBlockStyle('core/image', {
name: 'polaroid',
label: 'Polaroid',
});
});O uso de registerBlockStyle junto com domReady garante que a variação de estilo seja registrada somente quando o DOM estiver totalmente carregado. Consulte também a documentação oficial.
Quando o estilo Polaroid é selecionado, o WordPress adiciona automaticamente a classe .is-style-polaroid ao elemento wrapper do bloco.
A próxima etapa é fornecer o CSS para sua variação de estilo. Abra seu site /src/style.scss e adicione o seguinte código:
.wp-block-image.is-style-polaroid {
padding: 15px 15px 70px 15px;
background-color: white;
box-shadow: 0 4px 10px rgba(0, 0, 0, 0.2);
max-width: 360px;
transform: rotate(-3deg);
transition: transform 0.3s ease-in-out;
figure {
margin: 0 !important;
}
img {
display: block;
width: 100%;
height: auto;
}
figcaption {
position: absolute;
bottom: 15px;
left: 0;
right: 0;
text-align: center;
font-family: 'Permanent Marker', cursive;
color: #333;
font-size: 18px;
}
}Salve o código, execute npm run build e acesse o painel do WordPress. Crie um novo artigo ou página e adicione uma imagem. Com a imagem selecionada, clique no rótulo Styles (Estilos) na barra lateral do bloco e selecione Polaroid.
Adicione uma legenda, salve o artigo e verifique o resultado no frontend. Você verá uma imagem no estilo Polaroid com uma bela legenda em itálico.
Construindo a lógica
A próxima etapa é criar a lógica para animar a imagem. Criaremos uma animação simples usando a propriedade CSS transform. Para começar, adicione o seguinte bloco ao seu arquivo src/style.scss:
.wp-block-image.is-style-polaroid.has-image-animation:hover {
transform: rotate(0deg) scale(1.05);
}Esse código garante que o efeito hover seja aplicado somente se o bloco for uma imagem Polaroid e tiver uma classe has-image-animation aplicada a partir do botão de alternância (toggle) na barra de ferramentas.
Agora, precisamos da lógica para adicionar essa classe CSS ao contêiner da imagem, que é um elemento <figure>. Para isso, serão necessários alguns filters e funções de callback.
Primeiro, adicione a seguinte linha ao seu arquivo src/index.js:
import { addFilter } from '@wordpress/hooks';Etapa 1. Adicionar um novo atributo ao bloco de imagem
Você usará o addFilter para manipular o bloco de imagem nativo (core/image). Primeiro, você adicionará um novo atributo imageAnimation ao bloco de imagem:
function addImageAnimationAttribute( settings, name ) {
if ( name !== 'core/image' ) {
return settings;
}
settings.attributes = {
...settings.attributes,
imageAnimation: {
type: 'boolean',
default: false,
},
};
return settings;
}
addFilter(
'blocks.registerBlockType',
'image-hacker/add-image-animation-attribute',
addImageAnimationAttribute
);A função addImageAnimationAttribute recebe dois argumentos:
settings– Um array contendo as configurações atuais do bloco (incluindo atributos).name– O nome do bloco cujos atributos você deseja modificar.
A função retorna o objeto de configurações/atributos atualizado.
Etapa 2. Adicionar um botão de alternância (toggle) à barra de ferramentas do bloco de imagem
Em seguida, você precisará adicionar um controle à barra de ferramentas do bloco Imagem para ativar a animação.
Primeiro, adicione o seguinte import ao arquivo index.js:
import { createHigherOrderComponent } from '@wordpress/compose';
import { Fragment } from '@wordpress/element';
import { BlockControls } from '@wordpress/block-editor';
import { ToolbarGroup, ToolbarButton } from '@wordpress/components';
import { __ } from '@wordpress/i18n';Em seguida, adicione o seguinte código ao final do arquivo:
const withPolaroidControls = createHigherOrderComponent((BlockEdit) => {
return (props) => {
if (props.name !== 'core/image') {
return <BlockEdit {...props} />;
}
const { attributes, setAttributes, isSelected } = props;
const { imageAnimation, className, lightbox } = attributes;
return (
<Fragment>
<BlockEdit {...props} />
<BlockControls>
<ToolbarGroup>
<ToolbarButton
icon="format-image"
label={__('Toggle Animation', 'image-hacker')}
isActive={imageAnimation}
onClick={() =>
setAttributes({ imageAnimation: !imageAnimation })
}
/>
</ToolbarGroup>
</BlockControls>
</Fragment>
);
};
}, 'withPolaroidControls');
addFilter(
'editor.BlockEdit',
'image-hacker/with-polaroid-controls',
withPolaroidControls
);O que este código faz:
- A função
createHigherOrderComponentcria um componente de ordem superior (HOC) que envolve oBlockEdit, componente principal responsável por exibir blocos no editor. - O HOC intercepta o componente e verifica se ele é um bloco de imagem. Isso garante que todas as edições que você fizer se apliquem somente ao bloco de Imagem.
- Usamos a atribuição de desestruturação para extrair as propriedades e os atributos necessários dos objetos
propseattributes. - Usamos
BlockControls,ToolbarGroupeToolbarButtonpara adicionar um botão Toggle Animation à barra de ferramentas do bloco. isActivedefine o estado padrão deimageAnimationonClickalterna o valorimageAnimation.
Agora você tem um atributo e um botão. No entanto, se você clicar no botão, nada acontecerá.
Etapa 3. Adicionar a classe CSS ao elemento wrapper
A próxima etapa é aplicar a classe has-image-animation ao elemento figure que envolve a imagem. Para fazer isso, você precisa de um filtro que permita atribuir a classe CSS à imagem no frontend.
Acrescente o seguinte código ao arquivo index.js:
function addAnimationFrontendClass(extraProps, blockType, attributes) {
if (blockType.name === 'core/image' && attributes.imageAnimation) {
extraProps.className = `${extraProps.className || ''} has-image-animation`;
}
return extraProps;
}
addFilter(
'blocks.getSaveContent.extraProps',
'image-hacker/add-animation-frontend-class',
addAnimationFrontendClass
);Esse código adiciona dinamicamente a classe CSS has-image-animation ao elemento figure quando o atributo imageAnimation é definido como true.
Vamos tentar entender o que acontece em detalhes.
addFilterintercepta o hook do editor para modificar dados ou comportamentos.blocks.getSaveContent.extraPropsextraPropsé um hook especial que permite que você adicione atributos HTML extras ao elemento wrapper.image-hacker/add-animation-classé o nome exclusivo do seu filtro.addAnimationFrontendClassé o nome da função callback que é executada sempre que o hookblocks.getSaveContent.extraPropsé executado. Essa função recebe 3 argumentos:extraProps: um objeto que contém as propriedades do elemento envolvente do bloco, comoclassName.blockType: um objeto com detalhes do bloco, comoname(core/image).attributes: um objeto de atributos de bloco
- A lógica da função garante que o código seja executado somente quando
blockType.name === 'core/image'eattributes.imageAnimationforemtrue. - Se ambas as condições forem verdadeiras, a função retornará um novo objeto
propscomhas-image-animationanexado ao objeto de classe existente.
Agora, você pode tentar fazer isso sozinho. Adicione uma imagem ao seu conteúdo, selecione o estilo Polaroid na barra lateral do bloco e clique no botão Toggle Animation (Alternar animação) na barra de ferramentas do bloco. Salve sua postagem e verifique o resultado no frontend. Sua imagem deverá girar quando você passar o mouse sobre ela.
Registrar variação de bloco
As variações de bloco são versões pré-configuradas de um bloco, com um conjunto de atributos e blocos aninhados. O WordPress trata as variações de bloco como blocos independentes, tornando-os disponíveis no inseridor de blocos e marcando-os com um ícone personalizado.
Você pode usar uma variação de bloco para criar uma nova versão do bloco de Imagem com o estilo Polaroid aplicado por padrão.
O primeiro passo é importar a função registerBlockVariation no seu arquivo /src/index.js:
import { registerBlockStyle, registerBlockVariation } from '@wordpress/blocks';Em seguida, você adiciona uma chamada à função registerBlockVariation dentro de domReady(), logo abaixo de registerBlockStyle:
domReady(() => {
// Register a style variation for the image block.
registerBlockStyle('core/image', {
name: 'polaroid',
label: 'Polaroid',
});
// Register a block variation of the image block
registerBlockVariation('core/image', {
name: 'animated-polaroid',
title: 'Animated Polaroid',
icon: 'image-filter',
attributes: {
className: 'is-style-polaroid',
imageAnimation: true,
},
scope: ['inserter'],
});
});A função registerBlockVariation cria uma variação para um bloco existente. Ela aceita dois argumentos: o nome do bloco e um objeto que define a variação. (Consulte também a introdução às variações de bloco e a documentação da API Block Variations).
Salve o arquivo, execute o comando build para aplicar as alterações e retorne ao painel do WordPress. Crie um novo post e pesquise pelo bloco Animated Polaroid no inseridor de blocos.
Testes e depuração
Vamos fazer alguns testes. Adicione uma ou mais imagens a uma nova postagem. Selecione o estilo Polaroid para cada imagem, ative a animação e adicione links. Além disso, execute testes com o bloco Galeria (Gallery).
Tudo parece funcionar como esperado. No entanto, ao adicionar um link, com efeito lightbox a uma imagem com o estilo Polaroid, o resultado visual não é satisfatório.
Esse comportamento estranho parece estar relacionado a um problema de compatibilidade entre o lightbox do WordPress e as transições CSS.
Para evitar um processo de depuração longo e complexo, pode ser interessante desativar a opção “Ampliar ao clicar” e exibir um aviso notificando o usuário de que o lightbox foi desativado.
Primeiro, você precisa importar alguns recursos adicionais. Abaixo você encontra a lista completa de recursos importados do arquivo /src/index.js:
import { registerBlockStyle, registerBlockVariation } from '@wordpress/blocks';
import domReady from '@wordpress/dom-ready';
import { addFilter } from '@wordpress/hooks';
import { createHigherOrderComponent } from '@wordpress/compose';
import { Fragment, useEffect } from '@wordpress/element';
import { InspectorControls, BlockControls } from '@wordpress/block-editor';
import { PanelBody, Notice, ToolbarGroup, ToolbarButton } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
import { useDispatch } from '@wordpress/data';
import './style.scss';Adicionamos as seguintes importações:
useEffectde@wordpress/element. (documentação)InspectorControlsde@wordpress/block-editor(documentação).PanelBodyeNoticede@wordpress/components(documentação).useDispatchde@wordpress/data. (Blog do desenvolvedor WordPress)
Agora, altere a função withPolaroidControls da seguinte forma:
const withPolaroidControls = createHigherOrderComponent((BlockEdit) => {
return (props) => {
if (props.name !== 'core/image') {
return <BlockEdit {...props} />;
}
const { attributes, setAttributes, isSelected } = props;
const { imageAnimation, className, lightbox } = attributes;
const isPolaroid = className?.includes('is-style-polaroid');
const { createNotice } = useDispatch('core/notices');
useEffect(() => {
if (isPolaroid && lightbox?.enabled) {
// Disable the lightbox to prevent the conflict.
setAttributes({ lightbox: { ...lightbox, enabled: false } });
// Show the user a temporary 'snackbar' notice.
createNotice(
'warning', // The type of notice (info, success, warning, error)
__('Lightbox disabled for Polaroid style.', 'image-hacker'),
{
type: 'snackbar',
isDismissible: true,
}
);
}
}, [isPolaroid, lightbox]);
return (
<Fragment>
<BlockEdit {...props} />
<BlockControls>
<ToolbarGroup>
<ToolbarButton
icon="format-image"
label={__('Toggle Animation', 'image-hacker')}
isActive={imageAnimation}
onClick={() =>
setAttributes({ imageAnimation: !imageAnimation })
}
/>
</ToolbarGroup>
</BlockControls>
{isSelected && isPolaroid && (
<InspectorControls>
<PanelBody title={__('Polaroid Style', 'image-hacker')}>
<Notice status="info" isDismissible={false}>
{__(
'The "Expand on click" (lightbox) feature is disabled for this style to prevent visual conflicts.',
'image-hacker'
)}
</Notice>
</PanelBody>
</InspectorControls>
)}
</Fragment>
);
};
}, 'withPolaroidControls');Entendendo o código:
useEffecté um Hook do React que “permite sincronizar um componente com um sistema externo.” O código é executado depois que o componente é renderizado e sempre que um valor no array de dependência[isPolaroid, lightbox]mudar. A verificação só é executada quando o usuário aplica ou remove o estilo Polaroid, ou ativa, ou desativa o lightbox (documentação do React).- A condição
if (isPolaroid() && lightbox.enabled)garante que o código seja executado somente se a imagem tiver o estilo Polaroid e a opção lightbox estiver ativada. - Se a condição for
true, o lightbox será desativado e um aviso temporário será exibido. (Consulte também Referência de dados de avisos.) - A condição
isSelected && isPolaroidum novo painel na barra de ferramentas do bloco de imagem para notificar os usuários de que o lightbox está desativado.
Diferente do aviso do tipo snackbar, esse painel exibe um alerta permanente.
Resumo
Neste tutorial, analisamos alguns dos mais interessantes e poderosos recursos para desenvolvedores do editor de blocos WordPress, aplicados em um projeto real: estendemos o bloco de imagem nativo com funcionalidades que não estão disponíveis por padrão, adicionando estilos personalizados e efeitos de animação.
Adotamos uma abordagem de aprimoramento progressivo, criando uma variação de estilo para o bloco de imagem. Isso permite que os usuários apliquem facilmente um visual clássico de Polaroid às suas imagens.
Em seguida, adicionamos um botão dedicado à barra de ferramentas do bloco de imagem, permitindo criar um efeito de animação atraente ao passar o mouse.
Por fim, encerramos criando uma variação de bloco pré-configurada com o estilo Polaroid e as configurações de animação aplicadas por padrão.
Esperamos que as ideias e técnicas apresentadas neste tutorial ajudem você a criar personalizações realmente surpreendentes para os blocos nativos do Gutenberg!
Carlo é um apaixonado por webdesign e desenvolvimento frontend. Ele tem mais de 10 anos de experiência com WordPress e colaborou com diversas universidades e instituições educacionais na Itália e na Europa. Carlo já publicou inúmeros artigos e guias sobre WordPress, tanto em sites italianos quanto internacionais, além de revistas impressas. Você pode seguir ele no LinkedIn e no X.
