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

Cài đặt

Plugin @digiforce-nc/plugin-map cần cả client và server. Kích hoạt qua trang Plugin Manager.

Sau khi cài, plugin tạo bảng mapConfiguration trong database để lưu cấu hình API key.

Cấu hình Google Maps API key

Trước khi sử dụng Map block, admin cần cấu hình API key:

1. Vào Settings → Map Configuration.
2. Chọn provider: Google Maps.
3. Nhập API key từ Google Cloud Console.
4. Lưu lại — key được lưu vào bảng mapConfiguration.

Lưu ý

API key cần được cấp quyền cho Maps JavaScript API và Geocoding API trên Google Cloud Console. Không có key hợp lệ, Map block sẽ không tải được bản đồ.

Thêm Map block

1. Mở trang ở chế độ thiết kế (Schema Editor).
2. Click Add block → chọn Map.
3. Chọn collection chứa field địa lý (geo field).
4. Cấu hình field mapping — chọn geo field để hiển thị trên bản đồ.
5. Map block xuất hiện, tải Google Maps và hiển thị dữ liệu.

Các field type địa lý

Plugin đăng ký 4 field type mới vào hệ thống:

Field Type	Giá trị lưu trữ	Ví dụ
Point	[lng, lat]	[106.6297, 10.8231] (TP.HCM)
Polygon	[[lng, lat], ...]	Mảng tọa độ tạo vùng khép kín
LineString	[[lng, lat], ...]	Mảng tọa độ tạo đường
Circle	{ center: [lng, lat], radius }	Tâm + bán kính (mét)

Thêm geo field vào collection

1. Vào Collection Manager → chọn collection.
2. Add field → chọn một trong 4 loại: Point, Polygon, LineString, Circle.
3. Field mới xuất hiện với map picker widget — user click/vẽ trên bản đồ để nhập giá trị.

Sử dụng Map block

• Markers: Point field hiển thị dưới dạng marker trên bản đồ.
• Polygons: Polygon field hiển thị vùng tô màu.
• Lines: LineString field hiển thị đường nối.
• Circles: Circle field hiển thị hình tròn.

Tương tác

• Click marker → popup hiển thị thông tin record.
• Marker clustering — khi zoom xa, markers gần nhau gom thành nhóm.
• Zoom / Pan — navigation bản đồ thông thường.

Mẹo

Map block phù hợp cho quản lý bất động sản, theo dõi vị trí, quản lý chuỗi cửa hàng — bất kỳ nơi nào cần hiển thị dữ liệu trên bản đồ.