theme.json בוורדפרס: הסבר על settings, styles וסדר העדיפויות

theme.json הוא קובץ הגדרות יחיד בשורש של ערכת בלוקים שעושה שתי עבודות נפרדות: settings קובע מה עורך הבלוקים מציע למשתמשים, ו-styles קובע איך האתר באמת נראה כברירת מחדל. WordPress מפענח אותו, ממזג אותו עם ברירות המחדל שלו ועם כל מה שנשמר בעורך האתר, ופולט את התוצאה כמשתני CSS ועוד גיליון סגנונות מוטמע בכל עמוד.

הבלבול בין שתי העבודות האלה הוא הסיבה לכך שרוב השינויים ב-theme.json נראים כאילו הם לא עושים כלום. הצהרה על צבע תחת settings לא מחילה את הצבע הזה בשום מקום. היא רק יוצרת משתנה ודגימת צבע בסרגל הצד של העורך.

המפתחות ברמה העליונה

קובץ מינימלי נראה כך:

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

מפתח	מה הוא עושה
$schema	השלמה אוטומטית ובדיקת תקינות בעורך הקוד בלבד. WordPress מתעלם ממנו.
version	אומר ל-WordPress איזו צורת סכימה לפענח. זו לא גרסת הערכה שלכם.
settings	מייצר משתני CSS וקובע מה העורך חושף.
styles	מחיל את עיצוב ברירת המחדל בפועל.
templateParts	מצהיר על החלקים שבתיקיית parts/ ועל האזור שאליו הם שייכים.
customTemplates	רושם תבניות עמוד מתוך templates/ עבור עורך התוכן.

version מפיל אנשים כי הוא נראה כמו מספר גרסה של הערכה. הוא לא. הוא בוחר מצב פענוח, וגרסאות ישנות של WordPress מתעלמות בשקט ממפתחות של צורת סכימה שהן לא מכירות. אם אתם תומכים בהתקנות ישנות, כוונו לגרסה שההתקנות האלה מבינות במקום להניח שמפתחות חדשים יתנוונו בעדינות. גרסה 3 היא העדכנית בזמן כתיבת השורות האלה; גרסה 2 עדיין נפוצה מאוד ועדיין מפוענחת.

$schema מצביע על כתובת סכימה שמתארחת אצל WordPress. הצמדה ל-trunk נותנת לכם את הרמזים העדכניים ביותר בעורך הקוד; כתובת של גרסה ספציפית בטוחה יותר אם אתם נשארים בכוונה על סכימה ישנה.

settings: מה העורך מציע

כל דבר תחת settings מייצר משתנה CSS, וברוב המקרים גם פקד בעורך. שום דבר תחת settings לא מעצב כלום.

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

זה מייצר משתנים ששמם נגזר מנתיב ההגדרה ומה-slug:

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

זה גם מייצר מחלקות שירות כמו .has-brand-color ו-.has-brand-background-color, וכך העורך מחיל על בלוק צבע שנבחר מהדגימות.

השורה "custom": false היא החצי השני של settings: כיבוי אפשרויות. מגדירים אותה ובוחר הצבעים החופשי נעלם, כך שלמשתמשים נשאר לוח הצבעים שלכם ותו לא. אותה תבנית עובדת לרוחב כל הקובץ — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border וכן הלאה. שום דבר תחת settings אינו קישוט; כל מפתח או מוסיף משתנה, או מוסיף פקד, או מסיר פקד.

settings.custom הוא מגירה חופשית למשתנים משלכם:

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

אלה הופכים ל---wp--custom--line-height--body ול---wp--custom--shadow--card. שימו לב להמרה: מפתחות בכתיב גמל מפוצלים לכתיב מקף, וקינון מחובר בשני מקפים. שם משתנה שגוי הוא סיבה נפוצה לכך שערך נופל בשקט לברירת מחדל.

אפשר להגדיר settings ברמת בלוק בודד, וכך מאפשרים בוחר צבעים בכפתורים אבל לא בפסקאות:

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

styles: מה באמת נצבע על המסך

styles הוא המקום שבו ערכים מוחלים בפועל. המבנה שלו משקף את מבנה העורך: רמת שורש, אחריה elements, ואחריה 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)" } }
      }
    }
  }
}

styles ברמת השורש נוחתים על ה-body. elements מכסה רכיבי HTML בסיסיים שאינם בלוקים — קישור, כפתור, כותרות, כיתוב. blocks מכוון לסוג בלוק ספציפי לפי שם.

המגבלה, בכנות: styles לא יכול לבטא כל מה ש-CSS יכול. אין דרך לכתוב media queries משלכם, אין סלקטורים מורכבים, אין אנימציות, ויש רק אוסף קטן של מצבי פסאודו־מחלקה נתמכים. טיפוגרפיה נוזלית וגדלים מבוססי פריסה מכסים חלק גדול ממה שאנשים השתמשו בשבילו בנקודות שבירה, אבל לא את הכול. רוב ערכות הבלוקים שיוצאות לאוויר נושאות theme.json ועוד גיליון סגנונות צנוע, וזו תוצאה נורמלית, לא כישלון.

המלכודת של settings מול styles

שאלת התמיכה הנפוצה ביותר היא גרסה כלשהי של “הוספתי את צבע המותג שלי ושום דבר לא השתנה”.

נכון. ההוספה ל-settings.color.palette יצרה את --wp--preset--color--brand ודגימת צבע. היא לא החילה כלום. כדי שזה יהפוך לצבע ברירת המחדל של קישורים, צריך לכתוב את זה גם תחת styles:

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

תחשבו על זה כך: settings היא קופסת הצבעים שאתם מוסרים למשתמש, ו-styles היא השכבה שאתם צובעים לפני שהוא מגיע.

סדר העדיפויות, מהנמוך לגבוה

זה החלק שמסביר אתר ש”מתעלם” מקובץ הערכה. WordPress ממזג כמה שכבות לפני שהוא פולט CSS:

1. ברירות המחדל של ליבת WordPress — הליבה נשלחת עם theme.json משלה, הכולל לוח צבעים, גדלי גופן וסולם ריווח בסיסיים.
2. theme.json של ערכת האב
3. theme.json של ערכת הבת — ממוזג מעל האב מפתח אחרי מפתח, לא מחליף את כל הקובץ.
4. Global Styles ששמורים בבסיס הנתונים — מה שלשונית הסגנונות בעורך האתר כותבת.
5. עיצוב ברמת בלוק בודד — מאפיינים ששמורים בתוכן הפוסט ומוצגים כסגנון מוטמע או כמחלקות.

שכבה 4 היא זו ששוברת אתרים. ברגע שמישהו פותח את לשונית הסגנונות ושומר, WordPress מאחסן רשומת Global Styles, והרשומה הזו מנצחת את הקובץ שלכם עבור כל מאפיין שהיא מכילה. עריכת theme.json אחרי זה לא משנה שום דבר גלוי במאפיינים האלה — האתר נראה זהה אחרי פריסה, בזמן שהקובץ בדיסק שונה לגמרי.

הפתרון הוא למחוק את הרשומה השמורה, לא להסלים עם !important. פותחים את עורך האתר, נכנסים לסגנונות, פותחים את לוח הגרסאות ומאפסים לברירות המחדל של הערכה. תאמו את זה קודם עם הלקוח או עם בעל האתר — האיפוס מוחק את ההתאמות שלהם, וזה מחיר אמיתי, לא פעולה חינם.

החשוד השני הוא מטמון. WordPress שומר במטמון את נתוני theme.json המפוענחים במקום לקרוא את הקובץ מחדש בכל בקשה, וזה בדיוק מה שרוצים בייצור ובדיוק מה שלא רוצים בזמן פיתוח. הפעלת WP_DEBUG, או הגדרת מצב פיתוח הערכה בגרסאות חדשות יותר, גורמת ל-WordPress לקרוא את הקובץ מחדש בכל פעם. אם השינויים שלכם מופיעים רק אחרי פריסה או ניקוי מטמון, זה מה שאתם רואים.

templateParts ו-customTemplates

שניהם מערכים שמתארים קבצים שכבר יושבים בערכה שלכם.

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

name תואם לשם הקובץ בלי הסיומת — parts/header.html, templates/page-wide.html. הערך של area חשוב: הוא מכריע אם החלק נעטף באלמנט ציון דרך של כותרת עליונה או תחתונה, וכיצד העורך מסווג אותו. אם משמיטים אותו, החלק נחשב לא מסווג.

customTemplates הוא מה שגורם לתבנית להופיע ברשימת התבניות בעורך התוכן. בלי הרשומה הזו הקובץ קיים אבל אף אחד לא יכול לבחור בו.

סדר אבחון מהיר

כשערכת בלוקים לא מעצבת כמו שהקובץ אומר שהיא צריכה, עברו על זה לפני שאתם נוגעים במשהו:

1. הציגו את מקור העמוד וחפשו את בלוק הסגנונות הגלובליים שנוצר. אם המשתנה שלכם לא שם, הבעיה היא ב-settings או בשגיאת כתיב ב-slug.
2. אם המשתנה קיים אבל לא נמצא בשימוש, הבעיה היא רשומת styles חסרה.
3. אם שניהם קיימים ומשהו בכל זאת דורס אותם, בדקו אם יש רשומת Global Styles שמורה.
4. רק אז הסתכלו על גיליון הסגנונות שלכם, על תוספים, או על בונה עמודים שמזריק CSS מאוחר יותר בסדר העדיפויות.