Paliwanag sa WordPress theme.json: Settings, Styles at ang Cascade

Ang theme.json ay iisang configuration file sa ugat ng isang block theme na may dalawang magkahiwalay na trabaho: ang settings ang nagpapasya kung ano ang inaalok ng block editor sa user, at ang styles ang nagpapasya kung ano talaga ang itsura ng site bilang default. Pina-parse ito ng WordPress, pinagsasama sa sarili nitong defaults at sa anumang naka-save sa Site Editor, at inilalabas ang resulta bilang CSS custom properties kasama ang inline stylesheet sa bawat pahina.

Ang paghahalo sa dalawang trabahong iyon ang dahilan kung bakit parang walang epekto ang karamihan ng pagbabago sa theme.json. Ang pagdedeklara ng kulay sa ilalim ng settings ay hindi naglalagay ng kulay na iyon kahit saan. Gumagawa lang ito ng variable at ng swatch sa sidebar ng editor.

Ang mga top-level key

Ganito ang hitsura ng pinakasimpleng file:

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

Key	Ano ang ginagawa
$schema	Para lang sa autocomplete at validation sa code editor. Binabalewala ito ng WordPress.
version	Sinasabi sa WordPress kung anong hugis ng schema ang pa-parse-in. Hindi ito bersyon ng tema mo.
settings	Gumagawa ng CSS variables at nagtatakda kung ano ang ipinapakita ng editor.
styles	Naglalagay ng tunay na default na estilo.
templateParts	Nagdedeklara ng mga part sa parts/ at kung saang area sila kabilang.
customTemplates	Nagrerehistro ng page templates sa templates/ para sa post editor.

Nalilito ang marami sa version dahil mukha itong bersyon ng tema. Hindi ito iyon. Pumipili ito ng parsing mode, at tahimik lang na binabalewala ng mas lumang WordPress ang mga key mula sa hugis ng schema na hindi nito kilala. Kung sinusuportahan mo ang lumang installs, i-target ang bersyong naiintindihan ng mga iyon sa halip na umasang maayos na hahantong ang mas bagong mga key. Ang version 3 ang kasalukuyan habang isinusulat ito; malawak pa ring ginagamit at nababasa ang version 2.

Ang $schema ay tumuturo sa isang schema URL na naka-host sa WordPress. Kapag naka-pin sa trunk, makukuha mo ang pinakabagong hints sa code editor mo; mas ligtas ang URL na tiyak ang bersyon kung sadyang nananatili ka sa mas lumang schema.

settings: kung ano ang inaalok ng editor

Lahat ng nasa ilalim ng settings ay gumagawa ng CSS custom property at, kadalasan, ng kontrol sa editor. Walang nasa ilalim ng settings ang nag-eestilo ng kahit ano.

{
  "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"
    }
  }
}

Gumagawa iyan ng mga variable na pinangalanan mula sa preset path at slug:

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

Gumagawa rin ito ng utility classes gaya ng .has-brand-color at .has-brand-background-color, at iyan ang paraan kung paano inilalapat ng editor ang piniling swatch sa isang block.

Ang linyang "custom": false ang kabilang mukha ng settings: ang pag-off ng mga opsyon. Ilagay mo ito at mawawala ang basta-bastang color picker, kaya ang palette mo na lang ang maiiwan sa user. Gumagana ang parehong patakaran sa lahat ng bahagi — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border, at iba pa. Walang nasa ilalim ng settings ang pampaganda lang; bawat key ay nagdadagdag ng variable, nagdadagdag ng kontrol, o nag-aalis ng kontrol.

Ang settings.custom ay malayang lalagyan para sa sarili mong mga variable:

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

Nagiging --wp--custom--line-height--body at --wp--custom--shadow--card ang mga iyon. Pansinin ang pagbabago: hinahati ang camelCase na key papuntang kebab-case, at pinagdurugtong ang nesting gamit ang dalawang gitling. Ang maling pangalan ng variable ay karaniwang dahilan kung bakit tahimik na bumabalik sa fallback ang isang halaga.

Pwede mong i-scope ang settings kada block, at ganito mo papayagan ang color picker sa mga button pero hindi sa mga talata:

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

styles: kung ano talaga ang lumalabas

Sa styles inilalapat ang mga halaga. Sinasalamin nito ang istruktura ng editor: may root level, tapos elements, tapos 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)" } }
      }
    }
  }
}

Ang styles sa root level ay dumadapo sa body. Ang elements ang sumasakop sa mga HTML primitive na hindi block — link, button, headings, caption. Ang blocks ang tumutumbok sa isang tiyak na uri ng block ayon sa pangalan.

Ang tapat na limitasyon: hindi kayang ipahayag ng styles ang lahat ng kayang gawin ng CSS. Walang paraan para sumulat ka ng sarili mong media queries, walang komplikadong selector, walang animation, at kakaunti lang ang sinusuportahang pseudo-class states. Malaki ang nasasakop ng fluid typography at layout-based na sizing sa mga dating ginagawa ng breakpoints, pero hindi lahat. Karamihan sa mga block theme na ipinapadala ay may theme.json kasama ang katamtamang stylesheet, at normal iyon, hindi kabiguan.

Ang bitag ng settings kontra styles

Ang pinakakaraniwang tanong sa suporta ay may bersyong ganito: dinagdag ko na ang brand color ko pero walang nagbago.

Tama. Ang pagdagdag nito sa settings.color.palette ay gumawa ng --wp--preset--color--brand at ng swatch. Wala itong inilapat. Para gawin itong default na kulay ng link, kailangan mo rin itong isulat sa ilalim ng styles:

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

Isipin mo ito nang ganito: ang settings ang lata ng pinturang iniaabot mo sa user, at ang styles ang unang patong na inilalagay mo bago pa sila dumating.

Ang cascade, mula pinakamababa hanggang pinakamataas

Ito ang bahaging nagpapaliwanag kung bakit parang binabalewala ng site ang theme file. Pinagsasama ng WordPress ang ilang layer bago maglabas ng CSS:

1. Defaults ng WordPress core — may sariling theme.json ang core na may pangunahing palette, font sizes at spacing scale.
2. theme.json ng parent theme
3. theme.json ng child theme — isinasama sa parent kada key, hindi pinapalitan ang buong file.
4. Global Styles na naka-save sa database — ang isinusulat ng Styles panel ng Site Editor.
5. Per-block styles sa mga indibidwal na block — mga attribute na nakaimbak sa nilalaman ng post, lumalabas bilang inline styles o klase.

Ang layer 4 ang sumisira sa mga site. Sa sandaling may magbukas ng Styles panel at mag-save, mag-iimbak ang WordPress ng Global Styles record at ang record na iyon ang mananaig laban sa file mo para sa bawat property na nakapaloob dito. Ang pag-edit ng theme.json pagkatapos noon ay walang makikitang epekto sa mga property na iyon, kaya pareho pa rin ang itsura ng site pagkatapos ng deploy kahit halatang iba na ang file sa disk.

Ang solusyon ay burahin ang naka-save na record, hindi ang mag-igting gamit ang !important. Buksan ang Site Editor, pumunta sa Styles, buksan ang revisions panel, at ibalik sa mga default ng tema. Magtanong muna sa kliyente o may-ari ng site — ang pag-reset ay tumatapon sa mga kustomisasyon nila, at totoong gastos iyon, hindi libreng hakbang.

Ang pangalawang hinihinala ay ang caching. Kina-cache ng WordPress ang na-parse na theme.json data sa halip na basahing muli ang file sa bawat request, at iyon mismo ang gusto mo sa produksyon at iyon mismo ang ayaw mo habang nagde-develop. Ang pag-enable ng WP_DEBUG, o ng theme development mode setting sa mas bagong release, ang nagsasanhi sa WordPress na basahing muli ang file sa bawat pagkakataon. Kung lumalabas lang ang mga binago mo pagkatapos ng deploy o pagkatapos ng cache flush, iyan ang nangyayari.

templateParts at customTemplates

Pareho silang array na naglalarawan ng mga file na nasa tema mo na.

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

Ang name ay tumutugma sa pangalan ng file nang walang extension — parts/header.html, templates/page-wide.html. Mahalaga ang halaga ng area: dito nakadepende kung ibabalot ba ang part sa header o footer na landmark element at kung paano ito ikakategorya ng editor. Kapag inalis mo ito, ituturing na walang kategorya ang part.

Ang customTemplates ang nagpapalabas ng template sa template dropdown sa post editor. Kung wala ang entry, umiiral ang file pero walang makakapili nito.

Mabilisang pagkakasunod-sunod ng pagsusuri

Kapag hindi umaayon ang block theme sa sinasabi ng file, dumaan ka rito bago ka humipo ng kahit ano:

1. Tingnan ang source at hanapin ang nabuong global styles block. Kung wala roon ang variable mo, nasa settings ang problema o may maling baybay sa slug.
2. Kung nariyan ang variable pero hindi ginagamit, kulang ang entry sa styles.
3. Kung nariyan pareho pero may nag-o-override, tingnan kung may naka-save na Global Styles record.
4. Saka mo lang tingnan ang sarili mong stylesheet, ang mga plugin, o ang page builder na nag-i-inject ng CSS nang mas huli sa cascade.