Cài đặt và sử dụng

Kích hoạt plugin

Vào Settings → Plugin Manager, bật @digiforce-nc/plugin-field-vietnam-region. Khi install, plugin tự động bulk load dữ liệu hành chính Việt Nam vào collection vietnamRegions.

Thêm field Tỉnh/Huyện/Xã

1. Mở Collection Manager → chọn collection.
2. Thêm field mới → chọn interface Vietnam Region.
3. Đặt tên field (ví dụ: address, birthPlace, deliveryRegion).
4. Lưu — field hiển thị cascading picker 3 cấp trên form.

const addressField = {
  name: 'address',
  type: 'vietnamRegion',
  interface: 'vietnamRegion',
  uiSchema: {
    type: 'array',
    title: 'Địa chỉ',
    'x-component': 'VietnamRegionCascader',
  },
};

Cascading Picker — Chọn địa chỉ 3 cấp

Giao diện chọn địa chỉ hoạt động theo 3 bước:

1. Cấp 1 — Tỉnh/Thành phố: Hiển thị 63 tỉnh thành. Chọn một tỉnh.
2. Cấp 2 — Quận/Huyện: Hiển thị danh sách quận/huyện thuộc tỉnh đã chọn.
3. Cấp 3 — Phường/Xã: Hiển thị danh sách phường/xã thuộc huyện đã chọn.

Dữ liệu mỗi cấp được lazy-loaded — chỉ tải khi người dùng chọn cấp cha, giảm tải cho trang.

Giá trị lưu trữ

Field lưu mảng mã code trong database:

// Giá trị trong DB
const value = ['79', '760', '26734'];

// Hiển thị: "Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh"

Phần tử	Ý nghĩa	Ví dụ
value[0]	Mã tỉnh	'79' (TP.HCM)
value[1]	Mã huyện	'760' (Quận 1)
value[2]	Mã xã	'26734' (Phường Bến Nghé)

Dữ liệu hành chính sẵn có

Cấp	Số lượng	Ví dụ
Tỉnh/Thành phố	63	Hà Nội, TP.HCM, Đà Nẵng...
Quận/Huyện	700+	Quận 1, Huyện Bình Chánh...
Phường/Xã	10,000+	Phường Bến Nghé, Xã Bình Hưng...

Dữ liệu được import từ nguồn chính thức, lưu trong collection vietnamRegions.

Hiển thị trên giao diện

• Form: Cascading picker 3 dropdown liên tiếp.
• Table/Detail: Hiển thị tên đầy đủ "Phường X, Quận Y, Tỉnh Z".
• toString: Hàm chuyển mã code thành tên đầy đủ để hiển thị.

Lưu ý

• Dữ liệu hành chính có thể thay đổi theo quyết định hành chính (sáp nhập huyện, đổi tên...). Plugin cung cấp dữ liệu tại thời điểm cài đặt.
• Collection vietnamRegions chứa 11,000+ records — lần load đầu có thể mất vài giây.
• ACL cần cấp quyền vietnamRegions:list cho các role cần truy cập picker.