Estendendo theme.json para Tipos de Post Personalizados e Saída de Plugins: Um Guia Prático

Resumo

Muitos desenvolvedores WordPress criam tipos de post personalizados ou plugins que geram conteúdo (por exemplo, depoimentos, portfólios). No entanto, o theme.json — a configuração central para estilos globais — frequentemente ignora esses elementos personalizados por padrão, resultando em design desconexo. Este artigo orienta você sobre como registrar tipos de post personalizados para herdar estilos do theme.json, substituir configurações para blocos específicos e conectar a saída de plugins aos tokens de design principais. Você obterá instruções passo a passo, exemplos do mundo real como estilizar um CPT 'Membro da Equipe', e ressalvas sobre desempenho e conflitos de terceiros. Ao final, você pode garantir que qualquer conteúdo personalizado corresponda ao sistema de design definido pelo editor do seu site.

Você já criou um tipo de post personalizado ou integrou um plugin de terceiros, apenas para descobrir que sua saída ignora completamente o belo sistema de design que você configurou meticulosamente em theme.json? Você não está sozinho. Por padrão, o theme.json se aplica apenas a blocos principais do WordPress e estilos de bloco registrados, deixando os tipos de post personalizados e o conteúdo gerado por plugins se virarem sozinhos. Isso normalmente resulta em CSS inline, pilhas de fontes duplicadas ou uma paleta de cores incompatível que prejudica a experiência do usuário. Mas há uma maneira melhor: você pode estender o theme.json para cobrir esses elementos personalizados, garantindo um sistema de design consistente e sustentável em todo o seu site. Neste guia, abordaremos quatro passos práticos para fazer isso acontecer, completos com exemplos de código e ressalvas do mundo real.

Entendendo o Escopo do theme.json

Antes de mergulhar, é crucial entender que o theme.json é um conceito de tema de bloco. Ele define estilos globais, configurações (como paletas de cores e tamanhos de fonte) e estilos específicos de blocos para o editor de blocos e front-end. No entanto, seu alcance é limitado: controla apenas blocos que declaram explicitamente suporte às propriedades do theme.json via register_block_type ou o antigo add_theme_support. Tipos de post personalizados criados com register_post_type não herdam automaticamente esses estilos, a menos que sejam construídos com blocos ou explicitamente estilizados.

Passo 1: Registrando Tipos de Post Personalizados com Suporte ao Editor de Blocos

O primeiro passo é garantir que seu tipo de post personalizado use o editor de blocos. Ao chamar register_post_type, defina 'show_in_rest' => true e inclua 'editor' no array supports. Isso ativa o editor de blocos para aquele tipo de post, permitindo que autores usem estilos de nível de bloco do theme.json. Por exemplo, aqui está um CPT "Membro da Equipe":

function create_team_member_cpt() {
    $args = array(
        'public' => true,
        'show_in_rest' => true,
        'supports' => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
        'show_in_menu' => true,
        'labels' => array(
            'name' => 'Team Members',
            'singular_name' => 'Team Member',
        ),
        'rewrite' => array( 'slug' => 'team' ),
    );
    register_post_type( 'team_member', $args );
}
add_action( 'init', 'create_team_member_cpt' );

Agora, ao editar um post de membro da equipe, você verá o editor de blocos com os estilos globais do seu tema aplicados a blocos principais como Parágrafo, Título e Imagem. Isso por si só geralmente resolve a maioria dos problemas de estilização. Se você precisar de um controle mais granular, prossiga para o próximo passo. Para um mergulho mais profundo na construção de temas de bloco com theme.json, veja Como Construir um Tema de Bloco WordPress Personalizado com theme.json.

Passo 2: Adicionando Estilos de Bloco Personalizados via theme.json

Às vezes, você deseja aplicar estilos específicos a todas as instâncias do conteúdo do seu tipo de post personalizado — por exemplo, dando a todo o post uma cor de fundo ou padding especial. Você pode segmentar core/post-content ou envolver seu conteúdo em um bloco de grupo personalizado e estilizá-lo via theme.json. Adicione o seguinte ao seu arquivo theme.json sob o objeto styles:

{
  "styles": {
    "blocks": {
      "core/post-content": {
        "css": "background-color: var(--wp--preset--color--light); padding: 2rem;"
      }
    }
  }
}

Isso aplicará um fundo claro e padding à área de conteúdo de todos os posts, incluindo seu CPT Membro da Equipe. Você também pode definir variações específicas de bloco dentro de settings.blocks para fornecer opções de estilo no editor.

Passo 3: Usando Propriedades Personalizadas do theme.json para Saída de Plugins

Plugins frequentemente geram conteúdo via shortcodes, widgets ou blocos personalizados. Para estilizá-los de forma consistente, aproveite as propriedades personalizadas CSS que o theme.json gera. Por exemplo, se seu tema define uma cor primária como --wp--preset--color--primary, você pode usá-la no CSS do seu plugin:

.my-plugin-button {
    background-color: var(--wp--preset--color--primary);
    font-size: var(--wp--preset--font-size--medium);
}

Isso garante que, quando o administrador do site alterar a paleta de cores no theme.json, o botão do seu plugin seja atualizado automaticamente. Para tornar isso robusto, sempre use as variáveis CSS predefinidas em vez de valores codificados. Além disso, se seu plugin registrar seus próprios blocos, você pode herdar as configurações do theme.json usando useSetting em JavaScript ou passando $attributes na renderização PHP, conforme abordado em Dominando Blocos Dinâmicos do WordPress.

Passo 4: Lidando com Blocos Dinâmicos

Para blocos personalizados que geram conteúdo dinâmico (por exemplo, um slider de depoimentos), você precisa registrar o bloco com suporte ao editor de blocos e vinculá-lo explicitamente ao theme.json. Em PHP, use register_block_type com $args que incluam 'render_callback' e certifique-se de que o arquivo block.json do seu bloco defina 'supports' => array( 'color' => true, 'typography' => true ). Então, em seu callback de renderização, você pode acessar os estilos globais via wp_get_global_styles() e aplicá-los. Por exemplo:

function render_testimonial_block( $attributes, $content ) {
    $styles = wp_get_global_styles();
    $color = $styles['elements']['link']['color']['text'] ?? '#000';
    return '<div style="color: ' . esc_attr( $color ) . ';">' . $content . '</div>';
}

Essa abordagem garante que seu bloco personalizado respeite os tokens de design do tema. Para mais sobre registro de blocos, veja Construindo Plugins WordPress Robusto.

Ressalvas

Embora estender o theme.json seja poderoso, fique atento a estas armadilhas:

1. Desempenho: Adicionar muitos estilos personalizados no theme.json pode inflar o arquivo e aumentar o tempo de análise CSS. Mantenha-se nas configurações globais e use estilos específicos de bloco com moderação.
2. Conflitos de Plugins: Alguns plugins redefinem ou substituem as configurações do theme.json. Sempre teste com um conjunto mínimo de plugins e considere usar o hook after_setup_theme para reaplicar suas personalizações.
3. Temas Clássicos: Se seu tema não usa o editor de blocos (ou seja, é um tema clássico), o theme.json tem efeito limitado. Considere migrar para um tema de bloco ou usar a função wp_enqueue_global_styles para carregar os estilos.
4. Cache do Navegador: Alterações no theme.json podem não aparecer imediatamente devido ao cache. Limpe o cache do navegador e use versionamento para sua folha de estilo.

Conclusão

Agora você tem um roteiro claro para fazer com que os tipos de post personalizados e as saídas de plugins funcionem bem com seu sistema de design theme.json. A chave é registrar seu CPT com suporte ao editor de blocos, definir estilos específicos para o bloco de conteúdo do post, usar propriedades personalizadas CSS na saída do plugin e registrar seus blocos personalizados com integração adequada ao theme.json. Essa abordagem elimina inconsistências, reduz a manutenção e dá aos administradores do site o poder de controlar a aparência e a sensação a partir de uma única fonte de verdade. Comece a implementar esses passos hoje mesmo para trazer coesão aos seus projetos WordPress.