Migrando para v7
Este guia aborda as mudanças que você precisa fazer ao atualizar de Blockstudio 6 para 7.
Importações de módulos ES
Novo prefixo npm: (recomendado)
Blockstudio 7 introduz um novo prefixo npm: para importações de módulos ES, seguindo a convenção do especificador npm do Deno.
Antes (v6):
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";
Depois (v7):
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
Importações CSS
A mesma mudança se aplica às importações de CSS:
Antes (v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
Depois (v7):
import "npm:swiper@11.0.0/swiper.min.css";
Compatibilidade com versões anteriores
O prefixo blockstudio/ ainda é compatível com versões anteriores. Seu código existente continuará funcionando sem alterações. No entanto, recomendamos migrar para o prefixo npm: para manter a consistência com o ecossistema JavaScript mais amplo.
O prefixo npm: oferece várias vantagens:
- Alinhamento com o ecossistema – Segue a convenção estabelecida de Deno
- Clareza – Deixa imediatamente claro que você está importando de npm
- Preparação para o futuro – O prefixo
blockstudio/pode ser descontinuado em uma versão principal futura
Nomes dos hooks
Blockstudio 7 padroniza todos os nomes de hooks PHP para usar snake_case em vez de camelCase, seguindo as convenções do núcleo de WordPress.
Nomes de hooks alterados
| Nome antigo (v6) | Nome novo (v7) |
|---|---|
blockstudio/blocks/components/useblockprops/render |
blockstudio/blocks/components/use_block_props/render |
blockstudio/blocks/components/innerblocks/render |
blockstudio/blocks/components/inner_blocks/render |
blockstudio/blocks/components/innerblocks/frontend/wrap |
blockstudio/blocks/components/inner_blocks/frontend/wrap |
blockstudio/blocks/components/richtext/render |
blockstudio/blocks/components/rich_text/render |
blockstudio/assets/process/scss/importPaths |
blockstudio/assets/process/scss/import_paths |
blockstudio/settings/assets/process/scssFiles |
blockstudio/settings/assets/process/scss_files |
blockstudio/settings/editor/formatOnSave |
blockstudio/settings/editor/format_on_save |
blockstudio/settings/blockEditor/disableLoading |
blockstudio/settings/block_editor/disable_loading |
blockstudio/settings/blockEditor/cssClasses |
blockstudio/settings/block_editor/css_classes |
blockstudio/settings/blockEditor/cssVariables |
blockstudio/settings/block_editor/css_variables |
blockstudio/settings/ai/enableContextGeneration |
blockstudio/settings/ai/enable_context_generation |
Compatibilidade com versões anteriores
Os antigos nomes de hooks em camelCase ainda são compatíveis com versões anteriores. Seu código existente continuará funcionando sem alterações. No entanto, recomendamos migrar para os novos nomes em snake_case para manter a consistência.
Exemplo de migração:
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
return ['my-stylesheet'];
});
// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
return ['my-stylesheet'];
});
Tags canônicas de bloco
Blockstudio 7.6 mantém os prefixos de projeto e os aliases exatos como pontos de extensão em tempo de execução, mas usa <bs:namespace-slug> como grafia canônica em exemplos, na saída do catálogo, em declarações de renderização e em diagnósticos. As tags canônicas contêm o nome real do bloco registrado e não dependem de um filtro específico do host.
Para um projeto com brand => ["theme-components"] e ui => ["bsui"]:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
Um comando de migração independente inventaria um projeto existente e reescreve as formas abreviadas com a grafia canônica. Ele gera primeiro um relatório, bloqueia em casos não resolvidos e altera apenas os nomes das tags. Consulte Migração de tags de bloco para ver o comando, suas entradas e seu comportamento de segurança.
Nomenclatura de arquivos de recursos
Blockstudio 7 introduz a notação com ponto para sufixos de arquivos de recursos, substituindo a antiga notação com hífen como convenção recomendada.
Nomes de arquivos alterados
| Nome antigo (v6) | Nome novo (v7) |
|---|---|
*-inline.(s)css |
*.inline.(s)css |
*-inline.js |
*.inline.js |
*-editor.(s)css |
*.editor.(s)css |
*-editor.js |
*.editor.js |
*-scoped.(s)css |
*.scoped.(s)css |
*-view.js |
*.view.js |
Compatibilidade com versões anteriores
A antiga notação com hífen ainda é compatível com versões anteriores. Seus arquivos existentes continuarão funcionando sem renomeação. No entanto, recomendamos migrar para a notação com ponto nos novos blocos.
Exemplo de migração:
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css → style.inline.css
├── style-scoped.css → style.scoped.css
├── style-editor.css → style.editor.css
├── script.js
├── script-inline.js → script.inline.js
├── script-editor.js → script.editor.js
└── script-view.js → script.view.js
Alternância de campo
A propriedade switch agora tem false como padrão, em vez de true. No v6, cada campo tinha um controle invisível na borda esquerda, ativado por padrão. No v7, a alternância é opcional e usa um ícone de olho visível no rótulo do campo.
O que mudou
- Agora, o padrão é
false: os campos não têm mais um controle de alternância, a menos que você defina explicitamente"switch": true - Ícone de olho visível: em vez de uma área de clique oculta à esquerda, um botão com ícone de olho aparece na área do rótulo
- Sobreposição de desativação: quando um campo é desativado, uma sobreposição desfocada com o texto "Este campo está desativado" é exibida, em vez de apenas reduzir a opacidade
Migração
Se você dependia do comportamento padrão de alternância em v6, precisa ativá-lo explicitamente:
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
Se você definiu anteriormente "switch": false para desativar a alternância, pode removê-lo, pois false agora é o padrão.
Tailwind CSS
Blockstudio 7 substitui completamente a abordagem v6 Tailwind. No v6, Tailwind CSS era compilado no lado do cliente pelo CDN no editor e salvo em disco ao salvar a publicação. No v7, Tailwind CSS é compilado no lado do servidor a cada solicitação do frontend por meio de TailwindPHP, com cache automático baseado em arquivos.
Consulte a documentação de Tailwind CSS para ver todos os detalhes do novo sistema.
Compilação contínua no lado do servidor
Quando tailwind.enabled está true, cada solicitação do frontend é compilada no lado do servidor. O fluxo de compilação:
- WordPress renderiza a página completa HTML em um buffer de saída
- Os candidatos a classe CSS são extraídos de HTML (expressão regular rápida, sem compilação)
- Os candidatos são ordenados e recebem um hash com a configuração CSS para criar uma chave de cache
- Em caso de acerto no cache: o arquivo CSS em cache é lido e injetado
- Em caso de falha no cache: TailwindPHP compila CSS, grava-o no cache compartilhado de execução de Blockstudio sob o escopo
tailwinde o injeta
O CSS compilado é inserido como uma tag <style id="blockstudio-tailwind"> inline antes de </head>. Isso inclui o preflight de Tailwind e todas as classes utilitárias correspondentes.
O script CDN permanece ativo no editor apenas para pré-visualização ao vivo. Ele nunca é servido no frontend.
Formato de config alterado
A propriedade config mudou de um objeto JSON (Tailwind v3) para uma string CSS (sintaxe com Tailwind v4 CSS primeiro).
Antes (v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
Depois (v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
Configuração customClasses removida
A configuração de array customClasses foi removida. Com a abordagem de CSS primeiro de Tailwind v4, as classes utilitárias personalizadas são definidas diretamente na string config usando @layer utilities.
Antes (v6):
{
"tailwind": {
"customClasses": [
{ "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
{ "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
]
}
}
Depois (v7):
{
"tailwind": {
"config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
}
}
Ou pelo filtro para configurações multilinha:
add_filter('blockstudio/settings/tailwind/config', function () {
return <<<CSS
@layer utilities {
.btn { @apply px-4 py-2 rounded-lg font-medium; }
.card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
O filtro blockstudio/settings/tailwind/custom_classes também foi removido. Use o filtro blockstudio/tailwind/css para acrescentar regras personalizadas CSS.
Endpoint REST removido
O endpoint POST /blockstudio/v1/editor/tailwind/save foi removido. O CSS compilado não é mais salvo pelo editor. Se você tinha código personalizado que chamava esse endpoint, pode removê-lo com segurança.
Cache
Blockstudio usa uma estratégia de cache baseada em candidatos. Em vez de calcular o hash de toda a página HTML (o que invalidaria o cache a cada solicitação devido a nonces e marcas de tempo), apenas os candidatos de classe CSS são submetidos a hash. Isso significa que:
- Duas páginas com as mesmas classes CSS compartilham o mesmo arquivo em cache
- Conteúdo dinâmico (nonces, barras de administração, marcas de tempo) não invalida o cache
- O cache só é invalidado quando o conjunto de classes CSS muda ou quando a configuração muda
Os arquivos de cache usam a raiz de tempo de execução Blockstudio configurada em
sites/{network-blog}/{runtime-identity}/tailwind/. Chame
Blockstudio\Runtime_Cache::purge('tailwind') para forçar a recompilação.
Alterações nos filtros
| Nome antigo (v6) | Nome novo (v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
Removido |
blockstudio/settings/tailwind/custom_classes |
Removido |
Arquivos e enfileiramentos removidos
No v6, Tailwind CSS era enfileirado como folhas de estilo externas (blockstudio-tailwind, blockstudio-tailwind-preflight). No v7, todo o CSS é inserido inline por meio de um buffer de saída. Não há tags de link nem folhas de estilo enfileiradas para Tailwind no frontend.
Biblioteca de blocos
A biblioteca integrada “Elementos Blockstudio” foi removida. A configuração library em blockstudio.json e o filtro blockstudio/settings/library não têm mais efeito.
Se você usava os blocos da biblioteca (Galeria, Slider, Comparação de imagens, Código, Ícone), copie as pastas dos blocos do diretório includes/library/blockstudio-element/ da instalação de v6 para o diretório blockstudio do seu tema e atualize os arquivos block.json deles com os novos nomes e categorias.