Pular para o conteúdo

Contexto e comunicação entre blocos

A maioria dos blocos é independente. Cada um tem seus próprios campos e seu próprio template, sem se preocupar com o que há ao redor. Mas alguns componentes são naturalmente hierárquicos: uma grade de cartões em que o pai controla o número de colunas e o espaçamento, uma tabela de preços em que o pai define a moeda, um contêiner de seção que informa aos filhos se devem usar um tema claro ou escuro.

WordPress oferece um contexto de bloco API para isso. Um bloco pai expõe parte dos seus dados, e os blocos filhos assinam esse contexto. Quando o pai muda, os filhos são atualizados automaticamente. Blockstudio simplifica bastante esse processo: você não precisa configurar providesContext. Todo bloco Blockstudio fornece automaticamente todos os seus atributos como contexto. Os blocos filhos só precisam adicionar uma linha ao block.json para assinar o contexto.

Este guia apresenta quatro padrões de componentes do mundo real que usam contexto, cada um demonstrando uma necessidade de comunicação diferente.

Como funciona o contexto no Blockstudio

No WordPress padrão, você precisa mapear explicitamente cada atributo do pai para uma chave de contexto em providesContext e, em seguida, listar essas chaves no usesContext do filho. Blockstudio elimina totalmente a primeira etapa.

Bloco pai: nenhuma configuração necessária. Todo bloco Blockstudio fornece automaticamente todos os seus atributos usando o nome do bloco.

Bloco filho: adicione usesContext com o nome do bloco pai:

JSON
{
  "usesContext": ["my-theme/parent-block"]
}

Template do filho: acesse os atributos do pai por meio de $context (ou da forma abreviada $c):

PHP
<?php $parent = $context['my-theme/parent-block']; ?>
<p>Parent says: <?php echo esc_html( $parent['message'] ); ?></p>

Essa é toda a configuração. Nenhum providesContext no pai, nenhum mapeamento de atributos e nenhum código de registro. O filho recebe todos os atributos transformados do pai; isso significa que os campos de mídia são resolvidos para dados de anexos, os campos de seleção respeitam returnFormat e os repetidores são expandidos por completo.

Dois tipos de contexto

Blockstudio fornece duas variáveis de contexto nos templates, e elas têm finalidades diferentes:

Variável Contém Caso de uso
$context / $c Atributos do bloco pai (via usesContext) Comunicação entre componentes
$block['context'] / $b['context'] Dados de loop de WordPress (postId, postType) Loops de blocos de consulta

O primeiro serve para os blocos se comunicarem com seus pais. O segundo serve para blocos dentro de um loop de Query que precisam saber qual publicação estão renderizando. Este guia se concentra no primeiro tipo.

Suporte no editor

As atualizações de contexto são reativas no editor. Quando um usuário altera o valor de um campo do bloco pai, todos os blocos filhos que assinam o contexto desse pai são renderizados novamente automaticamente com o novo valor. Não é necessário atualizar manualmente.

Contêiner de seção

O padrão de contexto mais comum: um bloco contêiner que fornece configurações de tema aos filhos. O pai tem campos para cor de fundo, cor do texto e espaçamento interno. Os filhos leem esses valores para manter um estilo consistente.

Pai: seção

JSON
{
  "name": "my-theme/section",
  "title": "Section",
  "category": "design",
  "icon": "align-wide",
  "description": "Section wrapper with theme settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "theme",
        "type": "select",
        "label": "Theme",
        "default": "light",
        "options": [
          { "value": "light", "label": "Light" },
          { "value": "dark", "label": "Dark" },
          { "value": "accent", "label": "Accent" }
        ]
      },
      {
        "id": "spacing",
        "type": "select",
        "label": "Spacing",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$theme_classes = array(
	'light'  => 'bg-white text-gray-900',
	'dark'   => 'bg-gray-900 text-white',
	'accent' => 'bg-indigo-600 text-white',
);
$spacing_classes = array(
	'sm' => 'py-8',
	'md' => 'py-16',
	'lg' => 'py-24',
);
$classes = ( $theme_classes[ $a['theme'] ] ?? '' ) . ' ' . ( $spacing_classes[ $a['spacing'] ] ?? '' );
?>
<div useBlockProps class="<?php echo esc_attr( $classes ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/section-heading', 'my-theme/section-text', 'core/columns', 'core/group' ) ) ); ?>'
  />
</div>

Filho: título da seção

JSON
{
  "name": "my-theme/section-heading",
  "title": "Section Heading",
  "category": "design",
  "icon": "heading",
  "description": "Heading that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "text", "label": "Heading", "default": "Section Title" },
      {
        "id": "size",
        "type": "select",
        "label": "Size",
        "default": "lg",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "lg", "label": "Large" },
          { "value": "xl", "label": "Extra Large" }
        ]
      }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'light'  => 'text-gray-900',
	'dark'   => 'text-white',
	'accent' => 'text-white',
	default  => 'text-gray-900',
};

$size_class = match ( $a['size'] ) {
	'sm' => 'text-2xl',
	'lg' => 'text-4xl',
	'xl' => 'text-6xl',
	default => 'text-4xl',
};
?>
<h2 useBlockProps class="<?php echo esc_attr( "$color_class $size_class font-bold" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</h2>

O que isto demonstra: o título não tem um campo de cor próprio. Ele lê do contexto o valor de theme da seção e se adapta. Quando o usuário muda a seção de “Light” para “Dark” no editor, a cor do texto do título é atualizada imediatamente.

A propriedade parent no block.json do filho restringe os locais onde o bloco pode ser inserido. Ele só aparece no inseridor quando o usuário está dentro de um bloco my-theme/section. Isso é opcional, mas recomendado para blocos que só fazem sentido dentro de um pai específico.

Filho: texto da seção

JSON
{
  "name": "my-theme/section-text",
  "title": "Section Text",
  "category": "design",
  "icon": "text",
  "description": "Body text that adapts to section theme.",
  "usesContext": ["my-theme/section"],
  "parent": ["my-theme/section"],
  "blockstudio": {
    "attributes": [
      { "id": "text", "type": "textarea", "label": "Text", "default": "Section body text." }
    ]
  }
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';

$color_class = match ( $theme ) {
	'dark', 'accent' => 'text-white/80',
	default          => 'text-gray-600',
};
?>
<p useBlockProps class="<?php echo esc_attr( "$color_class text-lg leading-relaxed" ); ?>">
  <?php echo esc_html( $a['text'] ); ?>
</p>

Agora tanto o título quanto o texto respondem ao tema da seção. O usuário escolhe um tema uma única vez no pai, e cada filho se adapta.

Grade de cartões

Um bloco pai de grade controla as configurações de layout dos cartões filhos. O pai define o número de colunas e o espaçamento. Os filhos usam esses valores para entender o contexto de layout e ajustar seu estilo conforme necessário.

Pai: grade de cartões

JSON
{
  "name": "my-theme/card-grid",
  "title": "Card Grid",
  "category": "design",
  "icon": "grid-view",
  "description": "Responsive card grid with configurable columns.",
  "blockstudio": {
    "attributes": [
      {
        "id": "columns",
        "type": "range",
        "label": "Columns",
        "default": 3,
        "min": 1,
        "max": 4,
        "step": 1
      },
      {
        "id": "gap",
        "type": "select",
        "label": "Gap",
        "default": "md",
        "options": [
          { "value": "sm", "label": "Small" },
          { "value": "md", "label": "Medium" },
          { "value": "lg", "label": "Large" }
        ]
      },
      {
        "id": "cardStyle",
        "type": "select",
        "label": "Card Style",
        "default": "elevated",
        "options": [
          { "value": "elevated", "label": "Elevated (shadow)" },
          { "value": "outlined", "label": "Outlined (border)" },
          { "value": "flat", "label": "Flat (no decoration)" }
        ]
      }
    ]
  }
}
PHP
<?php
$gap_class = match ( $a['gap'] ) {
	'sm' => 'gap-4',
	'md' => 'gap-6',
	'lg' => 'gap-8',
	default => 'gap-6',
};
?>
<div useBlockProps class="grid grid-cols-<?php echo esc_attr( $a['columns'] ); ?> <?php echo esc_attr( $gap_class ); ?>">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/card' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
      array( 'my-theme/card', array() ),
    ) ) ); ?>'
  />
</div>

Filho: cartão

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "category": "design",
  "icon": "cover-image",
  "description": "Card that inherits style from its grid parent.",
  "usesContext": ["my-theme/card-grid"],
  "parent": ["my-theme/card-grid"],
  "blockstudio": {
    "attributes": [
      { "id": "image", "type": "files", "label": "Image", "multiple": false },
      { "id": "title", "type": "text", "label": "Title", "default": "Card Title" },
      { "id": "description", "type": "textarea", "label": "Description", "default": "Card description goes here." },
      { "id": "url", "type": "link", "label": "Link" }
    ]
  }
}
PHP
<?php
$grid      = $context['my-theme/card-grid'] ?? array();
$card_style = $grid['cardStyle'] ?? 'elevated';

$style_class = match ( $card_style ) {
	'elevated' => 'bg-white rounded-xl shadow-md',
	'outlined' => 'bg-white rounded-xl border border-gray-200',
	'flat'     => 'bg-gray-50 rounded-xl',
	default    => 'bg-white rounded-xl shadow-md',
};
?>
<div useBlockProps class="<?php echo esc_attr( "$style_class overflow-hidden" ); ?>">
  <?php if ( $a['image'] ) : ?>
    <img
      src="<?php echo esc_url( $a['image']['url'] ); ?>"
      alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
      class="w-full aspect-video object-cover" />
  <?php endif; ?>
  <div class="p-6">
    <h3 class="text-lg font-semibold"><?php echo esc_html( $a['title'] ); ?></h3>
    <p class="mt-2 text-gray-600"><?php echo esc_html( $a['description'] ); ?></p>
    <?php if ( $a['url'] ) : ?>
      <a href="<?php echo esc_url( $a['url']['url'] ); ?>" class="mt-4 inline-block text-indigo-600 font-medium">
        <?php echo esc_html( $a['url']['title'] ?: 'Learn more' ); ?>
      </a>
    <?php endif; ?>
  </div>
</div>

O que isto demonstra: o cartão não tem campo de estilo próprio. Ele lê cardStyle do bloco pai da grade. Quando o usuário muda a grade de “Elevated” para “Outlined”, todos os cartões da grade são atualizados de uma vez. Isso mantém a consistência visual dos cartões sem obrigar o usuário a atualizar cada um individualmente.

O atributo template em <InnerBlocks> preenche a grade com três cartões de antemão, oferecendo um ponto de partida ao usuário.

Tabela de preços

Um padrão mais avançado em que o pai fornece lógica de negócios compartilhada (moeda, período de cobrança) usada pelos filhos na exibição. Isso evita duplicar os mesmos campos em cada faixa de preço.

Pai: tabela de preços

JSON
{
  "name": "my-theme/pricing-table",
  "title": "Pricing Table",
  "category": "text",
  "icon": "money-alt",
  "description": "Pricing comparison with shared currency and billing settings.",
  "blockstudio": {
    "attributes": [
      {
        "id": "currency",
        "type": "select",
        "label": "Currency",
        "default": "usd",
        "options": [
          { "value": "usd", "label": "USD ($)" },
          { "value": "eur", "label": "EUR (\u20ac)" },
          { "value": "gbp", "label": "GBP (\u00a3)" }
        ]
      },
      {
        "id": "period",
        "type": "select",
        "label": "Billing Period",
        "default": "month",
        "options": [
          { "value": "month", "label": "Monthly" },
          { "value": "year", "label": "Yearly" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-6 items-start">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr( wp_json_encode( array( 'my-theme/pricing-tier' ) ) ); ?>'
    template='<?php echo esc_attr( wp_json_encode( array(
      array( 'my-theme/pricing-tier', array( 'name' => 'Starter', 'price' => 9 ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Pro', 'price' => 29, 'highlighted' => true ) ),
      array( 'my-theme/pricing-tier', array( 'name' => 'Enterprise', 'price' => 99 ) ),
    ) ) ); ?>'
  />
</div>

Filho: faixa de preço

JSON
{
  "name": "my-theme/pricing-tier",
  "title": "Pricing Tier",
  "category": "text",
  "icon": "tag",
  "description": "Single pricing tier that reads currency from parent.",
  "usesContext": ["my-theme/pricing-table"],
  "parent": ["my-theme/pricing-table"],
  "blockstudio": {
    "attributes": [
      { "id": "name", "type": "text", "label": "Tier Name", "default": "Plan" },
      { "id": "price", "type": "number", "label": "Price", "default": 0 },
      { "id": "highlighted", "type": "toggle", "label": "Highlighted", "default": false },
      {
        "id": "features",
        "type": "repeater",
        "label": "Features",
        "attributes": [
          { "id": "text", "type": "text", "label": "Feature" }
        ]
      }
    ]
  }
}
PHP
<?php
$table    = $context['my-theme/pricing-table'] ?? array();
$currency = $table['currency'] ?? 'usd';
$period   = $table['period'] ?? 'month';

$symbols = array(
	'usd' => '$',
	'eur' => "\u{20AC}",
	'gbp' => "\u{00A3}",
);
$symbol = $symbols[ $currency ] ?? '$';

$period_label = $period === 'year' ? '/year' : '/month';

$border_class = $a['highlighted'] ? 'border-2 border-indigo-600' : 'border border-gray-200';
?>
<div useBlockProps class="<?php echo esc_attr( "rounded-xl p-8 $border_class" ); ?>">
  <h3 class="text-lg font-semibold"><?php echo esc_html( $a['name'] ); ?></h3>
  <div class="mt-4">
    <span class="text-4xl font-bold"><?php echo esc_html( $symbol . $a['price'] ); ?></span>
    <span class="text-gray-500"><?php echo esc_html( $period_label ); ?></span>
  </div>
  <?php if ( ! empty( $a['features'] ) ) : ?>
    <ul class="mt-6 space-y-3">
      <?php foreach ( $a['features'] as $feature ) : ?>
        <li class="flex items-center gap-2">
          <span class="text-indigo-600">&#10003;</span>
          <?php echo esc_html( $feature['text'] ); ?>
        </li>
      <?php endforeach; ?>
    </ul>
  <?php endif; ?>
</div>

O que isto demonstra: o símbolo da moeda e o período de cobrança são definidos uma única vez na tabela de preços e herdados por cada faixa. Quando o usuário muda de USD para EUR, o símbolo da moeda é atualizado simultaneamente nas três faixas. Sem contexto, seria necessário duplicar o campo da moeda em cada faixa e mantê-los sincronizados manualmente.

Contexto de loop de consulta

Há um tipo de contexto separado que WordPress fornece dentro dos loops de blocos Query. Quando um bloco é renderizado dentro de um loop, $block['context'] (ou $b['context']) contém os dados da publicação da iteração atual:

PHP
<?php
$loop_post_id   = $block['context']['postId'];
$loop_post_type = $block['context']['postType'];
?>
<article useBlockProps>
  <h2><?php echo esc_html( get_the_title( $loop_post_id ) ); ?></h2>
  <p><?php echo esc_html( get_the_excerpt( $loop_post_id ) ); ?></p>
  <a href="<?php echo esc_url( get_permalink( $loop_post_id ) ); ?>">Read more</a>
</article>

Isso é diferente do contexto do bloco pai ($context / $c). O contexto de loop é fornecido pelo núcleo de WordPress e contém apenas postId e postType. Para isso, você não precisa de usesContext no seu block.json. Blockstudio assina automaticamente todos os blocos a postId e postType.

Onde o contexto de loop é útil: cartões personalizados de publicações dentro de blocos Query, blocos que exibem metadados de publicações ou qualquer bloco que precise ser renderizado de forma diferente para cada publicação em um loop.

Você também pode acessar os dados da publicação da página externa, independentemente do contexto do loop:

PHP
$outer_post_id   = $block['postId'];   // always the current page
$loop_post_id    = $block['context']['postId'];  // current loop iteration

Contexto aninhado

O contexto percorre toda a árvore de blocos, não apenas um nível. Se o bloco A contém o bloco B, que contém o bloco C, então C pode assinar o contexto de A. Isso funciona porque WordPress propaga o contexto por todos os níveis de InnerBlocks.

Código
my-theme/section (theme: "dark")
└── core/columns
    └── core/column
        └── my-theme/section-heading (reads section context)

O título não precisa ser filho direto da seção. Ele pode estar aninhado dentro de blocos do núcleo (colunas, grupos etc.) e ainda receber o contexto da seção. A assinatura de usesContext funciona em qualquer profundidade.

Vários pais

Um filho pode assinar vários pais:

JSON
{
  "usesContext": ["my-theme/section", "my-theme/card-grid"]
}
PHP
<?php
$section = $context['my-theme/section'] ?? array();
$grid    = $context['my-theme/card-grid'] ?? array();

$theme     = $section['theme'] ?? 'light';
$cardStyle = $grid['cardStyle'] ?? 'elevated';
?>

Se um pai não for encontrado na árvore de ancestrais, sua chave estará ausente de $context. Sempre use o operador de coalescência nula (??) ou verifique isset() ao ler valores de contexto, caso o bloco seja usado fora do pai esperado.

Codificação defensiva

Os blocos que usam contexto devem sempre lidar com o caso em que o pai está ausente. Um usuário pode inserir o bloco fora do pai previsto, ou o bloco pai pode não ter um valor definido para um campo específico.

PHP
<?php
// Always provide defaults
$section = $context['my-theme/section'] ?? array();
$theme   = $section['theme'] ?? 'light';
$spacing = $section['spacing'] ?? 'md';
?>

Se quiser garantir que um filho só apareça dentro do pai, adicione a propriedade parent:

JSON
{
  "parent": ["my-theme/section"]
}

Isso remove o bloco do inseridor quando o usuário não está dentro de um bloco my-theme/section. Sem parent, o bloco aparece em todos os lugares, e cabe ao seu template lidar de forma adequada com a ausência de contexto.

Use parent para blocos sem sentido fora do contêiner (faixas de preço, itens da grade de cartões). Ignore-o para blocos que funcionam de forma independente, mas ganham estilo adicional com um pai (títulos de seção que também podem ser usados sem ele).

Dicas

O contexto é somente leitura. Os filhos não podem modificar os atributos do pai por meio do contexto. Os dados fluem para baixo, nunca para cima. Se um filho precisar se comunicar com o pai, será necessária outra abordagem (como estado compartilhado no servidor por meio da API Interactivity ou metadados da publicação).

Todos os atributos são fornecidos. Blockstudio fornece todos os atributos do bloco pai, não apenas os selecionados. Isso significa que o filho pode acessar qualquer campo definido pelo pai. Se o pai adicionar um novo campo depois, os filhos terão acesso a ele automaticamente, sem nenhuma alteração de configuração.

Valores transformados. Os valores de contexto passam pelo pipeline de transformação de atributos de Blockstudio. Os campos de arquivo contêm os dados completos do anexo (url, alt, width, height), os campos de seleção respeitam returnFormat e os repetidores são expandidos recursivamente. Você recebe a mesma estrutura de dados que $a no template pai.

Reatividade no editor. Quando um usuário altera um campo do pai no editor, os blocos filhos são renderizados novamente automaticamente. Isso usa a propagação de contexto integrada de WordPress com um React useEffect que detecta mudanças no contexto e aciona uma nova renderização do filho no servidor.

Mantenha o contexto enxuto. Embora Blockstudio forneça automaticamente todos os atributos do pai, os filhos devem ler apenas os valores de que realmente precisam. Isso não é uma questão de desempenho (os dados já estão disponíveis), mas de clareza do código. Documente de quais campos do pai o filho depende para que futuros desenvolvedores entendam essa relação.

Próximas etapas

  • Referência de contexto: variáveis de template, contexto de loop e a estrutura de dados $block.
  • InnerBlocks: o componente <InnerBlocks />, allowedBlocks, templates e o filtro do contêiner do frontend.
  • Guia de Interactivity: para reatividade no lado do cliente entre blocos (a API Interactivity trata do que o contexto não pode fazer: comunicação do filho para o pai, estado entre blocos e atualizações acionadas pelo usuário).