@digiforce-nc/plugin-field-advanced

Plugin mở rộng các field nâng cao cho hệ thống — bổ sung giao diện number với pretty format, percent, hiển thị QR code, cùng nhiều cải tiến cho input/textarea/URL.

Plugin này làm gì?

Hãy hình dung: hệ thống đã có các field cơ bản (string, number...), nhưng thiếu những tùy chỉnh nâng cao như hiển thị số theo format đẹp (1,000,000), phần trăm với thanh progress, hay hiển thị giá trị dưới dạng QR code. Plugin này bổ sung tất cả — hoàn toàn ở phía client, không cần server xử lý thêm.

Ba khả năng chính

#	Khả năng	Chi tiết
1	Number pretty format	Hiển thị số có separator (1,000,000), tuỳ locale, precision
2	Percent field	Input phần trăm với thanh progress hoặc badge
3	Display as QR code	Biến giá trị field (URL, mã code...) thành hình QR để quét

Kiến trúc

Tổng quan

Plugin này là client-only — phần server hoàn toàn rỗng (empty plugin class). Toàn bộ logic nằm ở client: đăng ký field interface, component, settings form và hook.

Luồng hiển thị field nâng cao

Field Interfaces đăng ký

Interface	Mô tả	Component mặc định
input (mở rộng)	Input chuỗi với các tuỳ chỉnh nâng cao	Input
inputNumber (mở rộng)	Số với pretty format, min/max, precision	InputNumber
percent	Phần trăm — kế thừa từ inputNumber	Percent
displayAsQR	Hiển thị giá trị dưới dạng QR code	QR Display

Components

Component	Chức năng
`Input`	Input chuỗi nâng cao (hỗ trợ prefix, suffix, character count)
`InputNumber`	Input số với format separator, precision, đơn vị
`Percent`	Input phần trăm — tự nhân/chia 100 khi lưu/hiển thị
`QR Display`	Render giá trị field thành QR code image

Custom Hooks

Hook	Mô tả
`useNumberPrettyFormat`	Nhận giá trị số, trả về chuỗi format đẹp theo locale (1,000,000 hoặc 1.000.000)
`useDisplayAsQRCode`	Nhận giá trị chuỗi, trả về QR code data URL để render hình ảnh

Settings forms

Plugin đăng ký settings form cho từng loại field, cho phép admin tuỳ chỉnh hành vi:

Settings group	Các tuỳ chọn
input	Max length, placeholder, prefix/suffix
textarea	Rows, max length, auto resize
url	Validate URL format, open in new tab
number	Min, max, precision, step, separator style
percent	Tương tự number + hiển thị progress bar
display-as-QR	QR size, error correction level, foreground color

Ví dụ sử dụng

Cấu hình field number với pretty format

typescript

// Trong schema JSON, field price sẽ hiển thị theo format đẹp
const priceField = {
  name: 'price',
  type: 'double',
  interface: 'inputNumber',
  uiSchema: {
    'x-component': 'InputNumber',
    'x-component-props': {
      stringMode: true,
      step: '0.01',
      addonAfter: 'VND',
    },
  },
};

Thành phần client

Thành phần	Mô tả
`Input`	Input chuỗi nâng cao
`InputNumber`	Input số với separator
`Percent`	Input phần trăm
`QR Display`	Render giá trị thành mã QR
`useNumberPrettyFormat`	Hook format số theo locale
`useDisplayAsQRCode`	Hook chuyển giá trị thành QR

Dependencies

Package	Vai trò
`@digiforce-nc/client`	Client framework — đăng ký component và interface
`@digiforce-nc/server`	Server framework (peer) — plugin class rỗng