Block Theme چطور ساختار قالب مدرن را می‌سازد؟

در وردپرس مدرن، Block Theme (قالب بلوکی) لایه‌ای است که ساختار قالب را از PHP به HTML Template منتقل می‌کند و پایه معماری قالب‌های آینده وردپرس محسوب می‌شود. بدون ساختار درست پوشه‌ها و بدون سازگاری با Template Hierarchy در قالب بلاکی، هر تغییر در ادیتور ممکن است در فرانت‌اند رفتار غیرمنتظره نشان دهد. ساختار Block Theme بر پایه theme.json، پوشه templates، پوشه parts و پوشه patterns است و بدون تسلط بر این چهار لایه، نگهداشت پروژه در مقیاس بزرگ دشوار می‌شود. تست Block Theme در سه سطح قالب، ادیتور و فرانت‌اند انجام می‌شود و بدون آن، انتشار به تولید ریسک بالایی دارد. مستندسازی ساختار و آموزش تیم محتوا، بخشی از پیاده‌سازی حرفه‌ای Block Theme است. در این راهنما از ساختار پایه تا استقرار تولیدی Block Theme را با نگاه مهندسی و کد عملی پوشش می‌دهیم.

در پروژه‌های واقعی، بیشترین خطا در Block Theme مربوط به نبود فایل index.html در پوشه templates است. بدون این فایل، وردپرس قالب بلوکی را به‌عنوان قالب معتبر نمی‌شناسد و رفتار غیرمنتظره نشان می‌دهد. این راهنما از همان نقطه‌ای شروع می‌کند که در کار حرفه‌ای بیشترین ارزش را ایجاد کرده است.

Block Theme چیست و چه تفاوتی با قالب کلاسیک دارد؟

Block Theme یک قالب وردپرس است که ساختار صفحات را به‌جای فایل‌های PHP، از طریق HTML Template و بلاک‌ها تعریف می‌کند. این قالب‌ها از FSE پشتیبانی می‌کنند و اجازه می‌دهند همه بخش‌های سایت از ادیتور بلاک ویرایش شود.

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

تفاوت کلیدی با قالب کلاسیک

در قالب کلاسیک، فایل‌های PHP نقش اصلی را دارند. در Block Theme، HTML Templateها و theme.json جایگزین آن‌ها می‌شوند. این تغییر، مدل ذهنی توسعه‌دهنده را از PHP به Block Editor منتقل می‌کند.

ساختار پوشه‌ها و فایل‌های ضروری

ساختار یک Block Theme شامل فایل‌های ضروری و پوشه‌های استاندارد است.

wpk-block-theme/
├── style.css              (الزامی)
├── theme.json             (توصیه‌شده)
├── functions.php          (اختیاری)
├── templates/             (الزامی حداقل index.html)
│   ├── index.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   └── 404.html
├── parts/                 (اختیاری)
│   ├── header.html
│   └── footer.html
├── patterns/              (اختیاری)
│   └── hero.php
├── styles/                (اختیاری)
│   └── dark.json
└── assets/                (اختیاری)
    ├── css/
    ├── js/
    └── fonts/

الزامی‌های اصلی، فایل style.css و فایل index.html در پوشه templates هستند. بدون این دو، وردپرس قالب را معتبر نمی‌شناسد.

الگوی پوشه‌بندی حرفه‌ای

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

فایل style.css و header قالب بلوکی

هدر style.css در Block Theme مشابه قالب کلاسیک است، اما با یک تفاوت: نیازی به مشخص کردن Template نیست چون قالب والد محسوب نمی‌شود.

/*
Theme Name: WordPressKar Block Theme
Theme URI: https://wordpresskar.ir/
Author: WordPressKar Team
Author URI: https://wordpresskar.ir/
Description: قالب بلوکی حرفه‌ای WordPressKar با پشتیبانی کامل FSE.
Version: 1.0.0
Requires at least: 6.0
Tested up to: 6.7
Requires PHP: 7.4
License: GPL-2.0-or-later
Text Domain: wpk-block
Tags: block-theme, full-site-editing, custom-colors
*/

پارامترهای Requires at least و Tested up to برای سازگاری نسخه ضروری هستند.

نسخه‌بندی در قالب بلوکی

نسخه در هدر style.css و همچنین در theme.json استفاده می‌شود. بدون نسخه، کش مرورگر به‌درستی Invalidate نمی‌شود.

theme.json و تنظیمات سراسری

theme.json فایل تنظیمات سراسری قالب بلوکی است و شامل settings، styles و version می‌شود.

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "settings": {
        "appearanceTools": true,
        "layout": { "contentSize": "740px", "wideSize": "1180px" }
    },
    "styles": {
        "color": { "background": "#fff", "text": "#1f1f1f" },
        "typography": { "lineHeight": 1.7 }
    }
}

برای مطالعه کامل این فایل، راهنمای theme.json و تنظیمات ظاهری قالب را ببینید.

Style Variations در Block Theme

Style Variations امکان تعریف چند پالت ظاهری متفاوت را می‌دهد. فایل‌های JSON در پوشه styles قرار می‌گیرند و در ادیتور قابل انتخاب هستند.

ساختار پوشه templates

پوشه templates، ساختار صفحات را در قالب بلوکی تعریف می‌کند. هر فایل، یک HTML Template است که ترکیبی از بلاک‌ها و Template Partها محسوب می‌شود.

<!-- templates/single.html -->
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<!-- wp:post-title {"level":1} /-->
<!-- wp:post-featured-image /-->
<!-- wp:post-content /-->
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

نکته مهم، استفاده از بلاک‌های داینامیک مثل post-title و post-content است که به داده صفحه جاری متصل می‌شوند.

Template سفارشی برای CPT

برای پست‌تایپ سفارشی، فایل single-{cpt}.html تعریف کنید. راهنمای قالب اختصاصی CPT نقطه شروع مناسبی است.

ساختار پوشه parts

پوشه parts، بخش‌های قابل استفاده مجدد مثل هدر، فوتر و سایدبار را نگه می‌دارد.

<!-- parts/header.html -->
<!-- wp:group {"tagName":"header","layout":{"type":"flex","justifyContent":"space-between"}} -->
<!-- wp:site-logo /-->
<!-- wp:navigation /-->
<!-- /wp:group -->

الگوی حرفه‌ای این است که هدر و فوتر را در Template Part پیاده کنید و از تکرار در Templateها پرهیز کنید.

نام‌گذاری Template Part

نام فایل‌ها باید با slug مطابقت داشته باشد. برای مثال، parts/header.html با slug header فراخوانی می‌شود.

ساختار پوشه patterns

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

<?php
/**
 * Title: Hero Section WordPressKar
 * Slug: wpk/hero
 * Categories: featured
 */
?>
<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"4rem","bottom":"4rem"}}}} -->
<!-- wp:heading {"level":1} -->
<h1>عنوان اصلی</h1>
<!-- /wp:heading -->
<!-- /wp:group -->

وردپرس به‌طور خودکار فایل‌های PHP در این پوشه را به‌عنوان پترن ثبت می‌کند.

سازمان‌دهی پترن‌ها بر اساس دسته

دسته‌های استاندارد شامل featured، text، gallery و header هستند. توصیه می‌کنم پترن‌ها را بر اساس حوزه عملکردی سازمان دهید.

functions.php در قالب بلوکی

در قالب بلوکی، functions.php معمولاً سبک‌تر از قالب کلاسیک است، چون بخش عمده تنظیمات در theme.json تعریف می‌شود. اما هنوز برای افزودن Block Style، Block Variation و تنظیمات اختصاصی کاربرد دارد.

<?php
add_action( "init", function() {
    register_block_style( "core/button", array(
        "name"  => "wpk-outline",
        "label" => "دکمه خطی WordPressKar",
    ) );
} );

برای مطالعه بیشتر در مورد Block Style، راهنمای Block Customizer و تنظیمات بلوکی را ببینید.

بارگذاری CSS و JS اختصاصی

توصیه می‌کنم CSS و JS اختصاصی را فقط در صفحاتی که به آن نیاز دارند بارگذاری کنید. راهنمای بارگذاری شرطی CSS و JS نقطه شروع مناسبی است.

Template Hierarchy در Block Theme

در Block Theme، Template Hierarchy مشابه قالب کلاسیک است اما فایل‌ها به‌جای PHP، HTML هستند.

single-post-{slug}.html
single-post.html
single.html
singular.html
index.html

آشنایی دقیق با این سلسله‌مراتب، برای پیش‌بینی رفتار سایت ضروری است. راهنمای Template Hierarchy و اولویت قالب‌ها را ببینید.

آرشیو تاکسونومی در Block Theme

برای تاکسونومی سفارشی، فایل taxonomy-{tax}.html تعریف کنید. راهنمای قالب تاکسونومی اختصاصی را ببینید.

تست و دیباگ Block Theme

تست Block Theme در سه سطح انجام می‌شود: سطح قالب، سطح ادیتور و سطح فرانت‌اند. برای سطح قالب، اعتبارسنجی HTML Template. برای سطح ادیتور، تست تجربه ویرایش. برای سطح فرانت‌اند، تست رفتار و ریسپانسیو.

add_action( "wp_footer", function() {
    if ( defined( "WP_DEBUG" ) && WP_DEBUG ) {
        global $template;
        error_log( "Block theme template: " . $template );
    }
} );

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

اشتباهات رایج در تست Block Theme

اشتباه اول، نبود فایل index.html. اشتباه دوم، نبود تست در حالت کاربر غیرمدیر. اشتباه سوم، نبود تست با پست‌تایپ سفارشی. اشتباه چهارم، نبود تست با تاکسونومی سفارشی. اشتباه پنجم، نبود تست ریسپانسیو.

امنیت و Escape در Block Theme

در Block Theme، داده‌ها در سطح بلاک مدیریت می‌شوند اما در Template سفارشی PHP، باید Escape شوند. برای متن از esc_html، برای URL از esc_url و برای Attributes از esc_attr استفاده کنید.

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

کنترل دسترسی در Block Theme

در Block Theme، دسترسی به Site Editor باید بر اساس نقش کاربر کنترل شود. توصیه می‌کنم از map_meta_cap برای محدودسازی دسترسی استفاده کنید.

پرسش‌های پرتکرار درباره Block Theme

آیا Block Theme جایگزین قالب کلاسیک می‌شود؟

خیر، قالب کلاسیک همچنان پشتیبانی می‌شود، اما Block Theme رویکرد آینده است.

تفاوت Block Theme و قالب کلاسیک چیست؟

در Block Theme، ساختار در HTML Template و theme.json تعریف می‌شود، در قالب کلاسیک در PHP.

آیا Block Theme روی سرعت سایت اثر دارد؟

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

آیا می‌توان قالب کلاسیک را به Block Theme تبدیل کرد؟

بله، اما نیازمند بازنویسی قالب است. راهنمای تبدیل قالب کلاسیک به بلاکی را ببینید.

آیا Block Theme با Child Theme کار می‌کند؟

بله، Template و پترن‌ها در قالب فرزند override می‌شوند. راهنمای Child Theme حرفه‌ای را ببینید.

آیا Block Theme با Polylang و WPML سازگار است؟

بله، اما نیازمند تنظیمات خاص است. راهنمای مقایسه WPML و Polylang را ببینید.

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

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

پیشنهاد می‌کنم مسیر یادگیری را با theme.json و تنظیمات ظاهری قالب ادامه دهید و سپس Full Site Editing و ویرایش کامل سایت را به‌عنوان رویکرد جامع مطالعه کنید.

اگر روی پروژه واقعی خود Block Theme ساخته‌اید، برایم جالب است بدانید کدام بخش — ساختار پوشه‌ها یا سازگاری با پلاگین‌ها — بیشترین چالش را ایجاد کرده است. تجربه خودتان را در دیدگاه‌ها بنویسید.