@libs-ui/components-table

Component hiển thị dữ liệu dạng bảng mạnh mẽ với khả năng ghim cột, Virtual Scrolling, phân trang và hỗ trợ gọi API trực tiếp qua httpRequestData.

Giới thiệu

LibsUiComponentsTableComponent là một giải pháp toàn diện để hiển thị danh sách dữ liệu lớn. Nó tích hợp sẵn Virtual Scrolling để tối ưu hiệu năng, cơ chế ghim cột (Fixed Columns) linh hoạt và khả năng kết nối trực tiếp với các API service thông qua cấu hình httpRequestData.

Tính năng

• ✅ Ghim cột (Sticky Columns): Hỗ trợ ghim các cột quan trọng bên trái thông qua headerLeft.
• ✅ Virtual Scrolling: Tối ưu hiệu năng cho danh sách hàng ngàn bản ghi.
• ✅ Phân trang (Pagination): Hỗ trợ cả scroll-infinity và click-pagination.
• ✅ Custom Template: Tùy biến hiển thị từng row và cell thông qua cấu hình colTemplateConfig.
• ✅ Collapse/Expand Row: Hỗ trợ mở rộng xem chi tiết dữ liệu cấp dưới (Hierarchical/Sub-table) bằng giao diện có thể tuỳ biến cao.
• ✅ Sorting: Tích hợp sẵn logic sắp xếp dữ liệu.
• ✅ Checkbox Selection: Hỗ trợ chọn một hoặc nhiều hàng cùng lúc.
• ✅ Angular Signals: Hoạt động mượt mà với Signal-based state management.

Khi nào sử dụng

• Khi cần hiển thị dữ liệu dạng bảng với số lượng bản ghi lớn.
• Khi cần các tính năng Sort/Filter/Pagination kết nối trực tiếp với Backend.
• Khi bảng có nhiều cột thông tin và cần giữ các cột quan trọng luôn hiển thị (ghim cột).

Cài đặt

npm install @libs-ui/components-table

Import

import { LibsUiComponentsTableComponent } from '@libs-ui/components-table';

@Component({
  standalone: true,
  imports: [LibsUiComponentsTableComponent],
  // ...
})
export class YourComponent {}

Ví dụ sử dụng

1. Table thường với httpRequestData

Sử dụng httpRequestData là cách tốt nhất để component tự động quản lý việc tải dữ liệu, phân trang và sắp xếp.

<libs_ui-components-table
  [headerRight]="headerConfig"
  [httpRequestData]="userRequestConfig" />

// Cấu hình gọi API từ service
readonly userRequestConfig = {
  objectInstance: userService, // Inject của service chứa method lấy data
  functionName: 'getUsers',    // Tên phương thức gọi API
  argumentsValue: []           // Tham số bổ sung nếu có
};

readonly headerConfig = [
  { label: 'ID', colTemplateConfig: [{ cssWrapper: '', fieldsConfig: [{ field: 'id' }] }] },
  { label: 'Name', hasSort: true, orderby: 'name', colTemplateConfig: [{ cssWrapper: 'font-bold', fieldsConfig: [{ field: 'name' }] }] }
];

2. Table ghim cột (Fixed Columns)

Ghim các cột quan trọng bên trái bằng cách sử dụng headerLeft. Các cột trong headerRight sẽ có thể cuộn ngang nếu vượt quá chiều rộng container.

<libs_ui-components-table
  [headerLeft]="leftPinnedColumns"
  [headerRight]="scrollableColumns"
  [httpRequestData]="userRequestConfig" />

3. Hierarchical Data (Collapse/Expand Row)

Sử dụng configTemplateItemCollapseExpand để cấu hình hiển thị nội dung chi tiết mở rộng bên dưới mỗi hàng. Rất hữu ích cho các Sub-table (bảng con), Report nhiều lớp, v.v.

<libs_ui-components-table
  [headerRight]="headerConfig"
  [newData]="tableData"
  [configTemplateItemCollapseExpand]="configCollapseExpand" />

// Cấu hình Collapse/Expand Template
readonly configCollapseExpand: IConfigTemplateItemCollapseExpand = {
  // Biến dùng để nhận diện nội dung mở rộng mảng object chứa dữ liệu
  fieldGetDataExpand: 'expand_data', 
  colTemplateConfig: [
    {
      cssWrapper: 'flex w-full',
      fieldsConfig: [
        {
          field: 'details',
          parseValue: (data) => {
            // Un-wrap Signal và trả về HTML động tuỳ ý hoặc Component con
            const details = data.value() || [];
            let htmlInner = '';
            details.forEach(d => {
               htmlInner += `<div>Row Child Detail: \${d.name}</div>`;
            });
            return of(\`<div class="p-4 bg-gray-50">\${htmlInner}</div>\`);
          }
        }
      ]
    }
  ]
};

// Dữ liệu cần có cờ \`specificExpand\` để điều hướng state ẩn/hiện,
// và trường thông tin \`expand_data\` như đã định nghĩa ở trên.
readonly tableData = {
  data: convertObjectToSignal([
    { 
       id: 1, 
       name: 'Task Parent 1', 
       specificExpand: false, // Quản lý state đóng mở
       expand_data: [{ details: [ {name: 'Sub Task A'}, {name: 'Sub Task B'} ] }] 
    }
  ])
};

API Documentation

Inputs

| Property | Type | Default | Description | | :----------------------------------- | :---------------------------------------- | :------------------- | :--------------------------------------------------------------------------- | | [httpRequestData] | IHttpRequestConfig | undefined | (Khuyên dùng) Cấu hình service để component tự động gọi API lấy dữ liệu. | | [headerLeft] | ITableHeaderConfig[] | [] | Danh sách cột được ghim cố định bên trái (Sticky). | | [headerRight] | ITableHeaderConfig[] | [] | Danh sách các cột chính hiển thị trong vùng cuộn. | | [paginationSetting] | object | undefined | Cấu hình hiển thị phân trang (showTotalPage, showInputGotoPage, ...). | | [fieldKey] | string | 'id' | Thuộc tính định danh duy nhất cho mỗi hàng dữ liệu. | | [loading] | boolean | false | Trạng thái xoay loading (thường dùng khi không dùng httpRequestData). | | [newData] | TYPE_NEW_DATA_TABLE | undefined | Dữ liệu đẩy trực tiếp vào bảng (dùng khi không dùng httpRequestData). | | [showFooter] | boolean | false | Hiển thị footer của bảng. | | [footerLeft] | ITableFooterConfig[] | [] | Cấu hình footer ghim bên trái. | | [footerRight] | ITableFooterConfig[] | [] | Cấu hình footer bên vùng cuộn. | | [filter] | TYPE_DATA_FILTER_TABLE | { filterData: {} } | Cấu hình filter/search dữ liệu. | | [activityLoadData] | 'scroll-infinity' \| 'click-pagination' | 'scroll-infinity' | Chế độ tải trang (vô hạn hoặc click). | | [barButtons] | IButton[] | [] | Danh sách các nút thao tác nhanh trên header bar. | | [optimizeTableRenderByOnViewport] | boolean | false | Tối ưu render bảng khi nằm trong viewport. | | [bufferAmount] | number | 5 | Số lượng item render buffer cho Virtual Scroller. | | [enableUnequalChildrenSizes] | boolean | false | Hỗ trợ item có kích thước không đều trong Virtual Scroller. | | [configTemplateItemCollapseExpand] | IConfigTemplateItemCollapseExpand | undefined | Cấu hình template cho chức năng collapse/expand row. | | [noDataConfig] | ITableNoDataConfig | {...} | Cấu hình text/icon khi không có dữ liệu. |

Outputs

| Property | Type | Description | | ------------------------ | ------------------------- | ---------------------------------------------------------- | | (outKeysSelected) | Array<any> | Emit danh sách các fieldKey của các hàng đang được chọn. | | (outSort) | ISortEvent | Emit khi người dùng thực hiện sắp xếp cột. | | (outLoadMore) | ILoadMoreEvent | Emit khi cần tải thêm dữ liệu (scroll infinity). | | (outClickButtonAction) | ITabelButtonActionEvent | Emit khi click vào button trong template cell. | | (outLoading) | boolean | Emit trạng thái loading của component. | | (outTotalItem) | number | Emit tổng số lượng bản ghi hiện có. | | (outClickBarButton) | IButtonBarEvent | Emit khi click vào nút trên thanh công cụ. |

Types & Interfaces

ITableHeaderConfig

export interface ITableHeaderConfig {
  label?: string | TYPE_OBJECT;
  hasCheckbox?: boolean; // Có checkbox chọn row hay không
  hasCheckboxAll?: boolean; // Có checkbox "Chọn tất cả" hay không
  hasSort?: boolean; // Có nút sort hay không
  orderby?: string; // Field dùng để sort
  colTemplateConfig?: Array<ITableTemplateConfig>; // Cấu hình hiển thị cell
  ngStyle?: TYPE_OBJECT;
  ngClass?: TYPE_OBJECT;
}

ITableTemplateConfig

export interface ITableTemplateConfig {
  cssWrapper: string; // Class CSS cho wrapper của cell
  fieldsConfig: Array<ITableFieldTemplateConfig>; // Danh sách các field hiển thị trong 1 cell
}

TYPE_NEW_DATA_TABLE

export type TYPE_NEW_DATA_TABLE<T = TYPE_OBJECT> = {
  data: WritableSignal<Array<WritableSignal<T>>>;
  addToLastList?: boolean;
};

Công nghệ

| Technology | Version | Purpose | | ---------------- | ------- | ------------------------- | | Angular | 18+ | Framework | | Virtual Scroller | 15+ | Hiển thị dữ liệu lớn | | Angular Signals | - | Quản lý trạng thái nội bộ | | TailwindCSS | 3.x | Styling chính |

Demo

npx nx serve core-ui

Truy cập: http://localhost:4500/table

License

MIT