شرح ملف theme.json في ووردبريس: الإعدادات والأنماط والتتالي

ملف theme.json هو ملف إعدادات واحد في جذر قالب البلوكات يؤدي وظيفتين منفصلتين: القسم settings يقرر ما الذي يعرضه محرر البلوكات على المستخدم، والقسم styles يقرر كيف يبدو الموقع فعليًا بشكل افتراضي. يحلّله ووردبريس، ويدمجه مع افتراضياته الخاصة ومع كل ما هو محفوظ في محرر الموقع، ثم يُخرج النتيجة على هيئة متغيرات CSS مخصصة مع ورقة أنماط مضمّنة في كل صفحة.

الخلط بين هاتين الوظيفتين هو السبب في أن معظم تعديلات theme.json تبدو وكأنها لا تفعل شيئًا. تعريف لون تحت settings لا يطبّق ذلك اللون في أي مكان، بل ينشئ متغيرًا ومربّع لون في الشريط الجانبي للمحرر فحسب.

المفاتيح العليا

الملف في أبسط صوره يبدو هكذا:

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

المفتاح	وظيفته
$schema	الإكمال التلقائي والتحقق داخل محرر الأكواد فقط. يتجاهله ووردبريس.
version	يخبر ووردبريس أي شكل مخطط يحلّل. ليس رقم إصدار قالبك.
settings	يولّد متغيرات CSS ويتحكم فيما يعرضه المحرر.
styles	يطبّق التنسيق الافتراضي الفعلي.
templateParts	يعرّف الأجزاء الموجودة في parts/ وإلى أي منطقة تنتمي.
customTemplates	يسجّل قوالب الصفحات الموجودة في templates/ لمحرر المقالات.

المفتاح version يوقع الناس في الخطأ لأنه يبدو كرقم إصدار القالب، وهو ليس كذلك. إنه يختار وضع تحليل، والإصدارات الأقدم من ووردبريس تتجاهل بصمت المفاتيح الآتية من شكل مخطط لا تعرفه. إن كنت تدعم تنصيبات قديمة فاستهدف الإصدار الذي تفهمه تلك التنصيبات بدل افتراض أن المفاتيح الأحدث ستتدهور بلطف. الإصدار 3 هو الحالي وقت كتابة هذا الشرح، والإصدار 2 ما زال منتشرًا على نطاق واسع وما زال يُحلَّل.

أما $schema فيشير إلى عنوان مخطط تستضيفه ووردبريس. تثبيته على 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. لاحظ التحويل: مفاتيح camelCase تُفصَل إلى kebab-case، والتداخل يُوصَل بشرطتين مزدوجتين. الخطأ في اسم المتغير سبب شائع لعودة القيمة بصمت إلى الافتراضي.

ويمكنك حصر الإعدادات على بلوك بعينه، وهكذا تسمح بمنتقي ألوان على الأزرار دون الفقرات:

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

الأنماط في المستوى الجذري تنزل على عنصر body. و elements يغطي عناصر HTML الأساسية التي ليست بلوكات — الرابط والزر والعناوين والتسمية التوضيحية. و blocks يستهدف نوع بلوك بعينه بالاسم.

والقيد الذي يجدر قوله بصراحة: styles لا يستطيع التعبير عن كل ما تستطيعه CSS. لا سبيل لكتابة استعلامات وسائط خاصة بك، ولا محدِّدات مركّبة، ولا حركات، ولا سوى مجموعة صغيرة من حالات الأصناف الزائفة المدعومة. الطباعة المرنة والتحجيم المعتمد على التخطيط يغطيان كثيرًا مما كان الناس يستعملون نقاط التوقف من أجله، لكن ليس كله. معظم قوالب البلوكات المنشورة تحمل 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 هي الطبقة التي تطليها أنت قبل وصوله.

التتالي، من الأدنى إلى الأعلى

هذا هو الجزء الذي يفسّر موقعًا «يتجاهل» ملف القالب. يدمج ووردبريس عدة طبقات قبل أن يُخرج CSS:

1. افتراضيات نواة ووردبريس — تشحن النواة ملف theme.json خاصًا بها فيه لوحة ألوان وأحجام خطوط وسلّم تباعد أساسية.
2. ملف theme.json للقالب الأصلي
3. ملف theme.json للقالب الفرعي — يُدمج فوق الأصلي مفتاحًا بمفتاح، لا أن يستبدل الملف كله.
4. الأنماط العامة المحفوظة في قاعدة البيانات — ما تكتبه لوحة الأنماط في محرر الموقع.
5. أنماط البلوكات الفردية — سمات مخزّنة في محتوى المقالة، تُعرض كأنماط مضمّنة أو أصناف.

الطبقة الرابعة هي التي تكسر المواقع. في اللحظة التي يفتح فيها أحدهم لوحة الأنماط ويحفظ، يخزّن ووردبريس سجل أنماط عامة، ويفوز ذلك السجل على ملفك في كل خاصية يحتويها. تعديل theme.json بعد ذلك لا يغيّر شيئًا مرئيًا في تلك الخصائص، فيبدو الموقع كما هو تمامًا بعد النشر بينما الملف على القرص مختلف بوضوح.

والحل هو مسح السجل المحفوظ، لا التصعيد بـ !important. افتح محرر الموقع، وانتقل إلى الأنماط، وافتح لوحة المراجعات، وأعد الضبط إلى افتراضيات القالب. تأكّد أولًا من العميل أو صاحب الموقع — فإعادة الضبط تتخلّص من تخصيصاته، وهذه كلفة حقيقية لا إجراء مجاني.

والمتهم الثاني هو التخزين المؤقت. يخزّن ووردبريس بيانات theme.json المحلَّلة بدل إعادة قراءة الملف مع كل طلب، وهو تمامًا ما تريده في الإنتاج وتمامًا ما لا تريده أثناء التطوير. تفعيل WP_DEBUG، أو إعداد وضع تطوير القالب في الإصدارات الأحدث، يجعل ووردبريس يعيد قراءة الملف في كل مرة. فإن كانت تعديلاتك لا تظهر إلا بعد نشر أو مسح للتخزين المؤقت، فهذا ما تراه.

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 مهمة: هي التي تقرر ما إذا كان الجزء سيُغلَّف بعنصر معلَم header أو footer، وكيف يصنّفه المحرر. اتركها فيُعامَل الجزء على أنه غير مصنّف.

أما customTemplates فهو ما يجعل القالب يظهر في قائمة القوالب المنسدلة داخل محرر المقالات. وبدون هذا التسجيل يبقى الملف موجودًا لكن لا يستطيع أحد اختياره.

ترتيب تشخيصي سريع

حين لا ينسّق قالب بلوكات كما يقول الملف إنه ينبغي، امشِ في هذا الترتيب قبل أن تلمس أي شيء:

1. اعرض مصدر الصفحة وابحث عن كتلة الأنماط العامة المولَّدة. إن لم يكن متغيرك موجودًا فيها، فالمشكلة في settings أو خطأ مطبعي في الـ slug.
2. إن كان المتغير موجودًا لكنه غير مستخدَم، فالمشكلة إدخال ناقص في styles.
3. إن كان كلاهما موجودًا لكن شيئًا ما يتجاوزهما، فابحث عن سجل أنماط عامة محفوظ.
4. وعندئذٍ فقط انظر في ورقة أنماطك أنت، أو في الإضافات، أو في منشئ صفحات يحقن CSS في موضع لاحق من التتالي.