Block Bindings API در وردپرس چیست و چطور داده‌ها را به بلاک متصل می‌کند؟

Block Bindings API در وردپرس یک مکانیزم معماری برای اتصال مستقیم داده‌های پویا به اتریبیوت‌های بلاک‌های هسته است که از نسخه ۶.۵ معرفی شد و در نسخه‌های بعدی به بلوغ رسید. این API شکاف دیرینه بین سیستم بلاک‌های گوتنبرگ و داده‌های پویا مانند متادیتای نوشته، داده‌های تاکسونومی، و خروجی APIهای خارجی را پر می‌کند. برخلاف رویکرد سنتی که در آن برای نمایش داده پویا نیاز به ساخت بلاک سفارشی یا استفاده از شورت‌کد بود، Block Bindings API به بلاک‌های موجود اجازه می‌دهد مقادیر اتریبیوت‌های خود را از یک منبع داده خارجی دریافت کنند. این سیستم در سطح سرور عمل می‌کند و HTML نهایی را قبل از ارسال به مرورگر بازنویسی می‌نماید. در این راهنما، معماری، پیاده‌سازی، و نکات پیشرفته این API بررسی می‌شود.

نخستین بار که با مفهوم Block Bindings API مواجه شدم، بلافاصله به یاد مشکل همیشگی‌ام با بلاک‌های هسته افتادم: چگونه می‌توان یک بلاک پاراگراف را به یک فیلد سفارشی متصل کرد بدون نوشتن یک بلاک جدید؟ این API دقیقاً همان راه‌حل است، اما در لایه‌ای بسیار عمیق‌تر و انعطاف‌پذیرتر از آنچه در ابتدا به نظر می‌رسد. این راهنما حاصل پیاده‌سازی این API در پروژه‌های واقعی است. 🔗

Block Bindings API چیست؟

Block Bindings API (رابط برنامه‌نویسی اتصال بلاک) یک سیستم در وردپرس است که به اتریبیوت‌های بلاک اجازه می‌دهد مقادیر خود را از یک منبع داده خارجی دریافت کنند. این API از نسخه ۶.۵ وردپرس معرفی شد و به توسعه‌دهندگان امکان می‌دهد بدون ساخت بلاک سفارشی، داده‌های پویا را به بلاک‌های هسته متصل نمایند[reference:0]. در حقیقت، Block Bindings API یک لایه انتزاعی (Abstraction Layer) بین اتریبیوت‌های بلاک و منابع داده ایجاد می‌کند و در زمان رندر بلاک، مقدار اتریبیوت را با مقدار بازگشتی از منبع جایگزین می‌نماید.

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

این سیستم مشابه مفهوم Data Binding در فریم‌ورک‌هایی مانند Angular و React است، اما در سطح سرور و بدون نیاز به جاوااسکریپت اجرا می‌شود. برای آشنایی با مبانی بلاک‌های گوتنبرگ، مقاله Gutenberg چیست و چگونه ویرایش محتوای وردپرس را متحول کرد؟ را ببینید.

Block Bindings API یک پل بین ایستایی بلاک‌ها و پویایی داده‌هاست؛ پلی که در سطح موتور رندر وردپرس ساخته شده است.

چرا Block Bindings API یک تغییر معماری است؟

برای درک اهمیت Block Bindings API، باید به ریشه مشکل نگاه کرد. بلاک‌های گوتنبرگ به صورت ماهوی ایستا (Static) هستند. وقتی یک بلاک پاراگراف را در ویرایشگر ایجاد می‌کنید، محتوای آن به صورت HTML در دیتابیس ذخیره می‌شود. این رویکرد برای محتوای ثابت عالی است، اما برای داده‌های پویا مانند قیمت محصول، نام نویسنده، یا وضعیت موجودی، مناسب نیست.

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

Block Bindings API رویکردی متفاوت ارائه می‌دهد. به جای ساخت یک بلاک جدید یا بازنویسی کل HTML، فقط اتریبیوت‌های مشخصی از بلاک را با مقادیر داینامیک جایگزین می‌کند. این رویکرد حداقلی (Minimal) به توسعه‌دهندگان کنترل دقیقی بر اینکه کدام بخش از بلاک پویا باشد، می‌دهد. این طراحی مشابه الگوی Decorator در برنامه‌نویسی است که در آن رفتار یک آبجکت بدون تغییر ساختار آن گسترش می‌یابد.

از منظر معماری وردپرس، این API شکاف بین سیستم بلاک‌های ایستا و نیازهای داده‌های داینامیک را پر می‌کند. این شکاف یکی از دلایل اصلی کندی پذیرش Full Site Editing در پروژه‌های سازمانی بود. برای مطالعه درباره FSE، مقاله چرا Full Site Editing در وردپرس آن‌قدر که فکر می‌کنید ساده نیست؟ را ببینید.

تاریخچه و تکامل در نسخه‌های وردپرس

Block Bindings API در نسخه ۶.۵ وردپرس معرفی شد. در این نسخه اولیه، دو منبع داخلی ارائه شد: core/post-meta برای اتصال به فیلدهای سفارشی نوشته، و core/pattern-overrides برای استفاده در الگوهای همگام (Synced Patterns)[reference:1].

در وردپرس ۶.۶، قابلیت Pattern Overrides به عنوان یک ویژگی قدرتمند بر پایه Block Bindings API معرفی شد. این قابلیت به کاربران اجازه می‌دهد مقادیر مشخصی را در الگوهای همگام تغییر دهند بدون اینکه ساختار اصلی الگو دستکاری شود[reference:2].

وردپرس ۶.۷ گام مهمی در تکامل این API برداشت. یک رابط کاربری جدید در ویرایشگر بلاک اضافه شد که به مدیران و ویرایشگران اجازه می‌دهد اتریبیوت‌ها را مستقیماً از پنل تنظیمات بلاک به فیلدهای سفارشی متصل کنند، بدون نیاز به ویرایشگر کد[reference:3]. همچنین در این نسخه، فیلتر block_bindings_source_value معرفی شد که امکان تغییر مقدار بازگشتی از منبع را قبل از اعمال فراهم می‌کند[reference:4].

وردپرس ۶.۹ پشتیبانی از بلاک‌های بیشتری را اضافه کرد و منبع core/post-data گسترش یافت. همچنین فیلتر جدید block_bindings_supported_attributes معرفی شد که به بلاک‌های سفارشی اجازه می‌دهد به صورت انتخابی از Block Bindings API پشتیبانی کنند[reference:5]. در وردپرس ۷.۰، Pattern Overrides برای هر اتریبیوتی که از Block Bindings پشتیبانی می‌کند، از جمله بلاک‌های سفارشی، فعال شد[reference:6].

جدول ۱: تکامل Block Bindings API در نسخه‌های وردپرس
نسخه	قابلیت‌های کلیدی
۶.۵	معرفی API، منابع core/post-meta و core/pattern-overrides
۶.۶	Pattern Overrides در الگوهای همگام
۶.۷	رابط کاربری ویرایشگر، فیلتر block_bindings_source_value
۶.۹	پشتیبانی از بلاک‌های بیشتر، فیلتر block_bindings_supported_attributes
۷.۰	گسترش Pattern Overrides به بلاک‌های سفارشی

معماری فنی و نحوه کار در سطح موتور رندر

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

Block Bindings API در این فرآیند مداخله می‌کند. قبل از تولید HTML نهایی، وردپرس اتریبیوت metadata.bindings بلاک را بررسی می‌کند. اگر Binding تعریف شده باشد، سیستم منبع داده مربوطه را فراخوانی کرده و مقدار بازگشتی را به جای مقدار اصلی اتریبیوت قرار می‌دهد. این فرآیند به صورت کاملاً شفاف (Transparent) انجام می‌شود و بلاک از وجود آن بی‌خبر است.

در سطح پیاده‌سازی، کلاس WP_Block_Bindings_Registry مسئول مدیریت منابع ثبت‌شده است. هر منبع شامل یک نام یکتا، یک برچسب قابل خواندن، و یک تابع بازگشتی (Callback) است که مقدار را از منبع استخراج می‌کند. تابع بازگشتی سه پارامتر دریافت می‌کند: $source_args (آرگومان‌های تعریف‌شده در Binding)، $block_instance (نمونه بلاک)، و $attribute_name (نام اتریبیوت)[reference:7].

یکی از جنبه‌های مهم معماری، استفاده از Context است. برخی منابع داده نیازمند دسترسی به اطلاعات زمینه‌ای مانند شناسه نوشته فعلی (Post ID) یا نوع نوشته (Post Type) هستند. Block Bindings API از طریق پارامتر uses_context این اطلاعات را به تابع بازگشتی منتقل می‌کند[reference:8]. برای مثال، یک منبع که داده را از متادیتای نوشته فعلی می‌خواند، باید postId را در uses_context تعریف کند تا شناسه نوشته در دسترس باشد.

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

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

جدول ۲: بلاک‌های پشتیبانی‌شده از Block Bindings API
بلاک	اتریبیوت‌های پشتیبانی‌شده
Paragraph (پاراگراف)	content
Heading (عنوان)	content
Image (تصویر)	id، url، title، alt
Button (دکمه)	text، url، linkTarget، rel

در وردپرس ۶.۹، بلاک‌های بیشتری مانند core/post-date و core/navigation-link نیز پشتیبانی از Binding را دریافت کردند[reference:9]. برای بلاک‌های سفارشی، از وردپرس ۷.۰ می‌توان از فیلتر block_bindings_supported_attributes برای اعلام پشتیبانی اتریبیوت‌های خاص استفاده کرد[reference:10].

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

ثبت منبع سفارشی با PHP

قلب Block Bindings API، توانایی ثبت منابع سفارشی است. برای ثبت یک منبع، از تابع register_block_bindings_source() استفاده می‌شود که باید در هوک init فراخوانی شود[reference:11]. این تابع دو پارامتر می‌پذیرد: نام منبع (با پیشوند namespace) و آرایه‌ای از تنظیمات.

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

label: نام قابل خواندن برای نمایش در ویرایشگر
get_value_callback: تابع بازگشتی که مقدار را استخراج می‌کند
uses_context: آرایه‌ای از مقادیر زمینه‌ای مورد نیاز (اختیاری)

نمونه‌ای از ثبت یک منبع سفارشی برای خواندن متادیتای نوشته:

add_action( 'init', function () {
    register_block_bindings_source( 'my-plugin/post-meta', array(
        'label'              => __( 'Post Meta', 'my-plugin' ),
        'get_value_callback' => function ( array $source_args, $block_instance ) {
            $post_id = $block_instance->context['postId'];
            if ( isset( $source_args['key'] ) ) {
                return get_post_meta( $post_id, $source_args['key'], true );
            }
            return false;
        },
        'uses_context'       => array( 'postId' ),
    ) );
} );

در این مثال، منبع my-plugin/post-meta ثبت شده که از متادیتای نوشته فعلی مقدار را استخراج می‌کند. پارامتر uses_context تضمین می‌کند که postId در دسترس تابع بازگشتی باشد. برای آشنایی با هوک‌های وردپرس، مقاله آموزش استفاده از هوک‌های وردپرس برای توسعه‌دهندگان را ببینید.

در وردپرس ۶.۷ به بعد، تابع بازگشتی می‌تواند سه پارامتر دریافت کند: $source_args، $block_instance، و $attribute_name[reference:12]. پارامتر سوم به توسعه‌دهنده اجازه می‌دهد بسته به اتریبیوتی که Binding روی آن اعمال شده، رفتار متفاوتی داشته باشد.

استفاده از Binding در قالب و محتوا

پس از ثبت منبع، می‌توان از آن در اتریبیوت metadata.bindings بلاک استفاده کرد. این کار در سطح مارک‌آپ HTML انجام می‌شود. برای مثال، یک بلاک پاراگراف که محتوای آن از فیلد سفارشی office_email خوانده می‌شود:

<!-- wp:paragraph {
    "metadata": {
        "bindings": {
            "content": {
                "source": "my-plugin/post-meta",
                "args": {
                    "key": "office_email"
                }
            }
        }
    }
} -->
<p>متن پیش‌فرض که جایگزین می‌شود.</p>
<!-- /wp:paragraph -->

در این مارک‌آپ، source نام منبع ثبت‌شده و args شامل پارامترهای اضافی است که به تابع بازگشتی منتقل می‌شوند. نکته مهم این است که متن پیش‌فرض در HTML ذخیره می‌شود و در صورت عدم دسترسی به منبع داده، همان متن نمایش داده می‌شود.

در وردپرس ۶.۷ به بعد، همین Binding را می‌توان از طریق رابط کاربری ویرایشگر نیز ایجاد کرد. در پنل تنظیمات بلاک، بخش «Attributes» اضافه شده است که در آن می‌توان اتریبیوت مورد نظر را انتخاب و به یک فیلد سفارشی متصل کرد[reference:13].

مثال‌های عملی در پروژه‌های واقعی

۱. نمایش اطلاعات تماس در قالب تک‌نوشته

فرض کنید یک نوع نوشته سفارشی به نام «دفاتر» (Offices) دارید که شامل فیلدهای شماره تلفن و وب‌سایت است. با Block Bindings API می‌توانید در قالب تک‌نوشته (Single Template) بلاک‌های پاراگراف را به این فیلدها متصل کنید:

add_action( 'init', function () {
    register_block_bindings_source( 'my-theme/office-meta', array(
        'label'              => __( 'Office Contact Info', 'my-theme' ),
        'get_value_callback' => function ( $source_args ) {
            $office_email = get_post_meta( get_the_ID(), 'office_email', true );
            if ( $office_email ) {
                return sprintf(
                    '<a href="mailto:%s">%s</a>',
                    esc_html( $office_email ),
                    esc_html( $office_email )
                );
            }
            return false;
        },
        'uses_context'       => array( 'postId' ),
    ) );
} );

سپس در قالب، بلاک پاراگراف را به این منبع متصل می‌کنید. در صورت عدم وجود فیلد سفارشی، بلاک به صورت خالی نمایش داده می‌شود[reference:14].

۲. نمایش کپی‌رایت تصویر از متادیتای پیوست

در پروژه‌های رسانه‌ای، نمایش اطلاعات کپی‌رایت تصویر یک نیاز رایج است. با Block Bindings API می‌توان بلاک تصویر را به متادیتای پیوست متصل کرد:

register_block_bindings_source( 'my-plugin/image-copyright', array(
    'label'              => 'Image Copyright',
    'get_value_callback' => function ( array $source_args, $block_instance ) {
        $post_id = $block_instance->context['postId'];
        $thumbnail_id = get_post_thumbnail_id( $post_id );
        $metadata = wp_get_attachment_metadata( $thumbnail_id );
        return $metadata['image_meta']['copyright'] ?? false;
    },
    'uses_context'       => array( 'postId' ),
) );

این منبع از Context شناسه نوشته استفاده کرده و شناسه تصویر شاخص را استخراج می‌کند. سپس متادیتای پیوست را خوانده و مقدار کپی‌رایت را برمی‌گرداند[reference:15].

۳. یکپارچه‌سازی با ACF

افزونه Advanced Custom Fields (ACF) از Block Bindings API پشتیبانی می‌کند. با استفاده از منبع acf/field می‌توانید فیلدهای ACF را به بلاک‌های هسته متصل کنید. برای مطالعه درباره ACF، مقاله فیلدهای سفارشی ACF و کاربردهای واقعی آن را ببینید.

Pattern Overrides و اتصال در الگوهای همگام

یکی از قدرتمندترین کاربردهای Block Bindings API، قابلیت Pattern Overrides است. الگوهای همگام (Synced Patterns) مجموعه‌های از پیش تعریف‌شده از بلاک‌ها هستند که در چندین صفحه قابل استفاده مجدد هستند. پیش از Block Bindings API، تغییر محتوای یک الگو در یک صفحه خاص نیازمند جدا کردن آن الگو بود.

با Pattern Overrides، می‌توان بلاک‌های خاصی را به عنوان «قابل تغییر» علامت‌گذاری کرد. سپس در هر نمونه از الگو، کاربر می‌تواند مقدار آن بلاک را بدون تأثیر بر سایر نمونه‌ها تغییر دهد. این قابلیت بر پایه منبع core/pattern-overrides کار می‌کند[reference:16].

در وردپرس ۷.۰، Pattern Overrides برای هر اتریبیوتی که از Block Bindings پشتیبانی می‌کند، از جمله بلاک‌های سفارشی، گسترش یافت[reference:17]. این بدان معناست که توسعه‌دهندگان می‌توانند بلاک‌های سفارشی خود را برای Pattern Overrides فعال کنند.

رابط کاربری ویرایشگر در وردپرس ۶.۷ به بعد

تا پیش از وردپرس ۶.۷، ایجاد Binding نیازمند ویرایش مستقیم کد HTML یا استفاده از ویرایشگر کد بود. این محدودیت استفاده از این API را برای کاربران غیرفنی دشوار می‌کرد. وردپرس ۶.۷ یک رابط کاربری جدید به نام «Attributes Panel» معرفی کرد که در آن می‌توان با چند کلیک ساده، اتریبیوت‌های بلاک را به فیلدهای سفارشی متصل کرد.

در این رابط، کاربر بلاک مورد نظر را انتخاب کرده، به پنل تنظیمات می‌رود، و بخش «Attributes» را باز می‌کند. در آنجا می‌تواند اتریبیوت مورد نظر (مانند محتوای پاراگراف) را انتخاب و منبع داده را مشخص کند. اگر منبع core/post-meta باشد، لیست فیلدهای سفارشی موجود نمایش داده می‌شود و کاربر می‌تواند فیلد مورد نظر را انتخاب کند[reference:18].

در نسخه‌های فعلی، این رابط کاربری فقط از منبع core/post-meta پشتیبانی می‌کند. توسعه‌دهندگان در حال کار بر روی گسترش آن برای پشتیبانی از منابع سفارشی هستند[reference:19]. برای آشنایی با سایر قابلیت‌های ویرایشگر، مقاله WordPress Command Palette چطور سرعت کار با وردپرس را چند برابر می‌کند؟ را ببینید.

افزودن پشتیبانی Binding به بلاک‌های سفارشی

از وردپرس ۷.۰، بلاک‌های سفارشی می‌توانند از طریق فیلتر block_bindings_supported_attributes پشتیبانی از Block Bindings را اعلام کنند. این فیلتر به توسعه‌دهنده اجازه می‌دهد لیستی از اتریبیوت‌های قابل Binding را تعریف کند:

add_filter(
    'block_bindings_supported_attributes',
    function ( $supported_attributes, $block_type ) {
        if ( 'my-plugin/custom-block' === $block_type ) {
            $supported_attributes[] = 'title';
            $supported_attributes[] = 'description';
        }
        return $supported_attributes;
    },
    10,
    2
);

پس از این تعریف، اتریبیوت‌های title و description بلاک سفارشی قابل اتصال به منابع داده خواهند بود[reference:20]. این قابلیت به توسعه‌دهندگان اجازه می‌دهد بلاک‌های سفارشی خود را به همان سطحی از پویایی برسانند که بلاک‌های هسته دارند.

ملاحظات امنیتی و محدودیت‌ها

Block Bindings API دارای ملاحظات امنیتی مهمی است که توسعه‌دهندگان باید از آن‌ها آگاه باشند. یکی از مهم‌ترین محدودیت‌ها این است که فیلدهای متادیتا که با زیرخط (Underscore) شروع می‌شوند، در Block Bindings API قابل استفاده نیستند. این فیلدها به عنوان محافظت‌شده (Protected) در نظر گرفته می‌شوند و معمولاً برای داده‌های حساس استفاده می‌شوند[reference:21].

محدودیت دیگر این است که فیلدهای متادیتا باید از طریق REST API قابل دسترسی باشند. این بدان معناست که در تعریف register_meta() باید show_in_rest روی true تنظیم شود. این محدودیت یک لایه امنیتی اضافی ایجاد می‌کند، زیرا فیلدهایی که از REST API مخفی هستند، از Block Bindings API نیز مخفی می‌مانند[reference:22].

در وردپرس ۶.۷، کنترل دسترسی به Block Bindings UI اضافه شد. به طور پیش‌فرض، فقط مدیران (Administrators) می‌توانند Binding ایجاد یا ویرایش کنند. این محدودیت از سوءاستفاده کاربران کم‌دسترسی جلوگیری می‌کند[reference:23].

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

عملکرد و بهینه‌سازی

Block Bindings API از دو جنبه بر عملکرد تأثیر می‌گذارد: عملکرد سرور و عملکرد ویرایشگر. در سمت سرور، هر Binding نیازمند فراخوانی تابع بازگشتی و خواندن از منبع داده است. اگر منبع داده یک API خارجی باشد، این فراخوانی می‌تواند زمان‌بر باشد. برای بهینه‌سازی، توصیه می‌شود که داده‌های پرکاربرد را در حافظه کش (Object Cache) ذخیره کنید.

در سمت ویرایشگر، Block Bindings API از طریق جاوااسکریپت مدیریت می‌شود. در نسخه‌های اولیه، برخی مشکلات عملکردی در رندر مجدد بلاک‌های Bound وجود داشت. تیم گوتنبرگ با انتقال محاسبات به useSelect و حذف رندرهای غیرضروری، این مشکلات را برطرف کرد[reference:24].

یکی از جنبه‌های مهم بهینه‌سازی، کاهش تعداد فیلدهای متادیتای ثبت‌شده است. هر فیلد متادیتا که show_in_rest دارد، در پاسخ‌های REST API ظاهر می‌شود. اگر تعداد این فیلدها زیاد باشد، حجم پاسخ‌ها افزایش می‌یابد. توصیه می‌شود فقط فیلدهایی که واقعاً به Binding نیاز دارند، show_in_rest داشته باشند. برای مطالعه درباره بهینه‌سازی، مقاله چگونه سرعت سایت وردپرسی را افزایش دهیم؟ را ببینید.

هر Binding یک فراخوانی اضافی در زمان رندر است. بهینه‌سازی یعنی تعادل بین پویایی و عملکرد.

اشتباهات رایج در پیاده‌سازی

در پیاده‌سازی Block Bindings API، برخی اشتباهات رایج می‌توانند به مشکلات جدی منجر شوند:

فراموش کردن uses_context: اگر تابع بازگشتی به postId یا سایر Contextها نیاز دارد و uses_context تعریف نشده باشد، این مقادیر در دسترس نخواهند بود.
ثبت نکردن متادیتا با show_in_rest: فیلدهای متادیتا باید با show_in_rest => true ثبت شوند تا از طریق REST API قابل دسترسی باشند.
استفاده از فیلدهای Protected: فیلدهایی که با زیرخط شروع می‌شوند قابل Binding نیستند و تلاش برای استفاده از آن‌ها خطا ایجاد می‌کند.
عدم پاک‌سازی داده‌های بازگشتی: تابع بازگشتی باید داده‌ها را پاک‌سازی (Sanitize) کند تا از حملات XSS جلوگیری شود.
نادیده گرفتن مقادیر پیش‌فرض: اگر منبع داده مقدار برنگرداند، بلاک به صورت خالی یا با متن پیش‌فرض نمایش داده می‌شود. طراحی مناسب برای این حالت ضروری است.
استفاده در بلاک‌های غیرپشتیبانی‌شده: Block Bindings API فقط از بلاک‌های خاصی پشتیبانی می‌کند. تلاش برای Binding روی اتریبیوت‌های پشتیبانی‌نشده نادیده گرفته می‌شود.

دیدگاه مهندسی پیشرفته

از منظر مهندسی نرم‌افزار، Block Bindings API یک پیاده‌سازی از الگوی Inversion of Control (وارونگی کنترل) است. در این الگو، به جای اینکه بلاک مسئول دریافت داده باشد، یک منبع خارجی داده را تأمین می‌کند و بلاک فقط آن را نمایش می‌دهد. این جداسازی مسئولیت‌ها (Separation of Concerns) کد را قابل نگهداری‌تر و آزمایش‌پذیرتر می‌کند.

معماری این API از الگوی Registry برای مدیریت منابع استفاده می‌کند. کلاس WP_Block_Bindings_Registry به عنوان یک Singleton عمل می‌کند و منابع ثبت‌شده را در یک آرایه داخلی نگهداری می‌نماید. این رویکرد مشابه سیستم هوک‌های وردپرس است و توسعه‌دهندگان را با آن آشنا می‌کند.

در سطح موتور رندر، Block Bindings API از فیلتر block_bindings_source_value برای مداخله در مقدار بازگشتی استفاده می‌کند. این فیلتر به توسعه‌دهندگان اجازه می‌دهد مقدار نهایی را قبل از اعمال تغییر دهند. این قابلیت مشابه فیلترهای وردپرس است و انعطاف‌پذیری بالایی فراهم می‌کند[reference:25].

یکی از جنبه‌های پیشرفته، تعامل Block Bindings API با Interactivity API است. در حالی که Block Bindings برای داده‌های ایستا در زمان رندر استفاده می‌شود، Interactivity API برای تعاملات داینامیک در فرانت‌اند به کار می‌رود. ترکیب این دو API امکان ساخت رابط‌های کاربری پویا با داده‌های سرور را فراهم می‌کند[reference:26].

در آینده، انتظار می‌رود که Block Bindings API با قابلیت‌هایی مانند Binding شرطی (Conditional Binding) و Binding مبتنی بر نقش کاربر گسترش یابد. همچنین، ادغام با Abilities API و هوش مصنوعی می‌تواند امکان تولید خودکار Bindingها را فراهم کند. توسعه‌دهندگانی که امروز بر این API مسلط شوند، در آینده مزیت رقابتی خواهند داشت. برای مطالعه درباره آینده وردپرس، مقاله گوتنبرگ و آینده ویرایش محتوا در وردپرس را ببینید.

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

Block Bindings API چیست و چه تفاوتی با بلاک‌های داینامیک دارد؟

Block Bindings API یک سیستم برای اتصال اتریبیوت‌های بلاک به منابع داده خارجی است. برخلاف بلاک‌های داینامیک که کل HTML را در هر بار بارگذاری بازنویسی می‌کنند، Block Bindings فقط اتریبیوت‌های مشخصی را جایگزین می‌کند و ساختار بلاک را حفظ می‌نماید.

چگونه یک منبع سفارشی برای Block Bindings API ثبت کنم؟

با استفاده از تابع register_block_bindings_source() در هوک init می‌توانید یک منبع سفارشی ثبت کنید. این تابع نام منبع، برچسب، و تابع بازگشتی را دریافت می‌کند.

آیا Block Bindings API از فیلدهای سفارشی ACF پشتیبانی می‌کند؟

بله، افزونه ACF از Block Bindings API پشتیبانی می‌کند و می‌توانید فیلدهای ACF را به بلاک‌های هسته متصل کنید. برای این کار از منبع acf/field استفاده کنید.

چرا فیلدهای متادیتا با زیرخط در Block Bindings API قابل استفاده نیستند؟

فیلدهای متادیتا که با زیرخط شروع می‌شوند به عنوان محافظت‌شده (Protected) در نظر گرفته می‌شوند و از طریق REST API قابل دسترسی نیستند. از آنجا که Block Bindings API برای داده‌های سرور به REST API وابسته است، این فیلدها قابل استفاده نیستند.

آیا Block Bindings API بر سرعت سایت تأثیر منفی دارد؟

تأثیر آن بستگی به پیاده‌سازی دارد. هر Binding یک فراخوانی اضافی در زمان رندر است. اگر منبع داده در حافظه کش شود یا داده‌ها از متادیتای نوشته خوانده شوند، تأثیر ناچیز است. اما اگر منبع داده یک API خارجی باشد، می‌تواند زمان رندر را افزایش دهد.

چگونه Pattern Overrides با Block Bindings API کار می‌کند؟

Pattern Overrides بر پایه منبع core/pattern-overrides کار می‌کند. وقتی یک الگوی همگام دارای بلاک‌های Bound باشد، کاربر می‌تواند مقادیر آن بلاک‌ها را در هر نمونه تغییر دهد بدون تأثیر بر سایر نمونه‌ها.

آیا می‌توانم از Block Bindings API در بلاک‌های سفارشی استفاده کنم؟

بله، از وردپرس ۷.۰ می‌توانید با استفاده از فیلتر block_bindings_supported_attributes اتریبیوت‌های قابل Binding بلاک سفارشی خود را اعلام کنید.

آنچه در عمل اهمیت دارد

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

برای توسعه‌دهندگان، تسلط بر Block Bindings API به یک مهارت ضروری تبدیل شده است. این API نه تنها در پروژه‌های FSE کاربرد دارد، بلکه در ساخت قالب‌های سفارشی، یکپارچه‌سازی با سیستم‌های خارجی، و ساخت الگوهای پویا نیز نقش کلیدی ایفا می‌کند. با گسترش مداوم قابلیت‌های این API در نسخه‌های آینده، سرمایه‌گذاری بر یادگیری آن ارزشمند خواهد بود. 🚀

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