Notices API در وردپرس یک سیستم استاندارد برای نمایش پیام‌های سیستمی، هشدارها و اعلان‌ها در پیشخوان و ویرایشگر است که جایگزین روش‌های پراکنده و ناسازگار قبلی شده است. این API که به تدریج در نسخه‌های مختلف وردپرس تکامل یافته، یک رابط یکپارچه برای ثبت، مدیریت و نمایش اعلان‌ها فراهم می‌کند و به توسعه‌دهندگان امکان می‌دهد پیام‌های خود را با ظاهر و رفتار بومی وردپرس نمایش دهند. معماری این سیستم بر پایه پکیج @wordpress/notices و استور مرکزی @wordpress/data بنا شده و از مکانیزم‌های Snackbar، Notice و SnackbarList پشتیبانی می‌کند. این سیستم نقش مهمی در بهبود تجربه کاربری و کاهش ناسازگاری بصری در اکوسیستم وردپرس داشته است. در این راهنما، معماری، کاربردها و نکات پیشرفته Notices API بررسی می‌شود.

نخستین بار که با Notices API کار کردم، تفاوت آن با روش‌های قدیمی نمایش پیام در وردپرس برایم آشکار شد. به جای نوشتن HTML خام و مدیریت دستی CSS، یک ساختار استاندارد در اختیار داشتم که به‌طور خودکار با ظاهر وردپرس هماهنگ بود. این راهنما حاصل کار با این API در پروژه‌های واقعی است. 📢

Notices API چیست و چه مشکلی را حل می‌کند؟

Notices API یک سیستم استاندارد در وردپرس برای نمایش پیام‌های سیستمی است. این API به توسعه‌دهندگان امکان می‌دهد اعلان‌ها، هشدارها، خطاها و پیام‌های موفقیت را با ظاهر و رفتار بومی وردپرس نمایش دهند. برخلاف روش‌های سنتی که در آن هر افزونه یا قالب HTML و CSS اختصاصی خود را برای نمایش پیام استفاده می‌کرد، Notices API یک رابط یکپارچه فراهم می‌کند.

این سیستم از دو بخش اصلی تشکیل شده است: یک استور مرکزی در پکیج @wordpress/data که وضعیت اعلان‌ها را نگهداری می‌کند، و مجموعه‌ای از کامپوننت‌های React که این اعلان‌ها را در رابط کاربری نمایش می‌دهند. توسعه‌دهندگان می‌توانند از طریق API ساده‌ای اعلان‌ها را ثبت، حذف یا به‌روزرسانی کنند.

مشکل اصلی که Notices API حل می‌کند، پراکندگی و ناسازگاری در نمایش پیام‌های سیستمی است. پیش از این API، هر توسعه‌دهنده رویکرد خود را داشت: برخی از admin_notices استفاده می‌کردند، برخی HTML خام تزریق می‌کردند و برخی از کتابخانه‌های شخص ثالث بهره می‌بردند. این پراکندگی باعث ناهمگونی بصری و دشواری در نگهداری می‌شد. برای آشنایی با مبانی وردپرس، مقاله وردپرس چیست و چگونه شروع به کار با آن کنیم؟ را ببینید.

Notices API یک سیستم نمایش پیام نیست؛ یک زبان مشترک است که همه اجزای وردپرس برای گفتگو با کاربر از آن استفاده می‌کنند.

چرا نمایش پیام‌های سیستمی را متحول کرد؟

Notices API نمایش پیام‌های سیستمی در وردپرس را از چند منظر بنیادین متحول کرد. هر یک از این تحولات به تنهایی می‌توانست اهمیت این API را توجیه کند، اما ترکیب آن‌ها یک تغییر پارادایمی ایجاد کرده است.

۱. یکپارچگی بصری

پیش از Notices API، اعلان‌های هر افزونه ظاهر خاص خود را داشتند. برخی از رنگ‌های متفاوت استفاده می‌کردند، برخی از آیکون‌های غیراستاندارد، و برخی از چیدمان‌های نامتعارف. این ناهمگونی باعث می‌شد که کاربر نتواند به‌سرعت نوع پیام را تشخیص دهد. Notices API این مشکل را با ارائه یک زبان بصری واحد حل کرد.

۲. مدیریت متمرکز وضعیت

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

۳. کاهش کد تکراری

توسعه‌دهندگان دیگر نیازی به نوشتن HTML، CSS و جاوااسکریپت برای هر اعلان ندارند. کافی است یک آبجکت ساده به استور ارسال کنند و سیستم مسئولیت نمایش را بر عهده می‌گیرد.

۴. دسترس‌پذیری بهبودیافته

Notices API از ابتدا با رعایت اصول دسترس‌پذیری طراحی شده است. اعلان‌ها دارای نقش‌های ARIA مناسب، برچسب‌های قابل خواندن توسط صفحه‌خوان، و پشتیبانی از ناوبری با کیبورد هستند. این ویژگی در روش‌های سنتی به‌طور معمول نادیده گرفته می‌شد.

۵. پشتیبانی از Snackbar

Notices API دو نوع نمایش را پشتیبانی می‌کند: Notice که به صورت ثابت در بالای صفحه نمایش داده می‌شود، و Snackbar که به صورت موقت در گوشه صفحه ظاهر شده و به‌طور خودکار محو می‌گردد. این تنوع به توسعه‌دهنده اجازه می‌دهد بر اساس ماهیت پیام، نوع نمایش مناسب را انتخاب کند. برای مطالعه درباره Command Palette، مقاله WordPress Command Palette چطور سرعت کار با وردپرس را چند برابر می‌کند؟ را ببینید.

جدول ۱: تحولات کلیدی Notices API در نمایش پیام‌های سیستمی
معیار پیش از Notices API با Notices API
یکپارچگی بصری پراکنده و ناسازگار استاندارد و منسجم
مدیریت وضعیت محلی در هر کامپوننت متمرکز در استور مرکزی
کد مورد نیاز HTML + CSS + JS یک آبجکت ساده
دسترس‌پذیری معمولاً نادیده گرفته می‌شد بومی و استاندارد
انواع نمایش محدود به Notice Notice + Snackbar

پیش از Notices API: هرج‌ومرج پیام‌های سیستمی

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

مشکل تعدد رویکردها

هر توسعه‌دهنده رویکرد خود را برای نمایش پیام انتخاب می‌کرد. برخی از هوک admin_notices استفاده می‌کردند که فقط در پیشخوان کار می‌کرد. برخی HTML خام با کلاس‌های CSS سفارشی تزریق می‌کردند. برخی از کتابخانه‌های Toast شخص ثالث بهره می‌بردند. این تعدد باعث می‌شد که کاربر با چندین سبک بصری متفاوت روبرو شود.

مشکل مدیریت وضعیت

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

مشکل دسترس‌پذیری

بسیاری از پیاده‌سازی‌های سنتی، اصول دسترس‌پذیری را نادیده می‌گرفتند. اعلان‌ها بدون نقش ARIA، بدون برچسب قابل خواندن و بدون پشتیبانی از کیبورد نمایش داده می‌شدند. این ضعف در پروژه‌هایی که به استانداردهای WCAG نیاز داشتند، یک مانع جدی بود. برای مطالعه درباره دسترس‌پذیری، مقاله WCAG چیست و چه کاربردی دارد؟ را ببینید.

مشکل عدم هماهنگی با Global Styles

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

Notices API این چالش‌ها را با یک راه‌حل یکپارچه برطرف کرد. این رویکرد مشابه کاری است که Global Styles برای مدیریت رنگ و تایپوگرافی انجام داده است. برای مطالعه درباره آن، مقاله Global Styles در وردپرس چطور مدیریت استایل را متحول کرد؟ را ببینید.

معماری فنی و لایه‌های انتزاعی

Notices API از چند لایه فنی تشکیل شده که هر یک نقش مشخصی در مدیریت و نمایش اعلان‌ها ایفا می‌کند. درک این معماری برای استفاده حرفه‌ای از سیستم ضروری است.

لایه اول: استور مرکزی

قلب Notices API، استور مرکزی است که در پکیج @wordpress/notices تعریف شده است. این استور بر پایه @wordpress/data ساخته شده و وضعیت تمام اعلان‌ها را در یک آرایه نگهداری می‌کند. هر اعلان یک آبجکت با خصوصیات مشخص است: شناسه یکتا، وضعیت (Status)، محتوا (Content)، و گزینه‌های اضافی مانند نوع (Type).

لایه دوم: اکشن‌ها و انتخابگرها

استور از یک سیستم اکشن و انتخابگر استفاده می‌کند. اکشن‌هایی مانند createNotice، createSuccessNotice، createErrorNotice و removeNotice برای تغییر وضعیت به کار می‌روند. انتخابگرهایی مانند getNotices برای خواندن وضعیت استفاده می‌شوند.

لایه سوم: کامپوننت‌های رابط کاربری

پکیج @wordpress/components سه کامپوننت اصلی برای نمایش اعلان‌ها ارائه می‌دهد: Notice که یک اعلان ثابت را نمایش می‌دهد، Snackbar که یک اعلان موقت را نشان می‌دهد، و SnackbarList که چندین Snackbar را در یک منطقه جمع می‌کند.

لایه چهارم: هوک‌های React

پکیج @wordpress/notices چندین هوک React برای تعامل با استور فراهم می‌کند. هوک useSelect برای خواندن اعلان‌ها و هوک useDispatch برای ایجاد یا حذف اعلان‌ها استفاده می‌شود.

لایه پنجم: ادغام با پیشخوان وردپرس

وردپرس در پیشخوان، از یک نمونه سراسری از Notices API استفاده می‌کند. اعلان‌های ثبت‌شده از هر بخش، در یک مکان واحد نمایش داده می‌شوند. این ادغام، تجربه کاربری یکپارچه‌ای ایجاد کرده است.

جدول ۲: لایه‌های معماری Notices API
لایه مسئولیت پکیج
استور مرکزی نگهداری وضعیت اعلان‌ها @wordpress/notices
اکشن و انتخابگر تغییر و خواندن وضعیت @wordpress/data
کامپوننت‌ها نمایش بصری اعلان @wordpress/components
هوک‌های React رابط برنامه‌نویسی @wordpress/notices
ادغام با پیشخوان نمایش سراسری هسته وردپرس

انواع Notice و کاربرد هر یک

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

۱. Notice موفقیت (Success)

برای نمایش پیام‌های موفقیت‌آمیز مانند ذخیره تنظیمات، نصب افزونه یا انتشار نوشته استفاده می‌شود. این اعلان‌ها معمولاً با رنگ سبز و آیکون تیک نمایش داده می‌شوند.

۲. Notice خطا (Error)

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

۳. Notice هشدار (Warning)

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

۴. Notice اطلاعاتی (Info)

برای نمایش اطلاعات عمومی و راهنما به کار می‌رود. این اعلان‌ها با رنگ آبی نمایش داده می‌شوند و معمولاً غیرحیاتی هستند.

۵. Snackbar

نوع خاصی از اعلان است که به صورت موقت در گوشه صفحه ظاهر می‌شود و پس از چند ثانیه به‌طور خودکار محو می‌گردد. برای پیام‌های غیرحیاتی مانند «ذخیره شد» یا «حذف شد» مناسب است.

انتخاب نوع Notice مانند انتخاب لحن کلام است: هر پیام باید با شدت و اهمیت خودش منتقل شود.

API جاوااسکریپت و ثبت Notice

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

استفاده از dispatch

روش استاندارد ثبت اعلان، استفاده از dispatch از پکیج @wordpress/data است:

import { dispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';

dispatch( noticesStore ).createNotice(
    'success',
    'تنظیمات با موفقیت ذخیره شد.',
    {
        isDismissible: true,
        type: 'snackbar',
        id: 'save-success',
    }
);

در این مثال، یک اعلان موفقیت از نوع Snackbar با شناسه یکتا ثبت می‌شود. پارامتر isDismissible تعیین می‌کند که کاربر می‌تواند اعلان را ببندد یا خیر.

استفاده از هوک useDispatch

در کامپوننت‌های React، می‌توان از هوک useDispatch استفاده کرد:

import { useDispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';

const MyComponent = () => {
    const { createSuccessNotice, removeNotice } = useDispatch( noticesStore );

    const handleSave = () => {
        createSuccessNotice( 'تغییرات ذخیره شد.', {
            type: 'snackbar',
            id: 'my-save-notice',
        } );
    };

    return <button onClick={ handleSave }>ذخیره</button>;
};

این رویکرد در کامپوننت‌های مدرن React ترجیح داده می‌شود زیرا از قواعد هوک‌ها پیروی می‌کند و امکان مدیریت بهتر چرخه حیات کامپوننت را فراهم می‌آورد.

حذف اعلان

برای حذف یک اعلان خاص، از اکشن removeNotice استفاده کنید:

dispatch( noticesStore ).removeNotice( 'save-success' );

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

ادغام با PHP و پیشخوان

Notices API عمدتاً یک سیستم جاوااسکریپت است، اما ادغام آن با PHP نیز امکان‌پذیر است. این ادغام برای نمایش اعلان‌های سمت سرور مانند خطاهای ذخیره‌سازی یا پیام‌های پس از redirect کاربرد دارد.

استفاده از admin_notices

در سمت PHP، می‌توان از هوک admin_notices برای تزریق اعلان به پیشخوان استفاده کرد. اما این روش با Notices API یکپارچه نیست و اعلان در استور مرکزی ثبت نمی‌شود.

add_action( 'admin_notices', function () {
    if ( get_transient( 'my_plugin_notice' ) ) {
        printf(
            '<div class="notice notice-success is-dismissible"><p>%s</p></div>',
            esc_html__( 'عملیات با موفقیت انجام شد.', 'my-plugin' )
        );
        delete_transient( 'my_plugin_notice' );
    }
} );

ادغام با REST API

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

نمایش اعلان در ویرایشگر بلاک

در ویرایشگر بلاک، Notices API به صورت بومی ادغام شده است. وقتی یک خطا در ذخیره نوشته رخ می‌دهد، ویرایشگر به‌طور خودکار یک اعلان خطا نمایش می‌دهد. برای مطالعه درباره ویرایشگر، مقاله Gutenberg چیست و چگونه ویرایش محتوای وردپرس را متحول کرد؟ را ببینید.

استور مرکزی و مدیریت وضعیت

استور مرکزی Notices API بر پایه پکیج @wordpress/data بنا شده است. این پکیج یک سیستم مدیریت وضعیت مشابه Redux فراهم می‌کند که امکان دسترسی به وضعیت از هر نقطه‌ای از برنامه را میسر می‌سازد.

ساختار استور

استور Notices API شامل یک آرایه از اعلان‌هاست. هر اعلان یک آبجکت با خصوصیات زیر است:

  • id: شناسه یکتا برای اعلان
  • status: وضعیت اعلان (success، error، warning، info)
  • content: محتوای متنی اعلان
  • spokenMessage: پیام قابل خواندن توسط صفحه‌خوان
  • isDismissible: قابلیت بسته شدن توسط کاربر
  • type: نوع نمایش (default یا snackbar)
  • actions: دکمه‌های عملیاتی قابل افزودن

انتخابگرها (Selectors)

انتخابگرهای اصلی شامل getNotices برای خواندن همه اعلان‌ها و getNotices با پارامتر context برای خواندن اعلان‌های یک بخش خاص است. این انتخابگرها امکان فیلتر و سازمان‌دهی اعلان‌ها را فراهم می‌کنند.

Context و سازمان‌دهی اعلان‌ها

هر اعلان می‌تواند به یک Context خاص تعلق داشته باشد. برای مثال، اعلان‌های ویرایشگر نوشته در Context core/edit-post ثبت می‌شوند. این سازمان‌دهی امکان نمایش اعلان‌های مرتبط با هر بخش را در همان بخش فراهم می‌کند.

dispatch( noticesStore ).createNotice(
    'success',
    'پیش‌نویس ذخیره شد.',
    {
        id: 'draft-saved',
        type: 'snackbar',
        context: 'core/edit-post',
    }
);

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

کامپوننت‌های رابط کاربری

پکیج @wordpress/components سه کامپوننت اصلی برای نمایش اعلان‌ها ارائه می‌دهد که هر یک کاربرد خاصی دارد.

کامپوننت Notice

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

import { Notice } from '@wordpress/components';

const MyNotice = () => (
    <Notice status="warning" isDismissible onRemove={ () => {} }>
        این یک هشدار مهم است.
    </Notice>
);

کامپوننت Snackbar

کامپوننت Snackbar یک اعلان موقت را نمایش می‌دهد که به‌طور خودکار پس از چند ثانیه محو می‌شود. این کامپوننت برای پیام‌های غیرحیاتی مناسب است.

import { Snackbar } from '@wordpress/components';

const MySnackbar = () => (
    <Snackbar>
        تغییرات ذخیره شد.
    </Snackbar>
);

کامپوننت SnackbarList

کامپوننت SnackbarList چندین Snackbar را در یک منطقه جمع کرده و به‌طور خودکار آن‌ها را مدیریت می‌کند. این کامپوننت معمولاً با استور Notices API ادغام می‌شود.

import { SnackbarList } from '@wordpress/components';
import { useSelect, useDispatch } from '@wordpress/data';
import { store as noticesStore } from '@wordpress/notices';

const MySnackbarList = () => {
    const notices = useSelect( ( select ) =>
        select( noticesStore ).getNotices( 'my-context' )
    );
    const { removeNotice } = useDispatch( noticesStore );

    return (
        <SnackbarList
            notices={ notices }
            onRemove={ removeNotice }
        />
    );
};

این الگو در پروژه‌های واقعی رایج است و امکان نمایش هماهنگ چندین اعلان را فراهم می‌کند.

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

Notices API در پروژه‌های واقعی کاربردهای متنوعی دارد. در ادامه، چند سناریوی عملی بررسی می‌شود.

۱. اعلان موفقیت پس از ذخیره تنظیمات

رایج‌ترین کاربرد Notices API، نمایش پیام موفقیت پس از ذخیره تنظیمات است:

const handleSave = async () => {
    try {
        await saveSettings( formData );
        createSuccessNotice( 'تنظیمات با موفقیت ذخیره شد.', {
            type: 'snackbar',
            id: 'settings-saved',
        } );
    } catch ( error ) {
        createErrorNotice( error.message, {
            isDismissible: true,
            id: 'settings-error',
        } );
    }
};

۲. اعلان با دکمه عملیاتی

Notices API امکان افزودن دکمه‌های عملیاتی به اعلان را فراهم می‌کند. این ویژگی برای پیام‌هایی که نیازمند واکنش کاربر هستند، مفید است:

createNotice( 'info', 'آیا می‌خواهید تغییرات را ذخیره کنید؟', {
    id: 'unsaved-changes',
    actions: [
        {
            label: 'ذخیره',
            onClick: () => saveChanges(),
        },
        {
            label: 'انصراف',
            onClick: () => dismissChanges(),
        },
    ],
} );

۳. اعلان با پیام قابل خواندن توسط صفحه‌خوان

برای دسترس‌پذیری بهتر، می‌توان پیام جداگانه‌ای برای صفحه‌خوان تعریف کرد:

createSuccessNotice( 'فایل آپلود شد.', {
    id: 'file-uploaded',
    type: 'snackbar',
    spokenMessage: 'فایل با نام example.jpg با موفقیت آپلود شد.',
} );

۴. اعلان گروهی

در سناریوهایی که چندین عملیات همزمان انجام می‌شود، می‌توان اعلان‌ها را گروه‌بندی کرد:

const results = await Promise.all( tasks.map( runTask ) );
results.forEach( ( result, index ) => {
    if ( result.success ) {
        createSuccessNotice( `تسک ${ index + 1 } انجام شد.`, {
            id: `task-${ index }-success`,
            type: 'snackbar',
        } );
    }
} );

دسترس‌پذیری در Notices API

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

نقش‌های ARIA

اعلان‌های Notice از نقش status یا alert استفاده می‌کنند که به صفحه‌خوان اعلام می‌کند محتوای جدیدی ظاهر شده است. اعلان‌های خطا از alert و اعلان‌های موفقیت از status بهره می‌برند.

ویژگی aria-live

ویژگی aria-live تعیین می‌کند که تغییرات در ناحیه‌ای از صفحه چگونه به کاربر اطلاع داده شود. اعلان‌های مهم از aria-live="assertive" و اعلان‌های کم‌اهمیت از aria-live="polite" استفاده می‌کنند.

پیام spokenMessage

ویژگی spokenMessage امکان تعریف پیام متفاوتی برای صفحه‌خوان را فراهم می‌کند. این ویژگی برای اعلان‌هایی که محتوای بصری دارند اما باید به صورت صوتی توضیح داده شوند، حیاتی است.

پشتیبانی از کیبورد

اعلان‌ها با کلید Tab قابل دسترسی هستند و دکمه‌های بستن با Enter یا Space فعال می‌شوند. این ویژگی برای کاربرانی که نمی‌توانند از ماوس استفاده کنند، ضروری است. برای مطالعه درباره دسترس‌پذیری، مقاله استانداردهای دسترس‌پذیری وب را ببینید.

دسترس‌پذیری یک ویژگی اضافی نیست؛ یک نیاز بنیادین است که تجربه کاربری همه را بهبود می‌بخشد.

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

Notices API به عنوان یک سیستم مدیریت وضعیت، تأثیر مستقیمی بر عملکرد برنامه دارد. این تأثیر بستگی به نحوه استفاده دارد.

تعداد اعلان‌های همزمان

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

Context و بهینه‌سازی رندر

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

استفاده از Snackbar به جای Notice

Snackbarها به دلیل محو شدن خودکار، بار کمتری بر رابط کاربری وارد می‌کنند. برای پیام‌های غیرحیاتی، استفاده از Snackbar ترجیح داده می‌شود.

کش کردن نتایج

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

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

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

۱. عدم تعریف id یکتا

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

۲. استفاده نادرست از نوع Notice

استفاده از نوع error برای پیام‌های غیرحیاتی می‌تواند حس هشدار کاذب ایجاد کند. انتخاب نوع مناسب برای هر پیام ضروری است.

۳. نادیده گرفتن دسترس‌پذیری

عدم تعریف spokenMessage برای اعلان‌های پیچیده، دسترسی کاربران صفحه‌خوان را محدود می‌کند.

۴. عدم حذف اعلان‌های قدیمی

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

۵. استفاده از context نادرست

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

۶. عدم مدیریت خطا در عملیات async

در عملیات ناهمزمان، اگر خطا مدیریت نشود، اعلان نامناسبی نمایش داده می‌شود. استفاده از بلوک try/catch ضروری است.

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

Notices API چیست و چه کاربردی دارد؟

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

چگونه یک Notice در وردپرس ثبت کنم؟

از طریق dispatch یا هوک useDispatch می‌توانید اکشن createNotice را فراخوانی کنید. مثال: dispatch( noticesStore ).createNotice( 'success', 'ذخیره شد.' ).

تفاوت Notice و Snackbar چیست؟

Notice یک اعلان ثابت است که تا بسته شدن توسط کاربر باقی می‌ماند. Snackbar یک اعلان موقت است که پس از چند ثانیه به‌طور خودکار محو می‌شود. Snackbar برای پیام‌های غیرحیاتی مناسب‌تر است.

آیا Notices API از دسترس‌پذیری پشتیبانی می‌کند؟

بله، Notices API از نقش‌های ARIA، ویژگی aria-live، پیام spokenMessage و پشتیبانی از کیبورد بهره می‌برد. این ویژگی‌ها اعلان‌ها را برای کاربران صفحه‌خوان قابل درک می‌کند.

چگونه یک Notice را حذف کنم؟

از اکشن removeNotice با شناسه اعلان استفاده کنید: dispatch( noticesStore ).removeNotice( 'my-notice-id' ).

آیا می‌توانم دکمه عملیاتی به Notice اضافه کنم؟

بله، با تعریف آرایه actions در پارامترهای اعلان، می‌توانید دکمه‌های عملیاتی اضافه کنید. هر دکمه شامل label و onClick است.

آیا Notices API در PHP هم قابل استفاده است؟

Notices API عمدتاً جاوااسکریپت است. در PHP می‌توان از هوک admin_notices برای نمایش اعلان‌های سمت سرور استفاده کرد، اما این روش با استور مرکزی یکپارچه نیست.

تفاوت Notices API و admin_notices چیست؟

admin_notices یک هوک PHP است که HTML خام تزریق می‌کند و فقط در پیشخوان کار می‌کند. Notices API یک سیستم جاوااسکریپت است که مدیریت وضعیت متمرکز و کامپوننت‌های آماده ارائه می‌دهد و در ویرایشگر بلاک نیز قابل استفاده است.

نگاهی به لایه‌های زیرین

از منظر مهندسی نرم‌افزار، Notices API یک پیاده‌سازی از الگوی Observer است. در این الگو، کامپوننت‌ها به تغییرات وضعیت اعلان‌ها مشترک می‌شوند و در صورت تغییر، به‌طور خودکار به‌روزرسانی می‌شوند. این رویکرد مشابه الگوی Publisher-Subscriber است که در سیستم‌های توزیع‌شده رایج است.

در سطح پیاده‌سازی، وردپرس از استور core/notices برای نگهداری اعلان‌ها استفاده می‌کند. این استور با @wordpress/data ادغام شده و از تمام قابلیت‌های آن مانند میان‌افزار (Middleware) و رزولورهای (Resolvers) بهره می‌برد.

یکی از جنبه‌های پیشرفته، مدیریت Context است. هر اعلان می‌تواند به یک Context خاص تعلق داشته باشد و انتخابگرها می‌توانند اعلان‌های یک Context خاص را فیلتر کنند. این جداسازی، امکان استفاده همزمان از Notices API در بخش‌های مختلف برنامه را فراهم می‌کند بدون تداخل.

در سطح عمیق‌تر، Notices API از مکانیزم Optimistic Update استفاده می‌کند. وقتی یک اعلان ثبت می‌شود، بلافاصله در رابط کاربری نمایش داده می‌شود، بدون انتظار برای تأیید سرور. این رویکرد تجربه کاربری را روان‌تر می‌کند و تأخیر شبکه را پنهان می‌سازد.

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

در سطح معماری کلان، Notices API بخشی از یک روند گسترده‌تر در اکوسیستم وردپرس است: حرکت از مدیریت محلی به سمت مدیریت متمرکز. این روند در Global Styles، Font Library و Block Bindings نیز قابل مشاهده است. برای مطالعه درباره Font Library، مقاله Font Library در وردپرس چیست و چرا مدیریت فونت در FSE را ساده کرد؟ را ببینید.

در سطح عملکرد، Notices API از تکنیک‌هایی مانند Memoization و Selector-based Rendering بهره می‌برد. این تکنیک‌ها از رندر مجدد غیرضروری کامپوننت‌ها جلوگیری کرده و عملکرد رابط کاربری را بهبود می‌بخشند.

در آینده، انتظار می‌رود که Notices API با قابلیت‌هایی مانند اعلان‌های مبتنی بر هوش مصنوعی، اولویت‌بندی خودکار و ادغام عمیق‌تر با سیستم‌های خارجی گسترش یابد. این تحولات، Notices API را از یک سیستم نمایش پیام به یک دستیار هوشمند برای تعامل با کاربر تبدیل خواهد کرد. برای مطالعه درباره WordPress Playground، مقاله WordPress Playground چطور وردپرس را بدون نصب در مرورگر اجرا می‌کند؟ را ببینید.

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

Notices API یک تغییر پارادایمی در نحوه نمایش پیام‌های سیستمی در وردپرس است. این API با ارائه یک استور مرکزی، کامپوننت‌های آماده و پشتیبانی بومی از دسترس‌پذیری، تجربه کاربری را در سراسر اکوسیستم وردپرس بهبود بخشیده است. از منظر معماری، Notices API یک لایه انتزاعی تمیز روی سیستم مدیریت وضعیت وردپرس ایجاد می‌کند و نمایش پیام‌ها را از یک کار پراکنده به یک عملیات متمرکز تبدیل می‌نماید.

برای توسعه‌دهندگان، تسلط بر Notices API به یک مهارت ضروری تبدیل شده است. این API نه تنها در پیشخوان و ویرایشگر بلاک کاربرد دارد، بلکه در هر برنامه React که با وردپرس ادغام می‌شود، قابل استفاده است. با گسترش قابلیت‌های گوتنبرگ و معرفی APIهای جدید، Notices API احتمالاً به یک بخش جدانشدنی از تجربه توسعه وردپرس تبدیل خواهد شد. 🚀

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