Form Elements (ฟอร์มอิลิเมนต์) - ภาพรวม

คู่มือฉบับสมบูรณ์สำหรับ Form Elements ใน Now.js Framework - input components ที่เพิ่มความสามารถด้าน validation, formatting และการจัดการเหตุการณ์

📋 สารบัญ

1. ภาพรวม
2. สถาปัตยกรรม
3. เริ่มต้นใช้งานอย่างรวดเร็ว
4. ประเภทของ Element
5. คู่มือเลือกอย่างรวดเร็ว
6. คุณสมบัติทั่วไป
7. การลงทะเบียน Element
8. เอกสารที่เกี่ยวข้อง

ภาพรวม

Form Elements ใน Now.js คือ input components ที่สร้างบน ElementFactory base class ให้ validation, formatting, การจัดการสถานะ และการจัดการเหตุการณ์อัตโนมัติ - ตั้งค่าได้ทั้งหมดผ่าน HTML data attributes

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

• ✅ Declarative Configuration: ตั้งค่าผ่าน HTML data-* attributes
• ✅ Auto-Enhancement: HTML inputs ที่มีอยู่ถูกปรับปรุงอัตโนมัติ
• ✅ Validation System: รองรับ built-in และ custom validation rules
• ✅ Formatting: จัดรูปแบบ input/output อัตโนมัติ
• ✅ State Management: ติดตามสถานะ valid, modified, error
• ✅ Event System: เหตุการณ์สม่ำเสมอทุก element
• ✅ Wrapper Support: สร้าง label, container, comment ให้อัตโนมัติ
• ✅ FormManager Integration: ทำงานร่วมกับ FormManager ได้อย่างไร้รอยต่อ

วิธีการทำงาน

HTML Input → ElementManager ตรวจพบ data-element →
Factory ที่เหมาะสมปรับปรุง element → Instance พร้อม API เต็มรูปแบบ

สถาปัตยกรรม

Class Hierarchy

ElementFactory (Base Class)
├── TextElementFactory          # data-element="text"
│   ├── EmailElementFactory     # data-element="email"
│   ├── UrlElementFactory       # data-element="url"
│   └── UsernameElementFactory  # data-element="username"
├── PasswordElementFactory
├── SearchElementFactory
├── NumberElementFactory
│   └── CurrencyElementFactory
├── MaskElementFactory
│   └── TelElementFactory
├── SelectElementFactory
├── MultiSelectElementFactory
├── TextareaElementFactory
├── RichTextElementFactory
├── FileElementFactory
├── DateElementFactory
├── ColorElementFactory
├── RangeElementFactory
└── TagsElementFactory

ส่วนประกอบหลัก

เริ่มต้นใช้งานอย่างรวดเร็ว

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

เพียงใส่ data-element attribute ก็เปิด auto-enhancement:

<!-- Text input พร้อม autocomplete -->
<input type="text"
       data-element="text"
       data-autocomplete="true"
       data-source="/api/cities"
       name="city"
       placeholder="เลือกจังหวัด">

<!-- Number input พร้อม formatting -->
<input type="text"
       data-element="number"
       data-precision="2"
       data-use-grouping="true"
       name="price"
       placeholder="0.00">

<!-- Currency input ทศนิยม 4 ตำแหน่ง -->
<input type="currency"
  step="0.0001"
  data-decimals="4"
  name="unit_cost"
  placeholder="0.0000">

<!-- Password พร้อม strength meter -->
<input type="password"
       data-element="password"
       data-strength-meter="true"
       name="password">

<!-- Date picker -->
<input type="text"
       data-element="date"
       data-format="d/m/Y"
       name="birthdate">

<!-- Select พร้อม type-to-filter -->
<select data-element="select" name="country">
  <option value="">เลือกประเทศ</option>
  <option value="TH">ประเทศไทย</option>
  <option value="US">สหรัฐอเมริกา</option>
</select>

การเข้าถึงด้วย JavaScript

// รับ instance ที่ปรับปรุงแล้ว
const cityInput = document.querySelector('[name="city"]');
const instance = ElementManager.getInstance(cityInput);

// ใช้ API ของ instance
instance.element.value = 'กรุงเทพ';
instance.validate();
console.log(instance.isValid());    // true/false
console.log(instance.isModified()); // true/false

// รับฟังเหตุการณ์
cityInput.addEventListener('change', (e) => {
  console.log('ค่าใหม่:', e.target.value);
});

ประเภทของ Element

ตารางอ้างอิงอย่างรวดเร็ว

คู่มือเลือกอย่างรวดเร็ว

ควรใช้ Element ประเภทไหน?

คุณสมบัติทั่วไป

Form Elements ทั้งหมดมีคุณสมบัติร่วมเหล่านี้จาก ElementFactory:

1. Validation

<!-- ตรวจสอบว่าต้องกรอก -->
<input data-element="text" required>

<!-- ตรวจสอบด้วย pattern -->
<input data-element="text" pattern="[A-Za-z]+">

<!-- ตรวจสอบความยาว -->
<input data-element="text" minlength="3" maxlength="50">

<!-- กฎ validation กำหนดเอง -->
<input data-element="text" data-validate="required,email">

<!-- ข้อความผิดพลาดกำหนดเอง -->
<input data-element="text"
       data-validate="required"
       data-error-required="กรุณากรอกอีเมลของคุณ">

2. การจัดการสถานะ

const instance = ElementManager.getInstance(element);

// ตรวจสอบสถานะ
instance.isValid();     // ค่าถูกต้องหรือไม่?
instance.isModified();  // ค่าถูกแก้ไขแล้วหรือไม่?
instance.getError();    // รับข้อความผิดพลาดปัจจุบัน

// ตรวจสอบซ้ำและรีเซ็ต
instance.validate();    // ตรวจสอบค่าปัจจุบัน
instance.reset();       // คืนค่าและ config เดิม
instance.cleanup();     // ถอด handler และล้างข้อผิดพลาดของฟิลด์

ตัวสถานะจริงเก็บอยู่ใน WeakMap ชื่อ ElementFactory._privateState ไม่ได้อยู่บน instance จึงต้องอ่านผ่านสามเมธอดด้านบน

3. เหตุการณ์

ทุก element ส่งเหตุการณ์ change และ input แบบ native และมีสาม factory ที่ส่งต่อการเปลี่ยนค่าเข้าสู่ event system ของแอปด้วย EventManager.emit():

EventManager.emit() ไม่ได้ dispatch DOM event ดังนั้น element:change ต้องรับฟังผ่าน EventManager.on() - addEventListener('element:change') จะไม่ทำงาน

element.addEventListener('change', (e) => {
  const instance = ElementManager.getInstance(e.target);
  console.log('ค่า:', e.target.value);
  console.log('ถูกต้อง:', instance.isValid());
});

EventManager.on('element:change', (data) => {
  console.log(data.elementId, data.value, data.type);
});

4. โครงสร้าง Wrapper

Elements สร้างโครงสร้าง wrapper ให้อัตโนมัติได้:

<!-- ก่อนปรับปรุง -->
<input data-element="text"
       data-wrapper="label"
       data-label="ชื่อผู้ใช้"
       data-comment="3-20 ตัวอักษร">

<!-- หลังปรับปรุง -->
<label class="form-control">
  <span class="label-text">ชื่อผู้ใช้</span>
  <input type="text" ...>
  <span class="comment">3-20 ตัวอักษร</span>
</label>

5. Data Binding

<!-- ผูกกับข้อมูลของ FormManager -->
<input data-element="text"
       data-attr="value:user.name"
       name="name">

การลงทะเบียน Element

ElementManager ทำงานอย่างไร

// Elements ลงทะเบียนตัวเอง
ElementManager.registerElement('text', TextElementFactory);
ElementManager.registerElement('number', NumberElementFactory);
ElementManager.registerElement('password', PasswordElementFactory);
// ... ฯลฯ

// Auto-enhancement ตอนโหลดหน้า
document.querySelectorAll('[data-element]').forEach(el => {
  const type = el.dataset.element;
  const factory = ElementManager.getFactory(type);
  if (factory) {
    factory.enhance(el);
  }
});

ลงทะเบียน Element กำหนดเอง

// สร้าง factory กำหนดเอง
class PhoneElementFactory extends TextElementFactory {
  static config = {
    ...TextElementFactory.config,
    type: 'tel',
    format: 'xxx-xxx-xxxx'
  };

  static setupElement(instance) {
    // Setup กำหนดเอง
  }
}

// ลงทะเบียนกับ ElementManager
ElementManager.registerElement('phone', PhoneElementFactory);

ดูคู่มือฉบับเต็มที่ สร้าง Custom Elements

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

เอกสารหลัก

• ElementFactory - เอกสาร Base class
• FormManager - การจัดการระดับฟอร์ม
• FormError - การจัดการข้อผิดพลาด

กลุ่มของ Element

• Text Elements - Text, Password, Search
• Number Elements - Number, Currency
• Select Elements - Select, MultiSelect
• Date Elements - Date picker
• Special Elements - Color, Range, Tags, Mask, Textarea
• สร้าง Custom Elements - สร้างของคุณเอง

ส่วนประกอบที่เกี่ยวข้อง

• FileElementFactory - อัปโหลดไฟล์
• EditInPlaceManager - แก้ไขในหน้า