ساخت بلاک‌ های سفارشی گوتن‌برگ در وردپرس با React و TypeScript — راهنمای عملی

---

مقدمه

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

---

چرا بلاک‌ سفارشی گوتن‌برگ؟

۱. تجربه کاربری بهتر: می‌توانید المان‌ هایی فراتر از پاراگراف و تصویر بسازید (مثلاً جداول مقایسه، تب‌‌ها یا پاورقی‌ های تعاملی).
۲. سادگی برای نویسنده‌ ها: با رابط درگ‌-استاپ بلوک، افراد غیر فنی هم آسان محتوای پیشرفته ایجاد می‌کنند.
۳. یکپارچگی با وردپرس: همه تنظیمات بلوک در پنل سمت چپ گوتن‌برگ قرار می‌گیرد و بدون نیاز به Shortcode یا کد نویسی دستی استفاده می‌شود.

---

پیش‌ نیاز ها و نصب ابزار ها

قبل از شروع، مطمئن شوید که:

• وردپرس شما نسخه ۵.۰ به بالا دارد
• Node.js و npm روی سیستم نصب باشند
• افزونه @wordpress/create-block نصب شود

bashCopyEditnpm install -g @wordpress/create-block

---

قدم ۱: ایجاد اسکلت افزونه بلاک

از ابزار رسمی وردپرس برای ایجاد پکیج پایه استفاده می‌کنیم:

bashCopyEditnpx @wordpress/create-block my-custom-block \
  --namespace=farosia \
  --template=plugin \
  --variant=typescript

• my-custom-block نام پوشه و شناسه بلاک است.
• --namespace فضا نام (namespace) داخل وردپرس را تعیین می‌کند.
• --variant=typescript پروژه را با TypeScript ‌پیکربندی می‌کند.

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

• src/edit.tsx و src/save.tsx برای تعریف و رندر بلوک
• block.json برای متادیتای بلاک
• فایل‌ های پیکربندی TypeScript و Webpack

---

قدم ۲: بررسی فایل block.json

در ریشه پوشه ایجاد شده، فایل block.json تنظیمات اصلی را نگه می‌دارد:

jsoncCopyEdit{
  "apiVersion": 2,
  "name": "farosia/my-custom-block",
  "title": "بلوک سفارشی فرosia",
  "category": "widgets",
  "icon": "smiley",
  "description": "نمونه بلاک سفارشی با React و TypeScript",
  "supports": {
    "html": false
  },
  "textdomain": "farosia",
  "editorScript": "file:./build/index.js"
}

• category را بر اساس جایگاه بلوک تعیین کنید (مثل common, layout, widgets).
• supports.html را روی false بگذارید تا ویرایش HTML غیر فعال شود.

---

قدم ۳: نوشتن کد ویرایشگر (src/edit.tsx)

فایل ویرایش بلاک محیطی است که نویسنده در صفحه گوتن‌برگ با آن تعامل می‌کند:

tsxCopyEditimport { __ } from '@wordpress/i18n';
import { useBlockProps, RichText } from '@wordpress/block-editor';
import { PanelBody, TextControl } from '@wordpress/components';
import { InspectorControls } from '@wordpress/block-editor';

interface MyCustomBlockAttributes {
  title: string;
  content: string;
}

export default function Edit({ attributes, setAttributes }: any) {
  const { title, content } = attributes as MyCustomBlockAttributes;
  const blockProps = useBlockProps();

  return (
    <div {...blockProps}>
      <InspectorControls>
        <PanelBody title={__('تنظیمات بلوک', 'farosia')}>
          <TextControl
            label={__('عنوان', 'farosia')}
            value={title}
            onChange={(value) => setAttributes({ title: value })}
          />
        </PanelBody>
      </InspectorControls>
      <RichText
        tagName="h2"
        placeholder={__('عنوان وارد شود…', 'farosia')}
        value={title}
        onChange={(value) => setAttributes({ title: value })}
      />
      <RichText
        tagName="p"
        placeholder={__('متن خود را بنویسید…', 'farosia')}
        value={content}
        onChange={(value) => setAttributes({ content: value })}
      />
    </div>
  );
}

در این قسمت:

• از InspectorControls برای پنل تنظیمات کناری استفاده کردیم.
• RichText برای ویرایش متون عنوان و پاراگراف.
• تایپ‌ اسکریپت با تعریف interface برای attributes کمک می‌کند خطا های زمان توسعه کمتر شود.

---

قدم ۴: تعریف بخش ذخیره (src/save.tsx)

قسمت Save نسخه نهایی HTML را در خروجی سایت ثبت می‌کند:

tsxCopyEditimport { useBlockProps, RichText } from '@wordpress/block-editor';

export default function Save({ attributes }: any) {
  const { title, content } = attributes;
  const blockProps = useBlockProps.save();

  return (
    <div {...blockProps}>
      <RichText.Content tagName="h2" value={title} />
      <RichText.Content tagName="p" value={content} />
    </div>
  );
}

• RichText.Content خروجی HTML امن تولید می‌کند.
• useBlockProps.save() ویژگی‌ های لازم را اضافه می‌کند.

---

قدم ۵: کامپایل و فعال‌ سازی افزونه

۱. نصب وابستگی‌ ها و ساخت پروژه:

bashCopyEditnpm install
npm run build

۲. پوشه افزونه (my-custom-block) را در مسیر wp-content/plugins/ قرار دهید.
۳. از پیشخوان وردپرس به منوی «افزونه‌ ها» رفته و افزونه «بلوک سفارشی فرosia» را فعال کنید.
۴. در ویرایشگر گوتن‌برگ بلاک جدید را در دسته‌ بندی مربوطه (مثلاً Widgets) خواهید دید.

---

جمع‌بندی

در این راهنمای عملیاتی، یادگرفتید که چگونه با ابزار رسمی وردپرس و ترکیب React و TypeScript یک بلوک سفارشی گوتن‌برگ بسازید. این روش برای ایجاد المان‌ های خاص، تجربه‌ی کاربری حرفه‌ای‌ تر و کنترل کامل روی ظاهر و رفتار سایت، ایده‌ آل است.
اکنون وقت آن است که خلاقیت خود را به کار بگیرید و بلاک‌ های منحصر به‌ فردی طراحی کنید!