Chuyển tới nội dung chính

<Cthuvien:GridX> - <BSSGrid>

Mô tả​

BSSGrid là component UI dạng bảng (Data Grid) của hệ thống, thay thế toàn diện cho <Cthuvien:GridX> cũ (vốn kế thừa từ GridView của ASP.NET).

Trong hệ thống cũ, GridX sử dụng một file JavaScript đồ sộ để can thiệp trực tiếp vào DOM (ẩn/hiện hàng, bắt sự kiện phím, tô màu trạng thái GridX_doiMauH, xử lý trượt trang GridX_nhay). Trong kiến trúc React mới, BSSGrid xử lý tất cả thông qua Local State (useGridLogic) và tuân thủ mô hình Data-Driven, mang lại hiệu năng mượt mà hơn và code dễ bảo trì hơn.

Điểm nổi bật:

  • Khai báo Declarative: Hỗ trợ truyền mảng cấu hình columns hoặc khai báo trực tiếp qua thẻ con <BSSGrid.Column>.
  • Phân trang đa dạng: Hỗ trợ phân trang ảo (Virtual Slider), Pager truyền thống, Infinite Scroll, hoặc không phân trang (None).
  • Nhập liệu & Validation: Tích hợp chặt chẽ với các control BSS khác (BSSInput, BSSLke, BSSCalendar) trực tiếp bên trong từng ô dữ liệu.
  • Tự động tính tổng: Tự động tính tổng footer cho các cột số/tiền (hienTong, totalAmount).
  • Footer linh hoạt: Hỗ trợ bật/tắt các nút Thêm, Xóa, Chèn, Lọc dễ dàng thông qua props.

Thuộc tính​

So sánh cơ chế cũ và mới​

<Cthuvien:GridX> Cũ<BSSGrid> MớiMô tả / Chú ý khi chuyển đổi
loai ("X", "N", "C")kieu ('V', 'E')Cũ: Chỉ xem (X), Nhập liệu (N). Mới: 'V' (View - chỉ xem), 'E' (Edit - mặc định, cho phép nhập liệu).
cot="ma,ten,sl"<BSSGrid.Column field="...">Cũ: Truyền mảng chuỗi tên cột ở thuộc tính cha. Mới: Khai báo qua component con BSSGrid.Column hoặc mảng JSON columns.
cotRong="ma:80,ten:200"width={80} (trên Column)Cũ: Khai báo chuỗi gom chung. Mới: Khai báo width (số px hoặc 'auto') trực tiếp trên cấu hình từng cột.
cotS, cotN, cotNHtype="number", type="date"Cũ: Quy định kiểu dữ liệu qua thuộc tính gom chung. Mới: Chỉ định type trên từng cột. BSSGrid tự dùng đúng control (VD: BSSCalendar cho date).
truotphanTrangCũ: "K" có trượt, "D" tắt trượt. Mới: 'virtual' (trượt ảo, mặc định), 'pager', 'infinite', 'none'.
hangKtpageSizeCũ: Kích thước trang hiển thị. Mới: Số dòng trên 1 trang (mặc định cấu hình lấy từ store).
hamRowonRowClickSự kiện khi click/chuyển dòng active.
hamUponChangeDataCũ: Gọi khi ô bị sửa đổi. Mới: Grid trả về toàn bộ mảng dữ liệu mới (newData) mỗi khi có ô thay đổi.
GridX_datBang(...)data={...}Cũ: Gọi hàm JS đẩy data vào DOM. Mới: Đưa mảng state dữ liệu vào prop data.
Các hàm thao tác (Thêm, Xóa)Footer Tích hợp sẵnBSSGrid tích hợp sẵn các nút và logic cơ bản ở Footer (hienThem, hienXoa, hienChon). Có thể override qua onAddRow, onCut.

Các thuộc tính chung (Container)​

TênKiểuMặc địnhCó thể cóMục đích
dataArray[]Dữ liệu đầu vào (mảng các Object).
columnsArrayMảng cấu hình cột. (Thường dùng cách khai báo thẻ <BSSGrid.Column> tiện hơn).
kieustring'E''E', 'V''E' (Edit): cho phép sửa trên ô (dựa theo cấu hình cột). 'V' (View): chế độ chỉ đọc toàn lưới.
phanTrangstring'virtual''virtual', 'pager', 'infinite', 'none'Kiểu phân trang. virtual: thanh kéo ảo.
widthnumber / stringChiều rộng tổng của lưới (Ví dụ: 800, '100%').
pageSizenumberSố dòng hiển thị trên một trang.
loadingboolfalsetrue/falseHiển thị Skeleton loading khi đang fetch dữ liệu.
currencystring'VND''VND', 'USD'Ký hiệu tiền tệ hiển thị cho các cột kiểu tiền.

Cấu hình Footer / Hành động​

TênKiểuMặc địnhMục đích
hienChonbooltrueHiển thị cột checkbox "Chọn" ở đầu lưới.
hienThembooltrueBật/tắt nút "Thêm" (+).
hienXoabooltrueBật/tắt nút "Xóa" (-).
hienChenboolfalseBật/tắt nút "Chèn" (Insert).
hienTongboolfalseBật/tắt nút hiển thị Tổng (Sigma) và tự động tính tổng tiền.
hienLocbooltrueBật/tắt hàng Filter/Tìm kiếm trên Header.
footerReactNodeComponent/Nội dung tùy chỉnh bổ sung dưới cùng lưới (dưới cả phân trang).
gridActionsReactNodeNút bấm/Component custom nhúng vào vùng actions của thanh Footer.

Các sự kiện (Events)​

TênTrả vềMục đích
onChangeData(newData: T[])Callback kích hoạt mỗi khi dữ liệu trong lưới thay đổi (nhập liệu, thêm/xóa dòng). Nhận mảng dữ liệu mới.
onRowClick(row: T)Callback khi click chuột trái vào dòng.
onRowDoubleClick(row: T)Callback khi double click chuột trái vào dòng.
onSelectionChange(ids: string[])Trả về mảng ID (định dạng idx_{index}) của các dòng đang được check.
onPageChange(page, tu, den)Callback khi chuyển trang. Cần thiết khi kết hợp tải dữ liệu từ API.
onAddRow() => voidOverride hành vi Thêm dòng mặc định.
onCut(ids: string[])Override hành vi Xóa dòng mặc định. Nhận danh sách các index đang chọn.

Thành phần Cột <BSSGrid.Column>​

BSSGrid cho phép khai báo cột trực quan dưới dạng component con.

TênKiểuBắt buộcMặc địnhMục đích
fieldstringCóTên field dữ liệu map với Object. Dùng làm id nội bộ.
headerstringCóTiêu đề hiển thị của cột (Sẽ tự động dịch đa ngôn ngữ).
typestring'text'text, number, currency, date, list, lke, checkbox, toggle. Grid sẽ tự động nhúng control BSS tương ứng.
widthnumber/string150Độ rộng cột.
editablebooltrueXác định cột này có cho phép sửa hay không (chỉ có tác dụng khi lưới là kieu="E").
alignstringCanh lề chữ: 'left', 'center', 'right'. (Mặc định number/currency sẽ canh phải).
sortableboolfalseBật tính năng click vào tiêu đề để sort nội bộ.
optionsArray(Dành cho type list / toggle / checkbox) Danh sách tùy chọn [{value, label}].
ktrastring/func(Dành cho type lke) Cấu hình tra cứu bảng,mã,tên hoặc hàm fetcher, giống control BSSLke.
onSuggestSelectfunctionCallback trả về chi tiết dòng tra cứu khi chọn xong (cho lke).

Hoạt động phía Client​

  • Grid Thông minh: Nếu bạn đặt kieu="V", lưới tự động đặt cờ editable: false cho toàn bộ các cột, ép lưới về dạng chỉ xem.
  • Chỉnh sửa Ô (Local State): Khi bạn sửa dữ liệu trên một ô (ví dụ: nhập BSSInput), thay vì lưới bị giật/lag để render toàn bộ lại, Grid sử dụng kiến trúc local state. Nó tạo một row clone tạm thời, chỉ khi sự kiện blur/enter xảy ra, giá trị mới được commit lên mảng dữ liệu chính, kích hoạt onChangeData.
  • Thêm/Xóa Hàng (Internal): Nếu không truyền override onAddRow hay onCut, Grid cung cấp các hàm handleInternalAdd / handleInternalCut mặc định. Hàm Thêm sẽ tạo ra Object rỗng chứa đúng cấu trúc key của cột. Hàm Xóa sẽ yêu cầu check box chọn hàng rồi xóa.

Ví dụ​

1. Lưới chỉ Xem (View mode), có Custom Render:

<BSSGrid
  data={dataList}
  kieu="V"
  phanTrang="pager"
  pageSize={15}
  hienChon={false}
  hienThem={false}
  hienXoa={false}
  onRowClick={(row) => console.log('Click dòng:', row)}
>
  <BSSGrid.Column field="ma_nv" header="Mã NV" width={100} />
  <BSSGrid.Column field="ten" header="Họ và tên" width={200} />
  <BSSGrid.Column field="ngay_sinh" header="Ngày sinh" type="date" width={120} align="center" />
  <BSSGrid.Column field="gioi_tinh" header="Giới tính" type="list" width={100} 
    options={[{value: 'M', label: 'Nam'}, {value: 'F', label: 'Nữ'}]} />
  {/* Custom render trực tiếp nội dung HTML */}
  <BSSGrid.Column field="status" header="Trạng thái" width={120} align="center"
    render={(val) => (
      <span className={val === 'A' ? 'text-green-600' : 'text-red-600'}>
        {val === 'A' ? 'Đang làm' : 'Đã nghỉ'}
      </span>
    )}
  />
</BSSGrid>

2. Lưới Nhập Liệu Nghiệp Vụ (Edit mode):

const handleChangeData = (newData) => {
  setFormData(prev => ({ ...prev, chiTiet: newData }));
};

<BSSGrid
  data={formData.chiTiet}
  kieu="E"
  hienTong={true} // Bật tính tổng cho các cột tiền
  onChangeData={handleChangeData}
>
  {/* Cột mã phụ cấp tra cứu từ danh mục */}
  <BSSGrid.Column field="ma_pc" header="Mã Phụ cấp" type="lke" width={120} 
    ktra="dm_phucap,ma,ten"
    onSuggestSelect={({ row, rowIndex }) => {
      // Khi chọn mã, tự điền tên vào cột ten_pc trên cùng dòng
      const newData = [...formData.chiTiet];
      newData[rowIndex].ten_pc = row.ten;
      handleChangeData(newData);
    }}
  />
  <BSSGrid.Column field="ten_pc" header="Tên Phụ cấp" width={250} editable={false} />
  <BSSGrid.Column field="so_luong" header="Số lượng" type="number" width={100} />
  <BSSGrid.Column field="tien" header="Số tiền" type="currency" width={150} />
  <BSSGrid.Column field="ghi_chu" header="Ghi chú" type="text" width={300} />
</BSSGrid>