@libs-ui/components-checkbox-group

Component quản lý nhóm các checkbox với tính năng validation và cấu hình layout linh hoạt cho Angular.

Giới thiệu

LibsUiComponentsCheckboxGroupComponent là một standalone component cho phép hiển thị và quản lý một tập hợp các checkbox. Nó kế thừa đầy đủ sức mạnh của CheckboxSingleComponent cho mỗi item trong nhóm và bổ sung các tính năng quản lý tập trung:

• ✅ Quản lý trạng thái chọn hàng loạt thông qua model.
• ✅ Hỗ trợ validation bắt buộc chọn (Required selection).
• ✅ Cấu hình giao diện hàng ngang hoặc hàng dọc.
• ✅ Tích hợp nhanh với danh sách keys để set trạng thái chọn/vô hiệu hóa.
• ✅ Hỗ trợ nội dung bổ sung (subText/subTemplate) cho mỗi item.

Cài đặt

# npm
npm install @libs-ui/components-checkbox-group

# yarn
yarn add @libs-ui/components-checkbox-group

Sử dụng

Import Component

import { Component, signal } from '@angular/core';
import { LibsUiComponentsCheckboxGroupComponent, ICheckboxGroupItem } from '@libs-ui/components-checkbox-group';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [LibsUiComponentsCheckboxGroupComponent],
  template: `
    <libs_ui-components-checkbox-group
      [(groups)]="options"
      [labelConfig]="{ label: 'Chọn sở thích' }"></libs_ui-components-checkbox-group>
  `,
})
export class ExampleComponent {
  options = signal<ICheckboxGroupItem[]>([{ item: { key: 'music', label: 'Âm nhạc' } }, { item: { key: 'sport', label: 'Thể thao' } }, { item: { key: 'reading', label: 'Đọc sách' } }]);
}

API Reference

Inputs

| Tên | Kiểu | Mặc định | Mô tả | | ------------------------------ | ----------------------------- | ------------- | -------------------------------------------------------------- | | classGroupWhenModeHorizontal | string | 'flex' | Class CSS cho wrapper khi ở chế độ chiều ngang. | | classInclude | string | undefined | Class CSS bổ sung cho container chính. | | classItemWhenModeHorizontal | string | 'mr-[24px]' | Class CSS cho mỗi item khi ở chế độ chiều ngang. | | classLabelInclude | string | undefined | Class CSS cho nhãn tổng quát của nhóm. | | clickExactly | boolean | true | Nếu true, chỉ click vào checkbox/label mới đổi trạng thái. | | disable | boolean | false | Vô hiệu hóa tương tác cho toàn bộ nhóm. | | fieldKey | string | 'key' | Tên thuộc tính dùng làm khóa định danh cho item dữ liệu. | | groups | model<ICheckboxGroupItem[]> | required | Danh sách các item trong nhóm (hỗ trợ two-way binding). | | horizontal | boolean | false | Nếu true, hiển thị các item theo hàng ngang. | | keysChecked | string[] | undefined | Danh sách keys của các item cần được chọn sẵn. | | keysDisable | string[] | undefined | Danh sách keys của các item cần được vô hiệu hóa. | | labelConfig | ILabel | undefined | Cấu hình cho component Label hiển thị trên cùng của nhóm. | | modeBorder | boolean | false | Hiển thị viền bao quanh component. | | showValidateBottom | boolean | false | Hiển thị thông báo lỗi validation ở dưới cùng. | | validRequired | ICheckboxGroupValidRequired | undefined | Cấu hình validation bắt buộc người dùng chọn ít nhất một item. |

Outputs

| Tên | Kiểu | Mô tả | | --------------------- | ------------------------------------ | ---------------------------------------------------------------------------- | | outChange | ICheckboxEvent | Phát ra khi bất kỳ checkbox nào trong nhóm thay đổi trạng thái. | | outFunctionsControl | ICheckboxGroupFunctionControlEvent | Cung cấp các hàm điều khiển (API) như checkIsValid, reset, resetError. |

Interfaces & Types

ICheckboxGroupItem

interface ICheckboxGroupItem {
  item: ICheckboxItem; // Cấu hình checkbox (xem CheckboxSingle)
  subText?: string; // Văn bản bổ sung
  subTemplate?: TemplateRef; // Template tùy chỉnh bổ sung
  disableByKeys?: boolean; // Trạng thái disable tự động theo keysDisable
}

ICheckboxGroupFunctionControlEvent

interface ICheckboxGroupFunctionControlEvent {
  checkIsValid: () => Promise<boolean>; // Kiểm tra tính hợp lệ (validation)
  resetError: () => Promise<void>; // Xóa hiển thị lỗi
  reset: () => Promise<void>; // Reset toàn bộ về trạng thái chưa chọn
}

Công nghệ sử dụng

• Angular 18+ - Standalone Components
• Angular Signals & Model - Modern reactive state management
• NG-Zorro Style Integration

Demo

Demo có sẵn trong ứng dụng core-ui:

npx nx serve core-ui

File demo: apps/core-ui/src/app/components/checkbox-group/checkbox-group.component.ts

Tính năng Demo

• 🎮 Basic Group: Sử dụng cơ bản với danh sách dọc.
• ↔️ Horizontal Layout: Hiển thị items theo hàng ngang.
• ⚠️ Validation: Demo tính năng bắt buộc chọn với thông báo lỗi.
• 🛠️ External Control: Điều khiển nhóm checkbox bằng API (Reset, Validate).

License

MIT