AuthLoadingManager - ระบบจัดการสถานะการโหลด

เอกสารสำหรับ AuthLoadingManager ซึ่งเป็นระบบจัดการสถานะการโหลด สำหรับการดำเนินการยืนยันตัวตน ของ Now.js Framework

📋 สารบัญ

ภาพรวม

AuthLoadingManager จัดการสถานะการโหลดสำหรับการดำเนินการยืนยันตัวตน เพื่อให้ feedback กับผู้ใช้ตลอดช่วงเวลาที่ระบบกำลังทำงาน

ฟีเจอร์หลัก

• ✅ การติดตามการทำงาน: ติดตามสถานะการโหลดของแต่ละปฏิบัติการ
• ✅ ส่วนติดต่อผู้ใช้ระหว่างโหลด: แสดงตัวบ่งชี้สถานะโหลดอัตโนมัติ
• ✅ การติดตามความคืบหน้า: ติดตามเปอร์เซ็นต์ความคืบหน้าของงาน
• ✅ ตัวชี้วัดหลายรูปแบบ: รองรับตัวบ่งชี้หลายประเภท เช่น สปินเนอร์ แถบความคืบหน้า หรือสเกเลตัน
• ✅ ข้อความกำหนดเอง: กำหนดข้อความระหว่างโหลดได้เอง
• ✅ การจัดการหมดเวลา: จัดการงานที่ใช้เวลานานเกินกำหนด
• ✅ รองรับโอเวอร์เลย์: แสดงโอเวอร์เลย์เต็มหน้าจอระหว่างโหลด
• ✅ รองรับการยกเลิก: ยกเลิกการทำงานที่กำลังโหลดอยู่ได้
• ✅ ระบบเหตุการณ์: ส่งเหตุการณ์เมื่อสถานะการโหลดเปลี่ยนแปลง
• ✅ ล้างสถานะอัตโนมัติ: เคลียร์สถานะการโหลดหลังจบงานอัตโนมัติ

เมื่อไหร่ควรใช้ AuthLoadingManager

✅ ใช้ AuthLoadingManager เมื่อ:

• ต้องการแสดง feedback ระหว่างขั้นตอนยืนยันตัวตน
• ต้องการติดตามความคืบหน้าของแต่ละปฏิบัติการ
• ต้องการประสบการณ์ UX ที่สม่ำเสมอระหว่างโหลด
• ต้องการรองรับกรณีหมดเวลาระหว่างโหลด

❌ ไม่ควรใช้เมื่อ:

• ปฏิบัติการจบเร็วมาก (น้อยกว่า 100ms)
• ไม่ต้องการแสดง UI ระหว่างโหลด

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

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

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

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

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

// AuthLoadingManager ทำงานร่วมกับ AuthManager อัตโนมัติ
// ไม่ต้องตั้งค่าแยกเพิ่มเติม

await AuthManager.init({
  enabled: true,

  // Loading configuration
  loading: {
    // แสดงตัวชี้วัดระหว่างโหลด
    enabled: true,

    // ระยะเวลาแสดงขั้นต่ำเพื่อป้องกันการกระพริบ
    minDuration: 300,

    // เวลาหมดในการโหลด (มิลลิวินาที)
    timeout: 30000,

    // ข้อความแสดงระหว่างโหลดค่าเริ่มต้น
    defaultMessage: 'Loading...',

    // ประเภทตัวชี้วัดการโหลด
  indicator: 'spinner',  // spinner, progress, skeleton, overlay

    // แสดงโอเวอร์เลย์
    overlay: true,

    // ความทึบของโอเวอร์เลย์
    overlayOpacity: 0.5
  }
});

console.log('AuthLoadingManager initialized!');

ลำดับการโหลด

เริ่มปฏิบัติการ
      ↓
┌─────────────────────┐
│  เริ่มแสดงสถานะโหลด   │
│  - แสดงตัวชี้วัด      │
│  - ส่งเหตุการณ์           │
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│  ปฏิบัติการกำลังทำงาน │
│  - อัปเดตความคืบหน้า   │
│  - แสดงข้อความ             │
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│  ตรวจสอบเวลาหมด        │
│  - ยกเลิกหากจำเป็น    │
│  - แสดงคำเตือน           │
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│  ปฏิบัติการเสร็จสิ้น │
│  - ซ่อนตัวชี้วัด         │
│  - ส่งเหตุการณ์              │
│  - ทำความสะอาด                 │
└─────────────────────┘

เหตุการณ์การโหลด

เหตุการณ์ที่มีให้ใช้งาน

// AuthLoadingManager ส่งเหตุการณ์ผ่าน EventManager.emit() ซึ่งไม่ได้ dispatch
// DOM event จึงต้องดักด้วย EventManager.on() ไม่ใช่ addEventListener()

// 1. เริ่มงาน
EventManager.on('auth:loading:start', (data) => {
  const {operation, globalLoading, activeOperations} = data;
  console.log(`Loading started: ${operation.type} (${operation.id})`);
});

// 2. อัปเดตงาน
EventManager.on('auth:loading:update', (data) => {
  const {operation} = data;
  console.log(`Loading updated: ${operation.type}`);
});

// 3. งานเสร็จ
EventManager.on('auth:loading:complete', (data) => {
  const {operation} = data;
  console.log(`Loading finished: ${operation.type} (${operation.duration}ms)`);
});

ทุก payload มีคีย์เดียวกันสามตัว:

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

เมธอด

startLoading(operation, options)

เริ่มติดตามสถานะการโหลดสำหรับปฏิบัติการหนึ่ง

พารามิเตอร์:

• operation (string) - รหัสระบุปฏิบัติการ
• options (Object) - ตัวเลือกการตั้งค่าการโหลด

ค่าที่ส่งกลับ: string - ไอดีของปฏิบัติการ

ตัวอย่าง:

const id = AuthLoadingManager.startLoading('login', {
  message: 'Logging in...',
  indicator: 'spinner',
  overlay: true
});

cancelLoading(operationId, reason?)

ยกเลิกปฏิบัติการ

พารามิเตอร์:

• operationId (string) - ไอดีของปฏิบัติการ

ค่าที่ส่งกลับ: void

ตัวอย่าง:

AuthLoadingManager.cancelLoading(operationId, reason?);

isLoading(operation)

ตรวจสอบว่าปฏิบัติการกำลังโหลดอยู่หรือไม่

พารามิเตอร์:

• operation (string) - รหัสปฏิบัติการ

ค่าที่ส่งกลับ: boolean

ตัวอย่าง:

if (AuthLoadingManager.isLoading('login')) {
  console.log('Login in progress');
}

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

• Authentication.md - ภาพรวมระบบยืนยันตัวตน
• AuthManager.md - ผู้จัดการการยืนยันตัวตนหลัก
• AuthGuard.md - การป้องกันเส้นทาง
• AuthErrorHandler.md - การจัดการข้อผิดพลาด
• TokenService.md - การจัดการโทเค็น JWT