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

بلاک اختصاصی گوتنبرگ چیست و چرا برای ساخت آن از React استفاده میشود؟
بلاک اختصاصی گوتنبرگ یک عنصر قابل استفاده مجدد در ویرایشگر وردپرس است که میتواند برای نمایش محتوای مشخص یا اجرای یک قابلیت اختصاصی طراحی شود. برای مثال، میتوان بلاکی برای نمایش کارت خدمات، معرفی محصول، فراخوان اقدام (CTA)، جدول قیمت یا باکس اطلاعات ایجاد کرد. توسعهدهنده با استفاده از APIهای وردپرس و React، رفتار و ظاهر این اجزا را کنترل میکند. نتیجه این فرایند، افزایش انعطافپذیری ویرایشگر و کاهش نیاز به استفاده از کدهای تکراری در نوشتهها و صفحات است.
React چه نقشی در توسعه بلاکهای گوتنبرگ دارد؟
ویرایشگر بلوکی وردپرس از معماری React استفاده میکند و هر بلاک در محیط ویرایشگر از طریق یک کامپوننت React نمایش داده میشود. این کامپوننت معمولاً در بخش edit تعریف میشود و مسئول نمایش پیشنمایش بلاک، دریافت ورودی کاربر و بهروزرسانی ویژگیهای آن است. بنابراین آشنایی با مفاهیمی مانند کامپوننت، Props، State، JSX و مدیریت رویدادها برای توسعه بلاکهای اختصاصی اهمیت دارد.
وردپرس برای جلوگیری از توسعه مجدد اجزای رابط کاربری، مجموعهای از پکیجهای رسمی مانند @wordpress/block-editor و @wordpress/components را ارائه میدهد. با استفاده از این ابزارها میتوان کنترلهایی مانند فیلد متنی، انتخاب رنگ، تنظیمات کناری و ویرایش محتوای متنی را در اختیار کاربر قرار داد. در نتیجه، توسعهدهنده میتواند بهجای ساخت یک رابط کاربری کاملاً مستقل، از الگوهای استاندارد خود وردپرس استفاده کند.
بلاک اختصاصی چه تفاوتی با بلاکهای پیشفرض وردپرس دارد؟
بلاکهای پیشفرض مانند پاراگراف، تصویر، عنوان و دکمه برای نیازهای عمومی طراحی شدهاند؛ اما بلاک اختصاصی میتواند دقیقاً بر اساس ساختار یک پروژه ایجاد شود. فرض کنید یک وبسایت خدماتی به باکسی نیاز دارد که شامل عنوان، توضیح کوتاه، تصویر، رنگ پسزمینه و دکمه تماس باشد. استفاده از چند بلاک عمومی برای ساخت این بخش ممکن است باعث تکرار تنظیمات و کاهش یکپارچگی طراحی شود.
با توسعه یک بلاک اختصاصی، تمام این عناصر در قالب یک کامپوننت قابل مدیریت قرار میگیرند. همچنین میتوان محدودیتهایی برای ورودیها تعیین کرد تا نویسندگان محتوا نتوانند ناخواسته ساختار طراحی را تغییر دهند. این موضوع برای وبسایتهای سازمانی، فروشگاهی و محتوایی اهمیت دارد؛ زیرا یکپارچگی بصری و کنترل کیفیت صفحات را بهبود میدهد.
برای ساخت بلاک اختصاصی گوتنبرگ به چه ابزارها و پیشنیازهایی نیاز داریم؟
پیش از شروع توسعه، باید محیط برنامهنویسی مناسبی آماده شود. مهمترین پیشنیازها شامل نصب وردپرس، دسترسی به محیط توسعه محلی، Node.js، npm و آشنایی مقدماتی با JavaScript و React هستند. همچنین بهتر است توسعه بلاک در قالب یک افزونه مستقل انجام شود تا با تغییر قالب سایت، قابلیت ایجادشده از بین نرود. وردپرس ابزار رسمی @wordpress/create-block را برای تولید ساختار اولیه پروژه ارائه کرده است که بسیاری از تنظیمات و فایلهای ضروری را بهصورت خودکار ایجاد میکند.
چرا به Node.js و npm نیاز داریم؟
کدهای توسعه بلاک معمولاً با JavaScript مدرن و JSX نوشته میشوند. مرورگر و محیط وردپرس برای اجرای مستقیم تمام قابلیتهای این ساختار به فرایند آمادهسازی کد نیاز دارند. Node.js محیط اجرای ابزارهای توسعه را فراهم میکند و npm نیز برای نصب و مدیریت وابستگیهای پروژه به کار میرود.
با استفاده از این ابزارها میتوان پکیجهای موردنیاز را نصب کرد، فایلهای JSX را به کد قابل اجرا تبدیل کرد و هنگام توسعه، تغییرات را بهصورت خودکار در محیط ساخت اعمال کرد. برای شروع باید نسخه سازگار Node.js و npm را نصب کنید. سپس در ترمینال با اجرای دستورهای node -v و npm -v از نصب صحیح آنها مطمئن شوید. بر اساس مستندات فعلی ابزار رسمی Create Block، نسخه Node.js موردنیاز حداقل 22.13.0 است؛ بنابراین بهتر است پیش از شروع، نسخه مورد استفاده را با مستندات همان ابزار تطبیق دهید.
ابزار create-block چگونه ساختار اولیه پروژه را ایجاد میکند؟
ابزار @wordpress/create-block روش رسمی و سادهای برای ایجاد پروژه بلاک وردپرس است. این ابزار فایلهای PHP، JavaScript و CSS موردنیاز را تولید میکند و فرایند ساخت پروژه را با ابزار wp-scripts آماده میسازد. برای ایجاد یک بلاک جدید، ترمینال را باز کرده و دستور زیر را اجرا کنید:
npx @wordpress/create-block@latest service-card
پس از ایجاد پروژه، وارد پوشه آن شوید و سرور توسعه را اجرا کنید:
cd service-card
npm start
در صورت موفقیت، ساختار اولیه افزونه و فایلهای لازم ایجاد میشوند. برای ساخت نسخه نهایی و آمادهسازی فایلها جهت انتشار نیز از دستور زیر استفاده میشود:
npm run build
مزیت این روش آن است که توسعهدهنده مجبور نیست تنظیمات اولیه Webpack، وابستگیها و ساختار کامپایل را از ابتدا ایجاد کند. به این ترتیب، زمان بیشتری برای طراحی منطق بلاک و تجربه کاربری باقی میماند.

چگونه با React یک بلاک اختصاصی گوتنبرگ ایجاد کنیم؟
برای درک بهتر فرایند توسعه، یک بلاک ساده با عنوان «کارت خدمات» در نظر میگیریم. این بلاک باید امکان ویرایش عنوان و توضیحات را در محیط گوتنبرگ فراهم کند و پس از ذخیره نوشته، محتوای واردشده را در سایت نمایش دهد. در پروژه تولیدشده با Create Block، فایلهای اصلی در پوشه src قرار دارند. فایل block.json مشخصات بلاک را تعریف میکند، فایل edit.js رابط ویرایش را میسازد و فایل save.js خروجی ذخیرهشده را مشخص میکند. این تفکیک باعث میشود توسعه و نگهداری کد سادهتر باشد.
فایل block.json و registerBlockType چه کاربردی دارند؟
فایل block.json شناسنامه بلاک محسوب میشود و اطلاعاتی مانند نام، عنوان، دستهبندی، آیکون، ویژگیها و فایلهای مرتبط را در خود نگه میدارد. برای نمونه، بخش مهمی از این فایل میتواند به شکل زیر باشد:
{
"apiVersion": 3,
"name": "tik4/service-card",
"title": "کارت خدمات",
"category": "widgets",
"icon": "admin-tools",
"description": "نمایش کارت اختصاصی خدمات",
"attributes": {
"title": {
"type": "string",
"default": "عنوان خدمت"
},
"description": {
"type": "string",
"default": "توضیحات خدمت را وارد کنید."
}
},
"editorScript": "file:./index.js"
}
در این مثال، دو ویژگی با نامهای title و description تعریف شدهاند. این ویژگیها اطلاعاتی هستند که کاربر در ویرایشگر تغییر میدهد. در ساختار جدید توسعه بلاک، اطلاعات ثبتشده در block.json مبنای معرفی بلاک در سمت سرور و ویرایشگر قرار میگیرند. ابزار Create Block بخش مهمی از فرایند ثبت را آماده میکند؛ بنابراین لازم نیست همیشه ثبت بلاک را بهصورت دستی انجام دهید.
چگونه با RichText و useBlockProps بخش ویرایش بلاک را بسازیم؟
در فایل edit.js باید رابطی ایجاد کنیم که کاربر بتواند عنوان و توضیحات کارت را تغییر دهد. کامپوننت RichText برای ویرایش محتوای متنی و useBlockProps برای تعریف ویژگیهای عنصر اصلی بلاک استفاده میشوند.
import { RichText, useBlockProps } from '@wordpress/block-editor';
export default function Edit({ attributes, setAttributes }) {
const blockProps = useBlockProps();
return (
<div {...blockProps}>
<RichText
tagName="h3"
value={attributes.title}
onChange={(title) => setAttributes({ title })}
placeholder="عنوان خدمت..."
/>
<RichText
tagName="p"
value={attributes.description}
onChange={(description) =>
setAttributes({ description })
}
placeholder="توضیحات خدمت..."
/>
</div>
);
}
در این کد، attributes مقادیر فعلی بلاک را دریافت میکند و setAttributes برای بهروزرسانی آنها به کار میرود. هر بار که کاربر متنی را تغییر میدهد، مقدار جدید در ویژگی مربوط ذخیره میشود و پیشنمایش بلاک بهروزرسانی خواهد شد. استفاده از useBlockProps نیز برای اعمال کلاسها و ویژگیهای استاندارد وردپرس به عنصر اصلی بلاک ضروری است.
چگونه خروجی بلاک را با تابع save ذخیره کنیم؟
فایل save.js مشخص میکند محتوای بلاک استاتیک پس از ذخیره نوشته چگونه در پایگاه داده قرار بگیرد و در فرانتاند نمایش داده شود. برای نمونه:
import { RichText, useBlockProps } from '@wordpress/block-editor';
export default function save({ attributes }) {
const blockProps = useBlockProps.save();
return (
<div {...blockProps}>
<RichText.Content
tagName="h3"
value={attributes.title}
/>
<RichText.Content
tagName="p"
value={attributes.description}
/>
</div>
);
}
در این مرحله، محتوای عنوان و توضیحات در خروجی HTML ذخیره میشود. نکته مهم این است که ساختار HTML تولیدشده توسط تابع save باید با ساختار ذخیرهشده در نوشته هماهنگ باشد. اگر در نسخههای بعدی افزونه، خروجی ذخیرهسازی تغییر کند، ممکن است وردپرس خطای اعتبارسنجی بلاک نمایش دهد. بنابراین تغییر ساختار بلاکهای منتشرشده باید با توجه به سازوکار نسخهبندی و مهاجرت بلاک انجام شود.

چگونه بلاک اختصاصی را در وردپرس مدیریت، آزمایش و بهینهسازی کنیم؟
ساخت کامپوننت React بهتنهایی به معنای تکمیل بلاک نیست. توسعهدهنده باید ثبت صحیح افزونه، ذخیرهسازی دادهها، نمایش خروجی در فرانتاند و سازگاری با نسخههای مختلف وردپرس را بررسی کند. همچنین باید تصمیم بگیرد که بلاک بهصورت استاتیک یا داینامیک رندر شود. این انتخاب بر نحوه ذخیره محتوا، نگهداری کد و امکان تغییر خروجی در آینده تأثیر میگذارد. آزمایش در محیط واقعی و بررسی عملکرد نیز برای جلوگیری از مشکلات ویرایشگر و تجربه کاربری ضروری است.
تفاوت بلاک استاتیک و داینامیک چیست؟
در بلاک استاتیک، تابع save ساختار HTML نهایی را تولید میکند و وردپرس آن را همراه محتوای نوشته ذخیره میکند. این روش برای اجزایی مانند کارت خدمات، باکس نقلقول، دکمه و بخشهای محتوایی ثابت مناسب است. در مقابل، بلاک داینامیک میتواند خروجی خود را هنگام نمایش صفحه از طریق PHP تولید کند. برای مثال، اگر بلاکی اطلاعات محصولات، نوشتههای جدید یا دادههای متغیر پایگاه داده را نمایش دهد، رندر داینامیک انتخاب مناسبی خواهد بود.
در بلاک داینامیک معمولاً تابع save مقدار null برمیگرداند و اطلاعات موردنیاز از طریق ویژگیهای بلاک به تابع رندر سمت سرور ارسال میشود. این تابع میتواند با render_callback یا فایل render.php تعریف شود. انتخاب روش مناسب باید بر اساس ماهیت داده و نیازهای پروژه انجام شود؛ نه صرفاً بر اساس سادگی پیادهسازی.
چه خطاهایی هنگام ساخت بلاک اختصاصی رخ میدهند؟
یکی از خطاهای متداول، نمایش ندادن بلاک در ویرایشگر است. این مشکل ممکن است از نامگذاری اشتباه در block.json، ثبت ناقص بلاک، خطای JavaScript یا اجرا نشدن فرایند Build ناشی شود. بررسی Console مرورگر و گزارشهای PHP میتواند در شناسایی علت کمک کند. خطای دیگر، نمایش پیام Invalid Block است که معمولاً زمانی اتفاق میافتد که خروجی جدید تابع save با HTML ذخیرهشده قبلی تطابق نداشته باشد.
برای کاهش این مشکلات، باید پس از هر تغییر مهم، بلاک را در محیط آزمایشی بررسی کرد. همچنین استفاده از نام یکتای دارای Namespace، تعریف صحیح ویژگیها، رعایت ساختار HTML و آزمایش در نسخههای پشتیبانیشده وردپرس اهمیت دارد. در پروژههای بزرگتر، نوشتن تست و مستندسازی تغییرات میتواند هزینه نگهداری را کاهش دهد.
| ابزار یا فایل | کاربرد اصلی |
|---|---|
| React و JSX | ساخت رابط و منطق کامپوننت بلاک |
| Node.js و npm | اجرای ابزارهای توسعه و مدیریت وابستگیها |
@wordpress/create-block | ایجاد ساختار اولیه افزونه و بلاک |
block.json | تعریف مشخصات و ویژگیهای بلاک |
edit.js | نمایش رابط ویرایش در گوتنبرگ |
save.js | تولید خروجی ذخیرهشده بلاک استاتیک |
RichText | ویرایش محتوای متنی |
InspectorControls | افزودن تنظیمات در نوار کناری |
useBlockProps | مدیریت ویژگیهای عنصر اصلی بلاک |
render.php | تولید خروجی سمت سرور برای بلاک داینامیک |
جمعبندی کاربردی
ساخت بلاک اختصاصی گوتنبرگ با React راهکاری برای توسعه قابلیتهای متناسب با نیاز هر وبسایت وردپرسی است. با استفاده از React، APIهای گوتنبرگ و ابزار رسمی Create Block میتوان اجزایی ساخت که هم در محیط ویرایشگر قابل مدیریت باشند و هم خروجی استانداردی در صفحات سایت ارائه دهند. برای شروع، بهتر است یک بلاک ساده با چند ویژگی مشخص طراحی کنید و پس از تسلط بر ساختار block.json، توابع edit و save، به سراغ قابلیتهای پیشرفتهتر بروید.
انتخاب میان رندر استاتیک و داینامیک، رعایت استانداردهای وردپرس، آزمایش خروجی و توجه به دسترسپذیری و عملکرد، از عوامل مهم موفقیت پروژه هستند. در تیک4 نیز میتوانید با دنبال کردن آموزشهای تخصصی وردپرس، دانش فنی خود را برای توسعه و بهینهسازی وبسایت گسترش دهید.
سوالات متداول
بله، آشنایی با React، JavaScript و JSX برای توسعه بلاکهای مدرن بسیار مفید است؛ زیرا رابط ویرایش بلاک بر پایه کامپوننتهای React ساخته میشود.
امکان ثبت بلاک در قالب نیز وجود دارد، اما معمولاً توسعه بلاک در قالب افزونه مستقل توصیه میشود؛ زیرا با تغییر قالب، قابلیت بلاک همچنان فعال باقی میماند.
این ابزار ساختار اولیه افزونه، فایلهای موردنیاز و تنظیمات فرایند Build را ایجاد میکند تا توسعهدهنده سریعتر کار روی منطق بلاک را آغاز کند.
بلاک استاتیک خروجی HTML را هنگام ذخیره نوشته تولید میکند؛ اما بلاک داینامیک میتواند خروجی را در زمان نمایش صفحه از طریق PHP بسازد.
این فایل اطلاعات اصلی بلاک مانند نام، عنوان، ویژگیها، دستهبندی و فایلهای JavaScript و CSS مرتبط را تعریف میکند.
بله، اگر بلاک ساختار HTML استاندارد، محتوای قابل دسترسی برای موتورهای جستوجو و نمایش مناسبی در موبایل داشته باشد، میتواند به کیفیت صفحات کمک کند. البته صرف ساخت بلاک اختصاصی باعث بهبود رتبه نمیشود.
ابتدا خروجی تابع save را با ساختار HTML ذخیرهشده مقایسه کنید. سپس تغییرات ویژگیها، ساختار HTML و نسخههای قبلی بلاک را بررسی کنید. در صورت تغییر ساختار، ممکن است به سازوکار Deprecation و مهاجرت بلاک نیاز داشته باشید.