@libs-ui/components-checkbox-single

Component checkbox đơn lẻ với nhiều tùy chọn hiển thị và tích hợp nâng cao cho Angular.

Giới thiệu

LibsUiComponentsCheckboxSingleComponent là một standalone Angular component cung cấp giải pháp checkbox linh hoạt, không chỉ đơn thuần là một ô chọn mà còn tích hợp nhiều yếu tố UI phổ biến như:

• ✅ Hiển thị nhãn (label) với định dạng linh hoạt
• ✅ Tích hợp Popover (tooltip) khi di chuột vào nhãn
• ✅ Hiển thị hình ảnh hoặc Avatar cạnh checkbox
• ✅ Hỗ trợ Bullet (chấm tròn màu) để phân loại
• ✅ Hiển thị Description (mô tả chi tiết dưới nhãn)
• ✅ Hỗ trợ Component Outlet để render nội dung tùy chỉnh
• ✅ Trạng thái Error và Disable toàn diện
• ✅ Sử dụng Angular Signals & Model cho reactivity tối ưu

Cài đặt

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

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

Sử dụng

Import Component

import { Component, signal } from '@angular/core';
import { LibsUiComponentsCheckboxSingleComponent, ICheckboxEvent } from '@libs-ui/components-checkbox-single';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [LibsUiComponentsCheckboxSingleComponent],
  template: `
    <libs_ui-components-checkbox-single
      [(checked)]="isSelected"
      label="Chấp nhận điều khoản"
      (outChange)="onStatusChange($event)"></libs_ui-components-checkbox-single>
  `,
})
export class ExampleComponent {
  isSelected = signal(false);

  onStatusChange(event: ICheckboxEvent) {
    console.log('Trạng thái checkbox:', event.checked);
  }
}

API Reference

Inputs

| Tên | Kiểu | Mặc định | Mô tả | | ------------------------ | ---------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ | | avatarConfig | IAvatarConfig | undefined | Cấu hình cho component Avatar hiển thị cạnh checkbox. | | bullet | ICheckboxBullet | undefined | Cấu hình cho dấu chấm tròn màu (bullet) hiển thị cạnh checkbox. | | checked | model<boolean> | false | Trạng thái chọn của checkbox (hỗ trợ two-way binding). | | classIconInclude | string | undefined | Class CSS bổ sung cho thẻ chứa icon. | | classImageInclude | string | undefined | Class CSS bổ sung cho phần hình ảnh. | | classInclude | string | '' | Class CSS bổ sung cho container chính của component. | | classLabelInclude | string | 'libs-ui-font-h5r' | Class CSS cho phần nhãn văn bản. | | clickExactly | boolean | true | Nếu true, chỉ click vào checkbox/label mới đổi trạng thái. Nếu false, click vào toàn bộ area sẽ trigger. | | componentOutlet | any | undefined | Component tùy chỉnh để render thông qua ngComponentOutlet. | | dataComponentOutlet | TYPE_COMPONENT_OUTLET_DATA | undefined | Dữ liệu truyền vào cho componentOutlet. | | description | ICheckboxItemDescription | undefined | Nội dung mô tả chi tiết hiển thị bên dưới nhãn. | | disable | boolean | false | Vô hiệu hóa toàn bộ tương tác với checkbox. | | disableLabel | boolean | false | Vô hiệu hóa tương tác click trên nhãn văn bản. | | error | boolean | false | Đánh dấu checkbox đang ở trạng thái lỗi. | | iconImageClass | string | undefined | Class icon (ví dụ: fa fa-user) hiển thị cạnh checkbox. | | ignoreCheckbox | boolean | false | Ẩn ô chọn checkbox, chỉ hiển thị nhãn và các thành phần khác. | | ignoreShowPopoverLabel | boolean | false | Nếu true, sẽ không hiển thị popover khi di chuột vào nhãn. | | imgTypeIcon | boolean | false | Xác định hình ảnh truyền vào là dạng icon. | | key | string | undefined | Khóa định danh duy nhất cho checkbox. | | label | string | undefined | Văn bản hiển thị cho nhãn checkbox. | | linkImage | model<string> | undefined | URL hình ảnh hiển thị cạnh checkbox. | | linkImageError | string | undefined | URL hình ảnh hiển thị khi linkImage bị lỗi load. | | modeBorder | boolean | false | Hiển thị viền bao quanh toàn bộ component. | | popover | IPopover | undefined | Cấu hình Popover hiển thị khi di chuột vào nhãn. | | showBorderError | boolean | false | Hiển thị viền đỏ bao quanh khi error là true. | | stillOtherOptions | boolean | false | Hiển thị trạng thái "còn các lựa chọn khác" (dạng mờ/indicator). | | typeLabelPopover | 'text' \| 'component' | 'text' | Loại nội dung của popover trên nhãn. | | zIndexLabel | number | 1200 | Giá trị z-index cho phần nhãn và popover. |

Outputs

| Tên | Kiểu | Mô tả | | ------------------------------- | -------------------- | ------------------------------------------------------------------------------------- | | outChange | ICheckboxEvent | Phát ra khi trạng thái checked thay đổi. Gửi kèm key, trạng thái mới và hàm revert. | | outChangStageFlagMousePopover | IFlagMouse | Phát ra khi trạng thái chuột thay đổi trên vùng nhãn (để điều khiển popover). | | outClickLabel | void | Phát ra khi người dùng click trực tiếp vào nhãn văn bản. | | outEventPopover | TYPE_POPOVER_EVENT | Phát ra các sự kiện tương tác từ Popover. |

Interfaces & Types

ICheckboxEvent

interface ICheckboxEvent {
  key: any;
  checked: boolean;
  allCheckboxChecked?: Array<ICheckboxChecked>;
  revert: () => void;
}

ICheckboxItemDescription

interface ICheckboxItemDescription {
  content: string; // Nội dung mô tả (Hỗ trợ HTML)
  classInclude: string; // Class CSS bổ sung
}

ICheckboxBullet

interface ICheckboxBullet {
  classInclude?: string;
  backgroundColor: string;
  width: number;
  height: number;
}

Công nghệ sử dụng

• Angular 18+ - Standalone Components
• Angular Signals & Model - Modern reactive state management
• NG-Zorro Style Integration - Tuân thủ phong cách thiết kế chuyên nghiệp

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-single/checkbox-single.component.ts

Tính năng Demo

• 🎮 Basic Usage: Sử dụng cơ bản với nhãn và trạng thái.
• 🖼️ Image & Avatar: Kết hợp checkbox với hình ảnh minh họa.
• 💡 Popover & Description: Hiển thị thông tin chi tiết khi tương tác.
• 🛠️ Interactive Demo: Thử nghiệm các flag disable, error, ignoreCheckbox.

Unit Tests

# Chạy tests
npx nx test components-checkbox-single

License

MIT