NotificationManager - ระบบแจ้งเตือนแบบ Toast

เอกสารฉบับนี้อธิบาย NotificationManager ซึ่งเป็นระบบแจ้งเตือนแบบ toast notifications สำหรับ Now.js Framework รองรับการแสดงข้อความประเภทต่างๆ พร้อม animation และการจัดการอัตโนมัติ

📋 สารบัญ

1. ภาพรวม
2. การติดตั้งและนำเข้า
3. การเริ่มต้นใช้งาน
4. ประเภทการแจ้งเตือน
5. การตั้งค่า
6. ตัวอย่างการใช้งาน
7. เอกสารอ้างอิง API
8. แนวทางปฏิบัติที่แนะนำ
9. ปัญหาที่พบบ่อย

ภาพรวม

NotificationManager เป็นระบบแจ้งเตือนแบบ toast ที่ออกแบบมาเพื่อแสดงข้อความชั่วคราวให้ผู้ใช้เห็น โดยไม่รบกวนการทำงาน รองรับหลายประเภทการแจ้งเตือน animation และการจัดการอัตโนมัติ

ฟีเจอร์หลัก

• ✅ หลายประเภท: รองรับ success, error, warning, info และ loading
• ✅ Auto-dismiss: ปิดอัตโนมัติตามเวลาที่กำหนด
• ✅ Smart Replacement: แทนที่ notification ประเภทเดียวกันอัตโนมัติ
• ✅ Animation: รองรับ animation หลากหลายรูปแบบ
• ✅ ตำแหน่งที่ปรับได้: วางตำแหน่งได้ 4 มุมของหน้าจอ
• ✅ Progress Bar: แสดงแถบความคืบหน้าการปิดอัตโนมัติ
• ✅ Queue System: จัดการ notification ที่แสดงพร้อมกันได้
• ✅ การเข้าถึง: รองรับ ARIA attributes สำหรับ screen readers
• ✅ RTL Support: รองรับภาษาที่เขียนจากขวาไปซ้าย

เมื่อควรเลือกใช้ NotificationManager

✅ แนะนำให้ใช้เมื่อ:

• ต้องการแจ้งผลการดำเนินการให้ผู้ใช้ทราบ
• ต้องการแสดงข้อความชั่วคราวที่ไม่รบกวนการทำงาน
• ต้องการแจ้งเตือนที่มี animation สวยงาม
• ต้องการระบบที่จัดการ notification หลายรายการได้

❌ พิจารณาทางเลือกอื่นเมื่อ:

• ต้องการ dialog ที่ต้องให้ผู้ใช้ตอบรับ (ใช้ DialogManager แทน)
• ต้องการแสดงข้อความถาวรในหน้า (ใช้ FormError แทน)

การติดตั้งและนำเข้า

NotificationManager โหลดมาพร้อมกับ Now.js Framework และพร้อมใช้งานทันทีผ่าน window object:

// ไม่ต้อง import - พร้อมใช้งานทันที
console.log(window.NotificationManager); // อ็อบเจ็กต์ NotificationManager

การเริ่มต้นใช้งาน

การตั้งค่าพื้นฐาน

// เริ่มต้นใช้งาน NotificationManager (ทำอัตโนมัติโดย Now.js)
await NotificationManager.init({
  position: 'top-right',
  duration: 3000,
  maxVisible: 5,
  animation: true
});

console.log('NotificationManager พร้อมใช้งานแล้ว!');

ตัวอย่างการใช้งานพื้นฐาน

// แสดงข้อความสำเร็จ
NotificationManager.success('บันทึกข้อมูลสำเร็จ!');

// แสดงข้อความผิดพลาด
NotificationManager.error('เกิดข้อผิดพลาด กรุณาลองใหม่อีกครั้ง');

// แสดงคำเตือน
NotificationManager.warning('คุณมีการเปลี่ยนแปลงที่ยังไม่ได้บันทึก');

// แสดงข้อมูล
NotificationManager.info('มีข้อความใหม่ 3 รายการ');

ประเภทการแจ้งเตือน

1. Success (สำเร็จ) ✅

ใช้สำหรับแจ้งผลการดำเนินการที่สำเร็จ

NotificationManager.success('ลงทะเบียนสำเร็จ!');

// พร้อมตัวเลือกเพิ่มเติม
NotificationManager.success('อัปโหลดไฟล์สำเร็จ', {
  duration: 5000,
  progressBar: true
});

คุณสมบัติ:

• Duration: 3000ms (3 วินาที) - หายอัตโนมัติ
• Icon: ✓ (valid)
• สี: เขียว

2. Error (ผิดพลาด) ❌

ใช้สำหรับแจ้งข้อผิดพลาดที่ผู้ใช้ต้องรับทราบ

NotificationManager.error('ไม่สามารถบันทึกข้อมูลได้');

// พร้อมตัวเลือกเพิ่มเติม
NotificationManager.error('การเชื่อมต่อขาดหาย', {
  duration: 8000  // แสดงนานขึ้น 8 วินาที
});

คุณสมบัติ:

• Duration: 8000ms (8 วินาที) - ให้เวลาอ่านมากกว่า
• Icon: ⊗ (ban)
• สี: แดง

เหตุผล: Error messages ต้องการเวลาในการอ่านและเข้าใจมากกว่า ดังนั้นจึงแสดงนานกว่าประเภทอื่น

3. Warning (คำเตือน) ⚠️

ใช้สำหรับแจ้งเตือนสิ่งที่ผู้ใช้ควรระวัง

NotificationManager.warning('รหัสผ่านของคุณจะหมดอายุใน 7 วัน');

// พร้อมตัวเลือกเพิ่มเติม
NotificationManager.warning('พื้นที่จัดเก็บเหลือน้อย', {
  duration: 8000
});

คุณสมบัติ:

• Duration: 8000ms (8 วินาที) - ให้เวลาอ่านมากกว่า
• Icon: ⚠ (warning)
• สี: ส้ม/เหลือง

เหตุผล: Warning messages เป็นข้อมูลสำคัญที่ผู้ใช้ควรรับทราบ ต้องการเวลาในการอ่านและตัดสินใจ

4. Info (ข้อมูล) ℹ️

ใช้สำหรับแจ้งข้อมูลทั่วไปที่ไม่ critical

NotificationManager.info('ระบบจะปิดปรับปรุงในวันอาทิตย์');

// พร้อมตัวเลือกเพิ่มเติม
NotificationManager.info('เวอร์ชันใหม่พร้อมให้ใช้งาน', {
  duration: 5000
});

คุณสมบัติ:

• Duration: 3000ms (3 วินาที) - หายอัตโนมัติ
• Icon: ℹ (info)
• สี: น้ำเงิน

5. Loading (กำลังโหลด) ⏳

ใช้สำหรับแสดงสถานะกำลังทำงาน ต้องปิดด้วย code

// แสดง loading
const loadingId = NotificationManager.loading('กำลังอัปโหลดไฟล์...');

// ทำงานบางอย่าง
await uploadFile();

// ปิด loading
NotificationManager.dismiss(loadingId);

// หรือแสดงผลลัพธ์
NotificationManager.success('อัปโหลดเสร็จสิ้น!');

คุณสมบัติ:

• Duration: 0 (ไม่หายอัตโนมัติ)
• Icon: ⟳ (loader)
• Dismissible: false (ปิดไม่ได้ด้วยตนเอง)

การตั้งค่า

การตั้งค่าแบบ Global

NotificationManager.init({
  // ตำแหน่งการแสดง
  position: 'top-right',  // top-right, top-left, bottom-right, bottom-left

  // ระยะเวลาแสดงเริ่มต้น (มิลลิวินาที)
  duration: 3000,

  // จำนวนสูงสุดที่แสดงพร้อมกัน
  maxVisible: 5,

  // เปิด/ปิด animation
  animation: true,

  // ปิดได้ด้วยตนเอง
  dismissible: true,

  // แสดงปุ่มปิด
  closeButton: true,

  // แสดง icon
  icons: true,

  // แสดง progress bar
  progressBar: false,

  // หยุดชั่วคราวเมื่อ hover
  pauseOnHover: false,

  // รองรับ RTL
  rtl: false,

  // รองรับ ARIA
  aria: true
});

การตั้งค่าเฉพาะครั้ง

// กำหนด duration เฉพาะครั้ง
NotificationManager.success('บันทึกสำเร็จ', {
  duration: 5000  // แสดง 5 วินาที
});

// ปิด progress bar
NotificationManager.error('เกิดข้อผิดพลาด', {
  progressBar: false
});

// ไม่ให้ปิดได้
NotificationManager.warning('กรุณารอสักครู่', {
  dismissible: false,
  duration: 0  // ไม่หายอัตโนมัติ
});

ตัวอย่างการใช้งาน

ตัวอย่างที่ 1: การส่งฟอร์ม

// เมื่อกดส่งฟอร์ม
document.getElementById('myForm').addEventListener('submit', async (e) => {
  e.preventDefault();

  // แสดง loading
  const loadingId = NotificationManager.loading('กำลังบันทึกข้อมูล...');

  try {
    // ส่งข้อมูล
    const response = await fetch('/api/save', {
      method: 'POST',
      body: new FormData(e.target)
    });

    // ปิด loading
    NotificationManager.dismiss(loadingId);

    if (response.ok) {
      // แสดงความสำเร็จ
      NotificationManager.success('บันทึกข้อมูลสำเร็จ!');
    } else {
      // แสดงข้อผิดพลาด
      NotificationManager.error('ไม่สามารถบันทึกข้อมูลได้');
    }
  } catch (error) {
    // ปิด loading
    NotificationManager.dismiss(loadingId);

    // แสดงข้อผิดพลาด
    NotificationManager.error('เกิดข้อผิดพลาด: ' + error.message);
  }
});

ตัวอย่างที่ 2: การอัปโหลดไฟล์

async function uploadFile(file) {
  // แสดง loading พร้อม progress bar
  const loadingId = NotificationManager.loading('กำลังอัปโหลด...', {
    progressBar: true
  });

  try {
    const formData = new FormData();
    formData.append('file', file);

    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData
    });

    // ปิด loading
    NotificationManager.dismiss(loadingId);

    if (response.ok) {
      NotificationManager.success('อัปโหลดไฟล์สำเร็จ!');
    } else {
      NotificationManager.error('อัปโหลดล้มเหลว');
    }
  } catch (error) {
    NotificationManager.dismiss(loadingId);
    NotificationManager.error('เกิดข้อผิดพลาด: ' + error.message);
  }
}

ตัวอย่างที่ 3: การแจ้งเตือนหลายรายการ

// แสดงหลาย notification พร้อมกัน
NotificationManager.info('เริ่มต้นการประมวลผล...');

setTimeout(() => {
  NotificationManager.info('กำลังประมวลผลข้อมูล...');
}, 1000);

setTimeout(() => {
  NotificationManager.success('ประมวลผลเสร็จสิ้น!');
}, 3000);

หมายเหตุ: ระบบจะแทนที่ notification ประเภทเดียวกันอัตโนมัติ เพื่อป้องกันการแสดงซ้ำซ้อน

ตัวอย่างที่ 4: การใช้งานกับ FormManager

// ฟัง event จาก FormManager
document.addEventListener('form:submitted', (e) => {
  const { response } = e.detail;

  if (response.success) {
    NotificationManager.success(response.message || 'บันทึกสำเร็จ!');
  } else {
    NotificationManager.error(response.message || 'เกิดข้อผิดพลาด');
  }
});

document.addEventListener('form:error', (e) => {
  NotificationManager.error('กรุณาตรวจสอบข้อมูลในฟอร์ม');
});

เอกสารอ้างอิง API

Methods

init(options)

เริ่มต้นใช้งาน NotificationManager

await NotificationManager.init({
  position: 'top-right',
  duration: 3000,
  maxVisible: 5
});

Parameters:

• options (Object) - การตั้งค่า (ดูรายละเอียดใน การตั้งค่า)

Returns: Promise<NotificationManager>

setPosition(position)

เปลี่ยนตำแหน่งการแสดง notification

NotificationManager.setPosition('top-left');

Parameters:

• position (String) - ตำแหน่ง: 'top-right', 'top-left', 'bottom-right', 'bottom-left'

Returns: void

show(options)

แสดง notification แบบกำหนดเอง

NotificationManager.show({
  type: 'success',
  message: 'ข้อความของคุณ',
  duration: 5000,
  icon: 'custom-icon'
});

Parameters:

• options (Object|String) - ตัวเลือกหรือข้อความ
  • type (String) - ประเภท: 'success', 'error', 'warning', 'info', 'loading'
  • message (String) - ข้อความที่จะแสดง
  • duration (Number) - ระยะเวลาแสดง (มิลลิวินาที), 0 = ไม่หายอัตโนมัติ
  • icon (String) - ชื่อ icon class
  • dismissible (Boolean) - ปิดได้ด้วยตนเอง
  • progressBar (Boolean) - แสดง progress bar

Returns: String - ID ของ notification

success(message, options)

แสดง notification ประเภทสำเร็จ

NotificationManager.success('บันทึกสำเร็จ!');

Parameters:

• message (String) - ข้อความ
• options (Object) - ตัวเลือกเพิ่มเติม (optional)

Returns: String - ID ของ notification

คุณสมบัติเริ่มต้น:

• Duration: 3000ms
• Icon: 'valid'
• Type: 'success'

error(message, options)

แสดง notification ประเภทผิดพลาด

NotificationManager.error('เกิดข้อผิดพลาด!');

Parameters:

• message (String) - ข้อความ
• options (Object) - ตัวเลือกเพิ่มเติม (optional)

Returns: String - ID ของ notification

คุณสมบัติเริ่มต้น:

• Duration: 8000ms (ให้เวลาอ่านมากกว่า)
• Icon: 'ban'
• Type: 'error'

warning(message, options)

แสดง notification ประเภทคำเตือน

NotificationManager.warning('กรุณาตรวจสอบข้อมูล');

Parameters:

• message (String) - ข้อความ
• options (Object) - ตัวเลือกเพิ่มเติม (optional)

Returns: String - ID ของ notification

คุณสมบัติเริ่มต้น:

• Duration: 8000ms (ให้เวลาอ่านมากกว่า)
• Icon: 'warning'
• Type: 'warning'

info(message, options)

แสดง notification ประเภทข้อมูล

NotificationManager.info('มีข้อความใหม่');

Parameters:

• message (String) - ข้อความ
• options (Object) - ตัวเลือกเพิ่มเติม (optional)

Returns: String - ID ของ notification

คุณสมบัติเริ่มต้น:

• Duration: 3000ms
• Icon: 'info'
• Type: 'info'

loading(message, options)

แสดง notification ประเภทกำลังโหลด

const id = NotificationManager.loading('กำลังโหลด...');
// ทำงานบางอย่าง
NotificationManager.dismiss(id);

Parameters:

• message (String) - ข้อความ
• options (Object) - ตัวเลือกเพิ่มเติม (optional)

Returns: String - ID ของ notification

คุณสมบัติเริ่มต้น:

• Duration: 0 (ไม่หายอัตโนมัติ)
• Icon: 'loader'
• Type: 'loading'
• Dismissible: false

dismiss(id)

ปิด notification ที่ระบุ

const id = NotificationManager.success('สำเร็จ!');
// ปิดทันที
NotificationManager.dismiss(id);

Parameters:

• id (String) - ID ของ notification ที่ต้องการปิด

Returns: void

clear()

ปิด notification ทั้งหมด

NotificationManager.clear();

Returns: void

แนวทางปฏิบัติที่แนะนำ

1. เลือกประเภทที่เหมาะสม

// ✅ ดี - ใช้ประเภทที่เหมาะสมกับสถานการณ์
NotificationManager.success('บันทึกสำเร็จ');
NotificationManager.error('ไม่สามารถเชื่อมต่อได้');
NotificationManager.warning('รหัสผ่านจะหมดอายุ');
NotificationManager.info('มีข้อความใหม่');

// ❌ ไม่ดี - ใช้ประเภทไม่เหมาะสม
NotificationManager.success('เกิดข้อผิดพลาด'); // ควรใช้ error
NotificationManager.error('บันทึกสำเร็จ'); // ควรใช้ success

2. ข้อความกระชับและชัดเจน

// ✅ ดี - ข้อความสั้นกระชับ
NotificationManager.success('บันทึกสำเร็จ!');
NotificationManager.error('ไม่สามารถบันทึกได้');

// ❌ ไม่ดี - ข้อความยาวเกินไป
NotificationManager.success('ระบบได้ทำการบันทึกข้อมูลของคุณเรียบร้อยแล้ว และจะนำคุณไปยังหน้าถัดไป');

3. ปิด Loading เสมอ

// ✅ ดี - ปิด loading ในทุกกรณี
const loadingId = NotificationManager.loading('กำลังโหลด...');
try {
  await doSomething();
  NotificationManager.dismiss(loadingId);
  NotificationManager.success('สำเร็จ!');
} catch (error) {
  NotificationManager.dismiss(loadingId);
  NotificationManager.error('ผิดพลาด!');
}

// ❌ ไม่ดี - ลืมปิด loading
const loadingId = NotificationManager.loading('กำลังโหลด...');
await doSomething();
// ลืมปิด loading!

4. ใช้ Duration ที่เหมาะสม

// ✅ ดี - ข้อความสั้น ใช้ duration สั้น
NotificationManager.success('บันทึกแล้ว', { duration: 2000 });

// ✅ ดี - ข้อความยาว ใช้ duration ยาว
NotificationManager.error('ไม่สามารถบันทึกได้ กรุณาตรวจสอบการเชื่อมต่ออินเทอร์เน็ต', {
  duration: 8000
});

// ❌ ไม่ดี - ข้อความยาวแต่ duration สั้น
NotificationManager.error('ข้อความยาวมาก...', { duration: 1000 }); // อ่านไม่ทัน

5. หลีกเลี่ยงการแสดงซ้ำซ้อน

// ✅ ดี - ระบบจะแทนที่ notification ประเภทเดียวกันอัตโนมัติ
NotificationManager.error('ผิดพลาด 1');
NotificationManager.error('ผิดพลาด 2'); // จะแทนที่ข้อความแรก

// ✅ ดี - ใช้ clear() ก่อนแสดงใหม่
NotificationManager.clear();
NotificationManager.success('เริ่มต้นใหม่');

ปัญหาที่พบบ่อย

1. Notification ไม่แสดง

สาเหตุ: ยังไม่ได้เรียก init()

// ❌ ไม่ดี
NotificationManager.success('สำเร็จ'); // อาจไม่แสดง

// ✅ ดี
await NotificationManager.init();
NotificationManager.success('สำเร็จ');

2. Loading ไม่หาย

สาเหตุ: ลืมเรียก dismiss()

// ✅ ดี - ใช้ try-finally
const loadingId = NotificationManager.loading('กำลังโหลด...');
try {
  await doSomething();
} finally {
  NotificationManager.dismiss(loadingId); // ปิดในทุกกรณี
}

3. Notification แสดงเยอะเกินไป

วิธีแก้: ปรับ maxVisible หรือใช้ clear()

// ตั้งค่าจำนวนสูงสุด
NotificationManager.init({
  maxVisible: 3
});

// หรือล้างก่อนแสดงใหม่
NotificationManager.clear();
NotificationManager.success('ข้อความใหม่');

4. ข้อความยาวเกินไป

วิธีแก้: ใช้ข้อความสั้นกระชับ หรือเพิ่ม duration

// ✅ ดี - ข้อความสั้น
NotificationManager.error('บันทึกไม่สำเร็จ');

// ✅ ดี - ข้อความยาว + duration ยาว
NotificationManager.error('ไม่สามารถบันทึกได้ กรุณาตรวจสอบข้อมูล', {
  duration: 10000
});

Duration Guidelines (แนวทางการตั้งค่าระยะเวลา)

Smart Replacement Feature

NotificationManager จะแทนที่ notification ประเภทเดียวกันอัตโนมัติเพื่อป้องกันการแสดงซ้ำซ้อน:

// แสดง error แรก
NotificationManager.error('ข้อผิดพลาด 1');

// แสดง error ที่สอง - จะแทนที่ error แรกอัตโนมัติ
NotificationManager.error('ข้อผิดพลาด 2');

// ผลลัพธ์: จะเห็นแค่ "ข้อผิดพลาด 2" เท่านั้น

ข้อดี:

• ป้องกัน notification overflow
• ผู้ใช้เห็นข้อความล่าสุดเสมอ
• ไม่รบกวนการทำงาน

ข้อยกเว้น: Loading notifications จะไม่ถูกแทนที่ เพราะอาจมีหลาย loading พร้อมกัน

เอกสารที่เกี่ยวข้อง

• FormManager - ระบบจัดการฟอร์ม
• FormError - ระบบแสดงข้อผิดพลาดในฟอร์ม
• DialogManager - ระบบ dialog และ modal

สัญญาอนุญาต

Now.js Framework เผยแพร่ภายใต้ MIT License

ข้อมูลอัปเดตล่าสุด

• เวอร์ชัน: 2.0.0
• อัปเดตล่าสุด: 2025-11-28
• การเปลี่ยนแปลง:
  • ปรับ duration ของ error และ warning เป็น 8000ms
  • เพิ่มฟีเจอร์ Smart Replacement
  • ปรับปรุง animation และ UX