iframe اجباری ویرایشگر و Block API نسخه ۳؛ برای قالب‌سازها

Block API v3 یعنی نسخه سوم API بلاک‌های گوتنبرگ که با درج "apiVersion": 3 در فایل block.json اعلام می‌کند بلاک شما آماده اجرا داخل ویرایشگرِ iframe‌شده است. از وردپرس ۷.۱ (منتشرشده در ۱۹ اوت ۲۰۲۶) ویرایشگر نوشته برای همه قالب‌ها همیشه داخل iframe بارگذاری می‌شود؛ بنابراین هر قالب یا افزونه‌ای که بلاک سفارشی دارد باید با این محیط سازگار باشد.

نویسنده: تیم siloow (سیلو سولوشن) — آخرین به‌روزرسانی: آبان ۱۴۰۵

وضعیت تا آبان ۱۴۰۵: وردپرس ۷.۰ (مه ۲۰۲۶) فقط وقتی ویرایشگر نوشته را iframe می‌کرد که همه بلاک‌های درج‌شده در نوشته نسخه ۳ یا بالاتر باشند. وردپرس ۷.۱ (۱۹ اوت ۲۰۲۶) این شرط را حذف کرد و ویرایشگر نوشته را برای همه قالب‌ها، کلاسیک یا بلاکی، همیشه iframe می‌کند.

در این راهنمای فنی برای قالب‌سازها و توسعه‌دهنده‌های افزونه توضیح می‌دهیم iframe اجباری دقیقاً چه چیزی را تغییر داده، کدام کدها در محیط جدید از کار می‌افتند، چطور بلاک را به Block API v3 مهاجرت دهید، استایل‌ها را با کدام هوک بارگذاری کنید و چطور قبل از آپدیت سایت مشتری همه چیز را تست کنید.

Block API v3 چیست و چه فرقی با نسخه‌های ۱ و ۲ دارد؟

Block API v3 نسخه‌ای از API بلاک است که از وردپرس ۶.۳ معرفی شد و تنها پیامش این است: «این بلاک داخل iframe درست کار می‌کند». بر اساس مستندات رسمی نسخه‌های Block API، نسخه ۲ (از وردپرس ۵.۶) استفاده از هوک useBlockProps() را برای عنصر دربرگیرنده بلاک الزامی کرد و نسخه ۳ سازگاری با ویرایشگر iframe‌شده را اعلام می‌کند.

نسخه API	از چه نسخه وردپرس	تغییر اصلی	وضعیت در وردپرس ۷.۱
apiVersion 1	نسخه اولیه گوتنبرگ	کلاس‌ها و استایل‌ها خودکار به عنصر بیرونی اضافه می‌شد	داخل iframe اجرا می‌شود؛ بدون تضمین سازگاری
apiVersion 2	۵.۶	الزام useBlockProps() و useBlockProps.save()	داخل iframe اجرا می‌شود؛ بیشتر بلاک‌ها مشکلی ندارند
apiVersion 3	۶.۳	اعلام آمادگی برای اجرا داخل iframe	نسخه توصیه‌شده برای همه بلاک‌ها

نکته مهم این است که خود عدد ۳ رفتار رندر بلاک را عوض نمی‌کند؛ عدد ۳ فقط یک تعهد است. اگر کد بلاک هنوز به document سراسری صفحه مدیریت تکیه کند، با عوض کردن عدد درست نمی‌شود.

iframe اجباری ویرایشگر در وردپرس ۷.۱ چه چیزی را تغییر داد؟

iframe اجباری یعنی بوم ویرایش نوشته (همان ناحیه‌ای که بلاک‌ها در آن رندر می‌شوند) همیشه یک سند HTML جدا داخل یک iframe است و از رابط مدیریت وردپرس جدا می‌شود. اطلاعیه رسمی وردپرس ۷.۱ می‌گوید ویرایشگر نوشته اکنون برای همه قالب‌ها کاملاً iframe‌شده است، درست مثل ویرایشگر سایت.

این تغییر یک‌شبه اتفاق نیفتاد. مسیر آن طبق یادداشت‌های تیم هسته در make.wordpress.org این بود:

1. وردپرس ۶.۳: ویرایشگر نوشته فقط وقتی iframe می‌شد که همه بلاک‌های ثبت‌شده در سایت نسخه ۳ باشند و متاباکس سنتی وجود نداشته باشد.
2. وردپرس ۶.۹: با فعال بودن SCRIPT_DEBUG برای بلاک‌های نسخه ۲ و پایین‌تر هشدار کنسول نمایش داده شد.
3. وردپرس ۷.۰: طبق یادداشت تغییرات iframe در ۷.۰، فقط بلاک‌های درج‌شده در همان نوشته بررسی می‌شدند؛ اگر یک بلاک نسخه پایین‌تر وجود داشت، iframe حذف می‌شد.
4. افزونه گوتنبرگ ۲۲.۶ به بعد: iframe برای همه قالب‌ها، از جمله قالب‌های کلاسیک، اجباری شد تا بازخورد جمع شود.
5. وردپرس ۷.۱: طبق یادداشت تغییرات iframe در ۷.۱، ویرایشگر نوشته فارغ از نوع قالب و نسخه API بلاک‌ها همیشه iframe است.

نتیجه عملی برای قالب‌ساز: دیگر «راه فرار» خودکار وجود ندارد. قبلاً یک بلاک قدیمی نسخه ۲ کافی بود تا ویرایشگر به حالت بدون iframe برگردد و مشکل پنهان بماند؛ از ۷.۱ همان بلاک داخل iframe اجرا می‌شود و اگر ایرادی داشته باشد، ایراد دیده می‌شود.

چرا وردپرس ویرایشگر را داخل iframe می‌برد؟

وردپرس ویرایشگر را داخل iframe می‌برد تا استایل‌های پیشخوان روی محتوا اثر نگذارند و آنچه در ویرایشگر می‌بینید به ظاهر واقعی سایت نزدیک‌تر باشد. سه مزیت اصلی این جداسازی:

• ایزوله شدن استایل‌ها: CSS پیشخوان (مثل استایل دکمه‌ها و جدول‌های wp-admin) دیگر به محتوای نوشته نشت نمی‌کند و قالب مجبور نیست با !important با آن بجنگد.
• واحدهای واقعی viewport: مدیا کوئری‌ها و واحدهایی مثل vw نسبت به عرض بوم سنجیده می‌شوند، نه کل صفحه مدیریت؛ پیش‌نمایش موبایل و تبلت دقیق‌تر می‌شود. این موضوع برای استایل‌های ریسپانسیو جدید وردپرس ۷.۱ اهمیت زیادی دارد.
• یکسان شدن ویرایشگرها: ویرایشگر سایت، قالب‌ها و پیش‌نمایش دستگاه‌ها از قبل iframe بودند؛ حالا ویرایشگر نوشته هم همان رفتار را دارد و توسعه‌دهنده فقط یک محیط را باید پشتیبانی کند.

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

در ویرایشگر iframe‌شده بیشتر خرابی‌ها از یک ریشه می‌آیند: اسکریپت ویرایشگر در سند صفحه مدیریت اجرا می‌شود، اما بلاک‌ها در سند دیگری داخل iframe رندر می‌شوند. هر کدی که فرض کند این دو یکی هستند، شکست می‌خورد.

الگوی مشکل‌دار	علامت خرابی	راه درست
document.querySelector برای پیدا کردن عنصر بلاک	عنصر پیدا نمی‌شود و کد بی‌صدا کار نمی‌کند	گرفتن عنصر با ref و استفاده از element.ownerDocument
شنونده رویداد روی document یا window سراسری	کلیک بیرون از بلاک یا کلید Escape داخل بوم تشخیص داده نمی‌شود	useRefEffect و ownerDocument.defaultView
استایل محتوا با enqueue_block_editor_assets	ظاهر بلاک در ویرایشگر به هم می‌ریزد	editorStyle و style در block.json یا هوک enqueue_block_assets
سلکتورهای .wp-admin یا body.block-editor-page	قانون CSS به هیچ عنصری نمی‌خورد	محدود کردن استایل به کلاس خود بلاک
کتابخانه شخص ثالث (اسلایدر، نقشه، تقویم) که خودش document را جستجو می‌کند	کتابخانه در ویرایشگر مقداردهی نمی‌شود	پاس دادن خود عنصر به جای سلکتور، یا گرفتن کتابخانه از defaultView

یادداشت رسمی ۷.۱ هم تأکید می‌کند که بیشتر بلاک‌ها نیازی به تغییر ندارند و مشکل رایج، کدی است که از document یا window سراسری برای دسترسی به بوم استفاده می‌کند.

چطور بلاک را به Block API v3 مهاجرت دهیم؟

مهاجرت به Block API v3 چهار گام دارد: تغییر عدد نسخه، اصلاح دسترسی به سند و پنجره، جابه‌جایی استایل‌ها به هوک درست و پاک‌سازی CSS وابسته به پیشخوان. راهنمای رسمی مهاجرت بلاک‌ها برای سازگاری با ویرایشگر iframe مرجع اصلی این کار است.

گام ۱: اعلام نسخه ۳ در block.json

اولین تغییر، درج "apiVersion": 3 در فایل block.json است. همین‌جا بهتر است استایل مخصوص ویرایشگر را هم با فیلد editorStyle معرفی کنید تا وردپرس آن را داخل iframe بارگذاری کند:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "siloow/price-card",
  "title": "کارت قیمت",
  "category": "widgets",
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

گام ۲: سند و پنجره را از خود عنصر بگیرید

به جای document و window سراسری، از عنصر بلاک شروع کنید: element.ownerDocument سند داخل iframe است و ownerDocument.defaultView پنجره همان سند. هوک useRefEffect از پکیج @wordpress/compose اجازه می‌دهد شنونده‌ها را هنگام اتصال عنصر بسازید و هنگام جدا شدن پاک کنید:

import { useBlockProps } from '@wordpress/block-editor';
import { useRefEffect } from '@wordpress/compose';

export default function Edit() {
  const ref = useRefEffect( ( element ) => {
    // سند و پنجره درست: داخل iframe ویرایشگر
    const { ownerDocument } = element;
    const { defaultView } = ownerDocument;

    function onKey( event ) {
      if ( event.key === 'Escape' ) {
        element.classList.remove( 'is-open' );
      }
    }
    ownerDocument.addEventListener( 'keydown', onKey );
    defaultView.addEventListener( 'resize', onKey );

    return () => {
      ownerDocument.removeEventListener( 'keydown', onKey );
      defaultView.removeEventListener( 'resize', onKey );
    };
  }, [] );

  return <div { ...useBlockProps( { ref } ) }>کارت قیمت</div>;
}

گام ۳: استایل‌ها را با هوک درست بارگذاری کنید

قانون ساده است: هر چیزی که روی ظاهر محتوا اثر دارد باید داخل iframe برسد و هر چیزی که مربوط به رابط ویرایشگر است بیرون آن بماند. طبق راهنمای بارگذاری فایل‌ها در ویرایشگر، هوک enqueue_block_assets هم در ویرایشگر iframe‌شده و هم در فرانت‌اند اجرا می‌شود و هوک enqueue_block_editor_assets فقط برای رابط ویرایشگر است:

<?php
// استایل محتوای بلاک‌ها: داخل iframe و فرانت‌اند
add_action( 'enqueue_block_assets', function () {
    wp_enqueue_style(
        'siloow-content',
        get_theme_file_uri( 'assets/content.css' ),
        array(),
        wp_get_theme()->get( 'Version' )
    );
} );

// فقط رابط کاربری ویرایشگر (پنل‌ها، تولبار)
add_action( 'enqueue_block_editor_assets', function () {
    wp_enqueue_script(
        'siloow-editor-ui',
        get_theme_file_uri( 'assets/editor-ui.js' ),
        array( 'wp-plugins', 'wp-edit-post' ),
        wp_get_theme()->get( 'Version' ),
        true
    );
} );

// استایل ویرایشگر قالب
add_action( 'after_setup_theme', function () {
    add_editor_style( 'assets/editor-style.css' );
} );

گام ۴: CSS وابسته به پیشخوان را پاک کنید

سلکتورهایی مثل #wpadminbar، محاسبه‌هایی مثل calc(100vw - 160px) که عرض منوی پیشخوان را کم می‌کردند و قانون‌های !important که برای غلبه بر استایل wp-admin نوشته شده بودند، داخل iframe یا بی‌اثرند یا نتیجه اشتباه می‌دهند. استایل هر بلاک را به کلاس .wp-block-namespace-name همان بلاک محدود کنید.

نکته: تغییر عدد apiVersion به ۳ بدون اصلاح کد، فقط مشکل را پنهان‌تر می‌کند. اول در محیط iframe تست کنید، بعد عدد را بالا ببرید.

قالب بلاکی و theme.json در این تغییر چه نقشی دارند؟

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

در وردپرس ۷.۱ قالب‌های بلاکی می‌توانند در theme.json نقاط شکست (breakpoint) موبایل و تبلت را خودشان تعریف کنند و حالت‌های hover، focus و active را هم بدون CSS دستی تنظیم کنند. این قابلیت‌ها را در مقاله وردپرس ۷.۱ «Mary Lou»؛ طراحی ریسپانسیو بدون CSS مفصل بررسی کرده‌ایم. پیش‌نمایش درست این استایل‌های ریسپانسیو دقیقاً به iframe وابسته است، چون مدیا کوئری‌ها باید عرض بوم را بسنجند.

قالب‌های کلاسیک هم از این تغییر مستثنا نیستند. ویرایشگر نوشته در قالب کلاسیک هم iframe می‌شود و استایل‌هایی که با add_editor_style() ثبت شده باشند به داخل بوم می‌رسند؛ اما استایل‌هایی که قالب کلاسیک با هوک‌های عمومی پیشخوان بارگذاری می‌کرد، دیگر روی محتوا اثر ندارند.

چطور قبل از آپدیت، سازگاری با Block API v3 را تست کنیم؟

بهترین روش تست سازگاری با Block API v3 این است که بلاک‌ها را در هر دو حالت iframe و غیر iframe روی یک نسخه staging بررسی کنید و کنسول مرورگر را با SCRIPT_DEBUG فعال زیر نظر داشته باشید. چک‌لیست پیشنهادی ما:

1. یک کپی staging از سایت بسازید و وردپرس را روی آن به ۷.۱ یا بالاتر ببرید.
2. در wp-config.php مقدار SCRIPT_DEBUG را روی true بگذارید تا هشدار بلاک‌های نسخه ۱ و ۲ در کنسول دیده شود.
3. برای اطمینان از iframe بودن بوم، در DevTools دنبال iframe[name="editor-canvas"] بگردید.
4. هر بلاک سفارشی را درج کنید و تعامل‌ها را امتحان کنید: کلیک بیرون از بلاک، میانبرهای کیبورد، اسلایدرها، نقشه‌ها و پاپ‌آپ‌ها.
5. ظاهر بلاک را در ویرایشگر با فرانت‌اند مقایسه کنید؛ اختلاف معمولاً یعنی استایل با هوک اشتباه بارگذاری شده.
6. افزونه‌هایی که بلاک‌ها را گسترش می‌دهند (مثل افزونه‌های افزودن تنظیمات به همه بلاک‌ها) را جداگانه تست کنید.

اگر سایت روی وردپرس ۷.۰ است و هنوز آپدیت نکرده‌اید، یادتان باشد که در ۷.۰ وجود یک بلاک قدیمی iframe را حذف می‌کند؛ پس تست روی ۷.۰ ممکن است مشکلات واقعی ۷.۱ را نشان ندهد. برای مرور کلی تغییرات نسخه قبل، مقاله وردپرس ۷.۰؛ مهم‌ترین تغییرات را ببینید.

محدودیت‌ها: چه چیزهایی هنوز روشن نیست؟

iframe اجباری برای بیشتر سایت‌ها بی‌دردسر است، اما چند محدودیت و نکته مبهم را باید در نظر داشت:

• یادداشت رسمی ۷.۱ هیچ فیلتر یا گزینه رسمی برای برگرداندن ویرایشگر نوشته به حالت بدون iframe معرفی نکرده است؛ بنابراین برنامه‌ریزی برای «خاموش کردن iframe» راه‌حل پایدار نیست.
• افزونه‌ها و قالب‌های قدیمی که دیگر به‌روزرسانی نمی‌شوند، به‌احتمال زیاد اصلاح نخواهند شد؛ در این حالت جایگزینی یا بازنویسی بلاک تنها گزینه واقعی است.
• کتابخانه‌های شخص ثالث قدیمی ممکن است به اصلاح دستی (patch) نیاز داشته باشند تا عنصر را به جای سلکتور بپذیرند.
• ایمن بودن بلاک در iframe جایگزین به‌روز نگه داشتن افزونه‌ها نیست؛ برای امنیت کلی سایت چک‌لیست امنیت وردپرس در ۲۰۲۶ را دنبال کنید.

از تجربه تیم siloow

تیم siloow قالب‌های اختصاصی وردپرس می‌سازد؛ از قالب کلینیک با نوبت‌دهی آنلاین تا قالب آکادمی آموزشی. در بازبینی بلاک‌های سفارشی برای ویرایشگر iframe‌شده، رایج‌ترین مشکلی که دیدیم استایل‌هایی بود که سال‌ها پیش برای «درست دیده شدن در پیشخوان» با هوک ویرایشگر و سلکتورهای wp-admin نوشته شده بودند. درس اصلی ما این بود که اگر استایل محتوا از ابتدا یک‌بار برای فرانت‌اند و ویرایشگر (با style و editorStyle در block.json) نوشته شود، مهاجرت به نسخه ۳ تقریباً فقط تغییر یک عدد است. بلاک‌های تعاملی مثل تب، آکاردئون و اسلایدر بیشترین زمان تست را می‌گیرند، چون معمولاً به document سراسری وابسته‌اند. اگر برای توسعه بلاک وردپرس روی سیستم شخصی کار می‌کنید، مقاله انتخاب مک برای توسعه‌دهنده هم ممکن است به کارتان بیاید.

جمع‌بندی

• از وردپرس ۷.۱ ویرایشگر نوشته برای همه قالب‌ها همیشه iframe است و نسخه API بلاک‌ها دیگر این تصمیم را تغییر نمی‌دهد.
• Block API v3 با "apiVersion": 3 در block.json اعلام می‌شود و یعنی بلاک داخل iframe درست کار می‌کند.
• ریشه بیشتر خرابی‌ها استفاده از document و window سراسری است؛ از ownerDocument و useRefEffect استفاده کنید.
• استایل محتوا را با editorStyle/style یا enqueue_block_assets بارگذاری کنید، نه enqueue_block_editor_assets.
• قبل از آپدیت سایت اصلی، روی staging با SCRIPT_DEBUG تست کنید.

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

منابع

• Iframed Editor Changes in WordPress 7.1 — Make WordPress Core
• Iframed Editor Changes in WordPress 7.0 — Make WordPress Core
• Block API Versions — Block Editor Handbook
• WordPress 7.1 “Mary Lou” — WordPress.org News

سوالات متداول درباره Block API v3