Number Elements (อิลิเมนต์ตัวเลข)

เอกสารสำหรับ NumberElementFactory และ CurrencyElementFactory - components สำหรับ numeric input พร้อม formatting, validation และ step controls

📋 สารบัญ

1. ภาพรวม
2. NumberElementFactory
3. CurrencyElementFactory
4. ตัวเลือกการจัดรูปแบบ
5. เหตุการณ์
6. แนวทางปฏิบัติที่ดี

ภาพรวม

Number elements จัดการ numeric input พร้อม formatting, validation และ keyboard navigation อัตโนมัติ โดยแปลง numeric input อย่าง <input type="number"> และ <input type="currency"> เป็น text input ที่จัดรูปแบบแล้วเพื่อ UX ที่ดีกว่า

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

• ✅ Thousand Separators: จัดกลุ่มอัตโนมัติ (1,000,000)
• ✅ Decimal Precision: ควบคุมจำนวนทศนิยม
• ✅ Min/Max Validation: ตรวจสอบช่วงค่าในตัว
• ✅ Step Controls: ปุ่มลูกศรเพิ่ม/ลดค่า
• ✅ Keyboard Filtering: กรองเฉพาะตัวเลขที่ถูกต้อง
• ✅ Paste Validation: ตรวจสอบเนื้อหาที่วาง
• ✅ Negative Values: รองรับค่าลบ (เลือกเปิดได้)
• ✅ Currency Symbol: แสดงสัญลักษณ์สกุลเงิน (เลือกเปิดได้)

CurrencyElementFactory เปิดใช้ได้ทั้งผ่าน data-element="currency" และ <input type="currency"> โดยสามารถ override จำนวนทศนิยมด้วย data-precision หรือ data-decimals

NumberElementFactory

NumberElementFactory จัดการ numeric input พร้อม formatting และ validation โดยแปลง input เป็น type="text" ภายในเพื่อให้แสดงค่าที่จัดรูปแบบแล้วได้

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

<!-- Simple number input -->
<input type="number"
       data-element="number"
       name="quantity"
       min="0"
       max="100">

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

HTML Attributes

Configuration Object

NumberElementFactory.config = {
  type: 'text',
  inputMode: 'decimal',
  step: 1,
  min: null,
  max: null,
  precision: 0,
  padToPrecision: false,
  useGrouping: false,
  groupingSeparator: ',',
  decimalSeparator: '.',
  allowNegative: false,
  roundValues: false,
  showSymbol: false,
  symbol: '',
  symbolPosition: 'before',
  negativeWithParentheses: false,
  validationMessages: {
    required: 'Please fill in this field',
    min: 'Value must be at least {min}',
    max: 'Value must be no more than {max}',
    step: 'Value must be a multiple of {step}',
    number: 'Please enter a valid number'
  }
};

Keyboard Navigation

การกรองการพิมพ์ (Input Filtering)

NumberElementFactory บล็อกตัวอักษรที่ไม่ถูกต้องให้อัตโนมัติ:

// อนุญาตเฉพาะปุ่มเหล่านี้:
// - ตัวเลข 0-9
// - จุดทศนิยม (ครั้งเดียว ถ้า precision > 0)
// - เครื่องหมายลบ (ครั้งเดียว ที่ตำแหน่ง 0 ถ้า allowNegative)
// - ปุ่มเลื่อนตำแหน่ง (ลูกศร, home, end)
// - ปุ่มควบคุม (Ctrl+C, Ctrl+V ฯลฯ)

พฤติกรรมตอน Focus/Blur

ตอน Focus:

• ค่าที่จัดรูปแบบแล้วจะถูกแปลงกลับเป็นตัวเลขดิบเพื่อให้แก้ไขง่าย
• ตัวอย่าง: 1,234.50 → 1234.5

ตอน Blur:

• ตัวเลขดิบจะถูกจัดรูปแบบใหม่พร้อม grouping และการเติมศูนย์
• ตัวอย่าง: 1234.5 → 1,234.50

JavaScript API

const instance = ElementManager.getInstance(numberInput);

// ตั้งค่าจากโค้ด
instance.setValue(1234.56);
// Input แสดง: 1,234.56 (ถ้าเปิด useGrouping)

// แปลงค่าที่ผู้ใช้กรอกเป็นตัวเลข
const value = instance.parseNumber('1,234.56');
// คืนค่า: 1234.56

// จัดรูปแบบตัวเลขเพื่อแสดงผล
const formatted = instance.formatNumber(1234.56);
// คืนค่า: '1,234.56'

// เรียกดูผลการตรวจสอบ
const result = instance.validateValue('invalid', true);
// {validatedValue: 'invalid', error: 'Please enter a valid number'}

ตัวอย่าง

จำนวนเต็มเท่านั้น

<input type="number"
       data-element="number"
       data-precision="0"
       name="quantity"
       min="1"
       max="999">

ทศนิยม 2 ตำแหน่ง

<input type="text"
       data-element="number"
       data-precision="2"
       data-pad-to-precision="true"
       name="price"
       placeholder="0.00">

ตัวเลขใหญ่พร้อม Grouping

<input type="text"
       data-element="number"
       data-precision="0"
       data-use-grouping="true"
       name="population"
       placeholder="กรอกจำนวนประชากร">
<!-- ผู้ใช้เห็น: 1,000,000 แทน 1000000 -->

อนุญาตค่าลบ

<input type="text"
       data-element="number"
       data-allow-negative="true"
       data-precision="2"
       name="balance">
<!-- ผู้ใช้กรอกได้: -1,234.56 -->

CurrencyElementFactory

CurrencyElementFactory ขยาย NumberElementFactory ด้วยค่าเริ่มต้นสำหรับสกุลเงิน: ทศนิยม 2 ตำแหน่ง, thousand separators และรองรับค่าลบ

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

<input type="text"
       data-element="currency"
       name="price"
       placeholder="0.00">
<!-- จัดรูปแบบอัตโนมัติเป็น: 1,234.56 -->

<input type="currency"
       name="unit_cost"
       step="0.0001"
       data-decimals="4"
       placeholder="0.0000">
<!-- จัดรูปแบบอัตโนมัติเป็น: 1,234.5678 -->

Default Configuration

CurrencyElementFactory.config = {
  ...NumberElementFactory.config,
       precision: 2,              // ค่าเริ่มต้นทศนิยม 2 ตำแหน่ง
       padToPrecision: true,      // เติมศูนย์ท้ายตาม precision
       roundValues: true,         // ปัดเศษตาม precision ที่ตั้งไว้
  showSymbol: false,         // ไม่แสดงสัญลักษณ์เป็นค่าเริ่มต้น
  symbol: '',                // ใส่ '$' หรือ '฿' ตามต้องการ
  symbolPosition: 'before',  // สัญลักษณ์อยู่หน้าตัวเลข
  allowNegative: true,       // อนุญาตค่าลบ
  useGrouping: true,         // 1,000,000.00
  groupingSeparator: ',',
  decimalSeparator: '.',
  negativeWithParentheses: false,
  inputMode: 'decimal'
};

ตัวอย่าง

สกุลเงินพื้นฐาน

<input type="text"
       data-element="currency"
       name="amount">
<!-- กรอก: 1234.5 → แสดง: 1,234.50 -->

ต้นทุน inventory 4 ตำแหน่ง

<input type="currency"
       name="cost"
       step="0.0001"
       data-decimals="4">
<!-- กรอก: 1234.5 → แสดง: 1,234.5000 -->

สกุลเงินบาทไทย

<input type="text"
       data-element="currency"
       data-symbol="฿"
       data-symbol-position="before"
       name="price_thb">
<!-- แสดง: ฿1,234.50 -->

ค่าลบแบบวงเล็บ

<input type="text"
       data-element="currency"
       data-negative-with-parentheses="true"
       name="balance">
<!-- ค่าลบแสดงเป็น: (1,234.50) แทน -1,234.50 -->

ไม่แสดงสัญลักษณ์

<input type="text"
       data-element="currency"
       data-show-symbol="false"
       name="amount">
<!-- แสดงเฉพาะตัวเลข: 1,234.50 -->

ตัวเลือกการจัดรูปแบบ

ตัวอย่าง Precision

ตัวอย่าง Grouping

ตัวอย่าง Decimal Separator

สำหรับรูปแบบยุโรป (ใช้จุลภาคเป็นจุดทศนิยม):

<input type="text"
       data-element="number"
       data-decimal-separator=","
       data-grouping-separator="."
       data-use-grouping="true"
       data-precision="2"
       name="price">
<!-- แสดง: 1.234,56 (รูปแบบยุโรป) -->

ตำแหน่งสัญลักษณ์

<!-- สัญลักษณ์อยู่หน้า (ค่าเริ่มต้น) -->
<input data-element="currency" data-symbol="$">
<!-- แสดง: $1,234.56 -->

<!-- สัญลักษณ์อยู่หลัง -->
<input data-element="currency" data-symbol="EUR" data-symbol-position="after">
<!-- แสดง: 1,234.56 EUR -->

เหตุการณ์

เหตุการณ์มาตรฐาน

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

const numberInput = document.querySelector('[name="amount"]');

numberInput.addEventListener('change', (e) => {
  const instance = ElementManager.getInstance(e.target);
  const rawValue = instance.parseNumber(e.target.value);
  console.log('จัดรูปแบบแล้ว:', e.target.value);  // '1,234.56'
  console.log('ค่าดิบ:', rawValue);              // 1234.56
});

numberInput.addEventListener('focus', (e) => {
  // ค่าถูกถอดรูปแบบแล้วเพื่อให้แก้ไขง่าย
  console.log('โหมดแก้ไข:', e.target.value);  // '1234.56'
});

numberInput.addEventListener('blur', (e) => {
  // ค่าถูกจัดรูปแบบแล้ว
  console.log('โหมดแสดงผล:', e.target.value);  // '1,234.56'
});

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

1. ✅ ใช้ Precision ที่เหมาะสม

<!-- ✅ ดี: จำนวนเต็มสำหรับ quantities -->
<input data-element="number" data-precision="0" name="quantity">

<!-- ✅ ดี: ทศนิยม 2 ตำแหน่งสำหรับ currency -->
<input data-element="currency" name="price">

<!-- ❌ ไม่ดี: ทศนิยมเยอะเกินไปสำหรับการแสดงผล -->
<input data-element="number" data-precision="10" name="price">

2. ✅ กำหนด Min/Max สำหรับ Validation

<!-- ✅ ดี: ป้องกันช่วงค่าไม่ถูกต้อง -->
<input data-element="number"
       min="0"
       max="100"
       name="percentage">

<!-- ✅ ดี: รับเฉพาะค่าบวก -->
<input data-element="currency"
       min="0"
       name="price">

3. ✅ ใช้ Currency สำหรับเงิน

<!-- ✅ ดี: Currency element สำหรับเงิน -->
<input data-element="currency" name="total">
<!-- อัตโนมัติ: ทศนิยม 2 ตำแหน่ง, grouping, รองรับค่าลบ -->

<!-- ❌ ไม่ดี: ตั้งค่าเองทีละอย่าง -->
<input data-element="number"
       data-precision="2"
       data-pad-to-precision="true"
       data-use-grouping="true"
       data-allow-negative="true"
       name="total">

4. ✅ ใช้ Grouping สำหรับตัวเลขใหญ่

<!-- ✅ ดี: อ่านง่าย -->
<input data-element="number"
       data-use-grouping="true"
       name="population">
<!-- แสดง: 1,000,000 -->

<!-- ❌ ไม่ดี: นับศูนย์ยาก -->
<input data-element="number" name="population">
<!-- แสดง: 1000000 -->

5. ✅ ให้ตรงกับรูปแบบของภาษา

<!-- รูปแบบไทย/สหรัฐฯ (ค่าเริ่มต้น) -->
<input data-element="number"
       data-decimal-separator="."
       data-grouping-separator=",">

<!-- รูปแบบยุโรป -->
<input data-element="number"
       data-decimal-separator=","
       data-grouping-separator=".">

6. ✅ ใช้ Step สำหรับปุ่มเพิ่ม/ลดค่า

<!-- ✅ ดี: เพิ่มทีละ 0.5 -->
<input data-element="number"
       step="0.5"
       min="0"
       max="10"
       name="rating">
<!-- ปุ่มลูกศร: 0, 0.5, 1.0, 1.5, ... -->

<!-- ✅ ดี: เพิ่มทีละ 100 -->
<input data-element="number"
       step="100"
       min="0"
       name="budget">
<!-- ปุ่มลูกศร: 0, 100, 200, 300, ... -->

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

• Form Elements ภาพรวม
• ElementFactory - Base class
• Text Elements - Text inputs
• Select Elements - Dropdown inputs
• FormManager - Form-level validation