Date Elements (อิลิเมนต์วันที่)

เอกสารสำหรับ DateElementFactory - custom date/time picker พร้อม calendar UI, รองรับภาษา และ flexible formatting

📋 สารบัญ

1. ภาพรวม
2. การใช้งานพื้นฐาน
3. HTML Attributes
4. รูปแบบวันที่
5. Time Picker
6. Min/Max Dates
7. การรองรับภาษา
8. JavaScript API
9. เหตุการณ์
10. การจัดรูปแบบ
11. แนวทางปฏิบัติที่ดี

ภาพรวม

DateElementFactory สร้าง custom date picker พร้อม calendar UI เต็มรูปแบบ แทนที่ native HTML5 date input เพื่อประสบการณ์ที่สม่ำเสมอข้ามเบราว์เซอร์

คุณสมบัติหลัก

• ✅ Custom Calendar UI: ปฏิทินเดือนเต็มพร้อม navigation
• ✅ Time Picker: เลือกเวลาพร้อม hour/minute inputs
• ✅ Flexible Formats: รูปแบบวันที่กำหนดเองได้
• ✅ พ.ศ./ค.ศ.: รองรับปี พ.ศ. (BE year)
• ✅ Min/Max Dates: จำกัดช่วงวันที่ที่เลือกได้
• ✅ รองรับภาษา: ชื่อเดือน/วัน ภาษาไทยและอังกฤษ
• ✅ Keyboard Navigation: ปุ่มลูกศรเลื่อนในปฏิทิน
• ✅ DropdownPanel Integration: พฤติกรรม dropdown สม่ำเสมอกับส่วนอื่น

การใช้งานพื้นฐาน

<!-- Simple date picker -->
<input type="text"
       data-element="date"
       name="birthdate"
       placeholder="เลือกวันที่">

<!-- Date พร้อม format -->
<input type="text"
       data-element="date"
       data-format="d/m/Y"
       name="start_date">

<!-- Date พร้อม time -->
<input type="text"
       data-element="date"
       data-format="d/m/Y H:i"
       data-time="true"
       name="appointment">

UI ที่แสดง

date picker จะสร้าง:

1. Input wrapper พร้อมปุ่มไอคอนปฏิทิน
2. Dropdown ปฏิทิน ประกอบด้วย:
   • หัวเดือน/ปี พร้อมปุ่มเลื่อน
   • ตารางวัน (อาทิตย์-เสาร์)
   • ช่องกรอกเวลา (ถ้าเปิดใช้)
3. Hidden input สำหรับส่ง form (รูปแบบ ISO)

HTML Attributes

รูปแบบวันที่

Format Patterns

ตัวอย่างรูปแบบที่ใช้บ่อย

<!-- รูปแบบไทย: 31/12/2568 -->
<input data-element="date" data-format="d/m/y">

<!-- รูปแบบ ISO: 2025-12-31 -->
<input data-element="date" data-format="Y-m-d">

<!-- รูปแบบยาว: 31 มกราคม 2568 -->
<input data-element="date" data-format="d M y">

<!-- พร้อมเวลา: 31/12/2025 14:30 -->
<input data-element="date" data-format="d/m/Y H:i" data-time="true">

ปี พ.ศ. (Buddhist Era)

ใช้ตัวพิมพ์เล็ก y สำหรับปี พ.ศ. (ค.ศ. + 543):

<!-- แสดง: 10/12/2568 (ปี พ.ศ.) -->
<input data-element="date"
       data-format="d/m/y"
       data-locale="th"
       name="date_th">

Time Picker

เปิด time picker ด้วย data-time="true":

<input type="text"
       data-element="date"
       data-format="d/m/Y H:i"
       data-time="true"
       name="appointment">

UI ของ Time Picker

เมื่อเปิดใช้ dropdown จะแสดง:

• Input ชั่วโมง (00-23)
• Input นาที (00-59)
• เครื่องหมายทวิภาคคั่นกลาง

Input เฉพาะเวลา

สำหรับเลือกเฉพาะเวลาโดยไม่มีวันที่:

<input type="text"
       data-element="time"
       name="meeting_time">

Min/Max Dates

จำกัดช่วงวันที่ที่เลือกได้:

<!-- วันที่ตั้งแต่วันนี้เป็นต้นไป -->
<input type="text"
       data-element="date"
       data-min="today"
       name="future_date">

<!-- วันที่ในช่วงเฉพาะ -->
<input type="text"
       data-element="date"
       data-min="2025-01-01"
       data-max="2025-12-31"
       name="date_2025">

<!-- วันที่ในอดีตเท่านั้น (ถึงวันนี้) -->
<input type="text"
       data-element="date"
       data-max="today"
       name="past_date">

การแสดงวันที่ถูกปิด

วันที่นอกช่วงที่กำหนดจะ:

• แสดงเป็นสีจาง
• คลิกไม่ได้
• ปุ่มลูกศรข้ามไป

การรองรับภาษา

ภาษาไทย (ค่าเริ่มต้น)

<input data-element="date" data-locale="th">

ชื่อเดือน: มกราคม, กุมภาพันธ์, มีนาคม, ...
ชื่อวัน: อา, จ, อ, พ, พฤ, ศ, ส

ภาษาอังกฤษ

<input data-element="date" data-locale="en">

ชื่อเดือน: January, February, March, ...
ชื่อวัน: Sun, Mon, Tue, Wed, Thu, Fri, Sat

เปลี่ยนภาษาแบบไดนามิก

date picker ตอบสนองต่อเหตุการณ์ locale:changed จาก I18nManager:

I18nManager.setLocale('en');
// date picker ทุกตัวอัพเดทชื่อเดือน/วันตาม

JavaScript API

รับ Instance

const dateInput = document.querySelector('[name="appointment"]');
const instance = ElementManager.getInstance(dateInput);

// เข้าถึง EmbeddedDateTime component ภายใน
const picker = instance.picker;

เมธอด

// รับค่าปัจจุบัน (ISO format)
const value = instance.getValue();  // '2025-12-31' หรือ '2025-12-31T14:30'

// รับ Date object
const date = instance.getDate();    // Date object

// ตั้งค่า
instance.setValue('2025-12-31');
instance.setValue('2025-12-31T14:30');

// เปิด calendar
instance.open();

// ปิด calendar
instance.close();

// สลับเปิด/ปิด calendar
instance.toggle();

// เลื่อนเดือน
instance.previousMonth();
instance.nextMonth();

// ทำลายและเก็บกวาด
instance.destroy();

เข้าถึง Picker โดยตรง

const picker = instance.picker;

// รับ element wrapper
const wrapper = picker.getElement();

// เลือกวันที่ที่ต้องการ
picker.selectDate(new Date(2025, 11, 31));

เหตุการณ์

การใช้งาน

dateInput.addEventListener('change', (e) => {
  const instance = ElementManager.getInstance(e.target);
  console.log('ค่าที่แสดง:', e.target.value);        // '31/12/2025'
  console.log('ค่า ISO:', instance.getValue());       // '2025-12-31'
  console.log('Date object:', instance.getDate());    // Date object
});

การจัดรูปแบบ

CSS Variables

:root {
  --date-picker-bg: #ffffff;
  --date-picker-border: #e0e0e0;
  --date-picker-text: #333333;
  --date-picker-selected: #007bff;
  --date-picker-today: #28a745;
  --date-picker-disabled: #cccccc;
}

CSS Classes ที่สำคัญ

/* Wrapper */
.datetime-wrapper {
  position: relative;
  display: inline-flex;
}

/* ปุ่มปฏิทิน */
.datetime-button {
  padding: 8px;
  cursor: pointer;
}

/* Dropdown ปฏิทิน */
.datetime-calendar {
  background: var(--date-picker-bg);
  border: 1px solid var(--date-picker-border);
  border-radius: 4px;
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

/* หัวปฏิทิน */
.calendar-header {
  display: flex;
  justify-content: space-between;
  padding: 8px;
}

/* ช่องวัน */
.calendar-day {
  width: 36px;
  height: 36px;
  text-align: center;
  cursor: pointer;
}

.calendar-day.today {
  border: 2px solid var(--date-picker-today);
}

.calendar-day.selected {
  background: var(--date-picker-selected);
  color: white;
}

.calendar-day.disabled {
  opacity: 0.4;
  cursor: not-allowed;
}

/* Time picker */
.datetime-time {
  display: flex;
  align-items: center;
  gap: 4px;
  padding: 8px;
  border-top: 1px solid var(--date-picker-border);
}

.datetime-time input {
  width: 40px;
  text-align: center;
}

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

1. ✅ ใช้รูปแบบที่เหมาะกับภาษา

<!-- ✅ ดี: รูปแบบไทยพร้อมปี พ.ศ. -->
<input data-element="date"
       data-format="d/m/y"
       data-locale="th">

<!-- ✅ ดี: รูปแบบ ISO สำหรับงานสากล -->
<input data-element="date"
       data-format="Y-m-d"
       data-locale="en">

2. ✅ กำหนด Min/Max Dates ที่สมเหตุสมผล

<!-- ✅ ดี: วันที่อนาคตสำหรับนัดหมาย -->
<input data-element="date"
       data-min="today"
       name="appointment">

<!-- ✅ ดี: วันเกิดต้องอยู่ในอดีต -->
<input data-element="date"
       data-max="today"
       name="birthdate">

3. ✅ ใส่ Placeholder

<!-- ✅ ดี: คำแนะนำชัดเจน -->
<input data-element="date"
       placeholder="วว/ดด/ปปปป"
       name="date">

4. ✅ ใช้ Time สำหรับการนัดหมาย

<!-- ✅ ดี: วันที่ + เวลาสำหรับ scheduling -->
<input data-element="date"
       data-format="d/m/Y H:i"
       data-time="true"
       name="meeting_time">

5. ✅ จัดการการส่ง Form

hidden input เก็บค่ารูปแบบ ISO เพื่อให้ฝั่งเซิร์ฟเวอร์อ่านได้แน่นอน:

<!-- ผู้ใช้เห็น: 31/12/2568 -->
<!-- Form ส่ง: 2025-12-31 (รูปแบบ ISO) -->
<input data-element="date" data-format="d/m/y">

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

• Form Elements ภาพรวม
• ElementFactory - Base class
• Number Elements - Number inputs
• Special Elements - Specialized inputs อื่นๆ