آشنایی کامل با theme.json در وردپرس: settings، styles و ترتیب اعمال آن‌ها

فایل 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 همه را گمراه می‌کند چون شبیه شمارهٔ نسخهٔ قالب به نظر می‌رسد. نیست. این کلید حالت پردازش را انتخاب می‌کند و نسخه‌های قدیمی‌تر وردپرس، کلیدهای مربوط به اسکیمایی را که نمی‌شناسند بی‌صدا رد می‌کنند. اگر از نصب‌های قدیمی پشتیبانی می‌کنید، همان نسخه‌ای را هدف بگیرید که آن‌ها می‌فهمند و فرض نکنید کلیدهای جدیدتر بی‌دردسر کنار گذاشته می‌شوند. نسخهٔ ۳ در زمان نگارش جاری است؛ نسخهٔ ۲ هنوز روی سایت‌های زیادی فعال و همچنان قابل پردازش است.

مقدار $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"
    }
  }
}

نتیجه، متغیرهایی است که نامشان از مسیر پیش‌تنظیم و نامک ساخته می‌شود:

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

مقدارهای سطح ریشهٔ styles روی 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. Global Styles ذخیره‌شده در پایگاه داده — همان چیزی که پنل Styles در ویرایشگر سایت می‌نویسد.
5. استایل هر بلاک روی خود بلاک — ویژگی‌هایی که در محتوای نوشته ذخیره و به شکل استایل درون‌خطی یا کلاس رندر می‌شوند.

لایهٔ ۴ همان چیزی است که سایت‌ها را خراب می‌کند. لحظه‌ای که کسی پنل Styles را باز کند و ذخیره بزند، وردپرس یک رکورد Global Styles نگه می‌دارد و آن رکورد برای هر ویژگی‌ای که در خود دارد بر فایل شما پیروز می‌شود. ویرایش theme.json بعد از آن، برای همان ویژگی‌ها هیچ تغییر دیدنی‌ای ندارد؛ سایتی که بعد از استقرار دقیقاً همان‌شکل قبل مانده در حالی که فایل روی دیسک آشکارا فرق کرده.

راه‌حل، پاک‌کردن رکورد ذخیره‌شده است، نه بالابردن جنگ با !important. ویرایشگر سایت را باز کنید، به Styles بروید، پنل نسخه‌ها را باز کنید و به پیش‌فرض قالب برگردید. اول با مشتری یا صاحب سایت هماهنگ کنید — این بازنشانی سفارشی‌سازی‌های او را دور می‌ریزد و هزینهٔ واقعی دارد، کار بی‌خطری نیست.

مظنون دوم کش است. وردپرس دادهٔ پردازش‌شدهٔ 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 مهم است: تعیین می‌کند بخش داخل عنصر نشانه‌گذاری هدر یا فوتر پیچیده شود و ویرایشگر آن را در چه دسته‌ای بگذارد. اگر ننویسیدش، بخش بدون دسته‌بندی می‌ماند.

کلید customTemplates همان چیزی است که باعث می‌شود یک قالب در فهرست کشویی قالب‌ها در ویرایشگر نوشته ظاهر شود. بدون این ورودی، فایل وجود دارد اما هیچ‌کس نمی‌تواند انتخابش کند.

یک ترتیب سریع برای عیب‌یابی

وقتی قالب بلاکی آن‌طور که فایل می‌گوید استایل نمی‌گیرد، پیش از دست‌زدن به هر چیزی این مسیر را طی کنید:

1. سورس صفحه را ببینید و دنبال بلاک استایل‌های سراسری تولیدشده بگردید. اگر متغیر شما آنجا نیست، مشکل در settings است یا غلط تایپی در نامک.
2. اگر متغیر هست ولی هیچ‌جا استفاده نشده، مشکل نبودن ورودی در styles است.
3. اگر هر دو هستند ولی چیزی رویشان را می‌پوشاند، دنبال رکورد ذخیره‌شدهٔ Global Styles بگردید.
4. تازه بعد از این‌ها سراغ شیت استایل خودتان، افزونه‌ها یا صفحه‌سازی بروید که CSS را دیرتر در ترتیب لایه‌ها تزریق می‌کند.