Pular para o conteúdo

Configurações

Blockstudio inclui uma poderosa API de configurações, que permite definir opções por meio de um arquivo blockstudio.json dentro da pasta do tema e/ou de filtros. Além disso, usuários autorizados podem alterar as configurações visualmente na área administrativa.

Via JSON

Se houver um arquivo blockstudio.json na pasta do tema, ele será usado para definir as opções padrão do site atual. Há um esquema JSON disponível para validar o arquivo e ajudar no preenchimento automático em um IDE.

O arquivo é opcional. Sem ele, Blockstudio usa as configurações salvas na área administrativa, além dos valores padrão integrados. A adição, alteração ou remoção do arquivo é detectada automaticamente, portanto não é necessário limpar o cache nem recarregar manualmente.

As seguintes propriedades estão disponíveis:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "users": {
    "ids": [],
    "roles": []
  },
  "assets": {
    "enqueue": true,
    "reset": {
      "enabled": false,
      "fullWidth": []
    },
    "minify": {
      "css": false,
      "js": false
    },
    "process": {
      "scss": false
    }
  },
  "cache": {
    "enabled": true,
    "path": "blockstudio/cache"
  },
  "themeDefaults": {
    "titleTag": false,
    "suppressDirectoryUpdates": false
  },
  "performance": {
    "profile": "compat",
    "wordpress": {
      "headNoise": false,
      "embeds": false,
      "xmlrpc": false,
      "editor": false,
      "frontendAssets": false,
      "media": false,
      "heartbeat": false
    },
    "preload": {
      "links": "off"
    },
    "media": {
      "lazy": false,
      "skeleton": false,
      "metadata": false,
      "rootMargin": "300px"
    },
    "measurement": {
      "enabled": false,
      "queryMonitor": false,
      "headers": false,
      "timings": false
    }
  },
  "content": {
    "enabled": false,
    "id": "default",
    "path": "content",
    "includePageSyncManaged": false,
    "authors": "ignore",
    "postTypes": [],
    "meta": {
      "include": [],
      "exclude": ["_edit_lock", "_edit_last", "_wp_old_slug"],
      "references": {}
    },
    "taxonomies": [],
    "media": "manifest"
  },
  "editor": {
    "formatOnSave": false,
    "assets": [],
    "markup": false
  },
  "tailwind": {
    "enabled": false,
    "config": "",
    "output": "inline"
  },
  "blockTags": {
    "enabled": false,
    "allow": [],
    "deny": [],
    "prefixes": {}
  },
  "ui": {
    "enabled": false
  },
  "blockEditor": {
    "disableLoading": false,
    "enhance": false,
    "cssClasses": [],
    "cssVariables": [],
    "blocks": {
      "allow": [],
      "deny": [],
      "directory": true,
      "categories": {
        "allow": [],
        "deny": [],
        "rename": {},
        "order": []
      },
      "styles": {
        "deny": {}
      },
      "legacyWidgets": {
        "hide": []
      }
    },
    "patterns": {
      "core": true,
      "remote": true,
      "theme": true,
      "blockstudio": true,
      "categories": {
        "allow": [],
        "deny": [],
        "rename": {},
        "order": []
      }
    },
    "media": {
      "openverse": true,
      "imageSizes": {
        "allow": [],
        "deny": []
      }
    }
  },
  "dev": {
    "grab": {
      "enabled": false
    },
    "perf": false,
    "canvas": {
      "enabled": false,
      "adminBar": true
    }
  },
  "githooks": {
    "commit": false
  },
  "phpstan": {
    "preset": "base",
    "configuration": "",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "ai": {
    "enableContextGeneration": false
  }
}

Via filtros

Como alternativa, você pode usar o filtro blockstudio/settings/${setting} para definir opções via PHP e obter mais flexibilidade.

PHP
add_filter('blockstudio/settings/assets/enqueue', '__return_false');
add_filter('blockstudio/settings/editor/formatOnSave', '__return_true');
add_filter('blockstudio/settings/ui/enabled', '__return_true');
add_filter('blockstudio/settings/block_editor/patterns/remote', '__return_false');

As opções definidas pelo filtro blockstudio/settings/${setting} substituem as definidas pelo arquivo blockstudio.json. Os dois métodos podem ser usados em conjunto.

Os valores de tempo de execução também expõem filtros blockstudio/performance/${setting} e um filtro blockstudio/performance/config final. Este último deve retornar um objeto de configuração válido.

Como as fontes se sobrepõem

Cada fonte é carregada e mesclada, começando pela de menor prioridade:

  1. Valores padrão integrados
  2. Configurações salvas pela área administrativa UI (a opção blockstudio_settings)
  3. blockstudio.json no tema
  4. filtros blockstudio/settings/*

blockstudio.json substitui apenas as chaves que declara. Antes, substituía por completo as configurações salvas, fazendo com que um valor irrelevante salvo na área administrativa deixasse de ser aplicado assim que o arquivo aparecia; agora, ele se sobrepõe a elas. Por outro lado, um valor desatualizado salvo pela área administrativa UI continua sendo aplicado até que o arquivo declare essa chave ou o valor salvo seja removido. Se uma configuração se comportar de maneira diferente do que o arquivo indica, confira a camada salva com wp bs settings ou Settings::get_raw(), que retorna apenas o que a fonte ativa JSON ou de opções declarou explicitamente.

Lendo configurações de PHP

Blockstudio\Settings carrega a fonte ativa, informa sobre JSON malformados e recarrega automaticamente quando blockstudio.json muda:

PHP
use Blockstudio\Settings;

$enabled = Settings::get_bool('performance/media/lazy');
$margin = Settings::get_string('performance/media/rootMargin', '300px');
$roles = Settings::get_array('users/roles');
$ttl = Settings::get_int('performance/staticPrerender/ttl', 86400);

foreach (Settings::errors() as $error) {
    error_log($error);
}

Use Settings::get_raw() quando uma integração precisar apenas de valores declarados explicitamente pela fonte JSON ativa ou pela fonte de opções. Settings::fingerprint() retorna uma identidade determinística das configurações efetivas. Processos de longa duração podem chamar Settings::reload() explicitamente para detectar imediatamente uma alteração no arquivo. O acesso normal verifica o arquivo no máximo uma vez por segundo dentro de uma solicitação ou processo PHP de longa duração, inclusive para edições que mantêm o mesmo tamanho. Alterar o caminho configurado tem efeito na próxima leitura. Quando não há um arquivo JSON ativo, as configurações salvas no banco de dados não sofrem o atraso dessa janela.

O perfil de desempenho resolvido está disponível por meio de Blockstudio\Runtime_Settings::current(). Ele aceita caminhos com barras ou pontos:

PHP
use Blockstudio\Runtime_Settings;

$runtime = Runtime_Settings::current();

if ($runtime->enabled('measurement/queryMonitor')) {
    $hash = $runtime->hash();
}

Configurações disponíveis

users

Opção Tipo Padrão Descrição
ids array [] IDs de usuário com acesso ao editor
roles array [] Funções de usuário com acesso ao editor

assets

Opção Tipo Padrão Descrição
enqueue boolean true Enfileirar automaticamente os recursos dos blocos
reset.enabled boolean false Remover os estilos dos blocos do core e aplicar a redefinição de utilitários do editor
reset.fullWidth array [] Tipos de publicação que usam o layout de editor em largura total
minify.css boolean false Minificar a saída de CSS
minify.js boolean false Minificar a saída de JS
process.scss boolean false Processar arquivos SCSS
output string source Onde os recursos compilados são gravados: source ou cache
inlineLimit integer 0 Bytes de recursos externos de blocos CSS impressos em linha por página

output usa source por padrão, o que grava um diretório _dist ao lado de cada bloco. Defina como cache para gravar os recursos compilados no diretório de cache Blockstudio, mantendo a árvore de código-fonte dos blocos limpa e implantável a partir de um checkout imutável. As fontes Blockstudio não podem gravar em cache redirecionado independentemente desta configuração.

inlineLimit está desativado em 0, então cada folha de estilo externa mantém sua tag <link>. Defina-o com um número de bytes para imprimir em linha as menores folhas de estilo externas de blocos de uma página, desde que o total permaneça dentro desse número. 40000 é o limite que o core de WordPress usa para a mesma regra. Consulte Inserir folhas de estilo pequenas em linha.

Com reset.enabled ativo, Blockstudio também copia valores sanitizados de body_class do frontend para a tela do editor. Use blockstudio/editor/canvas/body_class para ajustar a lista de classes exclusiva do editor.

cache

Opção Tipo Padrão Descrição
enabled boolean true Ativar caches baseados em arquivos Blockstudio
path string "blockstudio/cache" Caminho do cache, relativo a WP_CONTENT_DIR ou absoluto
namespaceGrace integer 86400 Segundos durante os quais um namespace de cache aposentado é mantido antes da coleta

Por padrão, os arquivos de cache são gravados em wp-content/blockstudio/cache, fora do diretório de uploads. Um caminho path relativo é resolvido a partir de WP_CONTENT_DIR; um caminho absoluto é usado diretamente. Isso é compatível com hosts que fornecem um volume de cache gravável dedicado.

Quando ativado, Blockstudio usa essa raiz única para cargas de compilação, dados pré-compilados de registro de blocos, recursos resolvidos do editor, Tailwind CSS, documentos de renderização, fragmentos de ilhas, pré-renderizações estáticas, índices de grafo, filas e diagnósticos. Cada objeto é isolado por rede, site, identidade completa de tempo de execução e escopo. As identidades de tempo de execução abrangem Blockstudio, configurações, WordPress, PHP, o tema ativo, plugins ativos, fontes lógicas de descoberta, contexto do host e hashes explícitos de dependências fornecidos pela operação responsável.

Alterações em conteúdo, termos, usuários e metadados invalidam as opções de campos preenchidas, não a descoberta estrutural dos blocos nem os recursos compilados. As opções são atualizadas separadamente, sob um bloqueio fixo do caminho de compilação. Uma sequência de gravações, como uma sincronização de traduções ou uma importação, é agrupada: a primeira gravação após um período de inatividade atualiza imediatamente, e a última gravação da sequência é refletida quando se completam trinta segundos, intervalo ajustável com blockstudio/cache/populate_debounce. Metadados que WordPress grava como registro administrativo, como o bloqueio de edição de uma publicação, não contam como alteração; blockstudio/cache/populate_ignored_meta_keys amplia essa lista. O editor sempre consulta as opções em tempo real, portanto o intervalo afeta apenas as opções em cache lidas no momento da renderização. Arquivos de origem e configurações de compilação continuam invalidando o cache estrutural normalmente. Sobrescrever opções não faz uma nova varredura do diretório de cache a cada alteração de conteúdo; a limpeza periódica continua removendo arquivos temporários órfãos. As identidades de tempo de execução específicas de cada idioma permanecem isoladas; a existência de vários diretórios de namespace de cache em um site multilíngue não é, por si só, indício de falha de cache.

A atividade de registro SQLite dentro do diretório de dados db de um bloco não descarta os metadados do bloco em cache. Alterações em db.php, nos arquivos de origem monitorados ou na estrutura de arquivos de origem e subdiretórios do diretório de dados ainda invalidam o cache.

Há um único construtor eleito para reconstruções simultâneas em tempo de execução. Outras solicitações aguardam até cinco segundos e, em seguida, reutilizam os metadados válidos mais recentes dos blocos quando os arquivos-fonte e os recursos compilados necessários ainda existem. Uma solicitação sem dados em cache e sem uma carga útil segura retorna HTTP 503 com Retry-After, em vez de iniciar outra compilação. O filtro blockstudio/cache/build_wait_budget ajusta a espera em milissegundos tanto para reconstruções estruturais quanto para atualizações de opções. Um host sem bloqueios de arquivo consultivos atualiza as opções sem proteção e ainda as publica, permitindo que a próxima solicitação encontre os dados em cache.

Arquivos .build.lock de chave específica, ociosos e deixados por versões anteriores, são coletados em todos os namespaces de cache deste site por WP-Cron, a partir de cinco minutos após a atualização e removendo até 10,000 bloqueios por minuto dentro de um limite de dez segundos. wp bs cache status informa a quantidade restante e wp bs cache cleanup esvazia imediatamente a fila; wp bs cache clear limpa o cache de tempo de execução. Se uma execução agendada estiver mais de dez minutos atrasada porque cron não está sendo acionado, as solicitações examinam um número limitado de bloqueios uma vez por hora para que a limpeza não pare. Bloqueios recentes ou em uso são mantidos, e os novos bloqueios de caminho fixo nunca são coletados. Depois que a fila é esvaziada, a mesma tarefa coleta namespaces de cache abandonados quando namespaceGrace tiver expirado, no máximo uma vez por hora em cada site, mantendo uma execução diária. O período de carência começa na primeira varredura que encontra um namespace aposentado, não na data do arquivo mais recente; um namespace ainda atual em qualquer um dos seus escopos nunca é coletado. A limpeza interna do cache não aciona filtros de exclusão de anexos WordPress. Hosts com WP-Cron desativado devem continuar executando o processo agendado habitual de cron; não exclua indiscriminadamente arquivos de bloqueio ativos para esvaziar uma fila.

O filtro de configuração blockstudio/settings/cache/path altera o valor configurado. Para resolver caminhos específicos da implantação, blockstudio/cache/dir filtra o diretório base resolvido:

PHP
add_filter('blockstudio/cache/dir', function (string $directory): string {
    return WP_CONTENT_DIR . '/cache/blockstudio';
});

Hosts cuja identidade de locatário difere dos IDs de rede/blog WordPress podem filtrar blockstudio/cache/site_key. O resultado é sanitizado e usado somente como segmento de diretório. blockstudio/cache/context continua sendo o local correto para uma variante serializável de tempo de execução que precise alterar identidades de objetos.

themeDefaults

Opção Tipo Padrão Descrição
titleTag boolean false Ativar o suporte a etiquetas de título do tema WordPress
suppressDirectoryUpdates boolean false Remover os temas filho e pai ativos dos resultados de atualização do diretório

Os padrões continuam usando a API existente Blockstudio\Patterns API; esses valores padrão não introduzem fachadas alternativas para páginas ou padrões.

performance

O perfil compat mantém inalterado o comportamento genérico de WordPress. speed e strict ativam os mesmos padrões opcionais do frontend; cada configuração filha pode substituir o valor do perfil.

As configurações opcionais são controles de registro. Quando um recurso opcional está false, Blockstudio não conecta os callbacks de frontend, administração, editor, REST ou agendados desse recurso. Desativar o Early Serve ou o aquecimento agendado depois de usá-lo executa uma vez a limpeza que lhe corresponde; as solicitações seguintes permanecem inativas.

Opção Tipo Padrão de compatibilidade Padrão de velocidade/rigor Descrição
profile string "compat" Não aplicável compat, speed ou strict
wordpress.headNoise boolean false true Remove a descoberta genérica do cabeçalho e a saída de emojis
wordpress.embeds boolean false true Remove a descoberta do oEmbed e os scripts de host
wordpress.xmlrpc boolean false true Desativa XML-RPC e os pingbacks
wordpress.editor boolean false true Desativa as superfícies de descoberta remota do editor
wordpress.frontendAssets boolean false true Remove os recursos genéricos do frontend do núcleo
wordpress.media boolean false true Aplica os padrões de saída de imagem
wordpress.heartbeat boolean false true Limita o Heartbeat fora dos editores
preload.links string "off" "intent" Pré-carrega documentos da mesma origem após a intenção do usuário
media.lazy boolean false true Usa o carregador de imagens de Blockstudio
media.skeleton boolean false true Exibe o esqueleto de carregamento integrado
media.metadata boolean false true Declara o uso de assets/media.json
media.rootMargin string "300px" "300px" Margem de interseção do carregador lento
measurement.enabled boolean false false Ativa as APIs de medição em tempo de execução
measurement.queryMonitor boolean false false Inclui consultas que levam pelo menos 50ms
measurement.headers boolean false false Envia cabeçalhos com hash do perfil e da configuração
measurement.timings boolean false false Envia o cabeçalho do tempo decorrido em execução
staticPrerender.enabled boolean false false Ativa o armazenamento em cache HTML seguro para dados anônimos
staticPrerender.ttl integer 86400 86400 Idade máxima do documento em cache, em segundos
staticPrerender.invalidate string "signature" "signature" Usa a identidade signature ou incremental graph
staticPrerender.earlyServe boolean false false Exibe resultados seguros antes de WordPress iniciar
staticPrerender.serveLoggedIn boolean false false Permite que usuários consumam resultados em cache, mas nunca os criem
staticPrerender.dynamicPaths array [] [] Prefixos de caminho que devem permanecer dinâmicos
staticPrerender.replayHeaders array ["Link"] ["Link"] Cabeçalhos de resposta armazenados e enviados nos resultados em cache
staticPrerender.warm.enabled boolean false false Ativa a fila persistente de aquecimento agendado
staticPrerender.warm.interval integer 3600 3600 Intervalo de aquecimento em segundos
staticPrerender.warm.concurrency integer 2 2 Número máximo de tarefas processadas por ciclo de aquecimento
staticPrerender.warm.transport string "http" "http" Usa http ou um renderizador fornecido pelo host internal

A pré-renderização estática permanece desativada, a menos que seja ativada explicitamente. Uma chave mestra desativada não registra hooks de solicitação de pré-renderização, e as chaves desativadas earlyServe e warm.enabled não registram hooks de administração nem de cron. O modo de assinatura usa uma identidade ativada de baixo custo em solicitações comuns. O modo de grafo destina-se a compilações explícitas: ele registra dependências de origem por página para que a alteração de uma página não invalide documentos não relacionados. Consulte Pré-renderização estática para obter detalhes sobre aquecimento, implantação, fornecimento antecipado e segurança.

As medições estão disponíveis programaticamente:

PHP
use Blockstudio\Performance_Measurement;

$snapshot = Performance_Measurement::snapshot();

Quando os cabeçalhos estão ativados, Blockstudio envia X-Blockstudio-Performance-Profile, X-Blockstudio-Performance-Config e, opcionalmente, X-Blockstudio-Performance-Time. A ação blockstudio/performance/measurement_enabled recebe as configurações resolvidas em tempo de execução.

As opções media determinam bs_media_image(), o manifesto assets/media.json e o carregador sob demanda do frontend. Consulte Mídia para saber mais sobre o auxiliar, o criador do manifesto e o comportamento do carregador.

content

Opção Tipo Padrão Descrição
enabled boolean false Ativa a configuração do Content Sync
id string "default" Namespace do conjunto de conteúdo armazenado nas entidades sincronizadas
path string "content" Diretório de arquivos de conteúdo relativo ao tema
includePageSyncManaged boolean false Inclui publicações gerenciadas pelo Page Sync sem assumir o controle do conteúdo
authors string "ignore" Tratamento do autor (ignore ou login de usuário existente)
postTypes array [] Tipos de publicação permitidos
meta.include array [] Padrões glob para chaves meta a sincronizar
meta.exclude array ["_edit_lock", "_edit_last", "_wp_old_slug"] Padrões glob para chaves meta a excluir
meta.references object {} Referências meta declaradas, reescritas entre IDs e UIDs
taxonomies array [] Taxonomias registradas permitidas para termos e relacionamentos
media string "manifest" Comportamento das referências a anexos (manifest ou none)

O Content Sync é gerenciado por meio de wp bs content e projeta publicações permitidas, postmeta e referências declaradas em arquivos portáteis. Consulte Sincronização de conteúdo para conhecer o fluxo de trabalho e o formato dos arquivos.

editor

Opção Tipo Padrão Descrição
formatOnSave boolean false Formata block.json ao salvar
assets array [] Recursos adicionais a carregar no editor
markup boolean false Ativa a edição de marcação

tailwind

Opção Tipo Padrão Descrição
enabled boolean false Ativa a compilação de Tailwind CSS
config string "" Configuração Tailwind v4 baseada primeiro em CSS

Consulte Tailwind CSS para saber sobre o comportamento da compilação e o formato de configuração baseado primeiro em CSS.

blockTags

Opção Tipo Padrão Descrição
enabled boolean false Ativa a renderização de tags bs: em nível de página no conteúdo de publicações e nas áreas de widgets
allow array [] Lista de permissões de padrões de nomes de blocos; aceita curingas fnmatch()
deny array [] Lista de bloqueio de padrões de nomes de blocos; tem precedência sobre allow
prefixes object {} Prefixo para abreviações de namespace; cada valor é um namespace ou uma matriz ordenada

A renderização de tags no nível de modelos está sempre ativa; estas opções controlam a substituição no nível de página. Consulte Renderização para ver a sintaxe das tags e as regras de resolução.

ui

Opção Tipo Padrão Descrição
enabled boolean false Registra os componentes bsui/* UI incluídos e os aplicativos de demonstração app/*

blockEditor

Opção Tipo Padrão Descrição
disableLoading boolean false Desativa o carregamento de blocos no editor
enhance boolean false Ativa os recursos de foco e seleção do editor Blockstudio
cssClasses array [] URLs de folhas de estilo das quais extrair classes CSS para o preenchimento automático do campo de classes
cssVariables array [] URLs de folhas de estilo das quais extrair variáveis CSS para o preenchimento automático do campo de código

blockEditor.blocks

Use blockEditor.blocks para definir a política geral do projeto para o inseridor de blocos. allow e deny aceitam nomes de blocos e padrões curinga, como core/*.

JSON
{
  "blockEditor": {
    "blocks": {
      "allow": ["core/*", "my-theme/*"],
      "deny": ["core/embed", "core/freeform"],
      "directory": false,
      "categories": {
        "rename": {
          "text": "Writing",
          "design": "Layout"
        },
        "order": ["my-theme", "text", "media"]
      },
      "legacyWidgets": {
        "hide": ["archives", "calendar"]
      }
    }
  }
}

blocks.styles.deny cancela o registro de estilos que foram registrados pelo registro de estilos de blocos WordPress’PHP:

JSON
{
  "blockEditor": {
    "blocks": {
      "styles": {
        "deny": {
          "my-theme/card": ["outline"],
          "my-theme/media": ["framed"]
        }
      }
    }
  }
}

blockEditor.patterns

Use blockEditor.patterns para desativar as fontes de padrões globais e filtrar as categorias de padrões.

JSON
{
  "blockEditor": {
    "patterns": {
      "core": false,
      "remote": false,
      "theme": true,
      "blockstudio": true,
      "categories": {
        "deny": ["gallery"],
        "rename": {
          "featured": "Featured Layouts"
        },
        "order": ["featured", "buttons"]
      }
    }
  }
}

blockEditor.media

Use blockEditor.media para definir a política geral do inseridor de mídia.

JSON
{
  "blockEditor": {
    "media": {
      "openverse": false,
      "imageSizes": {
        "allow": ["thumbnail", "large"],
        "deny": ["medium_large"]
      }
    }
  }
}

dev

Opção Tipo Padrão Descrição
grab.enabled boolean false Ativa o capturador de elementos do frontend
perf boolean false Ativa o perfilador de desempenho em cada carregamento de página
canvas.enabled boolean false Ativa a tela
canvas.adminBar boolean true Exibe a barra de administração do WordPress ao visualizar a tela

githooks

Opção Tipo Padrão Descrição
commit boolean false Gera um hook de pré-commit apenas para análise quando blockstudio-githooks sync é executado

Consulte o hook de commit gerenciado para saber o que o hook gerado executa e como ele permanece sincronizado.

phpstan

Opção Tipo Padrão Descrição
preset string "base" Predefinição de análise quando a linha de comando não seleciona uma: base, theme, extreme-theme ou wordpress-render
configuration string "" Configuração de PHPStan do projeto incluída junto à predefinição, resolvida a partir de blockstudio.json
roots array ["."] Raízes de temas analisadas pelo comando canônico
excludePaths array [] Exclusões adicionais do scanner relativas a cada raiz configurada
maxFiles integer 10000 Número máximo de arquivos inspecionados pelo scanner de temas
blockTags object {} Mapeamentos de elementos, aliases de tags e scanPhp para a regra da tag de bloco

Essas configurações determinam o comando canônico blockstudio-phpstan. Consulte PHPStan para ver predefinições, camadas e adoção.

ai

Opção Tipo Padrão Descrição
enableContextGeneration boolean false Gera um arquivo de contexto combinado com blocos, configurações, esquemas e documentação para ferramentas de LLM

Consulte Integração com IA para ver o índice da documentação e o texto gerado completo.

Componentes de UI

Ative e combine os componentes de UI headless incluídos, introduzidos no Blockstudio 7.3.