Pular para o conteúdo

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

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):

JavaScript
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):

JavaScript
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):

JavaScript
import "blockstudio/swiper@11.0.0/swiper.min.css";

Depois (v7):

JavaScript
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:

PHP
// 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"]:

HTML
<!-- 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:

Código
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:

JSON
{
  "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:

  1. WordPress renderiza a página completa HTML em um buffer de saída
  2. Os candidatos a classe CSS são extraídos de HTML (expressão regular rápida, sem compilação)
  3. Os candidatos são ordenados e recebem um hash com a configuração CSS para criar uma chave de cache
  4. Em caso de acerto no cache: o arquivo CSS em cache é lido e injetado
  5. Em caso de falha no cache: TailwindPHP compila CSS, grava-o no cache compartilhado de execução de Blockstudio sob o escopo tailwind e 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):

JSON
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "primary": "pink"
          }
        }
      }
    }
  }
}

Depois (v7):

JSON
{
  "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):

JSON
{
  "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):

JSON
{
  "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:

PHP
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.