A introdução da edição completa de sites (FSE) no WordPress destaca a importância crescente do arquivo theme.json. Agora há uma hierarquia e uma estrutura totalmente novas a serem compreendidas, juntamente com as várias propriedades que ajudam você a criar seus designs. Em particular, a propriedade blocks em theme.json é essencial se você quiser criar temas WordPress modernos e flexíveis com blocos exclusivos.
Neste guia, exploraremos os prós e contras da propriedade blocks notheme.json para que você possa trabalhar com Blocos, projetá-los e estilizá-los para criar experiências mais dinâmicas e personalizáveis no WordPress.
Entendendo a propriedade blocks no theme.json
Antes de nos aprofundarmos nas complexidades da propriedade blocks, vamos primeiro entender sua função em theme.json e no desenvolvimento de temas do WordPress.
Primeiro, theme.json é o arquivo de configuração que permite que você defina estilos e configurações globais para seus temas. Esse “hub central” permite que você controle vários aspectos da aparência e do comportamento do seu tema, inclusive tipografia, cores e opções de layout. No entanto, ele pode fazer mais do que simplesmente fornecer a você ajustes cosméticos programáticos.
A propriedade blocks permite que você aplique controle granular sobre tipos de blocos individuais em vez de sobre o site como um todo. Você pode definir estilos, configurações e comportamentos padrão para Blocos específicos, o que garante consistência em todo o tema e flexibilidade para os proprietários do site.
A relação entre a propriedade de blocos e a edição completa de sites
O FSE (Full Site Editing) é uma abordagem mais visual para a construção do seu site, com Blocos no núcleo. No front-end, você tem a maioria das opções de estilização e personalização disponíveis para todo o seu site.
A propriedade blocks é uma parte crucial do arquivo theme.json por alguns motivos:
- Ela fornece uma maneira padronizada de definir estilos e configurações de blocos.
- Você pode criar sistemas de design coesos a partir de uma base programática.
- Você pode oferecer maior controle sobre a aparência dos blocos sem a necessidade de CSS personalizado.
- A propriedade ajuda você a criar padrões e modelos de blocos.
Os desenvolvedores podem usar a propriedade blocks para criar temas que aproveitem ao máximo a edição completa de sites.
Como estruturar a propriedade blocks (e sua sintaxe)
A padronização que a propriedade blocks oferece ajuda quando se trata de estrutura e sintaxe. Você sempre a aninhará dentro do objeto settings:
{
"version": 3,
"settings": {
"blocks": {
"core/paragraph": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
}
]
…O exemplo acima define tamanhos de fonte personalizados para um bloco de parágrafo. A divisão dos principais componentes é simples:
- Você aninha a propriedade
blocksno objetosettings. - Cada tipo de bloco tem um namespace e um nome (aqui,
core/paragraph). - Em seguida, você especifica as configurações do bloco dentro do objeto.
As configurações incluem a maior parte do que está disponível para estilos globais. Por exemplo, elas podem incluir tipografia, cor, espaçamento e muitas outras.
Definição das configurações globais do bloco
Vamos ver como você pode definir as configurações globais e, em seguida, analisar como isso afeta a propriedade blocks. É assim que você estabelecerá uma base de design consistente em todo o seu tema.
{
"version": 3,
"settings": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
}
…Neste exemplo, definimos os tamanhos de fonte globais disponíveis para todos os blocos. No Editor de Sites WordPress, você pode encontrar essas opções como parte da tela Tipografia > Elementos > Texto:
Cada tamanho de fonte que você define em theme.json está relacionado a uma das opções de tamanho aqui:
Obviamente, há muitas outras maneiras de personalizar seu tema a partir daqui. A ideia é criar um design global que funcione em 80% dos casos de uso.
Usando a propriedade blocks, você pode substituir esses estilos de bloco principais para cobrir os 20% finais. A tela Styles (Estilos) no Editor de Sites também permite que você personalize as configurações de design de cada bloco:
Isso é excelente para os usuários finais, mas de menor valor para um desenvolvedor. Estamos nos concentrando em usar o theme.json para trabalhar com a propriedade blocks.
Como personalizar tipos de blocos individuais
Embora as configurações globais sejam importantes para ajudar a manter a consistência, o verdadeiro poder está no escopo da propriedade blocks para personalização. Essa configuração de nível granular permite que você adapte a aparência e o comportamento de blocos específicos para corresponderem ao design do seu tema, assim como o Editor de Sites.
Vejamos um exemplo de personalização do bloco Heading para o seu tema:
{
"version": 3,
"settings": {
"blocks": {
"core/heading": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "20px"
},
{
"name": "Medium",
"slug": "medium",
"size": "30px"
},
{
"name": "Large",
"slug": "large",
"size": "40px"
}
],
"fontWeight": "bold"
},
"color": {
"palette": [
{
"name": "Heading Primary",
"slug": "heading-primary",
"color": "#333333"
},
{
"name": "Heading Secondary",
"slug": "heading-secondary",
"color": "#666666"
}
]
…Você pode ver que os atributos refletem como você faria alterações globais. Vamos resumir o que estamos fazendo:
- Definimos tamanhos de fonte específicos para os títulos e os atribuímos a etiquetas de tamanho.
- O peso da fonte para todos os títulos será simplesmente negrito.
- Esses títulos também receberão uma paleta de cores personalizada.
Isso garante que nossos títulos tenham uma aparência consistente em todo o design. Também podemos controlar esses elementos quando não sabemos como o usuário final os aplicará, o que beneficia ainda mais o design consistente.
Usando a combinação correta de namespace e slug
Ao chamar tipos de blocos, é fundamental que você use a combinação correta de namespace e slug. Sem isso, suas alterações não se aplicarão aos blocos que você deseja direcionar.
Cada bloco tem um namespace e um slug. Os blocos principais do WordPress têm geralmente o namespace core. A slug será o nome do bloco:
…
"blocks": {
"core/image": {
…Se precisar saber a slug de um bloco, você pode consultar o arquivo block.json específico dele. Você pode encontrá-lo no diretório wp-includes/blocks. Aqui, você terá várias pastas, cada uma das quais contém um arquivo block.json. Em cada uma delas, o namespace e o slug do bloco devem estar próximos à parte superior do arquivo:
Se você navegar por esses diretórios, perceberá que o diretório wp-includes tem um arquivo theme.json próprio. Embora isso possa parecer confuso, é simples de explicar.
Por que o theme.json inclui configurações personalizadas de blocos por padrão
O próprio arquivo theme.json do WordPress pode parecer estranho em um primeiro momento, principalmente porque não é um tema. No entanto, isso não é por acaso. O principal motivo é oferecer suporte à compatibilidade retroativa com versões mais antigas do WordPress.
Por exemplo, o bloco de botões define um raio de borda:
…
"blocks": {
"core/button": {
"border": {
"radius": true
}
},
…Outros blocos terão configurações semelhantes para ajudar na consistência entre diferentes versões do WordPress. No entanto, isso pode causar problemas no futuro se você não estiver ciente disso.
Se você tentar definir configurações globais e se perguntar por que essas alterações não se aplicam a blocos específicos, a compatibilidade com versões anteriores pode ser a resposta. Obviamente, você pode substituir essas configurações em seu próprio arquivo theme.json sem problemas.
Desenvolvimento de blocos personalizados com theme.json
O arquivo theme.json é ideal para personalizar os blocos existentes, mas seus recursos também se estendem ao desenvolvimento de blocos personalizados. Você pode aproveitar o theme.json para definir estilos e configurações padrão para qualquer um dos seus blocos personalizados. Isso ajuda você a oferecer uma integração perfeita com o design do seu tema.
Primeiro, porém, você precisa criar o próprio bloco. Isso está além do escopo deste artigo, mas, em resumo, há algumas facetas:
- Construir o bloco. Isso envolve a configuração de um ambiente de desenvolvimento local e a criação da estrutura de arquivos para todo o bloco.
- Atualização do arquivo
block.json. Aqui, você precisará alterar a identidade do bloco e adicionar suportes. Esses últimos são maneiras de declarar o suporte a funcionalidades específicas do WordPress. Por exemplo, você pode lidar com o alinhamento, implementar campos âncora, trabalhar com várias configurações de tipografia e muito mais. - Ajuste os arquivos JavaScript do bloco. Tanto o
index.jsquanto oedit.jsprecisam de código para informar ao WordPress como o bloco funciona e para permitir que ele apareça no Editor de Sites.
Talvez você também precise editar render.php, adicionar renderização estática e uma série de outras tarefas. Nesse ponto, você pode aplicar quaisquer alterações estilísticas ao theme.json como em qualquer outro bloco. Por enquanto, vamos dar uma olhada mais de perto em block.json.
O arquivo block.json
Esse arquivo é o que a equipe de desenvolvimento do WordPress chama de maneira “canônica” de registrar Blocos para o lado do servidor e do cliente. Os metadados que você inclui aqui informam ao WordPress tudo sobre o tipo de bloco e seus arquivos de suporte:
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "my-plugin/notice",
"title": "Notice",
"category": "text",
"parent": [ "core/group" ],
"icon": "star",
"description": "Shows warning, error or success notices...",
"keywords": [ "alert", "message" ],
"version": "1.0.3",
"textdomain": "my-plugin",
"attributes": {
"message": {
"type": "string",
"source": "html",
"selector": ".message"
}
},
…É semelhante aos metadados que você colocaria na parte superior de um arquivo PHP para temas e plugins. Embora o arquivo use exclusivamente dados JSON, você ainda pode compartilhar código por meio do PHP, JavaScript e CSS:
…
"editorScript": "file:./index.js",
"script": "file:./script.js",
"viewScript": [ "file:./view.js", "example-shared-view-script" ],
"editorStyle": "file:./index.css",
"style": [ "file:./style.css", "example-shared-style" ],
"viewStyle": [ "file:./view.css", "example-view-style" ],
"render": "file:./render.php"
…Voltaremos a esse assunto mais tarde na seção sobre variações. Para finalizar esta seção, você precisa saber como definir seu bloco personalizado como padrão no WordPress. Há algumas maneiras de fazer isso. A maneira clássica é registrar um tipo de post personalizado e incluir os blocos nele. Entretanto, há alguns outros métodos.
Por exemplo, você pode atualizar um tipo de post existente para adicionar um modelo de bloco. Aqui está um exemplo simples:
…
function load_post_type_patterns() {
// Define an initial pattern for the 'HypnoToad' post type
$post_type_object = get_post_type_object( 'hypnoToad' );
$post_type_object->template = array(
array(
'core/block',
…Outra maneira é chamar o hook default_content e definir o bloco usando a marcação:
function toad_content( $content, $post ) {
if ( $post->post_type === 'hypnoToad' ) {
$content ='
<div class="is-layout-flex wp-container-1 wp-block-columns"><!-- wp:column →
<div class="wp-block-column">
<p></p>
</div>
<div class="is-layout-flow wp-block-column">
<p></p>
</div>
</div>
';
}
return $content;
}
add_filter( 'default_content', 'toad_content', 10, 2 );Obviamente, você não usará apenas JSON, HTML e PHP. Você também usará outras linguagens para ajudar no design e na interatividade. A boa notícia é que o WordPress oferece a você uma maneira descomplicada de fazer isso.
Usando propriedades CSS personalizadas para seus blocos
Você pode conseguir muito usando as propriedades, os atributos e os objetos existentes em theme.json, mas isso não cobrirá todos os casos de uso. O arquivo fornece a propriedade custom que ajudará você a criar propriedades CSS relevantes:
{
"version": 3,
"settings": {
"custom": {
"toad": "hypno"
}
}
}Aqui, você fornece um par chave-valor, que se transforma em uma variável CSS no frontend:
body {
--wp--custom--toad: hypno;
}Observe que a variável usará hífens duplos para separar seus elementos. Em geral, você sempre verá --wp--custom--, que marcará a chave no final. Às vezes, você definirá variáveis e propriedades com camel case:
{
"version": 3,
"settings": {
"custom": {
"hypnoToad": "active"
}
}
}Aqui, o WordPress usará hífens para separar as palavras:
body {
--wp--custom--hypno-toad: active;
}Entre a propriedade custom e block.json, você tem total liberdade para criar seus Blocos como achar melhor, inclusive quaisquer variações que queira incluir.
Um breve resumo sobre variações de bloco, estilos e variações de estilos de blocos
Antes de passarmos ao estilo usando a propriedade blocks, vamos dar uma olhada nas variações. Você tem alguns tipos de variação diferentes para seus designs, e as convenções de nomenclatura podem fazer com que você use o tipo errado para suas necessidades. Aqui está um detalhamento das diferenças:
- Variações de bloco. Se o seu bloco tiver versões alternativas (pense em um bloco que exibirá muitos links personalizados definidos pelo usuário), isso é uma variação de bloco. O bloco de mídia social é um bom exemplo disso.
- Variações de estilo. Essas são versões alternativas do
theme.jsonque funcionam em seu site global. Não abordamos esse assunto aqui, mas a maioria dos temas de bloco os oferece para várias paletas de cores e configurações de tipografia. - Variações de estilos de blocos. Essa funcionalidade central das variações de estilo permite que você crie designs alternativos para um bloco.
Você pode se perguntar se deve usar uma variação de Bloco ou uma variação de estilo de Bloco. A resposta é simples: Se as mudanças que você deseja fazer podem ser realizadas no theme.json ou com CSS, crie uma variação de estilo de Bloco. Qualquer outra modificação requer uma variação de Bloco.
Variações de bloco
Com as variações de bloco, você as registrará usando JavaScript. Criar um arquivo dentro do diretório de um tema é uma boa ideia, mas você pode ir para qualquer lugar. Você precisa de uma linha para registrar uma variação no seu arquivo JavaScript:
const registerBlockVariation = ( blockName, variation )Para blockName, você precisará especificar o namespace aqui também, como faria com a propriedade blocks. No objeto variation, você adicionará o nome, o título, a descrição, se a variação está ativa por padrão e muito mais. Para carregar o arquivo no Editor de Sites, basta chamar o hook enqueue_block_editor_assets e enfileirar seu script dentro dele.
Variações de estilo de bloco
Quando se trata de variações de estilo de bloco, você tem duas opções:
- Use a função
register_block_style()com PHP. - Criar um arquivo JavaScript
block-editor.js, usar a funçãoregisterBlockStyle()de forma semelhante às variações de bloco e enfileirar o script.
Depois de registrar uma variação de estilo de bloco, você pode direcionar o bloco usando a propriedade variations:
…
"styles": {
"blocks": {
"core/button": {
"variations": {
"outline": {
"border": {
"color": "var:preset|color|black",
"radius": "0",
"style": "solid",
"width": "3px"
},
…Isso significa que talvez você não precise de nenhum CSS personalizado – quase todos os aspectos do design de um bloco são possíveis por meio da propriedade blocks.
Como estilizar um bloco padrão usando a propriedade blocks do início ao fim
Para demonstrar como a propriedade blocks funciona, vamos examinar um exemplo real. Nosso site usa o tema Twenty Twenty-Four e está usando a variação de estilo padrão:
Até o momento, isso parece ideal para nós, embora os cabeçalhos e o corpo do texto pareçam ter cores muito semelhantes. Queremos alterar uma ou ambas as cores para diferenciá-las. Como usuário final ou proprietário do site, podemos corrigir isso na barra lateral de estilos do Editor de Sites. Se você for para Blocks > Heading (Blocos > Título), poderá clicar no elemento Text (Texto) e alterar a cor para algo mais adequado:
Entretanto, como desenvolvedor, você pode fazer isso em theme.json. Como qualquer outro tema, a melhor abordagem é criar um tema filho (child theme) para preservar as alterações feitas. Uma segunda vantagem é que seu arquivo theme.json terá uma aparência mais limpa.
Criaremos um diretório em wp-content/themes/ e o chamaremos de twentytwentyfour-child. Aqui, adicione um arquivo style.css válido e um arquivo theme.json em branco.
A partir daqui, você pode abrir o arquivo JSON e começar a trabalhar.
Criando e preenchendo um arquivo theme.json para o tema filho (child theme)
A principal diferença entre a criação de um tema principal (parent theme) e um tema filho (child theme) com relação a theme.json é a estrutura do arquivo. Você não precisará declarar o esquema ou necessariamente colocar tudo dentro do objeto settings. Em nosso caso, temos que usar a propriedade styles:
{
"version": 3,
"styles": {
"blocks": {}
}
}Em seguida, precisamos encontrar o namespace e o slug para o Heading Block. O Guia de Referência oficial dos Core Blocks lista tudo isso e ainda nos informa quais atributos e propriedades o bloco suporta. O guia nos diz que podemos ajustar os valores background, gradient, link e text para a propriedade color.
"blocks": {
"core/heading": {
"color": {}
}
}Com a estrutura concluída, podemos começar a descobrir como reestilizar o texto.
Encontrar um esquema de cores e aplicar as alterações
Agora, precisamos de uma cor que atenda às nossas necessidades. A variação padrão do Twenty Twenty-Four tem uma paleta excelente, e verificá-la em um verificador de contraste dedicado nos dá algumas ideias:
Em seguida, podemos adicionar a opção de cor do nosso bloco a theme.json. Como o tema principal do Twenty Twenty-Four usa propriedades CSS personalizadas para definir estilos de paleta, podemos chamar isso aqui também:
…
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" },
…Se precisar saber o nome de uma cor da paleta, você poderá encontrá-lo no Editor de Sites, no seletor de cores:
Depois de salvar as alterações, atualize o site e você verá o novo esquema de cores em vigor. Se isso não ocorrer, verifique se você está aninhando a propriedade blocks no objeto correto, pois esse é um ponto de dificuldade comum.
Ao analisar o site, o texto está com menos contraste e mais fácil de ler. No entanto, ainda queremos ver uma definição maior entre o bloco de parágrafos e os títulos ao redor. A paleta padrão do tema tem algumas outras cores mais ousadas. Vamos experimentar a cor Accent / 3 para o bloco de título:
"blocks": {
"core/heading": {
"color": { "text": "var(--wp--preset--color--accent-3)" }
},
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" }
}
}Depois de salvar as alterações e atualizar o frontend, você verá que o Heading Block tem mais definição:
Isso não precisa ser o fim da sua edição. Você pode até mesmo personalizar as opções do Editor de Sites em theme.json.
Como adicionar opções de atributos aos blocos
Os suportes de cada bloco determinam suas opções no Editor de Sites. Por exemplo, o Bloco de parágrafo tem como padrão a desativação da funcionalidade de capitular.
Podemos reativar essa opção no arquivo theme.json e na propriedade blocks. Ao analisar o material de referência, podemos aproveitar a propriedade typography para habilitar o drop caps.
…
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" },
"typography": { "dropCap": true }
…Assim que salvamos essas alterações e atualizamos o editor, a opção para ativar ou desativar o drop cap estará disponível para você:
O arquivo theme.json não é apenas uma configuração para o design. Ele também pode ajudar a adicionar e remover funcionalidades do Editor de Sites.
Como a hospedagem gerenciada da Kinsta pode apoiar o desenvolvimento de temas WordPress
As complexidades do desenvolvimento de temas e do theme.json dependem de soluções de qualidade em toda a cadeia de desenvolvimento para que você possa aproveitar o potencial de desempenho aprimorado.
Um ambiente de desenvolvimento local é crucial, pois isso permite que você crie, gerencie e ajuste sites WordPress diretamente na sua máquina. O DevKinsta pode ser uma grande ajuda nesse processo.
O DevKinsta oferece muitos benefícios:
- Ele é executado em contêineres Docker, o que significa que você isola sua instalação do restante da máquina. Dessa forma, você pode testar as configurações do
theme.jsone os blocos personalizados sem preocupações. - Você pode fazer iterações rápidas em seu arquivo
theme.jsone ver os resultados imediatamente em seu ambiente local. - Criar vários sites locais para testar seu tema em diferentes versões e configurações do WordPress é muito fácil.
Além disso, você não usará nenhum dos recursos do seu servidor até que esteja satisfeito e pronto. Os ambientes de teste da Kinsta fornecem a próxima etapa ideal. Você pode criar uma cópia do seu site de produção rapidamente e até mesmo transferi-la para o seu ambiente local para continuar trabalhando.
Essa é uma ótima maneira de realizar testes de desempenho para o seu tema, especialmente quando você combina o ambiente de teste com a ferramenta de Monitoramento de Desempenho de Aplicativos (APM) da Kinsta.
Você também pode aproveitar a integração do Git da Kinsta em todos os seus ambientes. Isso permite que você faça push e pull de alterações nos repositórios e implemente a partir deles também.
Resumo
Entender a propriedade blocks em theme.json é uma etapa necessária para todos os desenvolvedores de temas. Você pode usar um design global e torná-lo mais exclusivo, coeso e relevante. Ter o escopo completo para trabalhar com o núcleo individual e as configurações personalizadas do bloco ajuda cada usuário a aproveitar os recursos de edição completa de sites. Além disso, ter essas opções disponíveis no Editor de Sites significa que os usuários finais podem fazer suas próprias alterações sem código, enquanto você apresenta opções padrão excepcionais.
Você tem alguma dúvida sobre o uso da propriedade blocks com o arquivo theme.json? Pergunte na seção de comentários abaixo!
Deixe um comentário