در وردپرس مدرن، Block Customizer (سفارشی‌ساز بلوکی) لایه‌ای است که تنظیمات اختصاصی هر بلوک را در ادیتور و فرانت‌اند مدیریت می‌کند و ستون فقرات قالب‌های بلاکی محسوب می‌شود. بدون ثبت درست block styles، block variations و block supports، هر سفارشی‌سازی در ادیتور به کد شکننده تبدیل می‌شود و در به‌روزرسانی‌های بعدی از هم می‌پاشد. شرط‌های نمایش در سطح بلوک، باید با Block Context و Block Bindings هماهنگ باشند تا تجربه محتواسازی پایدار بماند. مدیریت استایل بلوکی از طریق theme.json و استایل اختصاصی بلوک، تفاوت بین یک قالب بلاکی حرفه‌ای و یک قالب بلاکی آماتور است. تست Block Customizer در سه سطح ثبت، رفتار ادیتور و رفتار فرانت‌اند انجام می‌شود و بدون آن، انتشار به تولید ریسک بالایی دارد. در این راهنما از ساختار پایه تا استقرار تولیدی Block Customizer را با نگاه مهندسی و کد عملی پوشش می‌دهیم.

در پروژه‌های واقعی، بیشترین خطا در Block Customizer مربوط به block variations است که بدون توجه به Block Context ثبت می‌شوند. نتیجه این می‌شود که در ادیتور بلاک نمایش داده می‌شود، اما در فرانت‌اند رفتار متفاوتی دارد. این راهنما همان لایه‌ای است که پیش از هر سفارشی‌سازی بلوکی باید مستقر شود.

Block Customizer چیست و چه تفاوتی با Customizer سنتی دارد؟

Block Customizer یک مفهوم کلی است که شامل ثبت block styles، block variations، block supports، Block Context، Block Bindings و تنظیمات theme.json می‌شود. این لایه، جایگزین مدرن Customizer سنتی برای قالب‌های بلاکی است.

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

نشانه‌هایی که Block Customizer ضروری است

اگر روی قالب بلاکی کار می‌کنید، اگر می‌خواهید Block Variation اختصاصی برای تیم محتوا بسازید، یا اگر می‌خواهید داده سفارشی را به بلوک متصل کنید، Block Customizer انتخاب درستی است.

ثبت Block Styles و Block Variations

Block Styles با register_block_style() ثبت می‌شود و به کاربر امکان انتخاب استایل متفاوت می‌دهد. Block Variations با register_block_variation() یا از طریق JavaScript ثبت می‌شود و یک نسخه پیش‌پیکربندی‌شده از بلوک است.

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

    register_block_style( "core/quote", array(
        "name"         => "wpk-highlight",
        "label"        => "نقل قول برجسته",
        "inline_style" = ".wp-block-quote.is-style-wpk-highlight{border-right:4px solid #0073aa;padding-right:1rem;}",
    ) );
} );

Block Variations در JavaScript ثبت می‌شود و می‌تواند شامل تنظیمات پیش‌فرض attribute باشد:

wp.blocks.registerBlockVariation( "core/columns", {
    name: "wpk-feature-grid",
    title: "شبکه ویژگی WordPressKar",
    attributes: { columns: 3, className: "is-style-wpk-grid" },
    innerBlocks: [
        [ "core/column", {}, [ [ "core/heading", { level: 3 } ] ] ],
    ],
} );

برای مطالعه بیشتر، راهنمای ساخت بلاک سفارشی گوتنبرگ را ببینید.

نام‌گذاری Style و Variation

همیشه از پیشوند اختصاصی برند استفاده کنید تا از تداخل با استایل‌های هسته جلوگیری شود. مثال: wpk-outline، wpk-highlight.

Block Supports و کنترل تنظیمات

Block Supports به شما امکان می‌دهد تنظیمات یک بلوک را در سمت سرور کنترل کنید. برای مثال، می‌توانید پشتیبانی از رنگ، فاصله، تایپوگرافی یا لایه‌بندی را برای یک بلوک سفارشی اضافه یا حذف کنید.

register_block_type( "wpk/custom-block", array(
    "supports" => array(
        "align"           => array( "wide", "full" ),
        "color"           => array( "background" => true, "text" => true ),
        "spacing"         => array( "padding" => true, "margin" => true ),
        "typography"      => array( "fontSize" => true, "lineHeight" => true ),
    ),
) );

توصیه می‌کنم Block Supports را برای هر بلوک سفارشی به‌صورت دقیق تعریف کنید تا کاربر نتواند تنظیمات نامرتبط را تغییر دهد.

کنترل Block Supports در سطح theme.json

Block Supports را می‌توان در سطح سراسری با theme.json مدیریت کرد. راهنمای راهنمای theme.json در وردپرس نقطه شروع مناسبی است.

استایل اختصاصی بلوک

برای استایل اختصاصی بلوک، سه رویکرد وجود دارد: inline_style در ثبت، فایل CSS جدا با enqueue شرطی، و استفاده از theme.json. انتخاب رویکرد به اندازه استایل وابسته است.

add_action( "enqueue_block_assets", function() {
    if ( ! is_admin() && ! has_block( "wpk/custom-block" ) ) {
        return;
    }
    wp_enqueue_style(
        "wpk-custom-block",
        get_theme_file_uri( "assets/css/custom-block.css" ),
        array(),
        "1.0.0"
    );
} );

نکته مهم، بارگذاری شرطی استایل با has_block() است. این کار از بارگذاری غیرضروری جلوگیری می‌کند.

برای مطالعه بیشتر، راهنمای بارگذاری شرطی CSS و JS را ببینید.

کنترل Specificity در استایل بلوک

در پروژه‌های بزرگ، Specificity استایل بلوک می‌تواند منبع اختلاف شود. توصیه می‌کنم از کلاس‌های is-style-{name} که وردپرس به‌طور خودکار اضافه می‌کند استفاده کنید و از !important پرهیز کنید.

Block Context و اشتراک داده بین بلوک‌ها

Block Context به شما امکان می‌دهد داده را بین یک بلوک والد و بلوک‌های فرزند به اشتراک بگذارید. این قابلیت، پایه ساخت بلوک‌های پیشرفته مانند Query Loop است.

register_block_type( "wpk/context-provider", array(
    "provides_context" => array(
        "wpk/postId" => "postId",
    ),
) );

register_block_type( "wpk/context-consumer", array(
    "uses_context" => array( "wpk/postId" ),
) );

الگوی حرفه‌ای این است که Context را فقط برای داده‌ای استفاده کنید که به‌طور طبیعی از والد به فرزند منتقل می‌شود.

کنترل Context در Server Side Render

در render_callback، Context از طریق پارامتر $block->context در دسترس است. این داده باید با احتیاط استفاده و Escape شود.

Block Bindings API و اتصال داده

Block Bindings API یکی از جدیدترین قابلیت‌های وردپرس است که به شما امکان می‌دهد داده را از منابع خارجی (فیلد سفارشی، REST API و ...) به Attributeهای بلوک متصل کنید.

register_block_bindings_source( "wpk/custom-field", array(
    "label"              => "فیلد سفارشی WordPressKar",
    "get_value_callback" => function( $source_args, $block_instance ) {
        $post_id = $block_instance->context["postId"] ?? get_the_ID();
        return get_post_meta( $post_id, $source_args["key"] ?? "", true );
    },
) );

برای مطالعه بیشتر، راهنمای فیلد سفارشی در قالب و افزونه و راهنمای ACF Pro را ببینید.

اتصال فیلد سفارشی به بلوک

Block Bindings به شما امکان می‌دهد یک بلوک پاراگراف، عنوان یا تصویر را به فیلد سفارشی متصل کنید. این قابلیت، تجربه محتواسازی را متحول می‌کند.

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

در قالب‌های بلاکی، theme.json منبع اصلی تنظیمات سراسری است. در این فایل می‌توانید پالت رنگ، تایپوگرافی، فاصله‌ها، Block Supports و تنظیمات هر بلوک را تعریف کنید.

{
    "version": 3,
    "settings": {
        "color": {
            "palette": [
                { "slug": "wpk-primary", "color": "#0073aa", "name": "Primary" }
            ]
        },
        "blocks": {
            "core/button": {
                "color": { "palette": [ { "slug": "wpk-cta", "color": "#ff6b35", "name": "CTA" } ] }
            }
        }
    }
}

برای مطالعه بیشتر، راهنمای راهنمای theme.json در وردپرس را ببینید.

نسخه‌بندی theme.json

پارامتر version در theme.json تعیین می‌کند کدام نسخه از API اعمال شود. توصیه می‌کنم از آخرین نسخه پایدار استفاده کنید و در زمان ارتقا، سازگاری را تست کنید.

شرط نمایش بلوک در فرانت‌اند

در بلوک‌های داینامیک، می‌توانید شرط نمایش را در render_callback اعمال کنید. این رویکرد، امکان نمایش شرطی بلوک بر اساس وضعیت کاربر یا صفحه را می‌دهد.

register_block_type( "wpk/conditional-block", array(
    "render_callback" => function( $attributes, $content, $block ) {
        if ( ! is_user_logged_in() ) {
            return "";
        }
        return "<div class="wpk-logged-in-only">" . $content . "</div>";
    },
) );

الگوی حرفه‌ای این است که شرط‌ها را بر اساس Conditional Tags وردپرس پیاده کنید. راهنمای Conditional Tags پیشرفته در قالب نقطه شروع مناسبی است.

پنهان کردن بلوک در ویرایشگر

اگر می‌خواهید بلوک فقط در شرایط خاص در ویرایشگر دیده شود، از get_block_editor_settings و فیلترهای مربوطه استفاده کنید.

تست و دیباگ Block Customizer

تست Block Customizer در سه سطح انجام می‌شود: سطح ثبت، سطح رفتار ادیتور و سطح رفتار فرانت‌اند. برای سطح ثبت، از wp.blocks.getBlockTypes() در کنسول مرورگر استفاده کنید. برای سطح رفتار ادیتور، تست دستی و E2E توصیه می‌شود.

add_action( "enqueue_block_editor_assets", function() {
    wp_add_inline_script( "wp-blocks", "console.log( wp.blocks.getBlockTypes().filter( b => b.name.startsWith( 'wpk/' ) ) );" );
} );

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

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

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

امنیت و Escape در بلوک سفارشی

در بلوک سفارشی، همه Attributeها باید در render_callback Escape شوند. برای متن از esc_html، برای URL از esc_url، برای Attributes از esc_attr و برای محتوای HTML از wp_kses_post استفاده کنید.

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

کنترل دسترسی به بلوک‌های حساس

اگر بلوکی فقط برای نقش خاصی طراحی شده، در render_callback بررسی دسترسی انجام دهید. این کار، سطح حمله را کاهش می‌دهد.

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

تفاوت Block Style و Block Variation چیست؟

Block Style فقط ظاهر را تغییر می‌دهد، اما Block Variation می‌تواند attribute، innerBlocks و ساختار پیش‌فرض را تغییر دهد.

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

بله، Block Styles و Block Variations در هر قالبی که ادیتور بلاک فعال باشد کار می‌کنند.

آیا theme.json جایگزین Customizer می‌شود؟

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

آیا Block Bindings API جایگزین ACF می‌شود؟

خیر، Block Bindings API یک لایه اتصال است و ACF همچنان برای مدیریت فیلد سفارشی کاربرد دارد.

چرا Variation من در ادیتور نمایش داده نمی‌شود؟

احتمالاً اسکریپت ثبت Variation در زمان نامناسب بارگذاری شده یا نام بلوک والد اشتباه است.

آیا می‌توان Block Style را در قالب فرزند ثبت کرد؟

بله، دقیقاً مثل ثبت در قالب والد. راهنمای Child Theme حرفه‌ای را ببینید.

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

Block Customizer لایه اصلی مدیریت تنظیمات بلوکی در وردپرس مدرن است. کلید موفقیت، ثبت درست Block Styles و Variations، کنترل دقیق Block Supports، استفاده درست از Block Context و Block Bindings، و تست در سه سطح است. اگر این لایه با دقت طراحی شود، تجربه محتواسازی و نگهداشت پروژه در طول سال‌ها ساده باقی می‌ماند.

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

اگر روی پروژه واقعی خود Block Customizer پیاده کرده‌اید، برایم جالب است بدانید کدام بخش — ثبت Variation یا اتصال Block Bindings — بیشترین چالش را ایجاد کرده است. تجربه خودتان را در دیدگاه‌ها بنویسید.