Block Attributes در وردپرس ستون فقرات مدیریت داده‌های بلاک است؛ هر ویژگی که یک بلاک نگهداری می‌کند، از طریق Attributes تعریف، ذخیره و بازیابی می‌شود و همین لایه تعیین می‌کند بلاک چه داده‌ای را در پایگاه داده نگه دارد و چگونه آن را در ویرایشگر و فرانت‌اند بازتاب دهد.

Block Attributes در وردپرس لایه‌ای رسمی برای تعریف، اعتبارسنجی و ذخیره داده‌های یک بلاک گوتنبرگ است.

هر Attribute دارای نوع داده (type)، مقدار پیش‌فرض (default) و در برخی موارد منبع استخراج (source) است.

مدیریت داده‌های بلاک از طریق ترکیب Attributes، تابع setAttributes و مکانیزم سریالایز انجام می‌شود.

انتخاب نوع داده نادرست یا منبع استخراج اشتباه، می‌تواند به بلاک نامعتبر یا از دست رفتن داده منجر شود.

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

در نخستین بلاکی که برای یک پروژه فروشگاهی ساختم، ویژگی price را از نوع رشته تعریف کردم و پس از مدتی متوجه شدم که مقایسه عددی روی آن کار نمی‌کند و مرتب‌سازی نتایج به‌هم می‌ریزد. آن تجربه نشان داد که انتخاب نوع داده در Attributes، تنها یک تصمیم ظاهری نیست؛ یک تصمیم معماری است که بر تمام لایه‌های بلاک اثر می‌گذارد. آنچه در ادامه می‌خوانید حاصل کار عملی با Attributes در پروژه‌های واقعی و بررسی کد منبع گوتنبرگ است.

Block Attributes چیست و چه نقشی در معماری بلاک دارد؟

Block Attributes مجموعه‌ای از ویژگی‌های تعریف‌شده برای یک بلاک است که داده‌های آن بلاک را نگهداری می‌کند. هر Attribute یک نام، یک نوع داده و در صورت نیاز یک مقدار پیش‌فرض دارد. این ویژگی‌ها در فایل block.json یا در زمان ثبت بلاک تعریف می‌شوند و در سراسر چرخه حیات بلاک، از ویرایش تا ذخیره و بارگذاری، مورد استفاده قرار می‌گیرند. برای آشنایی با مبانی ساخت بلاک، مقاله آموزش ساخت بلوک سفارشی گوتنبرگ را مطالعه کنید.

نقش Attributes در معماری بلاک را می‌توان در چند لایه بررسی کرد. در لایه ویرایش، Attributes منبع داده رابط کاربری ویرایشگر هستند؛ هر فیلدی که کاربر پر می‌کند، در نهایت یک Attribute را به‌روزرسانی می‌کند. در لایه ذخیره‌سازی، Attributes مبنای تولید HTML در تابع save هستند. در لایه بارگذاری، Attributes از کامنت‌های سریالایز استخراج می‌شوند و به ساختار بلاک بازگردانده می‌گردند. برای مطالعه بیشتر درباره این فرآیند، مقاله Block Serialization در وردپرس چیست و ذخیره بلاک‌ها چطور کار می‌کند؟ را ببینید.

Attributes زبان مشترک بلاک است؛ بدون آن، ویرایشگر نمی‌داند چه داده‌ای را نگه دارد و بلاک نمی‌داند چگونه آن را نمایش دهد.

نکته مهمی که در بررسی‌های خود به آن پی بردم این است که Attributes تنها یک مخزن داده نیست؛ یک قرارداد معماری است. این قرارداد تعیین می‌کند که چه داده‌ای در پایگاه داده ذخیره شود، چه داده‌ای در HTML بازتاب یابد و چه داده‌ای صرفاً در حافظه ویرایشگر باقی بماند. برای مطالعه بیشتر درباره مدیریت state، مقاله Data API در وردپرس چیست و چطور state بلاک‌ها را مدیریت می‌کند؟ را ببینید.

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

چرا بدون Attributes مدیریت داده بلاک ممکن نیست؟

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

اولین دلیل، جداسازی داده از نمایش است. Attributes به شما اجازه می‌دهد که داده خام بلاک را از HTML نمایشی آن جدا کنید. این جداسازی، تغییر ظاهر بلاک را بدون تغییر داده ممکن می‌سازد و امکان اعتبارسنجی دقیق‌تر را فراهم می‌کند. برای مطالعه بیشتر درباره HTML، مقاله چرا HTML API در وردپرس امن‌ترین راه پردازش HTML است؟ را ببینید.

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

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

چهارمین دلیل، پشتیبانی از حالت‌های مختلف نمایش است. یک بلاک ممکن است در حالت‌های مختلف (ویرایش، پیش‌نمایش، فرانت‌اند) نمایش متفاوتی داشته باشد. Attributes منبع داده مشترک این حالت‌ها هستند و امکان هماهنگی میان آن‌ها را فراهم می‌کنند.

پنجمین دلیل، امکان ادغام با سرویس‌های خارجی است. Attributes به‌عنوان داده ساختاریافته می‌توانند به REST API یا سرویس‌های خارجی ارسال شوند و در فرآیندهای خارجی مورد استفاده قرار گیرند. برای مطالعه بیشتر درباره REST API، مقاله آموزش استفاده از REST API در وردپرس را ببینید.

انواع داده در Block Attributes

وردپرس مجموعه‌ای از انواع داده استاندارد را برای Attributes پشتیبانی می‌کند. انتخاب نوع داده صحیح، نقش کلیدی در پایداری بلاک و کارایی آن دارد. در ادامه به بررسی هر نوع داده می‌پردازیم.

String

نوع string برای نگهداری متن استفاده می‌شود و پرکاربردترین نوع داده در Attributes است. این نوع برای ویژگی‌هایی مانند عنوان، توضیحات، URL و شناسه‌های متنی مناسب است. مقدار پیش‌فرض این نوع معمولاً یک رشته خالی است.

"title": {
  "type": "string",
  "default": ""
}

Number

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

"numberOfPosts": {
  "type": "number",
  "default": 5
}

Boolean

نوع boolean برای نگهداری مقادیر درست یا غلط استفاده می‌شود. این نوع برای ویژگی‌های کلیدی مانند نمایش/عدم نمایش، فعال/غیرفعال و روشن/خاموش مناسب است.

"showDate": {
  "type": "boolean",
  "default": true
}

Array

نوع array برای نگهداری لیست مقادیر استفاده می‌شود. این نوع برای ویژگی‌هایی مانند لیست شناسه‌ها، مجموعه برچسب‌ها و ترتیب عناصر مناسب است.

"selectedIds": {
  "type": "array",
  "default": [],
  "items": { "type": "number" }
}

Object

نوع object برای نگهداری ساختارهای پیچیده استفاده می‌شود. این نوع برای ویژگی‌هایی مانند تنظیمات گروهی، پیکربندی تو‌در‌تو و داده‌های ساختاریافته مناسب است.

"style": {
  "type": "object",
  "default": {
    "color": "#000",
    "fontSize": 16
  }
}

Null و مقادیر خالی

وردپرس از نوع null به‌عنوان یک مقدار مجاز پشتیبانی می‌کند، اما استفاده از آن توصیه نمی‌شود. به‌جای null، بهتر است از مقادیر پیش‌فرض مشخص استفاده کنید تا رفتار بلاک قابل پیش‌بینی باشد.

نوع کاربرد مثال
string متن، URL، شناسه عنوان، توضیحات
number عدد، قیمت، اندازه تعداد، درصد
boolean وضعیت دو‌حالته نمایش، فعال
array لیست مقادیر شناسه‌ها، برچسب‌ها
object ساختار پیچیده تنظیمات گروهی

تعریف Attributes در block.json

روش مدرن و توصیه‌شده برای تعریف Attributes، استفاده از فایل block.json است. این فایل به‌عنوان یک قرارداد استاندارد، تمام اطلاعات بلاک را در خود جای می‌دهد و امکان استفاده مجدد از بلاک در افزونه‌ها و قالب‌ها را فراهم می‌کند.

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-plugin/info-card",
  "title": "Info Card",
  "category": "widgets",
  "icon": "id",
  "attributes": {
    "title": {
      "type": "string",
      "default": ""
    },
    "description": {
      "type": "string",
      "default": ""
    },
    "imageId": {
      "type": "number",
      "default": 0
    },
    "imageUrl": {
      "type": "string",
      "source": "attribute",
      "selector": "img",
      "attribute": "src"
    },
    "alignment": {
      "type": "string",
      "default": "left"
    },
    "showBorder": {
      "type": "boolean",
      "default": true
    }
  },
  "textdomain": "my-plugin",
  "editorScript": "file:./index.js",
  "style": "file:./style.css"
}

در این فایل، هر Attribute به‌صورت یک شیء تعریف شده که شامل type، default و در صورت نیاز source است. نکته مهم این است که تعریف Attributes در block.json به‌جای فایل JavaScript، امکان اشتراک‌گذاری خودکار با PHP را فراهم می‌کند و از تکرار کد جلوگیری می‌نماید. برای مطالعه بیشتر درباره ساختار استاندارد، مقاله چرا بدون React نمی‌توان بلاک حرفه‌ای در وردپرس ساخت؟ را ببینید.

ویژگی‌های اضافی در تعریف Attribute

هر Attribute می‌تواند ویژگی‌های اضافی داشته باشد که رفتار آن را دقیق‌تر تعریف می‌کند. مهم‌ترین این ویژگی‌ها عبارتند از:

  • type: نوع داده (الزامی)
  • default: مقدار پیش‌فرض (اختیاری)
  • source: منبع استخراج (اختیاری)
  • selector: انتخابگر CSS برای استخراج (اختیاری)
  • attribute: نام ویژگی HTML برای استخراج (اختیاری)
  • query: پرس‌وجوی ساختاریافته برای استخراج آرایه (اختیاری)
  • items: تعریف نوع عناصر آرایه (اختیاری)
  • enum: مجموعه مقادیر مجاز (اختیاری)
  • role: نقش معنایی (اختیاری)

منابع استخراج (Sources) و نقش آن‌ها

یکی از قدرتمندترین ویژگی‌های Attributes در گوتنبرگ، پشتیبانی از منابع استخراج (Sources) است. این مکانیزم به شما اجازه می‌دهد که مقادیر Attributes را مستقیماً از HTML بلاک استخراج کنید، بدون آنکه در JSON سریالایز ذخیره شوند. این رویکرد حجم محتوای ذخیره‌شده را کاهش می‌دهد و از بروز خطاهای همگام‌سازی جلوگیری می‌کند.

منبع attribute

منبع attribute برای استخراج مقدار یک ویژگی HTML استفاده می‌شود. برای مثال، استخراج مقدار src از یک تگ img:

"imageUrl": {
  "type": "string",
  "source": "attribute",
  "selector": "img",
  "attribute": "src"
}

منبع text

منبع text برای استخراج متن یک عنصر HTML استفاده می‌شود. برای مثال، استخراج متن یک پاراگراف:

"content": {
  "type": "string",
  "source": "text",
  "selector": "p"
}

منبع html

منبع html برای استخراج محتوای HTML یک عنصر استفاده می‌شود. این منبع امکان نگهداری HTML درون‌خطی را فراهم می‌کند:

"richContent": {
  "type": "string",
  "source": "html",
  "selector": "div.content"
}

منبع query

منبع query برای استخراج چندین عنصر و ساخت یک آرایه استفاده می‌شود. این منبع برای بلاک‌هایی مانند لیست و گالری مناسب است:

"items": {
  "type": "array",
  "source": "query",
  "selector": "li",
  "query": {
    "text": { "type": "string", "source": "text" },
    "url": { "type": "string", "source": "attribute", "attribute": "href" }
  }
}
منابع استخراج یک تصمیم معماری است: داده‌ای که می‌توان از HTML خواند، نباید در JSON تکرار شود.

انتخاب بین ذخیره در JSON و استخراج از HTML، یک trade-off میان صراحت و حجم است. Attributes استخراج‌شده حجم کمتری اشغال می‌کنند اما خواندن آن‌ها نیازمند پارس HTML است. Attributes ذخیره‌شده در JSON سریع‌تر خوانده می‌شوند اما حجم بیشتری اشغال می‌کنند.

setAttributes و مدیریت state بلاک

در ویرایشگر، مدیریت Attributes از طریق تابع setAttributes انجام می‌شود. این تابع در تابع edit بلاک در اختیار قرار می‌گیرد و به شما امکان می‌دهد که مقدار یک یا چند Attribute را به‌روزرسانی کنید. برای مطالعه بیشتر درباره state، مقاله useSelect و useDispatch در توسعه بلاک وردپرس چطور کار می‌کنند؟ را ببینید.

const Edit = ( { attributes, setAttributes } ) => {
  return (
    <div { ...useBlockProps() }>
      <input
        value={ attributes.title }
        onChange={ ( e ) => setAttributes( { title: e.target.value } ) }
      />
    </div>
  );
};

به‌روزرسانی چند Attribute

تابع setAttributes می‌تواند چندین Attribute را در یک فراخوانی به‌روزرسانی کند:

setAttributes( {
  title: newTitle,
  description: newDescription,
  alignment: 'center',
} );

این رویکرد باعث می‌شود که ویرایشگر تنها یک بار رندر مجدد شود و عملکرد بهبود یابد. به‌روزرسانی هر Attribute به‌صورت جداگانه می‌تواند به رندرهای متعدد منجر شود.

به‌روزرسانی مبتنی بر مقدار قبلی

در برخی موارد، نیاز دارید که مقدار جدید را بر اساس مقدار قبلی محاسبه کنید. وردپرس امکان استفاده از یک تابع callback در setAttributes را فراهم می‌کند:

setAttributes( ( prevAttributes ) => ( {
  count: prevAttributes.count + 1,
} ) );

این الگو از بروز خطاهای همگام‌سازی جلوگیری می‌کند و در به‌روزرسانی‌های سریع مفید است.

مدیریت state محلی

برخی داده‌ها نباید در Attributes ذخیره شوند، زیرا ماهیت موقت دارند. برای مثال، باز یا بسته بودن یک پنل تنظیمات، مقدار یک فیلد جستجو یا وضعیت یک تب فعال. این داده‌ها باید در state محلی کامپوننت با استفاده از هوک useState مدیریت شوند.

const [ isPanelOpen, setIsPanelOpen ] = useState( false );
const [ searchQuery, setSearchQuery ] = useState( '' );

تفکیک صحیح میان state محلی و Attributes، یکی از اصول مهم در طراحی بلاک‌های حرفه‌ای است.

تفاوت Attributes با Props و State

یکی از مباحثی که اغلب توسعه‌دهندگان تازه‌کار را سردرگم می‌کند، تفاوت میان Attributes، Props و State است. در حالی که این سه مفهوم در ظاهر مشابه به نظر می‌رسند، اما نقش‌های متفاوتی در معماری بلاک ایفا می‌کنند.

Attributes

Attributes داده‌های دائمی بلاک هستند که در پایگاه داده ذخیره می‌شوند. این داده‌ها در سراسر چرخه حیات بلاک باقی می‌مانند و در زمان بارگذاری ویرایشگر بازخوانی می‌شوند. Attributes منبع حقیقت برای داده‌های بلاک محسوب می‌شوند.

Props

Props ورودی‌هایی هستند که یک کامپوننت React از والد خود دریافت می‌کند. در گوتنبرگ، Props شامل Attributes، setAttributes، isSelected و سایر مقادیر کنترلی هستند. Props تنها در محدوده کامپوننت معتبر هستند و در پایگاه داده ذخیره نمی‌شوند.

State

State داده‌های موقت کامپوننت هستند که با استفاده از هوک useState مدیریت می‌شوند. این داده‌ها بر رفتار رابط کاربری اثر می‌گذارند اما در پایگاه داده ذخیره نمی‌شوند. State در زمان unmount کامپوننت از بین می‌رود.

ویژگی Attributes Props State
ذخیره در پایگاه داده بله خیر خیر
ماندگاری دائمی در طول رندر در طول عمر کامپوننت
مدیریت setAttributes والد useState
کاربرد اصلی داده‌های بلاک ورودی کامپوننت وضعیت موقت رابط

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

اعتبارسنجی Attributes و کنترل نوع داده

وردپرس از مکانیزم اعتبارسنجی نوع داده برای Attributes پشتیبانی می‌کند. این مکانیزم در زمان بارگذاری محتوا اجرا می‌شود و بررسی می‌کند که آیا مقادیر استخراج‌شده با انواع تعریف‌شده مطابقت دارند یا خیر. در ادامه به بررسی ابعاد مختلف این اعتبارسنجی می‌پردازیم.

اعتبارسنجی نوع پایه

وردپرس بررسی می‌کند که مقدار هر Attribute با نوع تعریف‌شده مطابقت داشته باشد. اگر مقدار یک Attribute از نوع number باشد اما در JSON به‌صورت رشته ذخیره شده باشد، وردپرس تلاش می‌کند آن را تبدیل کند. اگر تبدیل امکان‌پذیر نباشد، مقدار پیش‌فرض اعمال می‌شود.

اعتبارسنجی enum

اگر برای یک Attribute مجموعه مقادیر مجاز (enum) تعریف شده باشد، وردپرس بررسی می‌کند که مقدار در این مجموعه قرار دارد یا خیر. این مکانیزم از بروز مقادیر نادرست جلوگیری می‌کند.

"alignment": {
  "type": "string",
  "default": "left",
  "enum": [ "left", "center", "right" ]
}

اعتبارسنجی items در آرایه

برای Attributeهایی از نوع آرایه، می‌توانید نوع عناصر را با ویژگی items تعریف کنید:

"ids": {
  "type": "array",
  "default": [],
  "items": { "type": "number" }
}

این مکانیزم از ذخیره مقادیر نادرست در آرایه جلوگیری می‌کند و کیفیت داده را تضمین می‌نماید.

الگوی طراحی Schema-First

یکی از بهترین رویکردها در طراحی Attributes، الگوی Schema-First است. در این الگو، ابتدا ساختار داده بلاک را به‌صورت کامل تعریف می‌کنید و سپس بر اساس آن، رابط کاربری ویرایشگر را می‌سازید. این رویکرد از بروز ناهماهنگی میان داده و رابط جلوگیری می‌کند و نگهداری بلاک را ساده‌تر می‌نماید.

مدیریت Attributes در Dynamic Blocks

در Dynamic Blocks، مدیریت Attributes تفاوت‌های مهمی با Static Blocks دارد. در این نوع بلاک‌ها، تابع save مقدار null بازمی‌گرداند و خروجی در زمان نمایش از طریق PHP تولید می‌شود. در نتیجه، Attributes به‌عنوان تنها منبع داده بلاک عمل می‌کنند و تمام اطلاعات لازم باید در آن‌ها ذخیره شود. برای مطالعه بیشتر درباره این نوع بلاک‌ها، مقاله Dynamic Blocks در وردپرس چیست و چرا رندر سرور مهم است؟ را ببینید.

دسترسی به Attributes در PHP

در render_callback، Attributes به‌صورت یک آرایه در اختیار قرار می‌گیرند:

function my_plugin_render_block( $attributes, $content, $block ) {
  $title = isset( $attributes[ 'title' ] ) ? $attributes[ 'title' ] : '';
  $count = isset( $attributes[ 'count' ] ) ? absint( $attributes[ 'count' ] ) : 5;

  // تولید خروجی
  return '<div>' . esc_html( $title ) . '</div>';
}

توجه کنید که در PHP، همیشه باید مقادیر Attributes را پاکسازی کنید. برای اعداد از توابعی مانند absint و floatval استفاده کنید و برای متن‌ها از esc_html و esc_attr بهره ببرید.

Attributes استخراج‌شده در Dynamic Blocks

در Dynamic Blocks، استفاده از منابع استخراج محدودتر است زیرا HTML خروجی در زمان نمایش تولید می‌شود. اما می‌توانید از Attributes استخراج‌شده برای استخراج داده از HTML بلاک‌های دیگر استفاده کنید.

ServerSideRender و Attributes

در ویرایشگر، برای پیش‌نمایش خروجی Dynamic Block، از کامپوننت ServerSideRender استفاده می‌شود که Attributes را به سرور ارسال کرده و خروجی را دریافت می‌کند. این رویکرد تضمین می‌کند که پیش‌نمایش ویرایشگر با خروجی فرانت‌اند مطابقت داشته باشد.

Attributes در بلاک‌های تودرتو

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

Attributes بلاک والد و فرزند

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

اشتراک‌گذاری داده با Block Context

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

{
  "providesContext": {
    "my-plugin/theme": "theme"
  },
  "attributes": {
    "theme": { "type": "string", "default": "light" }
  }
}

در بلاک فرزند، می‌توانید این Context را با usesContext دریافت کنید:

{
  "usesContext": [ "my-plugin/theme" ]
}

Attributes گروهی در بلاک‌های والد

در بلاک‌های والد که چندین بلاک فرزند دارند، می‌توانید Attributes گروهی تعریف کنید. این Attributes به‌عنوان تنظیمات مشترک در اختیار تمام بلاک‌های فرزند قرار می‌گیرند و امکان هماهنگی ظاهری را فراهم می‌کنند.

الگوهای پیشرفته در مدیریت داده بلاک

در پروژه‌های بزرگ، مدیریت Attributes نیازمند الگوهای پیشرفته‌تری است که کیفیت کد و پایداری بلاک را تضمین کنند. در ادامه به بررسی چند الگوی مهم می‌پردازیم.

الگوی Normalize

در این الگو، پیش از استفاده از Attributes در رابط کاربری، مقادیر آن‌ها را نرمال‌سازی می‌کنید. برای مثال، اگر یک Attribute از نوع آرایه است اما مقدار آن undefined باشد، آن را به آرایه خالی تبدیل می‌کنید.

const normalizedItems = Array.isArray( attributes.items )
  ? attributes.items
  : [];

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

الگوی Derived Attributes

در برخی موارد، یک Attribute از ترکیب چند Attribute دیگر محاسبه می‌شود. به‌جای ذخیره آن به‌صورت جداگانه، می‌توانید آن را در زمان استفاده محاسبه کنید. این رویکرد حجم داده ذخیره‌شده را کاهش می‌دهد و از بروز ناهماهنگی جلوگیری می‌کند.

const fullTitle = `${ attributes.prefix } ${ attributes.title }`.trim();

الگوی Versioned Attributes

برای پشتیبانی از مهاجرت، می‌توانید Attributes را با نسخه‌بندی نگهداری کنید. برای مثال، ویژگی titleV1 و titleV2 را در کنار هم نگه دارید و در زمان بارگذاری، نسخه جدید را از نسخه قدیمی محاسبه کنید. این رویکرد از بروز خطا در زمان مهاجرت جلوگیری می‌کند.

الگوی Config-Driven Attributes

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

اشتباهات رایج در تعریف و استفاده از Attributes

در کار با Block Attributes، توسعه‌دهندگان اغلب مرتکب اشتباهاتی می‌شوند که منجر به کد شکننده یا از دست رفتن داده می‌شود. در ادامه به برخی از مهم‌ترین این اشتباهات اشاره می‌کنیم.

انتخاب نوع داده نادرست

رایج‌ترین اشتباه، انتخاب نوع داده نادرست برای Attributes است. برای مثال، استفاده از نوع string برای نگهداری اعداد، باعث می‌شود که مقایسه‌های عددی به‌درستی انجام نشوند. همیشه نوع داده را بر اساس ماهیت داده انتخاب کنید.

نادیده گرفتن مقدار پیش‌فرض

اگر برای یک Attribute مقدار پیش‌فرض تعریف نکنید، مقدار آن در زمان بارگذاری ممکن است undefined باشد و این می‌تواند به خطا منجر شود. همیشه مقدار پیش‌فرض مناسب تعریف کنید.

ذخیره داده موقت در Attributes

برخی توسعه‌دهندگان داده‌های موقت مانند وضعیت باز/بسته بودن یک پنل را در Attributes ذخیره می‌کنند. این کار حجم داده ذخیره‌شده را افزایش می‌دهد و ممکن است به رفتار غیرقابل پیش‌بینی منجر شود. داده‌های موقت را در state محلی کامپوننت نگه دارید.

عدم پاکسازی مقادیر در PHP

در Dynamic Blocks، اگر مقادیر Attributes را در PHP پاکسازی نکنید، ممکن است به آسیب‌پذیری‌هایی مانند XSS منجر شود. همیشه از توابع پاکسازی وردپرس استفاده کنید.

تکرار داده در Attributes و HTML

استفاده همزمان از ذخیره در JSON و استخراج از HTML برای یک داده واحد، می‌تواند به ناهماهنگی منجر شود. برای هر داده، تنها یکی از این دو رویکرد را انتخاب کنید.

عدم تعریف enum برای مقادیر محدود

اگر یک Attribute تنها می‌تواند مقادیر محدودی داشته باشد، تعریف enum از بروز مقادیر نادرست جلوگیری می‌کند. نادیده گرفتن این ویژگی می‌تواند به ذخیره مقادیر نامعتبر منجر شود.

نادیده گرفتن TypeScript در تعریف Attributes

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

بیشتر خطاهای Attributes از تصمیم‌های معماری نادرست در ابتدای پروژه ناشی می‌شوند، نه از پیچیدگی خود مکانیزم.

عیب‌یابی مشکلات Attributes

عیب‌یابی مسائل مربوط به Attributes نیازمند رویکردی سیستماتیک است. در ادامه به بررسی مراحل عیب‌یابی می‌پردازیم.

مرحله اول: بررسی کنسول مرورگر

اولین گام، بررسی کنسول مرورگر است. گوتنبرگ پیام‌های خطای دقیقی درباره Attributes در کنسول نمایش می‌دهد. به‌دنبال پیام‌هایی مانند «Invalid attribute type» یا «Attribute value is undefined» بگردید.

مرحله دوم: بررسی محتوای ذخیره‌شده

گام دوم، بررسی محتوای ذخیره‌شده است. با استفاده از نمای HTML ویرایشگر (Code Editor)، می‌توانید JSON Attributes را در کامنت بازکننده بلاک مشاهده کنید و از صحت آن مطمئن شوید.

<!-- wp:my-plugin/card {"title":"نمونه","count":5} /-->

مرحله سوم: بررسی تعریف Attributes

گام سوم، بررسی تعریف Attributes در block.json است. مطمئن شوید که نوع داده، مقدار پیش‌فرض و در صورت نیاز منبع استخراج به‌درستی تعریف شده‌اند.

مرحله چهارم: تست با مقادیر مختلف

گام چهارم، تست با مقادیر مختلف است. مقادیر لبه (مانند رشته خالی، عدد صفر، آرایه خالی) را آزمایش کنید تا از پایداری بلاک در شرایط مختلف مطمئن شوید.

مرحله پنجم: بررسی setAttributes

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

مرحله ششم: بررسی سازگاری با Dynamic Blocks

اگر بلاک شما Dynamic است، گام ششم بررسی سازگاری Attributes با کد PHP است. مطمئن شوید که مقادیر Attributes در PHP به‌درستی خوانده و پاکسازی می‌شوند.

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

Block Attributes چیست و چه تفاوتی با Props دارد؟

Attributes داده‌های دائمی بلاک هستند که در پایگاه داده ذخیره می‌شوند، در حالی که Props ورودی‌های یک کامپوننت React هستند که تنها در محدوده کامپوننت معتبرند.

چگونه می‌توانم یک Attribute جدید به بلاک اضافه کنم؟

تعریف Attribute جدید را در فایل block.json اضافه کنید و سپس در تابع edit از آن استفاده نمایید. در تابع save نیز باید نحوه نمایش آن را تعریف کنید.

آیا می‌توانم Attribute را به‌صورت پویا تعریف کنم؟

خیر، Attributes باید در زمان ثبت بلاک تعریف شوند. با این حال، می‌توانید مقادیر آن‌ها را در زمان اجرا به‌صورت پویا محاسبه کنید.

تفاوت منبع attribute و text چیست؟

منبع attribute برای استخراج مقدار یک ویژگی HTML استفاده می‌شود، در حالی که منبع text برای استخراج متن یک عنصر به کار می‌رود.

آیا استفاده از منابع استخراج همیشه توصیه می‌شود؟

خیر. منابع استخراج برای داده‌هایی مناسب هستند که به‌طور طبیعی در HTML وجود دارند. برای داده‌های ساختاریافته پیچیده، ذخیره مستقیم در JSON رویکرد بهتری است.

چگونه می‌توانم از بروز خطاهای نوع داده جلوگیری کنم؟

از یک سو، نوع داده صحیح را در تعریف Attribute انتخاب کنید. از سوی دیگر، از TypeScript در کد خود استفاده کنید تا بررسی نوع در زمان کامپایل انجام شود.

آیا Attributes در Dynamic Blocks تفاوتی دارند؟

بله، در Dynamic Blocks تابع save مقدار null بازمی‌گرداند و تمام داده‌ها باید در Attributes ذخیره شوند. همچنین مقادیر Attributes در PHP باید پاکسازی شوند.

چگونه می‌توانم Attributes را در بلاک‌های تودرتو مدیریت کنم؟

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

آیا می‌توانم یک Attribute را از بلاک حذف کنم؟

بله، اما توجه داشته باشید که حذف یک Attribute می‌تواند به بلاک نامعتبر منجر شود. برای رفع این مشکل، باید مکانیزم Deprecation را پیاده‌سازی کنید.

آیا Attributes بر سئو تأثیر می‌گذارند؟

Attributes به‌طور مستقیم بر سئو تأثیر نمی‌گذارند، اما داده‌هایی که در HTML خروجی بازتاب می‌یابند، می‌توانند بر سئو اثرگذار باشند. برای مطالعه بیشتر، مقاله Static یا Dynamic Blocks در وردپرس؛ کدام انتخاب درست است؟ را ببینید.

چگونه می‌توانم Attributes را در افزونه خود به‌اشتراک بگذارم؟

می‌توانید از فایل block.json به‌عنوان منبع مشترک استفاده کنید و آن را در چندین بلاک فراخوانی نمایید. همچنین می‌توانید تعاریف مشترک را در یک فایل JavaScript جداگانه نگه دارید و در بلاک‌های مختلف وارد کنید.

آیا می‌توانم Attributes را در سمت سرور اعتبارسنجی کنم؟

بله، در Dynamic Blocks می‌توانید در render_callback مقادیر Attributes را بررسی و در صورت نیاز مقادیر پیش‌فرض اعمال کنید. برای مطالعه بیشتر درباره REST API، مقاله آموزش استفاده از REST API در وردپرس را ببینید.

آیا استفاده از نوع object در Attributes توصیه می‌شود؟

نوع object برای داده‌های ساختاریافته مناسب است، اما استفاده از آن می‌تواند اعتبارسنجی را پیچیده‌تر کند. در صورت امکان، از ترکیب چند Attribute ساده به‌جای یک object استفاده کنید.

تحلیل معماری در سطح مهندسی نرم‌افزار

از منظر معماری نرم‌افزار، Block Attributes یک پیاده‌سازی از الگوی Schema-Driven Design هستند. در این الگو، ساختار داده به‌عنوان یک قرارداد رسمی تعریف می‌شود و تمام لایه‌های برنامه بر اساس آن ساخته می‌شوند. این رویکرد مزایای متعددی دارد: امکان اعتبارسنجی خودکار، جلوگیری از خطاهای نوع، تسهیل مهاجرت و امکان تولید کد از روی schema.

یکی از جنبه‌های کمتر شناخته‌شده، نحوه تعامل Attributes با مکانیزم سریالایز است. در زمان ذخیره، تنها Attributeهایی که مقدارشان با مقدار پیش‌فرض متفاوت است در JSON ذخیره می‌شوند. این بهینه‌سازی به کاهش حجم محتوای ذخیره‌شده کمک می‌کند، اما در زمان بارگذاری باید مقادیر پیش‌فرض برای Attributeهای غایب اعمال شوند. برای مطالعه بیشتر، مقاله آیا WordPress Interactivity API جایگزین React در وردپرس می‌شود؟ را ببینید.

از منظر عملکرد، تعداد و نوع Attributes می‌تواند بر سرعت ویرایشگر تأثیر بگذارد. هر Attribute اضافه، یک ورودی جدید در مکانیزم state بلاک است و می‌تواند زمان رندر را افزایش دهد. برای بهینه‌سازی، تنها Attributeهایی را تعریف کنید که واقعاً مورد نیاز هستند و از تعریف Attributeهای تزئینی خودداری نمایید.

از منظر امنیت، Attributes نقش مهمی در جلوگیری از آسیب‌پذیری‌ها دارند. با تعریف نوع داده دقیق، می‌توانید از ذخیره مقادیر مخرب جلوگیری کنید. همچنین، در Dynamic Blocks، پاکسازی مقادیر در PHP یک لایه امنیتی ضروری است.

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

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

از منظر مقیاس‌پذیری، Attributes امکان استفاده مجدد از بلاک را در پروژه‌های مختلف فراهم می‌کنند. با تعریف یک schema واحد، می‌توانید بلاک را در چندین افزونه یا قالب استفاده کنید و از تکرار کد جلوگیری نمایید. برای مطالعه بیشتر درباره ساختار استاندارد، می‌توانید صفحه JSON را در ویکی‌پدیا ببینید.

آینده Block Attributes

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

نکات کلیدی

  • Block Attributes لایه رسمی مدیریت داده‌های بلاک در گوتنبرگ است.
  • هر Attribute دارای نوع داده، مقدار پیش‌فرض و در صورت نیاز منبع استخراج است.
  • انواع داده پشتیبانی‌شده شامل string، number، boolean، array و object هستند.
  • منابع استخراج (attribute، text، html، query) امکان خواندن داده از HTML را فراهم می‌کنند.
  • تفکیک صحیح Attributes از state محلی، یکی از اصول طراحی بلاک حرفه‌ای است.
  • اعتبارسنجی نوع داده از بروز خطاهای پنهان جلوگیری می‌کند.
  • در Dynamic Blocks، تمام داده باید در Attributes ذخیره شود و مقادیر در PHP پاکسازی شوند.
  • Block Context امکان اشتراک‌گذاری داده میان بلاک والد و فرزند را فراهم می‌کند.
  • الگوهای Normalize، Derived Attributes و Versioned Attributes کیفیت کد را بهبود می‌بخشند.
  • انتخاب نوع داده نادرست، رایج‌ترین اشتباه در تعریف Attributes است.
  • همیشه از TypeScript برای بررسی نوع داده در زمان کامپایل استفاده کنید.
  • تعداد Attributes را به حداقل برسانید تا سرعت ویرایشگر حفظ شود.

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