theme.json în WordPress: settings, styles și cascada

theme.json este un singur fișier de configurare aflat în rădăcina unei teme bloc și face două treburi separate: settings decide ce oferă editorul de blocuri utilizatorilor, iar styles decide cum arată efectiv site-ul în mod implicit. WordPress îl parsează, îl combină cu propriile valori implicite și cu tot ce a fost salvat în Editorul de site, apoi scoate rezultatul sub formă de proprietăți CSS personalizate plus o foaie de stil inline pe fiecare pagină.

Confuzia dintre aceste două roluri este motivul pentru care majoritatea modificărilor din theme.json par să nu facă nimic. Declararea unei culori sub settings nu aplică acea culoare nicăieri. Creează doar o variabilă și un eșantion de culoare în bara laterală a editorului.

Cheile de nivel superior

Un fișier minimal arată așa:

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

Cheie	Ce face
$schema	Doar autocompletare și validare în editorul de cod. WordPress o ignoră.
version	Îi spune WordPress-ului ce formă de schemă să parseze. Nu este versiunea temei tale.
settings	Generează variabile CSS și controlează ce expune editorul.
styles	Aplică efectiv stilizarea implicită.
templateParts	Declară părțile din parts/ și zona căreia îi aparțin.
customTemplates	Înregistrează șabloanele de pagină din templates/ pentru editorul de articole.

version încurcă lumea pentru că seamănă cu numărul de versiune al temei. Nu este. Selectează un mod de parsare, iar versiunile mai vechi de WordPress ignoră în tăcere cheile dintr-o formă de schemă pe care nu o cunosc. Dacă susții instalări vechi, țintește versiunea pe care o înțeleg acelea, în loc să presupui că noile chei se degradează elegant. Versiunea 3 este cea curentă la momentul scrierii; versiunea 2 este încă răspândită și încă parsată.

$schema indică spre o adresă de schemă găzduită de WordPress. Fixarea pe trunk îți dă cele mai noi sugestii în editorul de cod; o adresă specifică unei versiuni este mai sigură dacă rămâi intenționat pe o schemă mai veche.

settings: ce oferă editorul

Tot ce se află sub settings produce o proprietate CSS personalizată și, în majoritatea cazurilor, un control în editor. Nimic din settings nu stilizează nimic.

{
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand", "color": "#1f4ed8", "name": "Brand" },
        { "slug": "ink", "color": "#111827", "name": "Ink" }
      ],
      "custom": false
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    },
    "layout": {
      "contentSize": "680px",
      "wideSize": "1200px"
    }
  }
}

Asta produce variabile denumite după calea presetării și după slug:

--wp--preset--color--brand
--wp--preset--color--ink
--wp--preset--font-size--small
--wp--preset--font-size--large

Produce și clase utilitare precum .has-brand-color și .has-brand-background-color, prin care editorul aplică unui bloc culoarea aleasă.

Linia "custom": false este cealaltă jumătate a lui settings: dezactivarea opțiunilor. O setezi și selectorul de culoare liberă dispare, lăsându-le utilizatorilor paleta ta și nimic altceva. Același tipar funcționează peste tot — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border și așa mai departe. Nimic din settings nu este decorativ; fiecare cheie fie adaugă o variabilă, fie adaugă un control, fie elimină un control.

settings.custom este un spațiu liber pentru propriile tale variabile:

{
  "settings": {
    "custom": {
      "lineHeight": { "body": 1.6 },
      "shadow": { "card": "0 1px 3px rgba(0,0,0,0.12)" }
    }
  }
}

Acestea devin --wp--custom--line-height--body și --wp--custom--shadow--card. Observă transformarea: cheile scrise camelCase sunt sparte în kebab-case, iar nivelurile de imbricare sunt unite cu două liniuțe. Un nume de variabilă greșit este un motiv frecvent pentru care o valoare cade în tăcere pe fallback.

Poți limita setările la nivel de bloc, așa permiți un selector de culoare pe butoane, dar nu și pe paragrafe:

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": { "custom": false, "customGradient": false }
      }
    }
  }
}

styles: ce se randează efectiv

styles este locul unde valorile chiar se aplică. Oglindește structura editorului: un nivel rădăcină, apoi elements, apoi blocks.

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--ink)"
    },
    "typography": {
      "lineHeight": "var(--wp--custom--line-height--body)"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--brand)" },
        ":hover": { "typography": { "textDecoration": "none" } }
      }
    },
    "blocks": {
      "core/quote": {
        "typography": { "fontStyle": "italic" },
        "spacing": { "padding": { "left": "var(--wp--preset--spacing--40)" } }
      }
    }
  }
}

Regulile styles de la rădăcină ajung pe body. elements acoperă primitivele HTML care nu sunt blocuri — link, buton, titluri, legendă de imagine. blocks țintește un anumit tip de bloc, după nume.

Limita, spusă cinstit: styles nu poate exprima tot ce poate CSS-ul. Nu ai cum să-ți scrii propriile media query-uri, nu ai selectori compuși, nu ai animații și ai doar un set mic de stări de pseudo-clasă suportate. Tipografia fluidă și dimensionarea bazată pe layout acoperă mult din ce se făcea înainte cu breakpoint-uri, dar nu tot. Majoritatea temelor bloc livrate au theme.json plus o foaie de stil modestă, iar asta este un rezultat normal, nu un eșec.

Capcana settings versus styles

Cea mai frecventă întrebare de suport este o variantă a lui „am adăugat culoarea brandului și nu s-a schimbat nimic”.

Corect. Adăugarea ei în settings.color.palette a creat --wp--preset--color--brand și un eșantion de culoare. Nu a aplicat nimic. Ca să devină culoarea implicită a linkurilor, trebuie să o scrii și sub styles:

{
  "settings": {
    "color": {
      "palette": [{ "slug": "brand", "color": "#1f4ed8", "name": "Brand" }]
    }
  },
  "styles": {
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--brand)" } }
    }
  }
}

Citește-o așa: settings este cutia de vopsea pe care i-o dai utilizatorului, styles este stratul pe care îl aplici tu înainte să vină el.

Cascada, de jos în sus

Aici se explică un site care „ignoră” fișierul temei. WordPress combină mai multe straturi înainte să emită CSS:

1. Valorile implicite din nucleul WordPress — nucleul livrează propriul theme.json, cu o paletă de bază, dimensiuni de font și o scară de spațiere.
2. theme.json al temei părinte
3. theme.json al temei child — combinat peste cel al părintelui cheie cu cheie, nu înlocuind tot fișierul.
4. Stilurile globale salvate în baza de date — ce scrie panoul Styles din Editorul de site.
5. Stilurile per bloc, pe blocuri individuale — atribute stocate în conținutul articolului, randate ca stiluri inline sau clase.

Stratul 4 este cel care strică site-uri. În clipa în care cineva deschide panoul Styles și salvează, WordPress stochează o înregistrare de Stiluri globale, iar acea înregistrare câștigă în fața fișierului tău pentru fiecare proprietate pe care o conține. Editarea ulterioară a lui theme.json nu schimbă nimic vizibil pentru acele proprietăți, pe un site care arată identic după deploy, deși fișierul de pe disc este evident diferit.

Soluția este să ștergi înregistrarea salvată, nu să escaladezi cu !important. Deschide Editorul de site, mergi la Styles, deschide panoul de revizii și revino la valorile implicite ale temei. Confirmă întâi cu clientul sau cu proprietarul site-ului — resetarea aruncă personalizările lui, ceea ce este un cost real, nu o acțiune gratuită.

Al doilea suspect este cache-ul. WordPress ține în cache datele parsate din theme.json în loc să recitească fișierul la fiecare cerere, ceea ce este exact ce vrei în producție și exact ce nu vrei în timpul dezvoltării. Activarea lui WP_DEBUG sau a setării de mod dezvoltare a temei, pe versiunile mai noi, face WordPress-ul să recitească fișierul de fiecare dată. Dacă modificările tale apar doar după un deploy sau după golirea cache-ului, exact asta vezi.

templateParts și customTemplates

Ambele sunt liste care descriu fișiere deja existente în tema ta.

{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ],
  "customTemplates": [
    { "name": "page-wide", "title": "Wide Page", "postTypes": ["page"] }
  ]
}

name corespunde numelui fișierului fără extensie — parts/header.html, templates/page-wide.html. Valoarea area contează: decide dacă partea este învelită într-un element de tip landmark header sau footer și cum o categorisește editorul. Dacă o omiți, partea este tratată ca necategorisită.

customTemplates este ceea ce face ca un șablon să apară în lista derulantă de șabloane din editorul de articole. Fără această intrare, fișierul există, dar nimeni nu îl poate selecta.

O ordine rapidă de diagnostic

Când o temă bloc nu stilizează așa cum spune fișierul, parcurge lista asta înainte să umbli la orice:

1. Deschide sursa paginii și caută blocul de stiluri globale generat. Dacă variabila ta nu este acolo, problema este în settings sau ai o greșeală de scriere în slug.
2. Dacă variabila există, dar nu este folosită nicăieri, problema este o intrare lipsă în styles.
3. Dacă ambele există, dar ceva le suprascrie, caută o înregistrare salvată de Stiluri globale.
4. Abia apoi uită-te la propria foaie de stil, la pluginuri sau la un page builder care injectează CSS mai târziu în cascadă.