Pular para o conteúdo

Blocos personalizados em 3 arquivos

Sem JavaScript, etapa de compilação ou código padrão.

Defina campos em JSON

Adicione uma chave blockstudio a block.json. Defina atributos com tipos como text, toggle e color. Blockstudio gera automaticamente o editor UI, com tipos de campo 27 que vão de campos de texto a repetidores e editores de código, além dos tipos de campo que você mesmo registrar.

O suporte completo ao esquema JSON oferece preenchimento automático e validação no VS Code, no PhpStorm e em todos os editores compatíveis.

Cada campo pode definir um default para novos blocos e um fallback que o modelo recebe enquanto o campo está vazio.

block.json
{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "showCta", "type": "toggle", "label": "Show CTA" },
      { "id": "background", "type": "color", "label": "Background" }
    ]
  }
}

Fluxo de trabalho com 3 arquivos

block.json para campos, um template para a marcação e uma folha de estilos opcional.

React em PHP

RichText, InnerBlocks e useBlockProps funcionam diretamente em PHP, Twig ou Blade.

SCSS e Tailwind

Use CSS, SCSS ou Tailwind. SCSS oferece suporte a caminhos de importação e a um prelude compartilhado, e a edição de uma parcial aninhada recompila todos os arquivos que a importam.

27 tipos de campo

Texto, cor, imagem, repetidor, seleção, editor de código e muito mais, configurados em JSON.

JSON Schema

Preenchimento automático e validação em VS Code, PhpStorm e editores compatíveis.

Três linguagens de templates

PHP, Twig e Blade compartilham as mesmas variáveis e os mesmos componentes.

Importações de npm

Importe pacotes em script.js; eles são locais em produção e dependem de CDN no editor.

Interactivity API

Ative a WordPress Interactivity API com uma única flag.

Componentes React em templates PHP

Use <RichText /> para edição em linha e HTML estático no frontend, <InnerBlocks /> para blocos filhos e useBlockProps para o wrapper, tudo em um único template.

No editor, eles se tornam componentes React de verdade. No frontend, são renderizados como HTML no servidor, sem enviar JavaScript aos visitantes.

index.php
<div useBlockProps class="container">
  <RichText
    class="text-xl font-semibold"
    tag="h1"
    attribute="headline"
    placeholder="Enter headline"
  />

  <?php if ($a['showCta']): ?>
    <a href="<?= esc_url($a['ctaUrl']) ?>">
      <?= esc_html($a['ctaLabel']) ?>
    </a>
  <?php endif; ?>

  <InnerBlocks class="mt-4 p-4 border" />
</div>

Escreva em PHP, Twig ou Blade

Use a linguagem de modelos que você conhece. PHP funciona imediatamente, Twig é executado assim que Timber é instalado, e Blade é executado em illuminate/view 8 a 12 por meio de Blockstudio\Blade_Renderer. As variáveis, os componentes e o comportamento permanecem iguais.

$a (atributos), $b (bloco), $c (contexto) e $innerBlocks estão disponíveis em todas as linguagens.

Twig os modelos também recebem o contexto completo de Timber. Blade também renderiza páginas, padrões e modelos do Editor do site. O wrapper antigo jenssegers/blade falha com illuminate/view 10 e versões posteriores, então use Blade_Renderer.

index.twig
<div useBlockProps class="card">
  <RichText tag="h2" attribute="title" placeholder="Card title" />
  {% if a.image %}
    <img src="{{ a.image.url|esc_url }}"
      alt="{{ a.image.alt|esc_attr }}" />
  {% endif %}
  <div class="card__body">{{ a.description|esc_html }}</div>
  <InnerBlocks allowedBlocks='["core/button"]' />
</div>

Lógica condicional e opções dinâmicas

Mostre e oculte campos com operadores como ==, !=, includes, empty e comparações. Combine condições com lógica OR.

As opções podem depender de outro campo. Inclua {attributes.post_type.value} nos argumentos de preenchimento e a lista será recarregada quando esse campo mudar. Adicione fetch: true para pesquisar posts enquanto o editor digita.

Compartilhe uma lista de opções entre blocos com type: custom e o filtro blockstudio/blocks/attributes/populate, e registre suas próprias condições globais, como uma verificação de compra, por meio de blockstudio/blocks/conditions.

block.json
{
  "name": "starter/posts",
  "title": "Posts",
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post type",
        "options": [
          { "value": "page", "label": "Pages" },
          { "value": "post", "label": "Posts" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": { "post_type": "{attributes.post_type.value}" }
        }
      },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "populate": { "type": "custom", "custom": "cardStyles" },
        "conditions": [[
          { "type": "purchasedProduct", "operator": "==", "value": "yes" }
        ]]
      }
    ]
  }
}

Repetidores que continuam fáceis de gerenciar

Defina min e max, inicie novos blocos com linhas default e recolha as linhas existentes com minimized. textMinimized identifica uma linha recolhida com um dos campos dela, como um nome.

As linhas aceitam todos os tipos de campo, exceto abas, incluindo repetidores aninhados. Uma condição dentro de uma linha verifica um campo externo a ela com "context": "main", e <RichText /> e <MediaPlaceholder /> editam uma única linha quando o attribute deles aponta para repeaterId[index].fieldId.

block.json
{
  "name": "starter/team",
  "title": "Team",
  "blockstudio": {
    "attributes": [
      {
        "id": "members",
        "type": "repeater",
        "label": "Team members",
        "min": 1,
        "max": 12,
        "minimized": true,
        "textMinimized": { "id": "name", "fallback": "Team member" },
        "attributes": [
          { "id": "name", "type": "text", "label": "Name" },
          { "id": "bio", "type": "richtext", "label": "Bio" }
        ]
      }
    ]
  }
}

Conjuntos de campos reutilizáveis

Defina um grupo de campos uma vez em um field.json e use-o em qualquer bloco com "type": "custom/cta". Os campos são incorporados diretamente, então os templates os leem como qualquer outro atributo.

Use o mesmo conjunto duas vezes com um idStructure, como hero_{id}, e altere rótulos, valores padrão ou condições por bloco com overrides. O tipo de campo block faz o mesmo com um bloco inteiro: expande os campos desse bloco diretamente e retorna seu HTML renderizado.

fields/cta/field.json
{
  "name": "cta",
  "title": "Call to action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
    { "id": "url", "type": "link", "label": "Button URL" }
  ]
}

Módulos ES sem etapa de compilação

Adicione script.js para carregá-lo como um módulo ES. Importe pacotes npm com o prefixo npm:, e Blockstudio os baixa localmente para produção.

O editor mostra uma prévia instantânea, enquanto o frontend usa módulos locais sem dependências externas, enfileirados uma única vez.

As folhas de estilo são importadas da mesma forma. import "npm:swiper@11.0.0/swiper.min.css" baixa o arquivo e o enfileira uma vez por versão, mesmo quando vários blocos o utilizam.

script.js
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";

for (const el of document.querySelectorAll(".swiper")) {
  new Swiper(el, {
    slidesPerView: 3,
    spaceBetween: 20,
    loop: true,
  });
}

Tags de bloco além dos templates

Associe um prefixo curto a um namespace em blockstudio.json, ou uma tag a um bloco com um filtro de alias, e <acme-card> renderiza acme/card. Ative blockTags.enabled para renderizar tags no conteúdo dos posts e nos widgets, limitado pelos padrões allow e deny.

Os atributos data-* chegam ao elemento raiz do bloco, e os atributos html-* chegam sem o prefixo. Adicione seus próprios criadores de tags com blockstudio/block_tags/builders e converta abreviações para a forma portátil <bs:acme-card> com o comando migrate-block-tags.

blockstudio.json
{
  "blockTags": {
    "enabled": true,
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    },
    "deny": ["acme-ui/admin-*"]
  }
}

Tipos de campo personalizados

Registre seu próprio controle de campo e use-o como um campo integrado.

Ilhas de blocos

Armazene a página inteira em cache e renderize um bloco na solicitação do visitante.

Registro condicional

Registre um bloco apenas para um tipo de post, função de usuário ou outra condição global, ou ignore-o quando faltar um plugin necessário ou a versão exigida dele.

Metadados de publicação e opções

Armazene valores nos metadados da publicação ou nas opções, junto com os atributos do bloco.

Lógica condicional

Mostre campos com base em valores, usando igualdade, inclusão, ausência de conteúdo e comparações.

Populações dinâmicas

Preencha opções com publicações, usuários, termos, funções ou APIs.

Substituições

Defina override: true com o nome de um bloco compartilhado para mesclar atributos por id, substituir recursos com nomes de arquivo correspondentes e trocar o template. Os templates Twig podem substituir blocos individuais com extends.

Variações

Declare variações em block.json que predefinem valores de campos e oculte com hidden o campo que as controla.

Componentes

Defina component: true para um bloco renderizado somente por PHP ou por tags de bloco. Ele mantém campos, templates, recursos e Tailwind, mas nunca aparece no inseridor.

Regras de InnerBlocks

Permita blocos com tokens namespace/*, category: e @theme, alterne o template interno por meio de uma opção de seleção e remova o wrapper no frontend com um filtro.

Recursos de campos de código

Um campo de código com asset: true transforma a entrada do editor em CSS, SCSS ou JavaScript para esse bloco, com escopo na instância por meio de %selector%.

Assets pelo nome do arquivo

*.view.js carrega apenas no frontend, e os prefixos global-, admin- e block-editor- carregam um arquivo em todas as páginas, no wp-admin ou no editor de blocos.

Ícones e pastas de blocos

Atribua a um bloco um ícone SVG personalizado ou HTML, altere o local de descoberta com o filtro blockstudio/path e adicione pastas com Blockstudio\Build::init().

Valores de ACF e Meta Box

Os templates recebem $post_id, então get_field() e rwmb_get_value() leem o post editado, e refreshOn atualiza a prévia após salvar.

Contexto do Query Loop

Dentro de um Query Loop, $block[‘context’][‘postId’] acompanha o item atual, enquanto $block[‘postId’] permanece como o post sendo visualizado.

WPML

wp bs wpml config grava o wpml-config.xml que marca os campos de texto como traduzíveis, e as imagens armazenadas nos campos são incluídas nos trabalhos de tradução de WPML com seus textos alternativos e legendas.

Plus

O kit oficial de extensões

Modelos premium de site, instruções de sistema para IA e uma comunidade privada Discord. Compra única, atualizações vitalícias.

  • 500+ modelos de sites
  • Instruções de sistema para IA
  • Atualizações vitalícias
  • Comunidade privada de Discord