@libs-ui/components-tags

Library Angular Component quản lý và hiển thị danh sách các thẻ (Tags/Labels) với hỗ trợ tìm kiếm, lựa chọn từ danh sách, và tùy chỉnh giao diện mạnh mẽ.

Giới thiệu

LibsUiComponentsTagsComponent là một component linh hoạt cho phép người dùng chọn một hoặc nhiều mục từ một danh sách hoặc nhập trực tiếp. Nó hỗ trợ hiển thị avatar, các trạng thái validation, tìm kiếm online/offline, và tích hợp sâu với libs_ui-components-list và libs_ui-components-popover.

Tính năng

• ✅ Multiple Selection: Chọn nhiều mục cùng lúc.
• ✅ Single Selection: Chế độ chọn một mục duy nhất (UI giống dropdown).
• ✅ Search Online/Offline: Tìm kiếm linh hoạt từ local data hoặc qua API.
• ✅ Avatar Support: Tự động hiển thị avatar hoặc text avatar cho mỗi tag.
• ✅ Enter to Add: Cho phép tạo mới tag bằng cách nhấn Enter.
• ✅ Validation: Hỗ trợ required, max items, và pattern validation.
• ✅ Custom Styling: Tùy chỉnh màu sắc, border cho từng tag qua config.
• ✅ OnPush Change Detection: Tối ưu hiệu năng.

Khi nào sử dụng

• Trong các form cần chọn nhiều nhãn (labels), người nhận (recipients), hoặc phân loại (categories).
• Khi cần một bộ chọn (selector) có khả năng tìm kiếm mạnh mẽ và hiển thị thông tin phong phú (ảnh, tên).
• Thay thế cho các input text thuần túy khi dữ liệu có cấu trúc.

Cài đặt

# npm
npm install @libs-ui/components-tags

# yarn
yarn add @libs-ui/components-tags

Import

import { LibsUiComponentsTagsComponent } from '@libs-ui/components-tags';

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

Ví dụ

Basic Usage

<libs_ui-components-tags
  [listConfig]="listConfig"
  [(keysSelected)]="selectedKeys"
  placeholder="Chọn nhãn..." />

// Trong component class
readonly listConfig: IListConfigItem = {
  // Config cho LibsUiComponentsListComponent
  httpRequest: {
    url: '/api/tags',
    method: 'GET'
  }
};
readonly selectedKeys = signal<string[]>([]);

API

libs_ui-components-tags

Inputs

| Property | Type | Default | Description | | ------------------------------ | -------------------- | ----------------------- | ----------------------------------------------------------- | | [config] | ITagsConfig | undefined | Cấu hình chuyên sâu cho giao diện và logic của tags. | | [listConfig] | IListConfigItem | undefined | Cấu hình cho danh sách gợi ý (Popover list). | | [placeholder] | string | 'i18n_import_content' | Nội dung placeholder khi chưa có tag nào hoặc đang focus. | | [singleSelected] | boolean | false | Nếu true, chỉ cho phép chọn duy nhất một mục. | | [maxItemInput] | number | undefined | Giới hạn số lượng tag tối đa có thể chọn. | | [defaultKeysSelected] | Array<any> | undefined | Danh sách các keys mặc định được chọn ban đầu. | | [httpRequestDetailItemByIds] | IHttpRequestConfig | undefined | API dùng để lấy thông tin chi tiết các items dựa trên keys. | | [disable] | boolean | false | Vô hiệu hóa component. | | [readonly] | boolean | false | Chế độ chỉ đọc, không thể xóa hoặc thêm tag. | | [zIndex] | number | 1000 | z-index cho popover list. | | [fieldLabel] | string | 'label' | Tên trường hiển thị label cho tag. | | [fieldGetImage] | string | undefined | Tên trường lấy URL ảnh avatar. | | [validRequired] | IMessageTranslate | undefined | Message lỗi khi không có tag nào được chọn. |

Outputs

| Property | Type | Description | | ----------------------- | --------------------------- | ---------------------------------------------------------- | | (outSelectMultiItem) | Array<any> | Emit danh sách các đối tượng (items) đã được chọn. | | (outFunctionsControl) | ITagsFunctionControlEvent | Cung cấp các methods để điều khiển component từ bên ngoài. | | (outValidEvent) | boolean | Emit trạng thái validation (true nếu hợp lệ). |

Types & Interfaces

export interface ITagsConfig {
  getValue?: (item: unknown) => string; // Hàm custom lấy label
  getStyles?: (item: unknown) => any; // Hàm custom style cho tag
  getDisableItem?: (item: unknown) => boolean; // Disable click xóa cho tag cụ thể
  ignoreInput?: boolean; // Ẩn input nhập text
  uiLikeDropdown?: boolean; // Giao diện giống dropdown classic
  directionList?: TYPE_POPOVER_DIRECTION; // Hướng hiển thị danh sách
  // ... (see source for all options)
}

export interface ITagsFunctionControlEvent {
  checkIsValid: () => Promise<boolean>;
  clearItemSelected: (ignoreValid?: boolean) => Promise<void>;
  focusInput: () => Promise<void>;
  refreshListData: () => Promise<void>;
  resetToDefaultDataSelected: (item?: Array<unknown>) => Promise<void>;
  // ... (see source for all methods)
}

Demo

npx nx serve core-ui

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

Unit Tests

npx nx test components-tags

License

MIT