O que é o arquivo theme.json no WordPress e como usá-lo

O arquivo theme.json é uma parte importante dos temas de blocos do WordPress, controlando muitos aspectos da aparência e funcionalidade do seu site. Se você mudou recentemente de um tema clássico para um tema de blocos, pode estar se perguntando o que é esse arquivo e se deve editá-lo.

Você não está sozinho. Nós e muitos usuários do WPBeginner também nos perguntamos a mesma coisa. Por isso, decidimos mergulhar fundo neste tópico para fornecer um guia completo.

Neste artigo, explicaremos o que é um arquivo theme.json, por que ele é importante e como você pode usá-lo para personalizar seu site WordPress. 

O que é o Arquivo theme.json do WordPress?

O arquivo theme.json é um arquivo de tema especial introduzido no WordPress 5.8. Ele desempenha um papel fundamental na experiência de edição completa do site (FSE), que permite personalizar visualmente todos os aspectos do seu tema de blocos do WordPress.

Essencialmente, o arquivo theme.json atua como um modelo que controla a estilização e a funcionalidade do seu tema de blocos. Ele contém código que informa ao WordPress como diferentes elementos, como cores, tipografia, layouts e modelos, devem parecer e se comportar.

Por que os Temas de Blocos do WordPress Precisam de um Arquivo theme.json?

Editar um tema de blocos no WordPress é diferente de editar um tema clássico.

Temas clássicos usam o arquivo functions.php para habilitar recursos como menus personalizados ou imagens destacadas com a função add_theme_support(). Em seguida, você pode estilizar esses recursos com regras CSS no arquivo de folha de estilo CSS (style.css).

Em temas de bloco, o theme.json atua como um hub central para tudo que define a aparência do seu tema de bloco. Ele permite que você defina coisas como fontes, cores e opções de layout em um só lugar, substituindo a necessidade de add_theme_support() no functions.php.

É por isso que o arquivo functions.php em temas de bloco é frequentemente menor do que o equivalente em temas clássicos.

Ter um arquivo theme.json dedicado oferece alguns ótimos benefícios em relação ao sistema anterior de temas clássicos.

Primeiro, o theme.json funciona em conjunto com o editor completo do site do WordPress. Isso permite que você personalize os estilos e configurações do seu tema facilmente diretamente no editor, sem precisar tocar em nenhum código.

Além disso, o theme.json visa criar uma experiência consistente para desenvolvedores e usuários. Alguns usuários acham realmente frustrante quando precisam trocar de tema porque precisam aprender layouts e opções de estilo completamente novos.

Com o theme.json, a troca de temas se torna um processo mais suave porque tudo está organizado de forma semelhante.

Finalmente, ao usar o theme.json, desenvolvedores e usuários de temas podem preparar seus trabalhos para o futuro, à medida que o WordPress continua a expandir suas capacidades de edição completa do site.

Agora que cobrimos o que é um arquivo theme.json, vamos nos aprofundar no tópico. Você pode usar os links rápidos abaixo para navegar por este guia:

• Onde Encontrar o Arquivo theme.json do WordPress?
• Como é o Arquivo theme.json?
• O Que Fazer Antes de Editar o Arquivo theme.json
• Como Editar o Arquivo theme.json do WordPress
• Dica Bônus: Use o WPCode para Adicionar Código Personalizado ao Seu Tema

Onde Encontrar o Arquivo theme.json do WordPress?

O arquivo theme.json é encontrado dentro do diretório do seu tema no seu servidor web. O caminho típico do arquivo seria public_html » wp-content » themes » nome-do-seu-tema » theme.json.

Para acessá-lo, você primeiro precisa se conectar ao seu site via FTP ou o gerenciador de arquivos da sua conta de hospedagem.

Se você usa o Bluehost, então você pode fazer login e mudar para a aba ‘Websites’. Em seguida, clique no botão ‘Settings’ abaixo do seu site.

Agora, certifique-se de permanecer na aba ‘Visão Geral’.

Em seguida, role para baixo para clicar no botão ‘Gerenciador de Arquivos’.

Quando você abre o gerenciador de arquivos desta forma, você estará automaticamente dentro da pasta raiz do seu site.

Aqui, procure pelo diretório ‘wp-content’ e abra-o. Lá, você encontrará a pasta ‘themes’, que contém todos os seus temas WordPress instalados.

Abra a pasta do tema de bloco específico que você está usando. O arquivo theme.json estará localizado diretamente dentro deste diretório de tema, ao lado de outros arquivos do tema.

Assim que o encontrar, você poderá visualizar o arquivo theme.json usando um editor de código.

Como é o Arquivo theme.json?

O arquivo theme.json tem uma estrutura específica que organiza todas as configurações globais do seu tema de bloco WordPress.

Dependendo de quão complexo ou simples seu tema parece, o arquivo pode ser muito curto ou longo. No entanto, você pode facilmente dividir este arquivo em 7 seções de nível superior:

{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {},
"styles": {},
"customTemplates": {},
"templateParts": {},
"patterns": []
}

Aqui está uma divisão simplificada:

Schema

Esta parte é, na verdade, opcional em temas de bloco, então você pode ou não vê-la no seu.

A propriedade schema vincula o URL ao esquema JSON do WordPress, que define as configurações globais, estilos e outras configurações para o seu tema.

Versão

Esta seção especifica qual versão da API do formato theme.json está sendo usada pelo arquivo e garante que ele siga a estrutura correta.

No momento da escrita deste artigo, a API está na versão 2.

Configurações

Esta propriedade define as opções e controles disponíveis para os usuários personalizarem seu tema. Isso inclui predefinições para a paleta de cores do tema, tipografia, espaçamento, gradientes, sombras, bordas e assim por diante.

Aqui está um exemplo muito simples de como a propriedade settings se parece:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "base",
          "color": "#ffffff",
          "name": "White"
        },
        {
          "slug": "contrast",
          "color": "#222222",
          "name": "Dark"
        },
        {
          "slug": "accent",
          "color": "#f08080",
          "name": "Pink"
        },
        {
          "slug": "accent-2",
          "color": "#90ee90",
          "name": "Light Green"
        },
        {
          "slug": "accent-3",
          "color": "#e0ffff",
          "name": "Light Blue"
        }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "Open Sans, sans-serif",
          "slug": "open-sans",
          "name": "Open Sans"
        },
        {
          "fontFamily": "Arial, sans-serif",
          "slug": "arial",
          "name": "Arial"
        },
        {
          "fontFamily": "Times New Roman, serif",
          "slug": "times-new-roman",
          "name": "Times New Roman"
        }
      ],
      "fontSizes": [
        {
          "name": "Extra Small",
          "slug": "xx-small",
          "size": "0.75rem"
        },
        {
          "name": "Small",
          "slug": "small",
          "size": "0.875rem"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "1rem"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "1.125rem"
        },
        {
          "name": "Extra Large",
          "slug": "x-large",
          "size": "1.25rem"
        },
        {
          "name": "XX-Large",
          "slug": "xx-large",
          "size": "1.5rem"
        }
      ],
      "spacing": {
        "units": ["rem"],
        "values": {
          "small": "1rem",
          "medium": "1.5rem",
          "large": "2rem"
        }
      }
    }
  }
}

Se você olhar o código, a linguagem usada é bem fácil de entender. Você pode dizer que as configurações estão definindo as cores, famílias de fontes, tamanhos de fontes e espaçamento usados no tema.

Se houver alguma referência aqui ou em seu tema que você não entenda, você pode consultar a Referência Oficial de Configurações do WordPress.

Alguns elementos, como cores e famílias de fontes, têm slugs, assim:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "base",
          "color": "#ffffff",
          "name": "White"
        },

Estes serão úteis para a seção de estilos mais tarde para criar predefinições, que explicaremos na próxima parte.

Estilos

Enquanto a seção de configurações define as opções de personalização padrão do tema, a seção de estilos as aplica ao tema.

Aqui, você pode aplicar as configurações de personalização a todo o site ou em nível de bloco usando predefinições.

Vamos conferir o exemplo abaixo:

{
  "settings": {
    // Existing settings from the previous example
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--accent-2)"
        }
      },
      "h1": {
        "fontSize": "var(--wp--preset--font-size--xx-large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      },
      "h2": {
        "fontSize": "var(--wp--preset--font-size--x-large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      },
      "h3": {
        "fontSize": "var(--wp--preset--font-size--large)",
        "lineHeight": "1.2",
        "marginBottom": "1rem"
      }
    }
  }
}

Como você pode ver, há esta linha de código aparecendo em todo este trecho: var(--wp--preset--xxx). Estas são predefinições, que são atalhos na seção de estilos que se referem aos valores definidos na seção de configurações.

Por exemplo, considere {"slug": "base", "color": "#ffffff", "name": "White"} na seção de configurações. Aqui, "base" é o slug, e a predefinição correspondente para esta cor é var(--wp--preset--color--base).

Portanto, o código "color": {"background": "var(--wp--preset--color--base)" nos estilos diz que a cor de fundo deste tema é branca.

Modelos Personalizados

No desenvolvimento de temas de blocos do WordPress, os desenvolvedores podem criar layouts predefinidos para páginas personalizadas, posts ou tipos de postagem personalizados para os usuários utilizarem.

Por exemplo, o tema Twenty Twenty-Four tem vários modelos personalizados definidos no arquivo theme.json: Página Sem Título, Página Com Barra Lateral, Página com Imagem Ampla e Único com Barra Lateral.

Você pode usar qualquer um deles para criar seu conteúdo.

],
"customTemplates": [
  {
    "name": "page-no-title",
    "postTypes": ["page"],
    "title": "Page No Title"
  },
  {
    "name": "page-with-sidebar",
    "postTypes": ["page"],
    "title": "Page With Sidebar"
  },
  {
    "name": "page-wide",
    "postTypes": ["page"],
    "title": "Page with wide Image"
  },
  {
    "name": "single-with-sidebar",
    "postTypes": ["post"],
    "title": "Single with Sidebar"
  }
]

Uma coisa a notar é que o arquivo theme.json apenas referencia os modelos pelo nome e fornece metadados sobre eles, como título e os tipos de postagem para os quais se destinam.

No entanto, a aparência e a funcionalidade reais dos modelos personalizados são definidas em arquivos de modelo separados dentro da pasta do tema.

Para vê-los, você pode ir para public_html » wp-content » themes » seu-nome-de-tema » templates.

Partes de Modelo

Partes de modelo são áreas reutilizáveis que você pode aplicar em seus modelos personalizados. Estes são elementos como cabeçalhos, rodapés, barras laterais e assim por diante.

Veja como essas partes de modelo aparecem registradas em theme.json:

"templateParts": [
  {
    "area": "header",
    "name": "header",
    "title": "Header"
  },
  {
    "area": "footer",
    "name": "footer",
    "title": "Footer"
  },
  {
    "area": "sidebar",  // Removed "uncategorized"
    "name": "sidebar",
    "title": "Sidebar"
  },
  {
    "area": "post-meta",  // Removed "uncategorized"
    "name": "post-meta",
    "title": "Post Meta"
  }
]

Assim como os modelos personalizados, o arquivo theme.json apenas referencia os modelos.

Sua aparência real é definida em seus próprios arquivos de parte de modelo na pasta parts.

Padrões

Padrões são coleções pré-fabricadas de blocos que permitem criar layouts de conteúdo personalizados em suas páginas, posts ou em qualquer outro lugar do seu tema.

Ao abrir o editor completo do site, você pode notar o menu Padrões. É aqui que você pode encontrar todos os padrões disponíveis para o seu tema de blocos Gutenberg.

Com o theme.json, os desenvolvedores de temas podem referenciar padrões do diretório público de Padrões. É uma ótima maneira de oferecer mais opções de personalização sem projetar esses blocos reutilizáveis você mesmo.

Por exemplo, o tema Twenty Twenty-Four referencia dois padrões do diretório oficial: três colunas de serviços e a seção de clientes:

"patterns": [
  "three-columns-of-services",
  "clients-section"
]

Sabemos disso porque esses padrões estão no menu Padrões no editor de site completo.

No entanto, eles não estão na pasta patterns dentro do diretório do tema.

O Que Fazer Antes de Editar o Arquivo theme.json

Como o theme.json é um arquivo principal do tema, editá-lo diretamente no seu site WordPress ativo apresenta alguns riscos. Erros acidentais podem potencialmente quebrar seu tema ou site.

Uma abordagem mais segura é usar um tema filho.

Um tema filho herda todas as variações de estilo e funcionalidades do seu tema pai (o tema de blocos que você está usando), mas permite que você personalize coisas sem modificar o tema pai em si. Dessa forma, se o tema pai receber atualizações, suas personalizações não serão substituídas.

Você pode ler nosso guia sobre como criar um tema filho no WordPress para mais informações. Este artigo mostra um método fácil com o plugin Create Block Theme, que gerará automaticamente um novo arquivo theme.json apenas para o seu tema filho.

Para garantir uma experiência de edição tranquila e evitar qualquer tempo de inatividade do site, também recomendamos a criação de um novo backup do seu site WordPress. Dessa forma, se algo der errado, você poderá restaurar facilmente seu site para seu estado anterior.

Recomendamos o uso de um plugin como o Duplicator para uma solução de backup rápida e confiável.

Também é recomendado trabalhar em um ambiente de desenvolvimento WordPress local ou em um site de staging. Isso cria uma réplica do seu site ativo onde você pode testar alterações com segurança sem afetar seus visitantes.

Aqui estão algumas dicas adicionais para ter em mente:

• Comece com edições menores no seu arquivo theme.json e teste-as completamente antes de fazer alterações mais complexas.
• Se você não tiver certeza sobre alguma propriedade ou configuração específica dentro do arquivo theme.json, consulte a documentação oficial do WordPress.
• Não hesite em procurar ajuda da equipe de suporte do desenvolvedor do tema ou dos fóruns de suporte do WordPress.org se encontrar algum problema. Confira nosso guia sobre como pedir suporte WordPress para mais informações.

Como Editar o Arquivo theme.json do WordPress

Com base em nossa pesquisa e testes, descobrimos duas maneiras de editar um arquivo theme.json do WordPress: usando o editor de site completo ou usando código. A primeira opção é muito mais fácil e segura, permitindo que você veja suas modificações na parte frontal do seu site.

Enquanto isso, a segunda opção é recomendada se você se sentir confortável com o desenvolvimento avançado do WordPress.

Edite theme.json Sem Código (Iniciantes)

Para editar seu arquivo theme.json sem tocar diretamente no código, você pode usar o plugin Create Block Theme. Este plugin foi publicado pela equipe oficial do WordPress.org para permitir que os usuários criem um tema de blocos personalizado, o editem e/ou salvem as variações de estilo do seu tema de blocos.

Primeiro, vá em frente e instale o plugin do WordPress em sua área de administração. Em seguida, abra o editor de site completo indo em Aparência » Editor.

Agora você verá vários menus para editar seu tema.

Aqui, selecione 'Estilos'.

Em seguida, clique no ícone de lápis 'Editar estilos'.

Isso o levará ao editor de blocos para editar as configurações globais e estilos do seu site.

Agora, você pode alterar o estilo do seu tema normalmente. Você pode ler a seção sobre como editar os estilos globais do seu tema em nosso guia de edição de site completo do WordPress para mais informações.

Vamos tentar criar uma paleta de cores personalizada como exemplo.

O esquema de cores ou paleta é um conjunto de cores padrão para elementos como texto, fundos e botões. Ele garante um visual coeso em todo o seu site.

Elementos que usam a mesma predefinição de cor sempre combinarão para que o design do seu site pareça polido e profissional.

Para editar a paleta, selecione 'Cores' na barra lateral de configurações de Estilos.

Na próxima tela, você verá algumas configurações para personalizar as cores do seu tema.

Aqui, clique nas cores na seção 'Paleta'.

Neste exemplo, o tema Twenty Twenty-Four já definiu 5 cores na paleta, mas você pode alterar qualquer uma delas para criar uma personalizada do zero.

Para fazer isso, clique em uma das cores em ‘Tema’. Em seguida, selecione qualquer cor na ferramenta de seleção de cores.

Agora, se você pré-visualizar seu site, verá que os blocos ou elementos específicos que usavam a cor anterior foram substituídos pela cor que você acabou de selecionar em sua paleta.

Você pode repetir os mesmos passos para cada cor. Em seguida, clique em ‘Salvar’.

Após salvar suas alterações, clique no botão Criar Tema de Bloco (o ícone de chave inglesa).

Em seguida, selecione ‘Salvar Alterações no Tema’.

Na próxima tela, você precisa rolar para baixo.

Depois disso, clique em ‘Salvar Alterações’. Isso solicitará ao WordPress que armazene todas as alterações que você fez em seu tema no arquivo theme.json.

Assim que fizer isso, o editor de blocos se atualizará.

Agora, clique novamente no botão Criar Tema de Bloco e selecione ‘Ver theme.json’.

Para ver o código da sua paleta de cores personalizada, procure por palette aninhado dentro de color e settings, assim:

"settings": {
  // Some code...
  "color": {
    // Some code...
    "palette":  
  }
}

Abaixo dele, você deverá ver os novos códigos hexadecimais da sua paleta de cores personalizada.

Editar theme.json com Código (Usuários Avançados)

Este método é recomendado se você é um aspirante a desenvolvedor de temas WordPress ou tem alguma experiência com código.

Primeiro, abra o arquivo theme.json do seu tema de bloco no seu diretório WordPress. Você pode usar o editor de código no gerenciador de arquivos do seu host da web ou baixar o arquivo, editá-lo no seu computador e fazer o upload de volta para o seu servidor.

Usaremos o tema Twenty Twenty-Four e o gerenciador de arquivos da Bluehost para fins de demonstração. Se você é um usuário Bluehost e está usando o gerenciador de arquivos, pode simplesmente clicar com o botão direito no seu arquivo theme.json e clicar em ‘Editar’.

Se você usa FTP, pode ler nosso guia sobre como usar FTP para fazer upload de arquivos para o WordPress.

Vamos tentar um exemplo simples de edição do seu arquivo theme.json: criando tamanhos de fonte personalizados.

Novamente, lembre-se que a propriedade settings especifica os estilos padrão do seu tema, enquanto a propriedade styles os implementa. Por esse motivo, editaremos a propriedade settings no arquivo theme.json.

Se você usar um tema filho, poderá simplesmente copiar e colar o seguinte código no seu arquivo theme.json e alterar os tamanhos das fontes em pixels conforme achar melhor:

{
  "settings": {
    "typography": {
      "fluid": false,
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "16px"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "24px"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "40px"
        },
        {
          "name": "Extra Large",
          "slug": "x-lagrge",  // Typo fixed (large -> large)
          "size": "48px"
        }
      ]
    }
  }
}

Observação: Se você estiver editando o arquivo do seu tema pai diretamente, precisará encontrar o código que diz fontSizes.

Ele deve estar aninhado dentro de typography e settings, assim:

{
  "settings": {
    // Some code...
    "typography": {
      // Some code...
      "fontSizes": [
        // Font size definitions here
      ]
    }
  }
}

Depois disso, substitua essas linhas de código pelo snippet de código acima. Apenas certifique-se de que não haja erros de sintaxe nele.

Quando terminar, salve o arquivo e visualize seu site para ver suas alterações. Para usuários do Bluehost, você pode simplesmente clicar em ‘Salvar Alterações’ no editor de código do gerenciador de arquivos.

Se você quiser editar seu theme.json ainda mais, nós o encorajamos fortemente a se familiarizar com a estrutura do arquivo, conforme explicado na seção anterior.

Também sugerimos a leitura da Referência Oficial de Configurações do WordPress, que inclui uma lista completa das propriedades de configurações disponíveis e instruções para usá-las.

Dica Bônus: Use o WPCode para Adicionar Código Personalizado ao Seu Tema

Neste guia, você aprendeu sobre theme.json e seu potencial para personalização de temas. Mas talvez ainda pareça um pouco avassalador editar diretamente.

Felizmente, existe outra opção amigável para adicionar código personalizado e fazer personalizações avançadas: WPCode.

Com o WPCode, você pode inserir trechos de código personalizados sem nunca precisar tocar nos arquivos do seu tema. Isso reduz significativamente o risco de quebrar seu site durante a personalização.

Se você quiser saber mais sobre este plugin de trechos de código, confira nossa análise completa do WPCode.

Além disso, aqui estão alguns tutoriais úteis para você começar a usar o WPCode:

• Trechos de Código WordPress Úteis para Iniciantes (Seleção de Especialistas)
• Como Destacar Novas Publicações para Visitantes Recorrentes no WordPress
• Como Destacar Texto no WordPress
• Como Adicionar Sombra de Caixa Facilmente no WordPress

Esperamos que este artigo tenha ajudado você a aprender sobre o arquivo theme.json no WordPress. Você também pode querer conferir nosso guia para iniciantes sobre como editar um site WordPress e nossa seleção de especialistas dos melhores construtores de página com arrastar e soltar para WordPress.

Se você gostou deste artigo, por favor, inscreva-se em nosso Canal do YouTube para tutoriais em vídeo do WordPress. Você também pode nos encontrar no Twitter e no Facebook.