
# Renderização programática

Com Gutenberg se tornando a principal ferramenta para criar sites facilmente editáveis para clientes, faz sentido criar todas as áreas necessárias do site como blocos. Embora essa abordagem atenda à maioria dos casos, usuários avançados e casos de uso específicos talvez precisem usar esses blocos existentes fora do editor.

Blockstudio oferece duas abordagens para renderizar blocos programaticamente:

- **Funções PHP**: `bs_render_block` e `bs_block` para renderizar a partir de código PHP
- **Tags HTML**: tags `<bs:block-name>` que são substituídas pela saída do bloco em qualquer lugar da página

Todos os recursos específicos de Blockstudio, como estilos em linha, scripts e estilos com escopo, são compatíveis.

[Ilhas](https://blockstudio.dev/pt/docs/blocks/islands/) também funcionam nesses caminhos de renderização. Uma ilha dinâmica renderizada com `bs_render_block()`, `bs_block()` ou uma tag de bloco retorna o mesmo marcador de placeholder que um bloco renderizado a partir do conteúdo do post, e o runtime do frontend é injetado quando esse marcador está presente na resposta.

## Composições estruturadas e documentos completos

Para ferramentas, pré-visualizações, exportações e galerias de componentes duradouras, use a `Blockstudio\Render` API versionada. Ela aceita uma declaração ou uma lista ordenada e renderiza sem imprimir:

```php
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);
```

A declaração normalizada canônica tem quatro chaves:

```php
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]
```

`data`, `inner`, `innerBlocks`, `root`, `layers` e `example` são conveniências de entrada e são removidas durante a normalização. Declarações aninhadas são renderizadas recursivamente pelo mesmo pipeline Blockstudio.

`Render::document()` retorna `schemaVersion`, `html`, `body`, `blocks`,
`assets`, `warnings` e `errors`. O valor `assets` separa `head`,
`footer`, `styles`, `scripts`, `modules`, `interactivity`, `ui` e `tailwind`.
A lista de blocos e os recursos incluem dependências referenciadas pelos modelos selecionados,
mas excluem recursos não relacionados e exclusivos do editor.

Documentos completos podem definir `bodyClasses`/`bodyAttributes` e, opcionalmente, envolver
 o corpo renderizado com `contentElement`, `contentClasses` e
`contentAttributes`. O wrapper é restrito a um nome de elemento seguro; o valor `body` retornado continua sendo o conteúdo renderizado sem wrapper.
As opções `head` e `footer` acrescentam marcação confiável do documento nas respectivas posições e são incluídas no conjunto de recursos retornado.

Para montar um documento em torno de HTML que já foi renderizado, forneça os nomes conhecidos
 dos blocos raiz:

```php
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);
```

Use `Render::content()` para conteúdo de bloco serializado de WordPress. Consumidores que renderizam vários documentos independentes em uma única solicitação devem chamar `Blockstudio\Batch_Render::reset()` entre eles; `Canvas::documents()` faz isso automaticamente.

## Renderização fora da página

Blockstudio insere um comentário `<!--blockstudio/namespace/slug-->` antes de cada bloco que renderiza. Em uma página do frontend, o buffer lê esses comentários para identificar os blocos presentes, carregar os recursos deles e remover os comentários antes de enviar a resposta.

A saída que não passa por esse buffer mantém os comentários. Isso se aplica a respostas REST, feeds, manipuladores AJAX e HTML que você armazena ou envia para outro lugar após `do_blocks()`, `Render::content()` ou `bs_render_block()`. Use
`bs_strip_render_markers()` para removê-los:

```php
$html = bs_strip_render_markers(do_blocks($post->post_content));
```

A função remove os comentários dos blocos Blockstudio registrados e deixa todo o restante intacto, inclusive outros comentários HTML. Ela corresponde aos mesmos marcadores removidos pelo buffer da página. Chame-a após o registro dos blocos (`init` ou depois).

Não remova a marcação que ainda será impressa em uma página do frontend processada pelo buffer. A página precisa dos comentários para saber quais recursos dos blocos carregar, e Blockstudio os remove no final.

Remover os comentários não adiciona recursos. Os arquivos de CSS bloco e JavaScript só são inseridos pelo buffer da página. Use
[`bs_block_assets()`](https://blockstudio.dev/pt/docs/blocks/assets/#inspecting-a-blocks-assets) ou
`Render::document()` quando o consumidor também precisar deles.

## Inspeção de blocos

Use `bs_block_fields()` após o registro dos blocos (em `init` ou depois) para obter as definições resolvidas dos campos sem ler registros internos:

```php
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}
```

O valor de retorno é o array registrado de definições de campos, incluindo filtros de atributos, campos personalizados expandidos, substituições e grupos, abas e repetidores aninhados. Um bloco Blockstudio sem campos retorna `[]`. O resultado é uma cópia: alterá-la não modifica o bloco registrado.

Estas são definições, não valores salvos. Para validar a marcação salva, use [`bs_validate_block()`](#validating-stored-values) em vez de manter um percorrimento separado dos campos. Para descrever os valores que um bloco aceita, use [`bs_block_schema()`](#describing-stored-values). Os atributos pertencentes a WordPress permanecem separados.

Os campos adicionados por [extensões](https://blockstudio.dev/pt/docs/extensions/) não fazem parte de
`bs_block_fields()`. Use `bs_block_extension_fields()` para obtê-los. A função identifica extensões pelo nome do bloco, portanto também funciona com blocos do núcleo e de terceiros:

```php
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);
```

O valor de retorno lista as definições de campos de cada extensão correspondente, na ordem em que foram registradas, com a mesma estrutura de `bs_block_fields()`. Para um bloco sem extensões correspondentes, o retorno é `[]`. Os valores das extensões são salvos no mesmo objeto `attrs.blockstudio.attributes` que os valores dos campos do próprio bloco, portanto todos os IDs compartilham um único espaço de nomes. Se duas extensões definirem o mesmo ID, ambas as definições serão retornadas e editarão o mesmo valor; na renderização, aplica-se a definição da extensão registrada por último.

Para ler os valores de um bloco salvo tal como são recebidos pelo modelo, use
[`bs_block_values()`](https://blockstudio.dev/pt/docs/blocks/attributes/rendering/#reading-attributes-programmatically).

Use [`bs_block_assets()`](https://blockstudio.dev/pt/docs/blocks/assets/#inspecting-a-blocks-assets) para
inspecionar o CSS e o JavaScript descobertos do bloco. Para obter um documento completo de prévia, incluindo blocos aninhados e dependências compartilhadas do ambiente de execução, use
`Render::document()`, conforme descrito acima.

### Validando valores armazenados

Use `bs_validate_block()` após o registro dos blocos (`init` ou depois) para verificar atributos de blocos gerados programaticamente ou importados antes de salvá-los:

```php
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}
```

Passe o array `attrs` completo, não apenas `blockstudio.attributes`. Uma renderização Blockstudio também aceita campos declarados no nível superior, e os valores aninhados prevalecem quando ambos são fornecidos. Extensões de blocos do núcleo e de terceiros leem apenas `blockstudio.attributes`. Um bloco Blockstudio vazio é gerenciado e retorna `[]`, não `null`.

A validação é explícita e somente para leitura. Ela não renderiza modelos, altera valores, salva posts, consulta mídia nem executa callbacks de preenchimento. Não é executada automaticamente durante o salvamento, a sincronização de páginas ou a renderização. Não é um sanitizador, uma verificação de autorização nem uma confirmação da existência de um anexo.

Cada resultado contém estas chaves estáveis:

```php
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]
```

Use `code`, não o `message` traduzido, nas ferramentas. `source` é `block` ou
`extension`. Os caminhos usam chaves de armazenamento e índices de linha de repetidor ou de seleção baseados em zero, sem barra inicial. Os caracteres literais `~` e `/` em uma chave são escapados como `~0` e
`~1`. Um grupo de nível superior prefixa seus filhos (`cta_title`); grupos anônimos
e abas não acrescentam níveis. O builder não oferece suporte a grupos com um ID dentro de outro grupo ou de um repetidor, portanto suas chaves não são aceitas. Campos de mensagem não têm valor armazenado. Um campo de arquivos permite seu complemento `<id>__size`.
Na raiz de um bloco Blockstudio, as chaves de controle e os atributos globais de HTML encaminhados ao elemento renderizado não são campos desconhecidos. Isso não permite chaves arbitrárias em linhas de repetidor nem extensões de blocos do núcleo.

| Código | Significado | `expected` |
| --- | --- | --- |
| `unknown_field` | Nenhum campo mantido declara esta chave de armazenamento. | Chaves de armazenamento conhecidas. |
| `unknown_option` | Uma seleção não está entre as opções conhecidas. | Valores de opção permitidos. |
| `wrong_type` | A estrutura armazenada não é compatível com o campo. | Família ou tipo de armazenamento esperado. |
| `too_few_rows`, `too_many_rows` | Um repetidor presente está fora do limite de `min` ou `max`. | O limite de linhas. |
| `definition_conflict` | As definições aplicáveis a uma chave exigem estruturas de armazenamento diferentes. | Origem e tipo de campo de cada definição. |
| `shadowed_value` | Um valor aninhado substitui um valor diferente de campo de nível superior. | O valor aninhado que prevalece. |
| `extension_top_level` | O modelo pode ler um valor de nível superior, mas as vinculações de extensão não. | O caminho necessário em `blockstudio/attributes`. |
| `unknown_attribute` | Uma chave de nível superior de um bloco Blockstudio não é lida pelo caminho de renderização e é descartada. | Nomes de atributos registrados, campos de extensão e `blockstudio`. |
| `missing_container` | `attributes`, `disabled`, `name` ou `editor` está armazenado no nível superior, e falta `blockstudio`. | O caminho necessário em `blockstudio`. |
| `invalid_container` | `blockstudio` ou `blockstudio.attributes` não é um objeto. | `object`. |

A mensagem de uma ocorrência de `unknown_field` indica a chave de armazenamento mais próxima no mesmo nível quando ela está a até três edições de distância, conforme a regra para configurações desconhecidas: `This storage key is not declared by the block or its extensions. Did you mean "title"?`. `expected` ainda lista todas as chaves conhecidas. A correspondência ignora maiúsculas e minúsculas e considera apenas as chaves de armazenamento desse contêiner. As mensagens são traduzidas; as integrações devem usar `code`, `path` e `expected` em vez de analisar o texto da mensagem.

Uma chave de nível superior de um bloco Blockstudio que não seja um atributo registrado
(seus campos, os atributos que WordPress adiciona para `supports`, `lock` e
`metadata`), um campo de uma extensão correspondente, `blockstudio`, uma
chave de controle ou um atributo global de HTML encaminhado é descartada antes da execução do modelo. Uma chave desse tipo, como um ID de campo digitado incorretamente ou um objeto de valores armazenado sem seu invólucro `blockstudio`, gera um apontamento porque o bloco é renderizado sem esse valor. Blocos que contêm apenas campos de extensão não são verificados quanto a chaves de nível superior.

As estruturas aceitas correspondem à renderização: seleções múltiplas e caixas de seleção podem conter uma lista, um objeto de opção ou um escalar importado, inclusive zero numérico. Strings numéricas são aceitas para números. Arquivos podem conter IDs de anexos, objetos de ID, listas ou referências de string. Valores de link e ícone precisam ser objetos; tipos de campo personalizados usam o tipo de atributo registrado.
Um campo `attributes` contém uma lista de pares com um nome `attribute` não vazio
e um escalar `value`; metadados opcionais, como `data.media`, são preservados.

WordPress valida atributos registrados de nível superior antes da renderização, o que
pode rejeitar uma estrutura aceita dentro de `blockstudio.attributes`. Por exemplo, um
valor de radio `"a"` funciona no objeto aninhado, mas é descartado no nível superior,
onde seu tipo registrado é `object`. Esse valor gera `wrong_type`.
Use o objeto aninhado para manter a mesma estrutura de armazenamento gravada pelo editor.

Campos ausentes não são obrigatórios. Valores aninhados vazios (`null`, `false`, `''`,
`[]`) e campos desativados não geram erros de valor. Um repetidor explicitamente vazio ainda é verificado em relação a `min`; um repetidor ausente ou desativado não é. Um valor vazio de nível superior é reportado se WordPress o descartar e restaurar um valor padrão não vazio. O mesmo valor no objeto aninhado pode limpá-lo. Conflitos entre definições são reportados mesmo quando a chave não tem valor salvo.

Opções estáticas e opções de preenchimento resolvidas no registro são verificadas sem chamar o preenchimento novamente. Opções remotas de `fetch` e argumentos de preenchimento que contêm `{attributes.*}` são ignorados. Valores de cor e gradiente podem ser personalizados, a menos que `disableCustomColors` ou `disableCustomGradients` esteja definido.
Isso verifica valores armazenados, não `default`, `fallback` nem regras de validação do editor.

Os campos de extensão correspondentes são incluídos em cada bloco ao qual se aplicam. No nível raiz, as definições posteriores prevalecem no bloco ou em suas extensões, como na renderização. Um campo do próprio bloco e um campo de extensão continuam sendo definições separadas da mesma chave, e ambas se aplicam. Nas linhas do repetidor, o renderizador lê o primeiro campo com um ID correspondente em cada origem, portanto suas opções e limites se aplicam. Definições duplicadas são mantidas para diagnósticos de conflito: estruturas de armazenamento incompatíveis geram `definition_conflict`, mesmo quando uma duplicata posterior não é lida na renderização.

A função verifica um bloco. Percorra `innerBlocks` ao validar um documento;
partes sincronizadas e outras referências não são expandidas automaticamente. O comando [`wp bs blocks validate`](https://blockstudio.dev/pt/docs/dev/cli/#validate-stored-fields) percorre os blocos de uma ou mais publicações e informa seus caminhos de bloco.

Sites com um resolvedor personalizado em tempo de renderização podem adaptar os apontamentos sem alterar os dados armazenados:

```php
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);
```

Sempre retorne uma lista de apontamentos; retornar `[]` aceita o bloco. Esse filtro é executado apenas para blocos gerenciados, nunca para o resultado de `null`.

### Descrição dos valores armazenados

Use `bs_block_schema()` após o registro do bloco (`init` ou posterior) para descrever os valores que um bloco armazena, por exemplo, para gerar marcação de bloco em uma ferramenta ou integração de IA, ou para verificar a entrada em uma rota REST:

```php
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}
```

O resultado é um Schema JSON do objeto salvo em `attrs.blockstudio.attributes`. Ele abrange os campos do bloco e os campos das extensões correspondentes, com as chaves de armazenamento usadas pela validação: um grupo de nível superior acrescenta um prefixo aos filhos; grupos anônimos e abas não adicionam níveis; e um campo de arquivos adiciona seu complemento `<id>__size`. Repetidores são listas de objetos de linha com `minItems` e `maxItems` provenientes de `min` e `max`. `additionalProperties` é `false` na raiz do armazenamento dos campos e nas linhas dos repetidores. Campos com valores de objeto, como links e objetos personalizados, podem ter seus próprios metadados. Um bloco sem campos não tem `properties`, portanto apenas um objeto vazio corresponde.

Cada campo é descrito em um formato canônico aceito por `bs_validate_block()`:

| Campo | Schema |
| --- | --- |
| `text`, `textarea`, `richtext`, `wysiwyg`, `code`, `date`, `datetime`, `unit`, `classes`, `html-tag`, `block` | Uma string. |
| `number`, `range` | Um número, com `minimum` e `maximum` provenientes de `min` e `max`. |
| `toggle` | Um booleano. |
| `select`, `radio`, `checkbox` | Um valor de opção ou uma lista de valores de opção para `checkbox` e `multiple`, com `enum`. |
| `color`, `gradient` | Uma string, com `enum` quando `disableCustomColors` ou `disableCustomGradients` está definido. |
| `token` | Uma lista de strings. |
| `files` | Um ID de anexo inteiro não negativo ou uma lista de IDs com `multiple`. |
| `link` | Um objeto com `url`, `title` e `opensInNewTab`; `url` é obrigatório. |
| `icon` | Um objeto com `set`, `subSet` e `icon`; `set` e `icon` são obrigatórios. |
| `attributes` | Uma lista de objetos com `attribute` não vazio e um `value` escalar. |
| `repeater` | Uma lista de objetos de linha. |
| Tipos de campo personalizados | O tipo de atributo registrado. |

`enum` lista as opções verificadas pela validação: opções estáticas e opções de preenchimento já resolvidas no registro. Opções `fetch` remotas e argumentos de preenchimento que contêm `{attributes.*}` não têm `enum`. Uma chave com definições de formatos de armazenamento diferentes é omitida, pois a validação informa todos os valores armazenados nela. Quando um campo de bloco e um campo de extensão compartilham uma chave, `enum` lista os valores aceitos por ambos. Repetidores compartilhados combinam seus campos filhos e aplicam os limites de linha mais restritos das duas definições. Nas linhas dos repetidores, aplica-se o primeiro campo com um ID correspondente em cada origem, como na renderização. Um campo explícito chamado `<id>__size` tem precedência sobre um complemento de tamanho de arquivo adicionado automaticamente.

Quando um campo fechado não tem opções disponíveis, ou dois conjuntos de opções aplicáveis não têm nenhuma opção em comum, seu valor canônico é `null` para uma seleção única ou uma lista vazia para seleções múltiplas. Uma lista de opções vazia não transforma o campo em irrestrito. As opções remotas e dependentes de atributos permanecem abertas.

O `label` de um campo se torna `title`, seu `help` se torna `description`, e seu `default` é mantido como anotação. O `title` próprio do schema é o título do bloco. Campos nunca são obrigatórios, e a lógica condicional não faz parte do schema.

As restrições usam apenas palavras-chave verificadas por `rest_validate_value_from_schema()`, então o schema funciona diretamente como schema de entrada de uma rota REST ou de uma habilidade:

```php
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}
```

O esquema descreve um formulário por campo; a validação também aceita formatos importados, como objetos de opções, strings numéricas e objetos de ID. Ele não substitui `bs_validate_block()`: conflitos de definição são problemas de configuração e ainda podem gerar ocorrências, mesmo quando a chave conflitante é omitida. Os filtros de validação também podem impor regras específicas do site. Use `bs_validate_block()` para verificar o conteúdo armazenado. Sites com um resolvedor personalizado no momento da renderização podem adaptar o esquema com o filtro [`blockstudio/blocks/attributes/schema`](https://blockstudio.dev/pt/docs/blocks/hooks/php/#attributesschema).

## Funções de PHP

### Sem dados

Na forma mais simples, a função aceita um único valor, que é o ID do bloco que deve ser renderizado na página.

```php
bs_render_block('blockstudio/cta');
```

### Com dados

Para renderizar o bloco com dados personalizados, é necessário usar um array no lugar de um único valor no primeiro parâmetro. O valor na chave data será passado para a variável `$attributes` e `$a` dentro do modelo do bloco.

```php
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);
```

### Aninhamento

É possível aninhar blocos usando a função `bs_block` em conjunto com a poderosa variável `$content` dentro dos modelos dos blocos.

```php title="index.php"
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
```

```php
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);
```

O bloco de botão será renderizado no lugar da variável `$content` dentro do modelo do bloco.

Blocos incorporados renderizados com `bs_render_block()` ou `bs_block()` sempre geram HTML resolvido no frontend, mesmo quando o bloco pai está renderizando uma prévia no editor. Pseudocomponentes de modelo, como `<RichText />` e `<InnerBlocks />`, são resolvidos antes que o bloco incorporado seja retornado.

### Vários espaços reservados

Também é possível criar vários espaços reservados de conteúdo simplesmente transformando a variável `$content` em um array associativo e chamando as chaves correspondentes na função `bs_block`.

```php title="index.php"
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
```

```php
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);
```

## Tags de bloco

Incorpore qualquer bloco usando a sintaxe de tag HTML. Há suporte para dois formatos:

```html
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
```

Ambos renderizam o mesmo bloco. A sintaxe `<bs:>` transforma um hífen no separador de namespace (`acme-hero` se torna `acme/hero`). Os hífens são testados da esquerda para a direita, e o primeiro candidato registrado é usado; assim, namespaces que contêm hífens também são resolvidos: `<bs:acme-ui-button>` testa `acme/ui-button` e depois `acme-ui/button`. A sintaxe `<block>` usa o nome completo do bloco como atributo `name`.

Tanto os blocos Blockstudio quanto os blocos principais do WordPress funcionam. Os blocos Blockstudio são renderizados pelo fluxo completo (modelos, Tailwind, recursos). Os blocos principais são renderizados pelo sistema de renderização de blocos do WordPress, usando os [renderizadores de blocos](https://blockstudio.dev/pt/docs/pages-and-patterns/) integrados.

### Como funciona

As tags de bloco se comportam de maneira diferente dependendo de onde aparecem:

**Em modelos de bloco e conteúdo de posts**, as tags são substituídas por HTML renderizado durante a execução. A saída é a marcação final do bloco referenciado, incorporada diretamente à página. Não há nenhum bloco WordPress no editor para essas tags. Elas são apenas um mecanismo de renderização.

**Em [Páginas, padrões e modelos do site](https://blockstudio.dev/pt/docs/pages-and-patterns/)**, as tags são convertidas em blocos nativos do WordPress antes de o arquivo de origem ser sincronizado ou registrado no WordPress. Isso significa que os blocos aparecem no editor, podem ser editados quando o destino oferece suporte à edição e passam por todo o ciclo de vida de blocos do WordPress. A sintaxe de tag é uma forma abreviada de definir conteúdo de bloco em arquivos de modelo.

Essa distinção é importante: tags de bloco em modelos geram saída; tags de bloco em páginas, padrões e modelos do site geram blocos nativos.

### Em modelos de bloco

As tags de bloco são renderizadas automaticamente dentro dos modelos Twig e PHP. Não é necessário configurar nada. Isso inclui as sintaxes `<bs:>` e `<block>`, além de qualquer [prefixo](#prefix-shorthands) e tags de alias registrados, para que um modelo possa emiti-los diretamente, sem chamar `bs_render_block()`. A saída é renderizada HTML e incorporada diretamente à saída do modelo do bloco:

```twig title="index.twig"
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>
```

### No conteúdo de posts

A renderização no nível da página (conteúdo de posts, áreas de widgets) é opcional:

```json title="blockstudio.json"
{
  "blockTags": {
    "enabled": true
  }
}
```

Ou por meio de um filtro:

```php
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
```

### Sintaxe

Tags sem fechamento:

```html
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
```

Tags pareadas com conteúdo interno:

```html
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>
```

Combine à vontade. As duas sintaxes podem ser aninhadas uma dentro da outra:

```html
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>
```

### Abreviações de prefixo

As tags de bloco também podem usar abreviações de prefixo específicas do projeto. Registre um prefixo com um ou mais namespaces e Blockstudio resolve `<prefix-slug>` para o primeiro bloco registrado nessa ordem de namespaces:

```php title="functions.php"
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
```

```html
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
```

Com o exemplo acima, `<theme-card>` é resolvido para `theme-components/card`, `<theme-button>` recorre a `bsui/button` quando `theme-components/button` não está registrado, e `<theme-ui-feature-matrix>` é resolvido para `theme-components/ui-feature-matrix`.

Os prefixos também podem ser compostos. Quando uma tag com prefixo não é resolvida diretamente e o slug restante é, por si só, uma tag de prefixo registrada, a resolução é recursiva; assim, um prefixo de marca pode se sobrepor a um prefixo de namespace:

```php title="functions.php"
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
```

```html
<theme-ui-input />
```

`<theme-ui-input>` não tem um bloco `theme-components/ui-input`, então recorre ao prefixo `ui` e resolve `bsui/input`. Correspondências diretas sempre prevalecem sobre a resolução aninhada, e as regras de permissão e bloqueio se aplicam ao bloco resolvido final.

Você também pode configurar prefixos em `blockstudio.json`:

```json title="blockstudio.json"
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}
```

Os prefixos devem conter letras minúsculas ou números, começar com uma letra e não podem conter hífens. Os aliases explícitos de `blockstudio/block_tags/tag_aliases` têm prioridade sobre a resolução de prefixos. Tags com prefixos desconhecidos permanecem inalteradas.

As tags de prefixo e alias continuam sendo conveniências de autoria. A forma canônica e portátil é sempre `<bs:namespace-slug>`, pois registra o nome real do bloco sem depender de filtros do projeto:

```html
<bs:theme-components-card />
<bs:bsui-input />
```

Os exemplos de Blockstudio, os diagnósticos gerados e a saída programática usam essa forma canônica. Projetos que queiram remover uma sintaxe abreviada antiga podem usar a [migração de tags canônicas](https://blockstudio.dev/pt/docs/dev/migration/v7/#canonical-block-tags) autônoma, com simulação antes da execução, sem iniciar o WordPress.

### Blocos principais

Qualquer bloco com um [renderizador](https://blockstudio.dev/pt/docs/pages-and-patterns/) registrado pode ser usado:

```html
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>
```

Ou com a sintaxe `<block>`:

```html
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>
```

### Listas de permissão e bloqueio

Controle quais blocos podem ser renderizados por meio de tags:

```json title="blockstudio.json"
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}
```

`allow` restringe a correspondência apenas aos padrões correspondentes. `deny` exclui os padrões correspondentes e tem prioridade. Ambos oferecem suporte a curingas `*` por meio de `fnmatch()`. Essas regras se aplicam às duas sintaxes e à renderização no nível do modelo e da página.

Filtros: `blockstudio/block_tags/allow` e `blockstudio/block_tags/deny`.

### Repasse de HTML

Atributos prefixados com `data-` são repassados ao elemento raiz do bloco renderizado. Atributos prefixados com `html-` também são repassados, com o prefixo removido. Funciona com as duas sintaxes. Um atributo repassado substitui o valor existente do elemento raiz em vez de combiná-lo; assim, `html-class` substitui as classes do próprio bloco.

Um bloco Blockstudio também insere no elemento raiz os atributos globais que não declara como campos: `id`, `style`, `role`, `title`, `lang`, `dir`, `hidden`, `tabindex` e todo atributo `aria-*`. Um campo declarado sempre prevalece; portanto, um bloco com um campo `title` recebe o valor em `$a['title']`. Os estilos encaminhados passam por `safecss_filter_attr()`; o filtro WordPress se aplica aos atributos de estilo no conteúdo de posts, e eles são acrescentados ao estilo já definido pelo modelo.

Os valores dos atributos são HTML; portanto, as entidades são decodificadas uma vez quando uma tag é analisada: `title="Tom &amp; Jerry"` chega ao modelo como `Tom & Jerry` e é escapado novamente na saída. Valores entre aspas podem conter `>`, como nas variantes de Tailwind e nos seletores de animação, tanto em tags sem fechamento quanto em tags pareadas.

Qualquer outro atributo que um bloco não declare, incluindo `class`, nunca chega ao HTML. Com `WP_DEBUG` ativado, Blockstudio relata cada um desses atributos uma vez por solicitação por meio de `_doing_it_wrong()`. Declare um campo para esse atributo ou escreva-o como atributo `data-`, `aria-` ou `html-`.

```html
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>
```

### Renderizadores personalizados

Registre renderizadores de bloco personalizados para tipos de bloco adicionais. Os renderizadores recebem um array de atributos e uma string de conteúdo interno e retornam um array de bloco WordPress:

```php
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);
```

Para blocos contêiner que precisam analisar o conteúdo interno em blocos filhos, adicione uma segunda entrada dentro do mesmo filtro:

```php
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};
```

`blockstudio/block_tags/builders` se aplica tanto às tags de bloco quanto aos blocos personalizados selecionados por meio de `blockstudio/parser/element_mapping`. Este é o gancho apropriado quando um bloco do projeto com mapeamento de elementos precisa mover o texto interno para um campo Blockstudio ou construir um array de bloco personalizado.

`blockstudio/block_tags/renderers` e `blockstudio/parser/renderers` recebem o mesmo registro e formato de callback. Continuam disponíveis por compatibilidade e para substituições finais no nível do analisador. Os filtros são executados nesta ordem:

1. `blockstudio/block_tags/builders`
2. `blockstudio/block_tags/renderers`
3. `blockstudio/parser/renderers`

Um filtro posterior pode substituir um renderizador registrado por um anterior.

### Uso programático

Aplique a renderização de tags a qualquer string de PHP:

```php
$html = apply_filters('blockstudio/block_tags/render', $content);
```

### Componentes

As tags de bloco combinam bem com [Componentes](https://blockstudio.dev/pt/docs/blocks/components/). Componentes são blocos que só são renderizados programaticamente e nunca aparecem no editor.

```html
<bs:mytheme-card title="My Card" description="Card content." />
```

### Analisador

As tags de bloco são processadas por um analisador leve de strings que substitui o DOMDocument. O analisador lida com as sintaxes `<bs:>` e `<block>`, tags aninhadas com o mesmo nome usando controle de profundidade, valores de atributos entre aspas e blocos contêiner recursivos. Foi desenvolvido especificamente para esse caso de uso, tem desempenho superior ao do DOMDocument e ao do WordPress `WP_HTML_Tag_Processor`, e evita problemas conhecidos do DOMDocument com a remoção de prefixos de namespace e a conversão de atributos para minúsculas.

Para [Páginas, padrões e modelos do site](https://blockstudio.dev/pt/docs/pages-and-patterns/), o mesmo analisador também lida com elementos HTML brutos (`<p>`, `<div>`, `<h1>` etc.), mapeando-os para os blocos principais WordPress correspondentes.

Quando um mapeamento de elemento direciona `<p>` para um bloco não principal Blockstudio registrado que declara um atributo richtext `content`, o conteúdo interno HTML é encaminhado automaticamente para esse atributo `content`, inclusive tags em linha como `code` e `img` mapeadas no nível do bloco. Um parágrafo cujo único filho é uma imagem se torna o bloco para o qual `<img>` aponta. Tags de bloco aninhadas ou HTML em nível de bloco continuam usando a análise normal de blocos internos. `<block name="core/shortcode">` mantém o texto do shortcode como conteúdo do bloco.
