theme.json چطور تنظیمات ظاهری قالب را یکپارچه می‌کند؟

در وردپرس مدرن، theme.json لایه اصلی تنظیمات ظاهری قالب است که رنگ، تایپوگرافی، spacing و تنظیمات بلوک را در یک منبع واحد مدیریت می‌کند و پایه معماری قالب‌های بلاکی محسوب می‌شود. بدون نسخه‌بندی صحیح و بدون سازگاری با نسخه هسته، هر theme.json در اولین به‌روزرسانی وردپرس ممکن است رفتار غیرمنتظره نشان دهد. تنظیمات سطح بلوک در theme.json، جایگزین مستقیم Customizer سنتی نیست بلکه یک لایه بالاتر و سراسری است که پایه Design Token را در قالب پیاده می‌کند. تست theme.json در سه سطح اعتبارسنجی ساختار، رفتار ادیتور و رفتار فرانت‌اند انجام می‌شود و بدون آن، انتشار به تولید ریسک بالایی دارد. در این راهنما از ساختار پایه تا استقرار تولیدی theme.json را با نگاه مهندسی و کد عملی پوشش می‌دهیم.

در پروژه‌های واقعی، بیشترین خطا در theme.json مربوط به نبود version است. وقتی این پارامتر مشخص نمی‌شود، وردپرس رفتار پیش‌فرض نسخه قدیمی را اعمال می‌کند و بخشی از تنظیمات جدید نادیده گرفته می‌شود. این راهنما از همان نقطه‌ای شروع می‌کند که در کار حرفه‌ای بیشترین ارزش را ایجاد کرده است.

theme.json چیست و چرا در قالب مدرن ضروری است؟

theme.json یک فایل پیکربندی مبتنی بر JSON است که در ریشه قالب قرار می‌گیرد و تنظیمات سراسری ظاهری سایت را تعریف می‌کند. این فایل، منبع اصلی Design Token در قالب بلاکی است و تنظیمات رنگ، تایپوگرافی، spacing و layout را در یک نقطه متمرکز می‌کند.

پیش از ادامه، راهنمای Block Theme و قالب بلوکی حرفه‌ای را مطالعه کنید. اگر با ساختار کلی قالب آشنایی ندارید، راهنمای ساختار فایل‌های قالب استاندارد وردپرس نقطه شروع مناسبی است.

جایگاه theme.json در معماری قالب بلاکی

theme.json یک لایه بالاتر از CSS و یک لایه پایین‌تر از تنظیمات کاربر است. ترتیب اعمال تنظیمات از theme.json به استایل قالب و سپس به تنظیمات کاربر در Global Styles است. آشنایی با این ترتیب، برای دیباگ رفتار ظاهری سایت ضروری است.

ساختار استاندارد theme.json

ساختار پایه theme.json شامل سه کلید اصلی است: version، settings و styles. بخش settings کنترل می‌کند چه چیزی در ادیتور قابل تغییر است و بخش styles مقدار پیش‌فرض ظاهری را تعیین می‌کند.

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "settings": {
        "appearanceTools": true
    },
    "styles": {
        "color": {
            "background": "#ffffff",
            "text": "#1f1f1f"
        }
    }
}

پارامتر $schema اختیاری است اما توصیه می‌شود، چون ویرایشگرهای مدرن از آن برای Autocomplete و اعتبارسنجی استفاده می‌کنند.

نقش appearanceTools در تنظیمات

کلید appearanceTools به‌صورت پیش‌فرض مجموعه‌ای از Block Supports مثل border، spacing و typography را فعال می‌کند. اگر این کلید را true کنید، کنترل بیشتری در ادیتور برای کاربر فراهم می‌شود.

بخش settings و کنترل تنظیمات

در بخش settings، تعریف می‌کنید چه تنظیماتی در ادیتور نمایش داده شوند. مثال‌ها شامل color، typography، spacing، layout، border، shadow و blocks است.

"settings": {
    "color": {
        "custom": false,
        "customDuotone": false,
        "palette": [ /* ... */ ]
    },
    "typography": {
        "fontFamilies": [ /* ... */ ],
        "fontSizes": [ /* ... */ ]
    },
    "spacing": {
        "units": [ "px", "rem", "%" ]
    }
}

الگوی حرفه‌ای این است که بخش settings را حداقلی نگه دارید تا ادیتور شلوغ نشود و در عین حال، اختیار کافی برای تیم محتوا باقی بماند.

کنترل Custom Color در ادیتور

اگر می‌خواهید کاربر فقط از پالت تعریف‌شده استفاده کند، مقدار custom را false بگذارید. این کار، یکنواختی ظاهری سایت را تضمین می‌کند.

بخش styles و استایل سراسری

در بخش styles، مقدار پیش‌فرض رنگ، تایپوگرافی و فاصله‌ها را تعریف می‌کنید. این تنظیمات در سطح سراسری اعمال می‌شوند و برای همه بلوک‌ها قابل ارث‌بری هستند.

"styles": {
    "color": {
        "background": "var(--wp--preset--color--base)",
        "text": "var(--wp--preset--color--contrast)"
    },
    "typography": {
        "fontSize": "var(--wp--preset--font-size--medium)",
        "lineHeight": 1.7
    },
    "spacing": {
        "blockGap": "1.5rem",
        "padding": {
            "top": "0", "bottom": "0",
            "left": "1rem", "right": "1rem"
        }
    }
}

استفاده از متغیرهای CSS تولیدشده توسط وردپرس، توصیه اصلی است چون نگهداشت را ساده می‌کند.

انتقال تنظیمات از Customizer به theme.json

در قالب‌های بلاکی، بخشی از تنظیمات Customizer به theme.json منتقل می‌شود. راهنمای Theme Customizer و تنظیمات زنده قالب برای درک این انتقال ضروری است.

پالت رنگ در theme.json

پالت رنگ در theme.json با ساختار slug/color/name تعریف می‌شود و به‌صورت خودکار به متغیر CSS تبدیل می‌شود.

"palette": [
    { "slug": "base", "color": "#ffffff", "name": "سفید پایه" },
    { "slug": "contrast", "color": "#1f1f1f", "name": "مشکی کنتراست" },
    { "slug": "primary", "color": "#0073aa", "name": "رنگ اصلی" },
    { "slug": "accent", "color": "#ff6b35", "name": "رنگ تأکید" }
]

این پالت در قالب‌های بلاکی به‌صورت --wp--preset--color--{slug} در دسترس است.

پالت اختصاصی برای هر بلوک

می‌توانید برای یک بلوک خاص، پالت اختصاصی تعریف کنید. این قابلیت، انعطاف بالایی برای کنترل تجربه کاربری فراهم می‌کند.

تایپوگرافی و فونت در theme.json

تایپوگرافی در theme.json شامل fontFamilies، fontSizes و fluid typography است.

"typography": {
    "fontFamilies": [
        {
            "slug": "primary",
            "name": "فونت اصلی",
            "fontFamily": "Vazirmatn, sans-serif",
            "fontFace": [
                {
                    "fontFamily": "Vazirmatn",
                    "fontWeight": "400",
                    "fontStyle": "normal",
                    "src": [ "file:./assets/fonts/Vazirmatn-Regular.woff2" ]
                }
            ]
        }
    ],
    "fontSizes": [
        { "slug": "small",  "size": "0.875rem", "name": "کوچک" },
        { "slug": "medium", "size": "1rem",     "name": "متوسط" },
        { "slug": "large",  "size": "1.5rem",   "name": "بزرگ" }
    ]
}

ترکیب fontFace و fontSizes، مدیریت فونت را در قالب بلاکی یکپارچه می‌کند و از بارگذاری غیرضروری جلوگیری می‌نماید.

Fluid Typography در theme.json

با تعریف fluid: true برای fontSizes، اندازه فونت به‌صورت خودکار با viewport تغییر می‌کند. این قابلیت، تجربه ریسپانسیو را به‌شدت بهبود می‌دهد.

Spacing و Layout در theme.json

بخش spacing در theme.json، واحدها و مقیاس فاصله‌ها را تعریف می‌کند. بخش layout نیز عرض محتوا و ساختار کلی را تنظیم می‌کند.

"spacing": {
    "units": [ "px", "rem", "em", "%", "vw" ],
    "spacingSizes": [
        { "slug": "20", "size": "0.5rem", "name": "XS" },
        { "slug": "40", "size": "1rem",   "name": "S"  },
        { "slug": "60", "size": "1.5rem", "name": "M"  }
    ]
},
"layout": {
    "contentSize": "740px",
    "wideSize":    "1180px"
}

این تنظیمات، ساختار کلی صفحات را در سطح سراسری کنترل می‌کند و از تنوع بی‌دلیل عرض محتوا جلوگیری می‌نماید.

Layout در سطح بلوک

برای بلوک‌های خاص مثل Group، می‌توانید Layout اختصاصی تعریف کنید. این قابلیت در قالب‌های حرفه‌ای بسیار کاربرد دارد.

تنظیمات سطح بلوک

در theme.json می‌توانید تنظیمات و استایل هر بلوک را به‌صورت اختصاصی تعریف کنید.

"styles": {
    "blocks": {
        "core/button": {
            "color": { "background": "var(--wp--preset--color--primary)" },
            "spacing": { "padding": { "top": "0.75rem", "bottom": "0.75rem" } },
            "border": { "radius": "6px" }
        }
    }
}

الگوی حرفه‌ای این است که استایل بلوک را در theme.json نگه دارید و از CSS اختصاصی فقط برای موارد پیچیده استفاده کنید. راهنمای Block Customizer و تنظیمات بلوکی نقطه شروع مناسبی است.

ساخت بلوک سفارشی و theme.json

بلوک سفارشی می‌تواند از تنظیمات theme.json ارث‌بری کند. راهنمای ساخت بلاک سفارشی گوتنبرگ را ببینید.

نسخه‌بندی و سازگاری theme.json

پارامتر version در theme.json تعیین می‌کند کدام نسخه از API اعمال شود. نسخه‌های مهم عبارت‌اند از 1، 2 و 3. نسخه 3 آخرین نسخه پایدار است و از ویژگی‌هایی مثل Style Variations پشتیبانی می‌کند.

اگر version را حذف کنید، وردپرس رفتار پیش‌فرض نسخه 1 را اعمال می‌کند که بسیاری از تنظیمات مدرن را نادیده می‌گیرد.

سازگاری با نسخه هسته وردپرس

هر نسخه از theme.json نیازمند حداقل نسخه‌ای از وردپرس است. در مستندات وردپرس، نسخه‌های سازگار مشخص شده‌اند و توصیه می‌شود قالب، حداقل نسخه وردپرس را در style.css مشخص کند.

تست و دیباگ theme.json

تست theme.json در سه سطح انجام می‌شود: سطح اعتبارسنجی ساختار، سطح رفتار ادیتور و سطح رفتار فرانت‌اند. برای اعتبارسنجی ساختار، از Schema JSON استفاده کنید. برای تست رفتار، از Playwright یا بازبینی دستی.

add_action( "admin_notices", function() {
    $theme_json = wp_get_global_settings();
    if ( defined( "WP_DEBUG" ) && WP_DEBUG ) {
        error_log( "theme.json version: " . wp_get_global_settings()["version"] );
    }
} );

برای تست خودکار، راهنمای تست E2E وردپرس با Playwright را ببینید.

اشتباهات رایج در تست theme.json

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

امنیت و Escape در theme.json

theme.json فقط تنظیمات را نگه می‌دارد، اما اگر از آن برای تعریف استایل پویا استفاده کنید، باید داده‌ها Escape شوند. برای متن از esc_html، برای URL از esc_url و برای Attributes از esc_attr استفاده کنید.

برای مطالعه بیشتر، راهنمای Escape کردن خروجی برای جلوگیری از XSS را ببینید. همچنین مفهوم JSON را در ویکی‌پدیا مرور کنید.

دسترسی‌پذیری و theme.json

theme.json می‌تواند کنتراست رنگ و اندازه فونت را در سطح سراسری کنترل کند. این قابلیت، دسترسی‌پذیری قالب را تقویت می‌کند. راهنمای کنتراست رنگ در وردپرس را ببینید.

پرسش‌های پرتکرار درباره theme.json

آیا theme.json در قالب کلاسیک هم کار می‌کند؟

بله، اما بخشی از قابلیت‌های آن فقط در قالب بلاکی فعال می‌شود.

تفاوت theme.json و style.css چیست؟

theme.json تنظیمات سراسری و Design Token را نگه می‌دارد، style.css برای استایل‌های اختصاصی است.

آیا می‌توان theme.json را در قالب فرزند override کرد؟

بله، theme.json قالب فرزند با والد ادغام می‌شود. راهنمای Child Theme حرفه‌ای را ببینید.

آیا theme.json روی سرعت سایت اثر دارد؟

خیر، در واقع با جلوگیری از بارگذاری CSS اضافی، سرعت را بهبود می‌دهد. راهنمای Object Cache در وردپرس را ببینید.

چرا تنظیمات theme.json من در ادیتور نمایش داده نمی‌شود؟

احتمالاً version نامعتبر است یا کلیدهای settings به‌درستی تعریف نشده‌اند.

آیا می‌توان theme.json را با Customizer ترکیب کرد؟

بله، اما توصیه می‌شود در قالب بلاکی، theme.json منبع اصلی باشد.

نتیجه و مسیر ادامه

theme.json لایه اصلی تنظیمات ظاهری قالب مدرن است. کلید موفقیت، ساختار درست settings و styles، نسخه‌بندی صحیح، سازگاری با نسخه هسته و تست در سه سطح است. اگر این لایه با دقت طراحی شود، قالب در طول به‌روزرسانی‌ها پایدار می‌ماند.

پیشنهاد می‌کنم مسیر یادگیری را با Block Theme و قالب بلوکی حرفه‌ای ادامه دهید و سپس Full Site Editing و ویرایش کامل سایت را به‌عنوان رویکرد جامع مطالعه کنید.

اگر روی پروژه واقعی خود theme.json پیاده کرده‌اید، برایم جالب است بدانید کدام بخش — پالت رنگ یا تنظیمات سطح بلوک — بیشترین چالش را ایجاد کرده است. تجربه خودتان را در دیدگاه‌ها بنویسید.