Pular para o conteúdo

Dennis · 23 de julho de 2026

Blockstudio 7.5

Blockstudio A versão 7.5 completa o fluxo de trabalho de Blockstudio que prioriza arquivos: tipos de campos personalizados, modelos do Editor do site baseados em arquivos, ilhas de blocos, armazenamento de banco de dados Storh, fontes lógicas de descoberta, tags de bloco compostas e caminhos de implantação e de tempo de execução mais rápidos.

Os campos personalizados reutilizáveis já permitem que os projetos definam uma vez um grupo de campos existentes e o reutilizem com type: "custom/{name}". Os tipos de campos personalizados resolvem outro problema. Eles permitem que um tema ou plugin registre um novo tipo de campo com namespace, forneça seu próprio controle de editor e armazene o valor como dados Blockstudio normais.

Em resumo:

  • Fontes lógicas de descoberta: os runtimes podem fornecer um inventário lógico composto de temas, incluindo proveniência e identidade do cache, enquanto Blockstudio mantém a responsabilidade pela descoberta, resolução de arquivos irmãos, assets gerados, Canvas e comportamento de Tailwind.
  • Registro de tipos de campo PHP: temas e plugins podem registrar tipos de campo com namespace, como acme/dimensions com bs_register_field_type() ou o filtro blockstudio/field_types.
  • Registro de controles do editor: scripts personalizados do editor podem chamar window.blockstudio.registerFieldType() e renderizar o controle React correspondente no UI normal do campo Blockstudio.
  • Valores estruturados: campos personalizados podem armazenar strings, números, booleanos, arrays ou objetos sem converter valores de objeto por meio da normalização de campos de opção.
  • Suporte a armazenamento: campos personalizados de metadados de posts e campos personalizados baseados em opções podem declarar seu tipo de valor e o esquema REST, incluindo valores de objeto e array.
  • Integração nativa: tipos de campo personalizados funcionam dentro de grupos, abas, repetidores, campos personalizados reutilizáveis, templates e caminhos de template de extensões.
  • Templates do Editor do site: temas podem definir fontes wp_template e wp_template_part a partir de arquivos de template template.json, part.json e Blockstudio.
  • Ilhas de blocos: os blocos podem renderizar primeiro um invólucro seguro para cache e, em seguida, hidratar ou buscar em lote fragmentos específicos da solicitação após o carregamento da página.
  • Armazenamento de banco de dados Storh: bs.db pode usar um armazenamento indexado de um arquivo por registro em uploads, preservando IDs inteiros públicos e a migração de JSONC para Storh por meio de WP-CLI.
  • Aprimoramentos do parser e do bsui: parágrafos richtext mapeados precisam de menos código de integração personalizado do parser; InnerBlocks pode usar allowedBlocks tokenizado; a saída aninhada de bs_render_block() corresponde à renderização do frontend nas prévias do editor; e bsui/button ganha ícones e opções de estilização mais simples.
  • Tags de bloco combináveis: tags de prefixo podem ser resolvidas por meio de outro prefixo (<theme-ui-input> para bsui/input), e tags de prefixo e de alias são renderizadas na saída de templates de bloco, não apenas no conteúdo da página.
  • Caches de build seguros para o host: os caches do runtime e do editor agora ficam, por padrão, fora de uploads, aceitam locais configuráveis e removem entradas obsoletas para que projetos de longa duração não acumulem arquivos de cache.
  • Reconciliação incremental de páginas: ferramentas de implantação podem reconciliar o inventário completo de páginas em arquivos, ignorar posts inalterados, informar exatamente o que mudou e persistir uma identidade de origem verificada após a ativação.
  • Renderização aquecida mais rápida: caches válidos do runtime são hidratados antes da descoberta; solicitações simultâneas sem cache publicam um único resultado atômico; e Tailwind mantém um cache do tamanho do site com estado do compilador reutilizável.
  • Renderização segura em lote: exportadores podem redefinir o estado de renderização por solicitação entre documentos sem reconstruir a descoberta e coletar dependências de origem durante a renderização dos blocos.

Novos recursos

A versão 7.5 traz um amplo conjunto de novos recursos para descoberta, templates e armazenamento.

Fontes lógicas de descoberta

Blockstudio normalmente descobre arquivos em diretórios físicos de temas. A versão 7.5 adiciona uma fonte de nível mais baixo, API, para runtimes que montam um tema a partir de sobreposições, prévias, arquivos gerados, montagens remotas ou outros inventários compostos.

Uma integração pode fornecer uma árvore lógica de arquivos final, enquanto Blockstudio mantém a responsabilidade por blocos, campos, páginas, padrões, Editor do site, Canvas, assets e comportamento de Tailwind:

PHP
use Blockstudio\Inventory_Discovery_Source;

add_filter(
    'blockstudio/discovery/sources',
    function (array $sources, string $context): array {
        if ('blocks' !== $context) {
            return $sources;
        }

        return [
            new Inventory_Discovery_Source(
                'preview:feature-card',
                '/runtime-preview/feature-card/blockstudio',
                [
                    'card/block.json' => [
                        'path' => '/theme/blockstudio/card/block.json',
                        'provenance' => ['layer' => 'parent'],
                    ],
                    'card/index.php' => [
                        'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
                        'provenance' => ['layer' => 'preview'],
                    ],
                ],
                'preview-fingerprint'
            ),
        ];
    },
    10,
    2
);

Os caminhos lógicos permanecem estáveis mesmo quando arquivos irmãos vêm de raízes físicas diferentes. IDs de origem e impressões digitais alimentam as identidades de cache do runtime e de Tailwind; alterações nas entradas monitoradas invalidam esses caches, e a proveniência determina onde os arquivos gerados podem ser gravados. A fonte padrão do sistema de arquivos não muda para temas comuns.

Templates do Editor do site baseados em arquivos

As páginas e os padrões já permitem que equipes mantenham estruturas de conteúdo em arquivos. A versão 7.5 estende esse modelo ao próprio Editor do site.

Text
theme/
  templates/
    front-page/
      template.json
      index.php
  parts/
    header/
      part.json
      index.php
JSON
{
  "slug": "front-page",
  "title": "Front Page"
}
PHP
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <block name="core/post-content" />
  </main>
</div>

Blockstudio compila a origem com o mesmo parser usado para páginas e padrões e, em seguida, disponibiliza o resultado para WordPress como um template ou parte de template normal do Editor do site. O Editor do site exibe o template, o frontend pode renderizá-lo e WordPress continua sendo responsável pelas personalizações.

Essa última parte é importante. Os templates baseados em arquivos são a origem usada como alternativa. Se alguém salvar um template no Editor do site, WordPress criará a personalização normal de banco de dados wp_template ou wp_template_part, e essa versão prevalecerá. Redefina a personalização para que a versão mais recente da origem em arquivo volte a aparecer.

Implantação incremental de páginas

As páginas baseadas em arquivos ganharam um API de reconciliação de implantação na versão 7.5. A partir de 7.6.2, somente API e wp bs pages sync explícitos são pontos de entrada para sincronização; solicitações comuns nunca aplicam alterações na origem:

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

O processo descobre todo o inventário desejado de páginas, compara o conteúdo e as impressões digitais do mecanismo de sincronização e informa quais páginas foram criadas, atualizadas, mantidas sem alterações, removidas ou apresentaram falha. Páginas com impressões digitais idênticas não geram gravações em post ou postmeta. Páginas gerenciadas ausentes só são removidas após a conclusão da descoberta sem erros.

A reconciliação retorna uma identidade de origem determinística, mas não marca a implantação como bem-sucedida. As ferramentas de implantação armazenam essa identidade somente após a ativação e verificação dos arquivos e das rotas correspondentes. A inicialização comum de WP-CLI registra tipos de post de coleção e regras de reescrita armazenados em cache sem descobrir e sincronizar todas as páginas.

Ilhas de blocos

A maioria dos blocos de Blockstudio é renderizada no servidor. Isso funciona bem com WordPress, mas cria um problema conhecido de cache: um bloco personalizado pode dificultar o armazenamento da página inteira em cache.

As ilhas de blocos dividem esse limite no nível do bloco.

JSON
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}

Uma ilha dinâmica renderiza apenas um espaço reservado seguro para cache na resposta inicial. Em seguida, o navegador envia uma única solicitação em lote para todas as ilhas dinâmicas prontas na página, e Blockstudio renderiza esses fragmentos no contexto real da solicitação do visitante.

Isso permite que um cache de página inteira armazene o invólucro da página, enquanto a contagem do carrinho, os controles da conta, o UI com acesso restrito por permissões e outros elementos específicos de cada usuário continuam atualizados.

PHP
<div class="cart-count-placeholder">Loading cart...</div>
PHP
<div class="cart-count">
  <?php echo esc_html(acme_cart_count()); ?>
</div>

Para blocos que já renderizam HTML seguros para cache e precisam apenas de um sinal de montagem no frontend, use uma ilha hidratada:

JSON
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}

Ilhas hidratadas não fazem uma solicitação REST. Elas são renderizadas normalmente e recebem um evento blockstudio:island:hydrate no frontend.

As ilhas dinâmicas também funcionam nos caminhos de renderização programática:

PHP
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

E também por meio de tags de bloco:

HTML
<bs:acme-cart-count product-id="42" />

O endpoint tem um escopo intencionalmente restrito. Ele só renderiza blocos Blockstudio registrados que sejam dinâmicos e estejam explicitamente marcados como ilhas dinâmicas. Os atributos são filtrados de acordo com o esquema do bloco e a lista de permissões da ilha, e cada marcador contém uma assinatura gerada pelo site WordPress que atende a solicitação.

Armazenamento de banco de dados Storh

A camada de banco de dados de Blockstudio já oferece suporte a tabelas, SQLite, JSONC, metadados de posts e tipos de posts personalizados. A versão 7.5 adiciona storage: "storh" para projetos que querem um armazenamento baseado em arquivos, com gravações simultâneas mais seguras e índices derivados do esquema, mas não querem registros ativos armazenados junto aos arquivos de origem dos blocos.

PHP
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];

Os registros de Storh ficam em uploads:

Text
wp-content/uploads/blockstudio/db/my-theme-my-block/default/

O API público permanece inalterado. bs.db(), REST e Db::get() continuam retornando valores inteiros de id. Internamente, Blockstudio associa esses IDs aos IDs de documento UUIDv7 de Storh, portanto o código cliente existente não precisa mudar.

Todos os campos declarados no esquema são indexados para filtros de igualdade; campos numéricos e semelhantes a datas recebem índices de intervalo, e as indicações explícitas de unicidade são repassadas. Para projetos que começaram com arquivos de seed JSONC, a nova migração CLI mantém o arquivo de origem no lugar e grava um armazenamento Storh equivalente:

Shell
wp bs db migrate my-theme/app subscribers --to=storh

Isso dá a JSONC uma função mais clara como formato simples de seed/configuração que pode ser versionado, enquanto Storh passa a ser a melhor opção padrão de backend em arquivos para dados de produção graváveis.

Aprimoramentos do parser e do bsui

A versão 7.5 também conclui pequenos aprimoramentos que costumam ser necessários quando um projeto passa a depender mais de templates baseados em arquivos e de UI empacotados.

O mapeamento de elementos agora lida com o caso comum de parágrafo richtext sem um builder personalizado. Se <p> for mapeado para um bloco Blockstudio registrado que não seja do núcleo e tiver um atributo richtext content, o texto interno simples será copiado para esse atributo. Tags aninhadas e elementos filhos mapeados continuam sendo analisados como blocos internos.

InnerBlocks aceita allowedBlocks tokenizado em templates:

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />

Os tokens compatíveis são namespace/*, category:<slug> e @theme. Eles são expandidos no servidor antes de o editor receber o template, portanto o caminho de renderização do frontend permanece inalterado.

Incorporações programáticas também estão mais previsíveis. Agora, bs_render_block() e bs_block() renderizam blocos incorporados como HTML resolvidos pelo frontend, mesmo quando chamados de dentro da prévia do editor de outro bloco. Assim, blocos aninhados não deixam componentes fictícios <RichText /> ou <InnerBlocks /> brutos na marcação da prévia.

Para UI empacotado, bsui/button agora oferece suporte a um atributo icon e a iconPosition. Os estilos inline de bsui/* empacotado são emitidos em uma camada de cascata @layer bsui, e as variantes de botões podem ser estendidas com blockstudio/ui/button/variants-style e o filtro blockstudio/blocks/attributes existente.

As tags de bloco também podem ser combinadas de outras formas. Um prefixo pode ser resolvido por meio de outro; assim, <theme-ui-input /> com o prefixo de projeto theme sobre o prefixo de namespace ui é resolvido como bsui/input. Tags de prefixo e de alias registradas agora também são renderizadas na saída de templates de bloco, não apenas no conteúdo da página, permitindo que um template as gere diretamente em vez de chamar bs_render_block().

Builders de blocos personalizados registrados por meio de blockstudio/block_tags/builders também participam de forma consistente da análise de tags e de elementos mapeados. Os filtros explícitos de renderização continuam sendo executados depois e podem substituir o builder.

Solicitações aquecidas e exportações mais rápidas

Agora, por padrão, os caches do runtime e do editor ficam em wp-content/blockstudio/cache, em vez de uploads. O local pode ser alterado por meio de cache.path ou blockstudio/cache/dir, permitindo manter o cache persistente em hosts que bloqueiam cargas PHP em uploads. Os caches do runtime, dos assets do editor e de Tailwind também removem automaticamente entradas obsoletas, para que projetos de longa duração não acumulem arquivos de cache ilimitados no disco.

Agora, as solicitações aquecidas do frontend hidratam um registro válido do runtime antes de construir as fontes de descoberta. Isso evita a descoberta recursiva das fontes, a construção de blocos, a análise de campos e as repetidas percorridas da árvore para gerar chaves de cache. Por padrão, solicitações de produção e de staging confiam em um snapshot validado das alterações monitoradas por 20 segundos, enquanto ambientes locais e de desenvolvimento continuam verificando a cada solicitação.

A criação de um cache frio é executada uma única vez por vez. Uma solicitação constrói e publica o payload atomicamente enquanto as solicitações simultâneas aguardam o resultado concluído. Agora, Tailwind mantém até 1,000 entradas compiladas por 30 dias, por padrão, e reutiliza o estado de construção aquecido do compilador, evitando que um conjunto de rotas do tamanho de um site fique alternando em um cache pequeno.

Exportadores de longa duração podem chamar Blockstudio\Batch_Render::reset() entre documentos. Isso limpa os contadores, assets, ilhas, layouts e a geração de Tailwind específicos da solicitação sem reconstruir a descoberta. O filtro blockstudio/render/dependencies disponibiliza os caminhos de templates e assets usados por cada bloco renderizado para criar grafos de dependências.

Confiabilidade e compatibilidade

Várias correções completam a versão:

  • As definições de campo alteradas por meio de blockstudio/blocks/attributes agora controlam a validação de opções no momento da renderização, assim como o esquema do editor. Os valores tipados de opções numéricas e booleanas também são resolvidos de forma consistente.
  • Os invólucros de blocos do editor usam as mesmas classes geradas que as renderizações do frontend, e o Canvas pode copiar as classes de corpo configuradas para o frontend por meio do novo filtro blockstudio/editor/canvas/body_class.
  • O Content Sync valida todo o plano de origem antes de gravações destrutivas, mantém as operações de remoção dentro do conjunto de conteúdo configurado e informa falhas ao gravar arquivos sem avançar o estado de sincronização dessa entidade.
  • Pacotes Composer incluídos em temas ativos ou pais vinculados simbolicamente resolvem os assets do editor a partir do URL do tema público.
  • Páginas em arquivos com chave preservam os valores de campos Blockstudio gerenciados pelo editor, migram a antiga estrutura de chaves aninhadas durante a sincronização e aceitam zero numérico como chave válida.
  • Ilhas dinâmicas verificam assinaturas antes dos filtros de atributos da solicitação, ignoram contexto de solicitação sem assinatura, restauram visitantes conectados da mesma origem e evitam colisões de cache de usuários por visitante anônimo.
  • Os endpoints de páginas Markdown brutas agora respeitam a visibilidade de posts e a proteção por senha.
  • Os controles do editor lidam de forma mais confiável com condições vazias, valores de alternância de todas as caixas de seleção, atualizações assíncronas de opções, ordenação da renderização dinâmica e estado RichText ou WYSIWYG de repetidores.

Tipos de campo personalizados

Saiba mais sobre os tipos de campo personalizados apresentados acima.

Por que usar tipos de campo personalizados?

Blockstudio deve continuar sendo útil desde o início, mas projetos reais costumam precisar de controles específicos do domínio: seletores de tokens de espaçamento, funções de cores de sistemas de design, dimensões responsivas, fontes de ícones, seletores de produtos ou controles editoriais associados a um valor estruturado.

Antes da versão 7.5, esses projetos podiam combinar vários campos integrados ou criar uma bifurcação do editor. A versão 7.5 oferece uma opção intermediária com suporte: Blockstudio gerencia o ciclo de vida do campo, e o projeto gerencia o controle.

PHP
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});
JavaScript
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});

Em seguida, o campo pode ser usado em block.json como um campo nativo:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "bottom"],
        "default": {
          "top": "md",
          "bottom": "md"
        }
      }
    ]
  }
}

Valores normais de template

O valor salvo está disponível em PHP, Twig e Blade como qualquer outro atributo Blockstudio.

PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>

Os mesmos caminhos de objeto também funcionam em templates de extensões:

JSON
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}

Observações de compatibilidade

Os tipos de campo integrados existentes permanecem inalterados. Os grupos reutilizáveis de campos custom/{name} existentes também permanecem inalterados. Os nomes dos tipos de campo personalizados devem estar em minúsculas e usar namespace, por exemplo, acme/dimensions; os namespaces custom/ e blockstudio/ continuam reservados.

Se PHP registrar um tipo de campo, mas o script do editor não registrar o controle correspondente, Blockstudio preservará o valor salvo e exibirá um aviso não editável no editor. Se um tipo de campo não estiver registrado em PHP, Blockstudio o excluirá dos atributos WordPress gerados.

Atualização de manutenção de 7.5.1

7.5.1 remove um aviso de conversão de array para string emitido ao preparar vários valores de seleção para renderização. Os valores salvos e renderizados já estavam corretos, mas os logs de depuração podiam receber um aviso para cada renderização de campo.

A atualização correspondente de blockstudio/phpstan v0.1.7 também reconhece campos aninhados em grupos anônimos em PHP, Twig, Blade e formatos inferidos de atributos de template. Projetos existentes podem receber essa correção do pacote com composer update blockstudio/phpstan.