Upload Component

@libs-ui/components-inputs-upload là một thành phần mạnh mẽ dùng để xử lý việc tải lên tệp tin. Nó hỗ trợ nhiều loại tệp (hình ảnh, video, âm thanh, tài liệu), tải lên nhiều tệp cùng lúc, kéo thả, chỉnh sửa hình ảnh trực tiếp và xem trước tệp.

Tính năng nổi bật

• 📁 Multi-format Support: Hỗ trợ image, video, audio, document và các tổ hợp của chúng.
• 🖱️ Drag & Drop: Hỗ trợ kéo thả tệp tin trực tiếp vào vùng tải lên.
• 🖼️ Image Editor: Tích hợp trình chỉnh sửa ảnh (cắt, xoay) trước khi lưu.
• 🔍 File Preview: Xem trước hình ảnh qua Gallery Viewer và các tài liệu khác qua Preview File component.
• 👤 Avatar Mode: Hỗ trợ chế độ chọn một hình ảnh làm ảnh đại diện (isAvatar).
• 📏 Size & Limit Control: Kiểm soát kích thước tệp tối đa (theo từng loại), tổng kích thước và số lượng tệp tối đa.
• 🎨 Display Modes: Hỗ trợ hai chế độ hiển thị danh sách tệp: full (chi tiết) và short (gọn nhẹ).
• 🔗 Sample Download: Hỗ trợ nút tải tệp mẫu đi kèm.
• 🛡️ Signal Based: Sử dụng Angular Signals để quản lý trạng thái tệp và cấu hình mượt mà.

Cài đặt

Sử dụng npm hoặc yarn để cài đặt:

npm install @libs-ui/components-inputs-upload

Cách sử dụng

Import Module

import { LibsUiComponentsInputsUploadComponent } from '@libs-ui/components-inputs-upload';

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

Ví dụ cơ bản (Tải lên hình ảnh)

<libs_ui-components-inputs-upload
  [fileType]="'image'"
  [multiple]="true"
  [limitFile]="5"
  (outFileChanged)="handleFileChanged($event)"></libs_ui-components-inputs-upload>

Chế độ Avatar và Chỉnh sửa ảnh

<libs_ui-components-inputs-upload
  [fileType]="'image'"
  [canSetAvatar]="true"
  [aspectRatio]="{ width: 1, height: 1 }"
  [multiple]="false"
  (outFileChanged)="onAvatarChanged($event)"></libs_ui-components-inputs-upload>

API Reference

Inputs

| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả | | :---------------------------------------- | :-------------------------------- | :----------------------- | :------------------------------------------------------------ | | allowShowPushMessageMaxSizeError | boolean | false | Hiển thị thông báo lỗi khi file vượt quá kích thước cho phép. | | aspectRatio | IAspectRatio | undefined | Tỉ lệ khung hình cố định khi chỉnh sửa ảnh. | | audioExtList | string[] | AudioExtList | Danh sách đuôi file âm thanh được phép. | | canSetAvatar | boolean | false | Hiển thị nút chọn ảnh đại diện cho các file ảnh. | | canUploadIfHasExistFile | boolean | false | Cho phép tải lên tiếp khi đã có file (với single mode). | | classIncludeAvatar | string | '' | Class CSS cho vùng ảnh đại diện. | | classIncludeFileContent | string | '' | Class CSS cho vùng nội dung file. | | classIncludeListItem | string | undefined | Class CSS cho từng item file. | | configDescriptionInputUpload | IMessageTranslate | {message: ...} | Cấu hình mô tả văn bản trong vùng upload. | | configDownloadSampleFile | IUploadConfigDownloadSampleFile | undefined | Cấu hình nút tải tệp mẫu. | | descriptionFormatAndSizeFile | Array<IUploadDescription> | undefined | Mô tả định dạng và kích thước file cho phép. | | disable | boolean | false | Vô hiệu hóa upload. | | documentExtList | string[] | DocumentExtList | Danh sách đuôi file tài liệu được phép. | | fileType | TYPE_FILE_UPLOAD | 'image_video_document' | Các loại tệp được phép tải lên. | | ignoreIconEdit | boolean | false | Ẩn nút chỉnh sửa. | | ignoreIconPreview | boolean | true | Ẩn nút xem trước (mặc định ẩn). | | ignoreIconRemove | boolean | false | Ẩn nút xóa. | | ignoreShowSizeFile | boolean | false | Ẩn thông tin kích thước file. | | imageExtList | string[] | ImageExtList | Danh sách đuôi file ảnh được phép. | | labelConfig | ILabel | undefined | Cấu hình nhãn phía trên vùng upload. | | limitFile | number | 10 | Số lượng tệp tối đa được phép. | | maxAudioSize | number | 10MB | Dung lượng tối đa cho 1 file âm thanh. | | maxDocumentSize | number | 10MB | Dung lượng tối đa cho 1 file tài liệu. | | maxImageSize | number | 5MB | Dung lượng tối đa cho 1 file ảnh. | | maxTotalSize | number | 10MB | Tổng dung lượng tối đa của tất cả các tệp (bytes). | | maxVideoSize | number | 10MB | Dung lượng tối đa cho 1 file video. | | messageFileUploadError | string | ... | Thông báo lỗi khi file upload không hợp lệ. | | messageMaxSizeError | string | ... | Thông báo lỗi khi file quá lớn. | | messageTotalFileExceedsError | string | ... | Thông báo lỗi khi số lượng file vượt quá giới hạn. | | messageTypeFileError | string | ... | Thông báo lỗi khi định dạng file không đúng. | | modeDisplayFile | 'full' \| 'short' | 'full' | Chế độ hiển thị danh sách tệp đã chọn. | | multiple | boolean | false | Cho phép chọn nhiều tệp. | | originFiles | Array<WritableSignal<IFile>> | [] | Danh sách file khởi tạo ban đầu. | | readonly | boolean | false | Chế độ chỉ đọc. | | showBorderErrorAllItemWhenError | boolean | false | Hiển thị border đỏ cho tất cả item khi có lỗi. | | showPopupUploadWhenHasFileAndModeSingle | boolean | false | Hiển thị popup upload khi click vào file ở chế độ single. | | showVideoDuration | boolean | false | Hiển thị thời lượng video. | | validRequired | IIsValidRequired | undefined | Cấu hình validate bắt buộc. | | videoExtList | string[] | VideoExtList | Danh sách đuôi file video được phép. | | zIndex | number | 1200 | Z-index của các popup (gallery, editor). |

Outputs

| Sự kiện | Kiểu dữ liệu | Mô tả | | :-------------------- | :----------------------------- | :------------------------------------------------------------------------------- | | outFileChanged | Array<WritableSignal<IFile>> | Phát ra danh sách tệp mỗi khi có sự thay đổi (thêm, xóa, sửa). | | outFileRemoved | WritableSignal<IFile> | Phát ra tệp bị xóa khỏi danh sách. | | outFunctionsControl | IUploadFunctionControlEvent | Cung cấp các phương thức điều khiển (validate, removeAll, handlerUploadFile...). | | outClose | boolean | Phát ra khi đóng popup. |

Methods (via outFunctionsControl)

• checkIsValid(): Kiểm tra tính hợp lệ của danh sách tệp hiện tại.
• removeAll(): Xóa sạch danh sách tệp.
• handlerUploadFile(): Kích hoạt cửa sổ chọn tệp của trình duyệt.

Types & Interfaces

TYPE_FILE_UPLOAD

Định nghĩa các tập hợp định dạng tệp được phép.

export type TYPE_FILE_UPLOAD =
  | 'document'
  | 'image'
  | 'video'
  | 'audio'
  | 'image_document'
  | 'image_video'
  | 'image_audio'
  | 'document_audio'
  | 'video_audio'
  | 'image_document_audio'
  | 'image_video_audio'
  | 'document_video_audio'
  | 'image_video_document'
  | 'image_audio_video_document';

IUploadConfigDownloadSampleFile

Cấu hình cho nút tải xuống tệp mẫu.

export interface IUploadConfigDownloadSampleFile {
  position?: 'top' | 'bottom';
  title: string;
  url?: string;
  classLabel?: string;
  classInclude?: string;
  classIconLeftInclude?: string;
  callBack?: () => void;
}

IUploadFunctionControlEvent

Giao diện điều khiển component bên ngoài.

export interface IUploadFunctionControlEvent {
  checkIsValid: () => Promise<boolean>;
  removeAll: () => Promise<void>;
  uploading: (process: IHttpProcessUpload, id: string) => Promise<void>;
  setMessageError: (message: string, id?: string) => Promise<void>;
  handlerUploadFile: () => Promise<void>;
}

Tech Stack

• Core: Angular 18+, Signals, RxJS
• Dependencies: @libs-ui/components-buttons-button, @libs-ui/components-gallery, @libs-ui/components-image-editor, @libs-ui/components-label, @libs-ui/components-preview-file, @libs-ui/services-dynamic-component.

License

MIT