آموزش theme.json وردپرس

فایل theme.json یکی از مهم‌ترین بخش‌های توسعه پوسته‌های مدرن وردپرس است. اگر با پوسته‌های بلوکی، سایت ادیتور یا گوتنبرگ کار می‌کنید، بخش قابل‌توجهی از تنظیماتی که قبلاً بین functions.php، فایل‌های CSS و APIهای مختلف وردپرس پراکنده بودند، حالا می‌توانند از یک فایل مرکزی مدیریت شوند. با فایل theme.json می‌توان مشخص کرد:

• چه ابزارهایی برای کاربر در ادیتور بلوکی فعال باشند،
• پالت رنگ پوسته شامل چه رنگ‌هایی باشد،
• چه اندازه فونت‌هایی در دسترس باشند،
• عرض محتوای اصلی و قالب گسترده چقدر باشد،
• فاصله‌ها، تایپوگرافی، بوردرها و سایه‌ها چگونه مدیریت شوند،
• استایل پیش‌فرض صفحه، عناصر HTML و بلوک‌ها چه باشد،
• تمپلیت‌ها و اجزای تمپلیت‌های اختصاصی پوسته کدام باشند.

این فایل فقط مخصوص پوسته‌های بلوکی (Block Theme) هم نیست؛ وردپرس امکان استفاده از theme.json را در پوسته‌های کلاسیک نیز فراهم کرده است. با این حال در یک پوسته بلوکی، theme.json عملاً یکی از اجزای اصلی معماری پوسته است.

آشنایی با theme.json

فایل theme.json یک فایل تنظیمات JSON است که باید در پوشه اصلی پوسته قرار بگیرد:

my-theme/
├── assets/
├── parts/
├── patterns/
├── styles/
├── templates/
├── functions.php
├── style.css
└── theme.json

وردپرس این فایل را می‌خواند و تنظیمات آن را وارد سیستم Global Settings and Styles می‌کند. برای مثال، به‌جای تعریف یک پالت رنگ در PHP و سپس نوشتن CSS جداگانه برای همان رنگ‌ها، می‌توان آن را در theme.json تعریف کرد. وردپرس هم گزینه‌های مربوط به آن را در ادیتور نمایش می‌دهد و هم Custom Propertyهای موردنیاز را تولید می‌کند. به همین دلیل بهتر است theme.json را صرفاً یک «فایل CSS با سینتکس متفاوت» در نظر نگیریم. این فایل بخشی از قرارداد میان پوسته، هسته وردپرس، ادیتور بلوکی، افزونه‌ها و تنظیمات کاربر است.

theme.json چه مشکلی را حل می‌کند؟

در توسعه سنتی پوسته‌های وردپرس، معمولاً چند سیستم مختلف باید همزمان مدیریت می‌شدند. مثلاً ممکن بود برای اضافه‌کردن قابلیت‌های ادیتور از تابع add_theme_support استفاده کنید، پالت رنگ را در PHP ثبت کنید، استایل‌ها را در style.css قرار دهید و برای هماهنگ کردن محیط ویرایشگر با فرانت‌اند نیز CSS دیگری بنویسید.

theme.json بخش بزرگی از این تنظیمات را یکپارچه می‌کند. برای نمونه، می‌توانید با یک ساختار مشخص:

• قابلیت انتخاب رنگ را محدود کنید.
• پالت رنگی برند را تعریف کنید.
• اندازه‌های استاندارد تایپوگرافی بسازید.
• سیستم فاصله‌گذاری مشخصی برای طراحی ایجاد کنید.
• استایل‌های عمومی دکمه‌ها و عنوان‌ها را تعیین کنید.
• کنترل‌های خاصی را فقط برای یک بلوک خاص فعال یا غیرفعال کنید.

مزیت مهم این روش این است که بسیاری از تنظیمات هم در فرانت‌اند و هم در ادیتور قابل استفاده هستند.

کدام نسخه theme.json بهتر است؟

ساختار theme.json دارای یک ویژگی به نام version است. در مستندات فعلی وردپرس، نسخه ۳ آخرین نسخه است و از وردپرس نسخه 6.6 به بعد کار می‌کند. نسخه ۲ همچنان توسط نسخه‌های جدیدتر وردپرس پشتیبانی می‌شود، اما قابلیت‌های جدید روی جدیدترین نسخه API توسعه داده می‌شوند.

برای قالبی که حداقل نسخه وردپرس آن 6.6 یا جدیدتر است، نقطه شروع مناسبی داریم:

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3
}

پراپرتی مربوط به schema$ برای اجرای پوسته الزامی نیست، اما استفاده از آن در محیط توسعه بسیار مفید است. ادیتورهایی مانند VS Code با خواندن JSON Schema می‌توانند:

• خطاهای ساختاری را تشخیص دهند.
• پراپرتی‌های معتبر را پیشنهاد دهند.
• قابلیت تکمیل خودکار (Autocomplete) ارائه کنند.
• نوع مقدار هر پراپرتی را بررسی کنند.

وردپرس برای نسخه‌های مختلف، اسکیمای جداگانه ارائه می‌دهد. بهتر است اسکیما را مطابق قدیمی‌ترین نسخه وردپرس که پوسته شما رسماً پشتیبانی می‌کند انتخاب کنید.

ساختار اصلی theme.json

یک نمای ساده از فایل theme.json می‌تواند چنین باشد:

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

دو بخش مهمی که تقریباً در هر پروژه با آنها سروکار دارید عبارت‌اند از:

۱) settings: مشخص می‌کند چه امکاناتی وجود داشته باشند یا چه پیش‌فرض‌هایی در اختیار ادیتور قرار بگیرند. مثلاً:

{
  "settings": {
    "color": {
      "palette": []
    },
    "typography": {
      "fontSizes": []
    }
  }
}

۲) styles: ظاهر پیش‌فرض پوسته را مشخص می‌کند. مثلاً:

{
  "styles": {
    "color": {
      "text": "#222222",
      "background": "#ffffff"
    }
  }
}

این تفاوت را به خاطر بسپارید:

settings بیشتر درباره امکانات و گزینه‌های سیستم طراحی است؛ styles درباره نحوه استفاده پیش‌فرض از آنهاست.

مهم‌ترین قابلیت‌های settings

در ادامه، با مهم‌ترین قابلیت‌ها و امکاناتی که از طریق قسمت settings فایل theme.json می‌توان آنها را پیاده‌سازی کرد، آشنا خواهیم شد:

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

۱) ساخت پالت رنگ در theme.json

فرض کنید پوسته مدنظر شما، یک سیستم طراحی (Design System) ساده با چهار رنگ دارد:

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Base",
          "slug": "base",
          "color": "#ffffff"
        },
        {
          "name": "Contrast",
          "slug": "contrast",
          "color": "#171717"
        },
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#2563eb"
        },
        {
          "name": "Muted",
          "slug": "muted",
          "color": "#64748b"
        }
      ]
    }
  }
}

این تعریف صرفاً چند مقدار JSON نیست. وردپرس برای همه این پری‌سِت‌ها، پراپرتی‌های سفارشی CSS ایجاد می‌کند. مثلاً رنگ primary به متغیری با الگویی شبیه زیر تبدیل می‌شود:

--wp--preset--color--primary

وردپرس برای پری‌سِت‌های استاندارد از الگویی با پیشوند --wp--preset-- استفاده می‌کند. در CSS سفارشی نیز می‌توانید همان توکن طراحی را مصرف کنید:

.my-component {
  color: var(--wp--preset--color--primary);
}

این روش بهتر از تکرار مستقیم کد رنگی 2563eb# در چند فایل مختلف است. اگر رنگ اصلی برند تغییر کند، نقطه تغییر مشخصی دارید.

۲) استفاده از پری‌سِت‌ها داخل استایل

تعریف پالت رنگی به تنهایی الزاماً به این معنی نیست که رنگ‌ها به طراحی پیش‌فرض صفحه اعمال می‌شوند. می‌توان پری‌ست تعریف‌شده را در قسمت styles استفاده کرد:

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        {
          "name": "Base",
          "slug": "base",
          "color": "#ffffff"
        },
        {
          "name": "Contrast",
          "slug": "contrast",
          "color": "#171717"
        },
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#2563eb"
        }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var:preset|color|base",
      "text": "var:preset|color|contrast"
    }
  }
}

سینتکس داخلی theme.json برای اشاره به پری‌ست با چیزی که در CSS می‌بینیم متفاوت است:

var:preset|color|primary

وردپرس هنگام تولید CSS آن را به پراپرتی سفارشی CSS مربوطه تبدیل می‌کند. این الگو باعث می‌شود settings نقش تعریف توکن طراحی را داشته باشد و styles آن توکن‌ها را در طراحی واقعی مصرف کند.

۳) تنظیم تایپوگرافی پوسته وردپرس

بخش settings.typography امکان تعریف اندازه فونت، خانواده فونت و بسیاری از قابلیت‌های تایپوگرافی را فراهم می‌کند. یک مثال کاربردی:

{
  "version": 3,
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "name": "System UI",
          "slug": "primary",
          "fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif"
        }
      ],
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "0.875rem"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "1rem"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "1.5rem"
        }
      ]
    }
  }
}

انتخاب نام معنادار و سمانتیک برای نامک (slug) معمولاً انتخاب بهتری است. برای مثال نامک‌هایی مانند:

primary
secondary
small
medium
large

معمولاً از نامک‌هایی مثل موارد زیر، انعطاف‌پذیرتر هستند:

vazirmatn
18px
blue-font

چون ممکن است در نسخه بعدی پوسته، خانواده فونت یا مقدار واقعی توکن طراحی تغییر کند، بدون اینکه لازم باشد نام توکن نیز تغییر کند. مستندات رسمی وردپرس نیز برای خانواده فونت، استفاده از نامگذاری سمانتیک را توصیه می‌کنند.

۴) فعال کردن ابزارهای طراحی

یکی از گزینه‌های مفید theme.json، تنظیم appearanceTools است:

{
  "version": 3,
  "settings": {
    "appearanceTools": true
  }
}

این گزینه مجموعه‌ای از ابزارهای ظاهری را در ادیتور فعال می‌کند؛ از جمله تعدادی از کنترل‌های مربوط به تایپوگرافی، بوردرها، فاصله‌گذاری‌ها، رنگ‌بندی و غیره. با این حال فعال کردن همه ابزارها همیشه بهترین تصمیم نیست. اگر در حال توسعه یک پوسته عمومی هستید که کاربر باید آزادی طراحی زیادی داشته باشد، appearanceTools می‌تواند مناسب باشد. اما در یک سیستم طراحی کنترل‌شده برای سایت سازمانی، ممکن است بهتر باشد فقط قابلیت‌هایی را که واقعاً لازم دارید به‌صورت جداگانه فعال کنید. در غیر این صورت، کاربر می‌تواند به‌سادگی از قواعد طراحی برند خارج شود.

۵) مدیریت قالب و عرض محتوا

یکی از کاربردهای مهم theme.json تعریف عرض معمولی و حالت گسترده محتواست:

{
  "version": 3,
  "settings": {
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  }
}

پراپرتی contentSize عرض معمولی محتوا را مشخص می‌کند و wideSize برای بلوک‌هایی کاربرد دارد که از حالت Wide استفاده می‌کنند. این تنظیم در پوسته‌های بلوکی اهمیت زیادی دارد؛ چون قالب (Layout) دیگر صرفاً یک container. در CSS نیست. سیستم ادیتور بلوکی نیز باید از قواعد عرض محتوا آگاه باشد.

۶) ساخت سیستم فاصله‌گذاری

به‌جای استفاده پراکنده از مقادیری مانند 13px یا 27px یا 41px می‌توان یک مقیاس فاصله‌گذاری مشخص ساخت. مثلاً:

{
  "version": 3,
  "settings": {
    "spacing": {
      "spacingSizes": [
        {
          "name": "XS",
          "slug": "xs",
          "size": "0.5rem"
        },
        {
          "name": "S",
          "slug": "s",
          "size": "1rem"
        },
        {
          "name": "M",
          "slug": "m",
          "size": "1.5rem"
        },
        {
          "name": "L",
          "slug": "l",
          "size": "2.5rem"
        }
      ]
    }
  }
}

بعداً همین مقادیر را در بلوک‌ها، استایل‌ها یا CSS سفارشی استفاده می‌کنید. مزیت اصلی، یکسان شدن زبان طراحی پوسته است. توسعه‌دهنده به‌جای انتخاب عدد دلخواه برای هر کامپوننت، از توکن‌های تعریف‌شده استفاده می‌کند.

۷) پراپرتی‌های سفارشی CSS

گاهی توکن طراحی موردنظر شما جزء پری‌ست‌های استاندارد وردپرس نیست. برای چنین شرایطی settings.custom کاربرد دارد. مثلاً:

{
  "version": 3,
  "settings": {
    "custom": {
      "lineHeight": {
        "tight": "1.25",
        "normal": "1.7",
        "loose": "2"
      }
    }
  }
}

وردپرس از این مقادیر پراپرتی سفارشی یا Custom Property می‌سازد. برای مثال:

--wp--custom--line-height--normal

در خود theme.json نیز می‌توان آن را با سینتکس مخصوص custom values فراخوانی کرد:

{
  "styles": {
    "typography": {
      "lineHeight": "var:custom|line-height|normal"
    }
  }
}

این قابلیت برای ایجاد توکن‌های طراحی مانند شعاع انحنای (radius) بوردر، اندازه کامپوننت یا مقادیری که مستقیماً پری‌ست استاندارد وردپرس ندارند، مفید است.

محدودکردن تنظیمات برای یک بلوک خاص

یکی از قابلیت‌های مهم theme.json این است که settings را می‌توان در سطح بلوک نیز تغییر داد. فرض کنید انتخاب اندازه فونت آزاد برای بیشتر بلوک‌ها مجاز است، اما نمی‌خواهید کاربران اندازه هدینگ را به صورت دلخواه تغییر دهند. می‌توان تنظیمات بلوک را به شکل دقیق‌تر کنترل کرد. این موضوع برای پوسته‌هایی که سیستم طراحی جدی دارند بسیار مهم است؛ چون توسعه‌دهنده مجبور نیست بین «آزادی کامل کاربر» و «ادیتور کاملاً محدود» یکی را انتخاب کند.

می‌توانید برای هر بلوک سطح مناسبی از کنترل تعریف کنید. وردپرس نیز UI مربوط به بلوک‌ها را بر اساس قابلیت‌هایی که بلوک پشتیبانی می‌کند و تنظیماتی که در سیستم استایل‌ها تعریف شده‌اند، مدیریت می‌کند.

بخش styles چگونه کار می‌کند؟

بخش styles فایل theme.json را می‌توان در چند سطح به کار برد:

• سطح عمومی
• المان‌های HTML
• بلوک‌ها

این ساختار اجازه می‌دهد استایل‌دهی از قواعد عمومی شروع شود و در بخش‌های خاص‌تر بازنویسی شود.

۱) استایل عمومی پوسته: این تنظیمات روی طراحی عمومی سایت اثر می‌گذارند.

{
  "version": 3,
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#18181b"
    },
    "typography": {
      "lineHeight": "1.7"
    }
  }
}

۲) استایل عناصر HTML: فرض کنید می‌خواهید همه Headingها رنگ مشخصی داشته باشند:

{
  "version": 3,
  "styles": {
    "elements": {
      "heading": {
        "color": {
          "text": "#111827"
        }
      }
    }
  }
}

همچنین می‌توان عناصر خاص‌تری مانند h1 تا h6 و دکمه‌ها یا لینک‌ها را هدف گرفت.

۳) استایل یک بلوک مشخص: برای مثال، بلوک مربوط به کُد:

{
  "version": 3,
  "styles": {
    "blocks": {
      "core/code": {
        "color": {
          "background": "#111827",
          "text": "#f8fafc"
        },
        "spacing": {
          "padding": {
            "top": "1.25rem",
            "right": "1.25rem",
            "bottom": "1.25rem",
            "left": "1.25rem"
          }
        }
      }
    }
  }
}

نام بلوک از namespace و نام آن تشکیل می‌شود:

core/code
core/group
core/paragraph
core/heading
core/image

برای بلوک‌های سفارشی نیز namespace افزونه یا پروژه استفاده می‌شود.

چه نیازی به style.css داریم؟

شاید بپرسید با داشتن theme.json و CSS چه نیازی به style.css پوسته داریم؟ باید توجه داشت که theme.json جایگزین کامل CSS نیست. وردپرس طی سال‌های اخیر محدوده بسیار بزرگی از استایل‌دهی را وارد Global Styles کرده و حتی مستندات رسمی توصیه می‌کنند در مواردی که یک استایل استاندارد وردپرس را می‌توان از طریق styles پیاده‌سازی کرد، استفاده از این روش می‌تواند هماهنگی بهتری با رابط کاربری Styles ایجاد کند. اما CSS هنوز برای موارد مختلف لازم است؛ مثلاً:

• سلکتورهای پیچیده
• کامپوننت‌های کاملاً سفارشی
• بعضی تعامل‌ها
• استایل‌هایی که توسط schema پشتیبانی نمی‌شوند
• برخی مدیا کوئری‌ها یا شرایط واکنشگرایی خاص
• حالت‌هایی که به مارک‌آپ اختصاصی پوسته وابسته‌اند

بنابراین معماری مناسب معمولاً چنین است: فایل theme.json برای توکن‌های طراحی و تنظیمات استاندارد (و حتی‌الامکان برای استایل‌های استاندارد بلوک‌ها و المان‌های HTML) و فایل style.css برای رفتارهای خاص و سلکتورهای پیچیده انتخاب شوند. حتی بلاگ توسعه‌دهندگان وردپرس نیز تأکید کرده که لازم نیست همه استایل‌های یک پوسته بلوکی الزاماً داخل theme.json باشند؛ انتخاب معماری CSS باید بر اساس نیاز پروژه انجام شود.

تعریف تمپلیت اختصاصی

فایل theme.json فقط برای CSS و استایل‌دهی نیست. در پوسته‌های بلوکی می‌توان تمپلیت اختصاصی یا Custom Template نیز ثبت کرد:

{
  "version": 3,
  "customTemplates": [
    {
      "name": "landing-page",
      "title": "Landing Page",
      "postTypes": ["page"]
    }
  ]
}

در کنار آن باید فایل متناظر وجود داشته باشد:

templates/landing-page.html

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

ثبت اجزای تمپلیت

اجزای تمپلیت یا همان Template Part بخش قابل استفاده مجددی از تمپلیت است؛ مانند هدر و فوتر. مثلاً:

{
  "version": 3,
  "templateParts": [
    {
      "name": "header",
      "title": "Header",
      "area": "header"
    },
    {
      "name": "footer",
      "title": "Footer",
      "area": "footer"
    }
  ]
}

فایل‌های مربوط به آنها معمولاً در مسیر زیر قرار می‌گیرند:

parts/header.html
parts/footer.html

استفاده از اجزای تمپلیت از تکرار کدهای یک بخش در چند تمپلیت جلوگیری می‌کند.

تنوع استایل چیست؟

فرض کنید پوسته شما یک طراحی پیش‌فرض دارد ولی می‌خواهید چند ظاهر متفاوت نیز در اختیار کاربر قرار دهید. به‌جای ساخت چند پوسته مستقل، می‌توانید یک Variation بسازید. ساختار فایل‌ها ممکن است چنین باشد:

my-theme/
├── styles/
│   ├── dark.json
│   └── minimal.json
└── theme.json

هر Variation می‌تواند بخش‌هایی از تنظیمات و استایل‌های theme.json را بازنویسی کند. برای مثال styles/dark.json:

{
  "version": 3,
  "title": "Dark",
  "styles": {
    "color": {
      "background": "#09090b",
      "text": "#fafafa"
    }
  }
}

کاربر می‌تواند Variation را از رابط Styles انتخاب کند. نکته مهم این است که Variation و پوسته فرزند، یک مفهوم نیستند. وقتی کاربر Variation را انتخاب و ذخیره می‌کند، داده‌های آن وارد تنظیمات کاربر سایت می‌شوند و نسبت به theme.json اصلی اولویت پیدا می‌کنند.

نمونه theme.json عملی

نمونه زیر می‌تواند نقطه شروع مناسبی برای یک پوسته بلوکی ساده در وردپرس باشد:

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    },
    "color": {
      "palette": [
        {
          "name": "Base",
          "slug": "base",
          "color": "#ffffff"
        },
        {
          "name": "Contrast",
          "slug": "contrast",
          "color": "#18181b"
        },
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#2563eb"
        }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "name": "System UI",
          "slug": "primary",
          "fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif"
        }
      ],
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "0.875rem"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "1rem"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "1.5rem"
        }
      ]
    },
    "spacing": {
      "spacingSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "1rem"
        },
        {
          "name": "Medium",
          "slug": "medium",
          "size": "1.5rem"
        },
        {
          "name": "Large",
          "slug": "large",
          "size": "3rem"
        }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var:preset|color|base",
      "text": "var:preset|color|contrast"
    },
    "typography": {
      "fontFamily": "var:preset|font-family|primary",
      "fontSize": "var:preset|font-size|medium",
      "lineHeight": "1.7"
    },
    "elements": {
      "link": {
        "color": {
          "text": "var:preset|color|primary"
        }
      },
      "heading": {
        "color": {
          "text": "var:preset|color|contrast"
        }
      }
    },
    "blocks": {
      "core/code": {
        "color": {
          "background": "var:preset|color|contrast",
          "text": "var:preset|color|base"
        }
      }
    }
  }
}

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

نقش theme.json در معماری پوسته

یک پوسته بلوکی استاندارد معمولاً از چند بخش تشکیل می‌شود:

theme.json          → سیستم طراحی و استایل‌های عمومی
templates/          → ساختار صفحات
parts/              → هدر، فوتر و بخش‌های مشترک
patterns/           → ترکیب‌های آماده
styles/             → Variations
assets/             → فونت‌ها، تصاویر، استایل‌ها و جاوا اسکریپت‌های اضافی
functions.php       → منطق PHP موردنیاز قالب

در چنین معماری‌ای، بهتر است theme.json را لایه Design System قالب ببینید.

رنگ‌ها، تایپوگرافی، فاصله‌گذاری، قالب و قابلیت‌های ادیتور باید تا جای ممکن در این لایه تعریف شوند. تمپلیت‌ها تصمیم می‌گیرند این سیستم چگونه ترکیب شود و CSS سفارشی مواردی را پوشش می‌دهد که خارج از امکانات استاندارد Global Styles هستند. این تفکیک باعث می‌شود قالب با ادیتور سایت و ادیتور بلوکی هماهنگ‌تر باشد و نگهداری آن نیز ساده‌تر شود.

آیا یادگیری theme.json الزامی است؟

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

مسیر مناسب برای یادگیری و نیز نحوه کار با فایل theme.json می‌تواند به صورت زیر باشد:

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

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

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

۱) استفاده از JSON نامعتبر: JSON برخلاف جاوا اسکریپت اجازه کامنت‌گذاری معمولی، ویرگول انتهایی و بعضی سینتکس‌های انعطاف‌پذیر را نمی‌دهد. مثلاً این کد معتبر نیست:

{
  "version": 3,
  "settings": {
    "appearanceTools": true,
  }
}

ویرگول بعد از true باعث خطای JSON می‌شود. استفاده از schema$ در ادیتور کد کمک می‌کند چنین خطاهایی سریع‌تر پیدا شوند.

۲) استفاده از پراپرتی‌های مربوط به نسخه جدید وردپرس: ممکن است یک پراپرتی در schema جدید وجود داشته باشد اما حداقل نسخه وردپرس پوسته شما قدیمی‌تر باشد. به همین دلیل، همواره schema متعلق به پروژه را با نسخه‌ای که واقعاً پشتیبانی می‌کنید هماهنگ کنید.

۳) Hard-code کردن همه مقادیر: اگر رنگ اصلی را در ده بخش مختلف به صورت 2563eb# قرار دهید، مزیت توکن‌های طراحی را از دست داده‌اید. یک بار پری‌ست را تعریف کنید و سپس همان پری‌ست را استفاده کنید.

۴) تبدیل theme.json به یک فایل CSS بسیار بزرگ: صرف اینکه وردپرس اجازه می‌دهد استایل‌های زیادی را در JSON تعریف کنید به این معنی نیست که تمام CSS پروژه باید به JSON منتقل شود. برای هر استایل، این سؤال را بپرسید: «آیا این پراپرتی، بخشی از سیستم طراحی عمومی است یا استایل‌دهی استاندارد بلوک‌ها را در بر می‌گیرد؟» اگر پاسخ مثبت باشد، theme.json گزینه خوبی است. اگر با کامپوننت بسیار اختصاصی و سلکتور پیچیده سروکار دارید، CSS ممکن است خواناتر و قابل نگهداری‌تر باشد.

۵) فعال کردن کنترل‌های بیش از حد: در یک پوسته تجاری یا سازمانی، فعال بودن تمام گزینه‌های تایپوگرافی، رنگ و فاصله‌گذاری ممکن است باعث شود کاربران طراحی صفحات را به‌سادگی از سیستم اصلی خارج کنند. theme.json فقط ابزار اضافه‌کردن قابلیت نیست؛ برای محدودکردن قابلیت‌ها نیز کاربرد دارد!

سوالات متداول