آموزش جامع Toastify.js - نوتیفیکیشن Toast فارسی

📚معرفی و شروع سریع

Toastify.js یک کتابخانه سبک و ساده برای نمایش پیام‌های Toast است. بدون هیچ dependency، فقط یک JS و یک CSS — کافیست Toastify({...}).showToast() را فراخوانی کنید.

نصب

<!-- CSS در <head> -->
<link rel="stylesheet" href="toastify.min.css">

<!-- JS قبل از </body> -->
<script src="toastify.min.js"></script>

// ساده‌ترین استفاده
Toastify({
  text: "سلام! این یک Toast است."
}).showToast();

▶ دمو: ساده‌ترین Toast ممکن

ⓘ ساختار پایه: Toastify(options) یک آبجکت Toast برمی‌گرداند. با .showToast() آن را نمایش می‌دهید. می‌توانید نتیجه را در متغیر ذخیره کرده و بعداً .hideToast() صدا بزنید.

📍موقعیت و Gravity

با gravity بالا/پایین و با position چپ/راست/مرکز را انتخاب می‌کنید.

Toastify({
  text:     "بالا راست",
  gravity:  "top",    // 'top' | 'bottom'
  position: "right",  // 'left' | 'center' | 'right'
  duration: 3000
}).showToast();

▶ دمو: ۶ موقعیت مختلف

گزینه	مقادیر	پیش‌فرض
gravity	"top" \| "bottom"	"top"
position	"left" \| "center" \| "right"	"right"

🎨استایل سفارشی

با style (آبجکت CSS) می‌توانید هر جنبه‌ای از ظاهر Toast را تغییر دهید. همچنین className برای اعمال کلاس CSS سفارشی قابل استفاده است.

Toastify({
  text:  "استایل سفارشی",
  style: {
    background:   "linear-gradient(to right, #8e44ad, #3498db)",
    borderRadius: "12px",
    fontSize:     "15px",
    fontWeight:   "bold",
    padding:      "14px 24px",
    boxShadow:    "0 4px 20px rgba(0,0,0,.3)"
  }
}).showToast();

// یا با className
Toastify({
  text:      "با کلاس سفارشی",
  className: "my-toast"
}).showToast();

▶ دمو: استایل‌های متنوع

⏳Duration و Close Button

duration مدت نمایش (میلی‌ثانیه) را تعیین می‌کند. مقدار -1 یا false Toast را دائمی می‌کند. با close دکمه بستن نمایش می‌دهید.

// ۵ ثانیه
Toastify({ text: "۵ ثانیه", duration: 5000 }).showToast();

// دائمی — باید دستی بسته شود
Toastify({
  text:     "این پیام دائمی است",
  duration: -1,    // یا false
  close:    true    // دکمه × نمایش بده
}).showToast();

// بستن برنامه‌ای
const toast = Toastify({ text: "...", duration: -1 });
toast.showToast();
setTimeout(() => toast.hideToast(), 3000);

▶ دمو: duration و close

گزینه	نوع	توضیح
duration	number	مدت نمایش به ms — پیش‌فرض 3000
duration: -1	number	دائمی — بدون بسته شدن خودکار
close	boolean	نمایش دکمه × — پیش‌فرض false
.hideToast()	method	بستن برنامه‌ای Toast

📏Offset — جابجایی دقیق

offset فاصله Toast را از لبه‌های صفحه تنظیم می‌کند. وقتی نمی‌خواهید Toast دقیقاً در گوشه باشد مفید است.

Toastify({
  text:     "با offset سفارشی",
  gravity:  "top",
  position: "right",
  offset: {
    x: 50,   // px از راست/چپ
    y: 80    // px از بالا/پایین
  }
}).showToast();

// مقادیر string (px, %, rem) هم قبول می‌شود
offset: { x: '50px', y: '5rem' }

▶ دمو: offset‌های مختلف

⚡Callback و onClick

با onClick کلیک روی Toast را مدیریت کنید. با callback بعد از بسته شدن Toast کدی اجرا کنید.

Toastify({
  text:    "روی من کلیک کن!",
  duration: 5000,
  onClick: function() {
    console.log("Toast کلیک شد!");
    // مثلاً: navigate('/notifications')
  }
}).showToast();

Toastify({
  text:     "بعد از بسته شدن اجرا می‌شود",
  duration: 3000,
  callback: function() {
    console.log("Toast بسته شد");
  }
}).showToast();

▶ دمو: onClick و callback

💡 UX: برای Toast‌هایی که قابل کلیک هستند، cursor: 'pointer' را در style اضافه کنید تا کاربر بداند می‌تواند کلیک کند.

👤Avatar و Node سفارشی

با avatar یک تصویر کنار Toast اضافه می‌کنید. با node کاملاً HTML سفارشی داخل Toast قرار می‌دهید.

// avatar — تصویر گرد کنار متن
Toastify({
  text:   "علی محمدی یک پیام فرستاد",
  avatar: "user.jpg",
  style:  { background: "#2c343b" }
}).showToast();

// node — HTML کاملاً سفارشی
const el = document.createElement('div');
el.innerHTML = `
  <div style="display:flex;align-items:center;gap:10px">
    <span style="font-size:24px">🎉</span>
    <div>
      <b>تبریک!</b><br>
      <small>سفارش شما تأیید شد</small>
    </div>
  </div>
`;
Toastify({ node: el, duration: 4000 }).showToast();

▶ دمو: node HTML سفارشی

▮▮Progress Bar

Toastify.js نوار پیشرفت داخلی ندارد، اما با node می‌توانید به سادگی یک Progress Bar سفارشی بسازید.

function toastWithProgress(text, duration, bg) {
  const wrap = document.createElement('div');
  wrap.style.cssText = 'min-width:220px';
  wrap.innerHTML = `
    <div>${text}</div>
    <div class="prog-track" style="margin-top:8px;background:rgba(255,255,255,.2);border-radius:3px;height:4px">
      <div class="prog-bar" style="height:4px;background:#fff;border-radius:3px;width:100%;
           transition:width ${duration}ms linear"></div>
    </div>
  `;
  const toast = Toastify({ node: wrap, duration: duration, style: { background: bg } });
  toast.showToast();
  requestAnimationFrame(() =>
    requestAnimationFrame(() =>
      wrap.querySelector('.prog-bar').style.width = '0'
    )
  );
}

▶ دمو: Toast با Progress Bar

📈الگوهای رایج

تابع helper برای انواع Toast

// یک بار تعریف کنید، همه جا استفاده کنید
const notify = {
  success: msg => Toastify({ text: `✅ ${msg}`, style: { background:'#27ae60' }, duration:3000, gravity:'top', position:'right' }).showToast(),
  error:   msg => Toastify({ text: `❌ ${msg}`, style: { background:'#e74c3c' }, duration:4000, gravity:'top', position:'right' }).showToast(),
  warning: msg => Toastify({ text: `⚠️ ${msg}`, style: { background:'#e67e22' }, duration:4000, gravity:'bottom', position:'center' }).showToast(),
  info:    msg => Toastify({ text: `ℹ️ ${msg}`, style: { background:'#3498db' }, duration:3000, gravity:'top', position:'center' }).showToast()
};

// استفاده
notify.success('اطلاعات ذخیره شد');
notify.error('خطا در ارتباط با سرور');

▶ دمو: notify helper

Toast زنجیره‌ای (Queue)

// Toast‌های پشت سر هم با تأخیر
function queueToasts(messages) {
  messages.forEach((msg, i) => {
    setTimeout(() => Toastify({ text: msg.text, style: { background: msg.color }, duration: 2500 }).showToast(), i * 800);
  });
}

▶ دمو: چند Toast پشت سر هم

🔥چیت‌شیت

گزینه	نوع	پیش‌فرض	توضیح
text	string	""	متن Toast
node	Element	—	HTML سفارشی (جایگزین text)
duration	number	3000	مدت نمایش (ms) — 1- برای دائمی
gravity	string	"top"	"top" \| "bottom"
position	string	"right"	"left" \| "center" \| "right"
close	boolean	false	نمایش دکمه ×
style	object	{}	CSS inline — background، borderRadius، ...
className	string	""	کلاس CSS سفارشی
offset	object	{x:0, y:0}	جابجایی از لبه
avatar	string	""	URL تصویر گرد کنار متن
onClick	function	—	هنگام کلیک روی Toast
callback	function	—	بعد از بسته شدن Toast
stopOnFocus	boolean	true	توقف تایمر هنگام hover
escapeMarkup	boolean	true	false = اجازه HTML در text
selector	string/Element	—	container سفارشی برای Toast

متدها

متد	توضیح
.showToast()	نمایش Toast
.hideToast()	بستن برنامه‌ای Toast

💡 بهترین روش: یک آبجکت notify با متدهای success/error/warning/info تعریف کنید و در کل پروژه استفاده کنید. این کار ظاهر Toast‌ها را یکدست نگه می‌دارد.

⚠ stopOnFocus: پیش‌فرض true است — وقتی ماوس روی Toast می‌رود تایمر متوقف می‌شود. برای Toast‌های اطلاعاتی مفید است، برای Toast‌های کوتاه غیرضروری.

🚀زمین بازی کد (Playground)

نوتیفیکیشن‌های Toastify را امتحان کن: رنگ، موقعیت و مدت‌زمان را تغییر بده و دکمه‌ها را بزن. نسخهٔ ۱.۱۲.۰ آفلاین بارگذاری می‌شود.