@libs-ui/components-list 0.2.355-9 → 0.2.356-0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,3 +1,176 @@
|
|
|
1
|
-
# list
|
|
1
|
+
# @libs-ui/components-list
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Component mạnh mẽ hỗ trợ hiển thị danh sách với nhiều định dạng: Text, Radio, Checkbox và Group/Tree.
|
|
4
|
+
|
|
5
|
+
## Giới thiệu
|
|
6
|
+
|
|
7
|
+
`LibsUiComponentsListComponent` là một standalone Angular component được thiết kế để xử lý các bài toán hiển thị danh sách phức tạp trong ứng dụng. Component này không chỉ hiển thị dữ liệu mà còn tích hợp sâu với các dịch vụ lấy dữ liệu (HTTP), tìm kiếm và quản lý trạng thái chọn item.
|
|
8
|
+
|
|
9
|
+
### Tính năng
|
|
10
|
+
|
|
11
|
+
- ✅ **Đa dạng Template**: Hỗ trợ 5 loại hiển thị: `text`, `radio`, `checkbox`, `tag`, `group`.
|
|
12
|
+
- ✅ **Cấu trúc Cây (Group/Tree)**: Hiển thị phân cấp không giới hạn level với logic quan hệ cha-con tinh tế.
|
|
13
|
+
- ✅ **Tìm kiếm Thông minh**: Hỗ trợ cả tìm kiếm Online (server-side) và Offline (client-side).
|
|
14
|
+
- ✅ **Tích hợp HTTP**: Tự động load dữ liệu thông qua cấu hình `httpRequestData`.
|
|
15
|
+
- ✅ **OnPush Change Detection**: Tối ưu hiệu năng render.
|
|
16
|
+
- ✅ **Standalone Component**: Dễ dàng import và sử dụng.
|
|
17
|
+
- ✅ **Angular Signals**: State management hiện đại và reactive.
|
|
18
|
+
|
|
19
|
+
## Khi nào sử dụng
|
|
20
|
+
|
|
21
|
+
- Khi cần hiển thị danh sách các tùy chọn cho người dùng chọn một hoặc nhiều.
|
|
22
|
+
- Khi xây dựng các bộ lọc (filters) có cấu trúc phân cấp phức tạp.
|
|
23
|
+
- Khi danh sách có kích thước lớn và cần tối ưu hiệu năng render (Virtual Scroll).
|
|
24
|
+
- Khi muốn đồng bộ hóa việc tìm kiếm và hiển thị dữ liệu từ API một cách tự động.
|
|
25
|
+
|
|
26
|
+
## Cài đặt
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# npm
|
|
30
|
+
npm install @libs-ui/components-list
|
|
31
|
+
|
|
32
|
+
# yarn
|
|
33
|
+
yarn add @libs-ui/components-list
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Import
|
|
37
|
+
|
|
38
|
+
```typescript
|
|
39
|
+
import { LibsUiComponentsListComponent } from '@libs-ui/components-list';
|
|
40
|
+
|
|
41
|
+
@Component({
|
|
42
|
+
standalone: true,
|
|
43
|
+
imports: [LibsUiComponentsListComponent],
|
|
44
|
+
// ...
|
|
45
|
+
})
|
|
46
|
+
export class YourComponent {}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Ví dụ
|
|
50
|
+
|
|
51
|
+
### Basic (Text)
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<libs_ui-components-list
|
|
55
|
+
[config]="{
|
|
56
|
+
type: 'text',
|
|
57
|
+
configTemplateText: signal({
|
|
58
|
+
fieldKey: 'id',
|
|
59
|
+
getValue: (item) => item.label
|
|
60
|
+
})
|
|
61
|
+
}"
|
|
62
|
+
(outSelectKey)="onSelect($event)"></libs_ui-components-list>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Checkbox (Multi-select)
|
|
66
|
+
|
|
67
|
+
```html
|
|
68
|
+
<libs_ui-components-list
|
|
69
|
+
[config]="{
|
|
70
|
+
type: 'checkbox',
|
|
71
|
+
configTemplateCheckbox: signal({
|
|
72
|
+
fieldKey: 'id',
|
|
73
|
+
getValue: (item) => item.name
|
|
74
|
+
})
|
|
75
|
+
}"
|
|
76
|
+
[multiKeySelected]="['1', '2']"
|
|
77
|
+
(outSelectMultiKey)="onMultiSelect($event)"></libs_ui-components-list>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## API
|
|
81
|
+
|
|
82
|
+
### libs_ui-components-list
|
|
83
|
+
|
|
84
|
+
#### Inputs
|
|
85
|
+
|
|
86
|
+
| Property | Type | Default | Description |
|
|
87
|
+
| ------------------------------------------------- | -------------------------------- | -------------- | ---------------------------------------------------------- |
|
|
88
|
+
| `autoSelectedFirstItemCallOutsideBefore` | `boolean` | `false` | Tự động chọn item đầu tiên nếu chưa có item nào được chọn. |
|
|
89
|
+
| `backgroundListCustom` | `string` | `bg-[#ffffff]` | Màu nền tùy chỉnh cho danh sách. |
|
|
90
|
+
| `buttonsOther` | `IButton[]` | `undefined` | Danh sách các nút bấm khác hiển thị trên cùng. |
|
|
91
|
+
| `clickExactly` | `boolean` | `undefined` | Chỉ kích hoạt chọn khi click chính xác vào item. |
|
|
92
|
+
| `config` | `IListConfigItem` | `REQUIRED` | Cấu hình chính (loại template, logic lấy dữ liệu...). |
|
|
93
|
+
| `disable` | `boolean` | `false` | Vô hiệu hóa toàn bộ component. |
|
|
94
|
+
| `disableLabel` | `boolean` | `false` | Vô hiệu hóa nhãn (label). |
|
|
95
|
+
| `dividerClassInclude` | `string` | `undefined` | Class CSS bổ sung cho đường kẻ phân cách. |
|
|
96
|
+
| `dropdownTabKeyActive` | `string` | `undefined` | Key của tab đang active trong dropdown. |
|
|
97
|
+
| `focusInputSearch` | `boolean` | `undefined` | Tự động focus vào ô tìm kiếm khi dữ liệu load xong. |
|
|
98
|
+
| `functionGetItemsAutoAddList` | `() => Array<any>` | `undefined` | Hàm lấy danh sách item tự động thêm vào list. |
|
|
99
|
+
| `hasButtonUnSelectOption` | `boolean` | `undefined` | Hiển thị nút bỏ chọn tất cả. |
|
|
100
|
+
| `hasDivider` | `boolean` | `true` | Hiển thị gạch phân cách giữa các item. |
|
|
101
|
+
| `hiddenInputSearch` | `boolean` | `false` | Ẩn/hiện thanh tìm kiếm. |
|
|
102
|
+
| `ignoreClassDisableDefaultWhenUseKeysDisableItem` | `boolean` | `undefined` | Bỏ class disable mặc định khi dùng keysDisableItem. |
|
|
103
|
+
| `isSearchOnline` | `boolean` | `false` | Bật tìm kiếm từ Server (call API). |
|
|
104
|
+
| `keySearch` | `string` | `undefined` | Giá trị tìm kiếm khởi tạo. |
|
|
105
|
+
| `keySelected` | `any` | `undefined` | Key đang chọn (áp dụng cho single select). |
|
|
106
|
+
| `keysDisableItem` | `Array<any>` | `undefined` | Danh sách các keys bị vô hiệu hóa. |
|
|
107
|
+
| `keysHiddenItem` | `Array<any>` | `undefined` | Danh sách các keys bị ẩn đi. |
|
|
108
|
+
| `labelConfig` | `ILabel` | `undefined` | Cấu hình label tiêu đề. |
|
|
109
|
+
| `loadingIconSize` | `'large' \| 'medium' \| 'small'` | `undefined` | Kích thước icon loading. |
|
|
110
|
+
| `maxItemShow` | `number` | `undefined` | Số lượng item tối đa hiển thị trước khi scroll. |
|
|
111
|
+
| `multiKeySelected` | `Array<any>` | `[]` | Danh sách keys đang chọn (áp dụng cho multi select). |
|
|
112
|
+
| `paddingLeftItem` | `boolean` | `undefined` | Thêm padding bên trái cho item. |
|
|
113
|
+
| `resetKeyWhenSelectAllKeyDropdown` | `boolean` | `undefined` | Reset key khi chọn tất cả trong dropdown. |
|
|
114
|
+
| `searchConfig` | `IInputSearchConfig` | `{}` | Cấu hình chi tiết cho ô tìm kiếm. |
|
|
115
|
+
| `searchPadding` | `boolean` | `undefined` | Thêm padding cho thanh tìm kiếm. |
|
|
116
|
+
| `showValidateBottom` | `boolean` | `undefined` | Hiển thị thông báo validate ở phía dưới. |
|
|
117
|
+
| `skipFocusInputWhenKeySearchStoreUndefined` | `boolean` | `undefined` | Bỏ qua focus input nếu keySearchStore là undefined. |
|
|
118
|
+
| `templateRefSearchNoData` | `TemplateRef` | `undefined` | Template hiển thị khi tìm kiếm không có kết quả. |
|
|
119
|
+
| `validRequired` | `IValidRequired` | `undefined` | Bắt buộc phải chọn item. |
|
|
120
|
+
| `zIndex` | `number` | `undefined` | Z-index cho danh sách. |
|
|
121
|
+
|
|
122
|
+
#### Outputs
|
|
123
|
+
|
|
124
|
+
| Property | Type | Description |
|
|
125
|
+
| --------------------------------- | ----------------------------------------- | -------------------------------------------------------- |
|
|
126
|
+
| `(outChangeView)` | `Array<any>` | Phát ra khi danh sách hiển thị thay đổi (ví dụ sau lọc). |
|
|
127
|
+
| `(outChangStageFlagMousePopover)` | `IFlagMouse` | Phát ra trạng thái hover chuột cho popover. |
|
|
128
|
+
| `(outClickButtonOther)` | `IButton` | Phát ra khi click vào các nút bấm bổ sung. |
|
|
129
|
+
| `(outFieldKey)` | `string` | Phát ra key của trường dữ liệu được chọn. |
|
|
130
|
+
| `(outFunctionsControl)` | `IListFunctionControlEvent` | Cung cấp các method điều khiển từ bên ngoài. |
|
|
131
|
+
| `(outKeySearch)` | `string` | Phát ra khi keyword tìm kiếm thay đổi. |
|
|
132
|
+
| `(outLoadItemsComplete)` | `{ items: Array<any>, paging?: IPaging }` | Phát ra khi việc tải dữ liệu hoàn tất. |
|
|
133
|
+
| `(outLoading)` | `boolean` | Trạng thái đang tải dữ liệu. |
|
|
134
|
+
| `(outSelectKey)` | `IListDataEmitKey` | Phát ra khi chọn 1 item (Single Select). |
|
|
135
|
+
| `(outSelectMultiKey)` | `IListDataEmitMultiKey` | Phát ra khi chọn nhiều item (Multi Select). |
|
|
136
|
+
| `(outUnSelectMultiKey)` | `Array<unknown>` | Phát ra danh sách các keys bị bỏ chọn. |
|
|
137
|
+
|
|
138
|
+
#### Methods (via outFunctionsControl)
|
|
139
|
+
|
|
140
|
+
| Method | Parameters | Description |
|
|
141
|
+
| -------------------- | -------------------------- | --------------------------------------------------------- |
|
|
142
|
+
| `checkIsValid()` | `-` | Kiểm tra tính hợp lệ của lựa chọn (nếu có validRequired). |
|
|
143
|
+
| `getRectListView()` | `-` | Lấy kích thước và vị trí của list view container. |
|
|
144
|
+
| `refresh()` | `-` | Làm mới danh sách và tải lại dữ liệu từ đầu. |
|
|
145
|
+
| `removeItems()` | `keys: Array<any>` | Xóa các item cụ thể khỏi danh sách theo keys. |
|
|
146
|
+
| `resetKeySelected()` | `-` | Xóa sạch toàn bộ các item đang được chọn. |
|
|
147
|
+
| `updateData()` | `data: IDataUpdateToStore` | Cập nhật dữ liệu cụ thể vào store của list. |
|
|
148
|
+
|
|
149
|
+
## Types & Interfaces
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
export interface IListConfigItem {
|
|
153
|
+
type: 'text' | 'radio' | 'checkbox' | 'group' | 'tag';
|
|
154
|
+
httpRequestData?: WritableSignal<IHttpRequestConfig>;
|
|
155
|
+
configTemplateText?: WritableSignal<IListConfigItemText>;
|
|
156
|
+
// ...
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
export interface IListDataEmitKey {
|
|
160
|
+
key: any;
|
|
161
|
+
item: any;
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Công nghệ
|
|
166
|
+
|
|
167
|
+
| Technology | Purpose |
|
|
168
|
+
| ----------------- | --------------------------- |
|
|
169
|
+
| Angular 18+ | Framework chính |
|
|
170
|
+
| Angular Signals | Quản lý state reactive |
|
|
171
|
+
| TailwindCSS | Styling hệ thống |
|
|
172
|
+
| Dynamic Component | Khởi tạo template linh hoạt |
|
|
173
|
+
|
|
174
|
+
## License
|
|
175
|
+
|
|
176
|
+
MIT
|