Cài đặt và sử dụng — Number Format Field

Tổng quan

@digiforce-nc/plugin-number-format-field bổ sung hai kiểu field cho hệ thống: Number (số có định dạng) và Percent (phần trăm). Plugin sử dụng Intl.NumberFormat của trình duyệt để định dạng số theo locale, hỗ trợ dấu phân cách hàng nghìn, độ chính xác thập phân, và validation nâng cao.

Bước 1: Kích hoạt Plugin

Vào Settings → Plugin Manager, tìm plugin-number-format-field và bật lên.

Sau khi kích hoạt, hai kiểu field mới xuất hiện trong Collection Manager:

• Number (nhóm Basic, thứ tự 7)
• Percent (nhóm Basic, thứ tự 8)

Bước 2: Tạo field Number

Trong Collection Manager, thêm trường mới → chọn loại Number.

Cấu hình field Number

Tham số	Mô tả	Giá trị
Precision (step)	Độ chính xác thập phân	1 / 1.0 / 1.00 / 1.000 / 1.0000 / 1.00000
Use pretty format	Bật/tắt định dạng đẹp	Checkbox (mặc định: bật)
Unique	Giá trị duy nhất	Checkbox
Database type	Kiểu lưu trữ	double (mặc định) / float / decimal

Validation nâng cao

Rule	Mô tả	Ví dụ
Maximum	Giá trị tối đa cho phép	999999
Minimum	Giá trị tối thiểu cho phép	0
Format	Ràng buộc kiểu số	Integer / Odd / Even
Regular expression	Pattern tùy chỉnh	/^\d{6}$/

Ví dụ hiển thị (locale: vi-VN)

Giá trị gốc	Precision	Hiển thị
1234567	1	1.234.567
1234567.89	1.00	1.234.567,89
0.5	1.0	0,5
1000000	1	1.000.000

Ví dụ hiển thị (locale: en-US)

Giá trị gốc	Precision	Hiển thị
1234567	1	1,234,567
1234567.89	1.00	1,234,567.89
0.5	1.0	0.5
1000000	1	1,000,000

Bước 3: Tạo field Percent

Chọn loại Percent khi thêm trường mới.

Cơ chế lưu trữ Percent

Field Percent lưu dạng decimal trong database và hiển thị dạng phần trăm trên UI:

Giá trị lưu (DB)	Hiển thị (UI)
0.5	50%
0.156	15.6%
1.0	100%
0.0025	0.25%

Lưu ý: Khi nhập 50 trên UI, giá trị lưu vào DB là 0.5. Công thức: DB value = UI value / 100.

Cấu hình field Percent

Tham số	Mô tả	Giá trị
Precision (step)	Độ chính xác	1% / 1.0% / 1.00% / 1.000% / 1.0000% / 1.00000%
Maximum	Giá trị tối đa (dạng decimal)	VD: 1 = 100%
Minimum	Giá trị tối thiểu (dạng decimal)	VD: 0 = 0%
Format	Ràng buộc kiểu	Integer

Validation đặc biệt cho Percent

Plugin đăng ký hai validation rule riêng:

• percentMode: Kiểm tra giá trị nằm trong khoảng min/max (so sánh trên giá trị decimal)
• percentFormats: Nếu format là "Integer", kiểm tra giá trị nhân 100 phải là số nguyên

Cách hoạt động bên trong

Formatter và Parser

Khi bật pretty format, plugin tạo cặp formatter/parser cho input:

• Formatter: Nhận raw number → thêm dấu phân cách theo locale, cắt precision
• Parser: Nhận chuỗi đã format → loại bỏ dấu phân cách → trả về raw number

Locale detection

Plugin đọc locale từ localStorage:

const locale = localStorage.getItem('DIGIFORCE_LOCALE') || 'en-US';

Dấu phân cách được lấy tự động qua Intl.NumberFormat:

• vi-VN: dấu chấm cho hàng nghìn (.), dấu phẩy cho thập phân (,)
• en-US: dấu phẩy cho hàng nghìn (,), dấu chấm cho thập phân (.)

Lưu ý quan trọng

• Database luôn lưu raw number — định dạng chỉ áp dụng ở tầng UI
• Khi tắt pretty format, input hiển thị số thô không có dấu phân cách
• Precision dựa trên step value — VD: step 0.01 → 2 chữ số thập phân
• Filter và sort hoạt động trên giá trị gốc, không bị ảnh hưởng bởi format
• Export dữ liệu cũng xuất giá trị gốc (raw number)