Pular para o conteúdo

Canvas

O canvas oferece uma visão geral afastada, semelhante a Figma, de todas as páginas gerenciadas por Blockstudio. Cada página é exibida como uma prancheta em um iframe ativo, em uma única fileira horizontal. Desloque a visualização com o trackpad e ajuste o zoom com o gesto de pinça ou Ctrl+rolagem.

Ativação

O canvas está disponível em uma página de administração oculta. Acesse:

Código
/wp-admin/admin.php?page=blockstudio-canvas

A página só pode ser acessada quando dev.canvas.enabled está true e o usuário atual tem a capacidade edit_posts.

Configurações

Ative o canvas e configure seu comportamento em blockstudio.json do seu tema:

JSON
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
Propriedade Tipo Padrão Descrição
enabled boolean false Ative o recurso de canvas.
adminBar boolean true Mostre a barra de administração WordPress dentro dos iframes das pranchetas. Defina como false para uma prévia mais limpa.

As duas configurações também estão disponíveis como filtros:

PHP
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');

Visualizações

Alterne entre as visualizações pelo menu suspenso no canto superior direito.

  • Páginas: todas as páginas gerenciadas por Blockstudio, exibidas como pranchetas de largura total em uma única fileira.
  • Blocos: todos os blocos Blockstudio registrados em uma grade, cada um renderizado com os valores de atributo padrão.

Inventário público e documento API

Canvas expõe um contrato PHP versionado e neutro para consumidores, destinado a ferramentas que precisam do mesmo conteúdo registrado sem recriar a lógica de descoberta ou renderização de Blockstudio:

PHP
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);

A versão atual está disponível como Canvas::SCHEMA_VERSION. Os resultados do inventário contêm:

  • inventory: exemplos normalizados de pages, blocks, patterns, templates, parts e da família ui pública
  • order: a ordem estável de exibição entre tipos
  • sources: caminhos de origem exatos selecionados, com proveniência em cada registro; o source de um registro de página é sua identidade de origem estável, enquanto path é o caminho físico do modelo de renderização
  • warnings e errors: problemas estruturados em vez de saída emitida
  • deleted: identificadores solicitados que já não existem
  • selection: a seleção normalizada e se ela foi direcionada

Canvas::documents() adiciona um documento de renderização completo para cada registro selecionado. Cada documento contém seu corpo, o HTML montado, nomes de blocos com dependências resolvidas e CSS, JavaScript, módulos, inicialização de interatividade, globais UI agrupadas e saída Tailwind. Os documentos de página usam um contêiner de conteúdo semântico <main>; os chamadores podem substituí-lo ou desativá-lo usando as opções compartilhadas do documento Render. Cada página selecionada é renderizada em seu próprio contexto WordPress restaurado do frontend, para que condicionais de consulta, filtros de classes do body, shortcodes, layouts, redirecionamentos e callbacks wp_enqueue_scripts observem essa página, em vez da solicitação administrativa ou REST que pediu o resultado do Canvas. As classes do body fornecidas pelo chamador são combinadas com as classes contextuais da página, e os registros de enqueue do frontend são isolados entre documentos. O Canvas resolve esses callbacks do ciclo de vida pelos nomes públicos de função WordPress, preservando o mesmo contexto quando Blockstudio é carregado por Composer ou por um namespace de aplicação realocado.

Semântica da seleção exata

A seleção é estrita:

  • Sem chaves de tipo reconhecidas, todos os tipos são carregados.
  • true, null ou "*" carrega todos os registros daquele tipo.
  • Uma string ou lista carrega apenas IDs, nomes, slugs, caminhos ou caminhos de origem exatos.
  • Uma string/lista vazia ou false não carrega nenhum registro daquele tipo.
  • Depois que qualquer chave de tipo é especificada, os tipos omitidos não são descobertos, sincronizados, renderizados nem compilados.

Isso torna seguras as solicitações somente de itens alterados em projetos grandes. Os blocos e páginas existentes são resolvidos por seus registros canônicos. Quando uma solicitação de frontend carrega apenas a projeção persistida da página, o Canvas faz uma descoberta de origem somente para leitura e combina IDs de posts e links permanentes correspondentes sem sincronizar conteúdo. A mesma combinação de identidades também ocorre quando uma fonte de descoberta lógica preenche primeiro o registro baseado na origem, para que a renderização contextual da página ainda use o post WordPress gerenciado correspondente. A nova topologia da sessão ativa só é descoberta ao redor do diretório alterado, enquanto fontes selecionadas de padrões e modelos do Editor do site só são compiladas após a seleção.

O endpoint de atualização de REST segue a mesma regra para os parâmetros de consulta blocks e pages existentes. Por exemplo, ?blocks=theme/hero retorna esse bloco e nenhuma página; use os dois parâmetros para uma resposta mista. Chamar o endpoint sem nenhum dos parâmetros preserva a resposta legada completa.

Modo ao vivo

O modo ao vivo usa Server-Sent Events (SSE) para detectar alterações nos arquivos e atualizar o canvas em tempo real. Quando você edita um modelo de bloco, um modelo de página ou uma folha de estilo, as pranchetas afetadas são atualizadas automaticamente em cerca de um segundo.

Ative ou desative o modo ao vivo no menu suspenso. Quando está ativo, aparece um indicador verde pulsante. A configuração persiste entre sessões por meio de localStorage.

O modo ao vivo acompanha alterações em arquivos .php, .json, .css, .scss, .js, .twig e .html dentro dos diretórios de blocos e páginas. Alterações conhecidas atualizam somente o bloco ou a página registrada. Um bloco ou página realmente novo aciona uma verificação topológica restrita ao diretório, permitindo criar conteúdo durante uma sessão ao vivo aberta sem verificar novamente fontes não relacionadas.

Modo de foco

Clique em qualquer rótulo de prancheta para entrar no modo de foco. A prancheta selecionada ocupa toda a largura da janela, com rolagem vertical. Pressione Escape ou clique no botão de fechar para voltar à visão geral.

Controles

Ação Entrada
Deslocar a visualização Rolagem / arrasto com dois dedos no trackpad
Ajustar o zoom Ctrl+rolagem ou gesto de pinça
Ajustar à visualização Menu suspenso
Zoom para 100% Menu suspenso
Focar na prancheta Clique no rótulo da prancheta
Sair do modo de foco Escape / botão de fechar

Segurança

O script do canvas e os dados da página só são carregados quando todas as condições são atendidas:

  • A configuração dev.canvas.enabled está true.
  • O usuário atual tem a capacidade edit_posts.

Visitantes públicos nunca veem o script do canvas nem os metadados da página.