Avatar Component

Version: 0.2.355-10

Component hiển thị avatar (ảnh đại diện) với khả năng fallback sang text/icon khi ảnh lỗi hoặc không có.

Giới thiệu

LibsUiComponentsAvatarComponent là một standalone Angular component để hiển thị avatar (ảnh đại diện) của người dùng. Component hỗ trợ nhiều kích thước, hình dạng (circle/rectangle), và có cơ chế fallback thông minh khi ảnh lỗi.

Tính năng

• ✅ Hiển thị ảnh avatar từ URL
• ✅ Fallback tự động sang text/icon khi ảnh lỗi
• ✅ Hỗ trợ nhiều kích thước: 16, 24, 32, 40, 48, 64px
• ✅ Hỗ trợ 2 hình dạng: circle (mặc định) và rectangle
• ✅ Tự động tạo màu nền dựa trên ID (hash color)
• ✅ Preview ảnh khi click (tùy chọn)
• ✅ OnPush Change Detection
• ✅ Angular Signals

Lưu ý quan trọng (Important Notes)

⚠️ Caveats:

• Thứ tự Input quan trọng: Nếu sử dụng getLastTextAfterSpace, phải truyền input này TRƯỚC textAvatar để logic transform hoạt động đúng.
• Error Handling Chain: Component có chuỗi xử lý lỗi: linkAvatar → linkAvatarError → textAvatar + idGenColor. Nếu tất cả đều fail, sẽ hiển thị icon với text.
• Màu nền tự động: Màu nền được tạo từ idGenColor thông qua hàm hash. Cùng ID sẽ luôn có cùng màu.
• Font size tự động: Font size của text avatar được tính tự động dựa trên size (16/24 → 6, 32 → 4, 40 → 3, 64 → 1, default → 4).
• Preview Image: Khi clickPreviewImage = true, click vào ảnh sẽ mở gallery viewer. Component tự quản lý lifecycle của gallery viewer.

Khi nào sử dụng

• Hiển thị ảnh đại diện người dùng trong danh sách, comment, profile
• Hiển thị avatar với fallback khi ảnh không tải được
• Cần hiển thị avatar với nhiều kích thước khác nhau
• Cần preview ảnh khi click vào avatar

Cài đặt

npm install @libs-ui/components-avatar

Import

import { LibsUiComponentsAvatarComponent, TYPE_SHAPE_AVATAR, TYPE_SIZE_AVATAR_CONFIG, IAvatarConfig } from '@libs-ui/components-avatar';

@Component({
  standalone: true,
  imports: [LibsUiComponentsAvatarComponent],
  // ...
})

Cách sử dụng

1. Basic - Avatar với ảnh

<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [size]="32" />

2. Avatar với fallback text

<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [linkAvatarError]="'https://example.com/fallback.jpg'"
  [textAvatar]="'John Doe'"
  [idGenColor]="'user-123'"
  [size]="40" />

3. Avatar rectangle

<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [typeShape]="'rectangle'"
  [size]="48" />

4. Avatar với preview

<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [clickPreviewImage]="true"
  [zIndexPreviewImage]="1000"
  [size]="64" />

5. Avatar với custom classes

<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [classInclude]="'mr-4 mb-2'"
  [classImageInclude]="'rounded-lg'"
  [size]="32" />

API

libs_ui-components-avatar

Inputs

| Property | Type | Default | Description | |----------|------|---------|-------------| | [typeShape] | TYPE_SHAPE_AVATAR \| undefined | 'circle' | Hình dạng avatar: 'circle' hoặc 'rectangle' | | [classInclude] | string \| undefined | 'mr-[8px]' | Class CSS tùy chỉnh cho container | | [size] | TYPE_SIZE_AVATAR_CONFIG \| undefined | 32 | Kích thước avatar: 16, 24, 32, 40, 48, 64 | | [linkAvatar] | string | - | URL ảnh avatar chính | | [linkAvatarError] | string | - | URL ảnh fallback khi linkAvatar lỗi | | [classImageInclude] | string \| undefined | '' | Class CSS tùy chỉnh cho thẻ img | | [zIndexPreviewImage] | number | - | Z-index cho gallery viewer khi preview | | [clickPreviewImage] | boolean | - | Bật preview ảnh khi click | | [idGenColor] | string | - | ID để generate màu nền (hash color) | | [getLastTextAfterSpace] | boolean | - | Lấy text cuối cùng sau khoảng trắng (phải truyền TRƯỚC textAvatar) | | [textAvatar] | string \| undefined | '' | Text hiển thị khi không có ảnh (tự động clean unicode và ký tự đặc biệt) | | [textAvatarClassInclude] | string | '' | Class CSS tùy chỉnh cho text | | [containertextAvatarClassInclude] | string | '' | Class CSS tùy chỉnh cho container text |

Outputs

| Property | Type | Description | |----------|------|-------------| | (outAvatarError) | EventEmitter<void> | Emit khi cả linkAvatar và linkAvatarError đều lỗi | | (outEventPreviewImage) | EventEmitter<'open' \| 'remove'> | Emit khi mở/đóng gallery viewer |

Types & Interfaces

export type TYPE_SIZE_AVATAR_CONFIG = 16 | 24 | 32 | 40 | 48 | 64;

export type TYPE_SHAPE_AVATAR = 'circle' | 'rectangle';

export interface IAvatarConfig {
  classImageInclude?: string;
  classInclude?: string;
  size?: TYPE_SIZE_AVATAR_CONFIG;
  linkAvatar?: string;
  linkAvatarError?: string;
  idGenColor?: string;
  textAvatar?: string;
  typeShape?: TYPE_SHAPE_AVATAR;
  getLastTextAfterSpace?: boolean;
}

Type Descriptions

• TYPE_SIZE_AVATAR_CONFIG: Các kích thước avatar được hỗ trợ. Font size của text sẽ tự động điều chỉnh theo size.
• TYPE_SHAPE_AVATAR: Hình dạng avatar. 'circle' có border-radius 50%, 'rectangle' có border-radius 4px.
• IAvatarConfig: Interface để định nghĩa object config, hữu ích khi truyền config từ parent component.

Styling

CSS Classes

| Class | Description | |-------|-------------| | .libs_ui-component-avatar | Container chính của avatar | | .libs_ui-component-avatar-rectangle | Class khi typeShape = 'rectangle' | | .libs_ui-component-avatar-icon | Container cho text/icon fallback |

CSS Variables

Component không sử dụng CSS variables, màu nền được generate từ idGenColor thông qua hàm hash.

Công nghệ

| Technology | Version | Purpose | |------------|---------|---------| | Angular | 18+ | Framework | | Angular Signals | - | State management | | TailwindCSS | 3.x | Styling | | OnPush | - | Change Detection |

Demo

npx nx serve core-ui

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

Unit Tests

# Chạy tests
npx nx test components-avatar

# Coverage
npx nx test components-avatar --coverage

# Watch mode
npx nx test components-avatar --watch

License

MIT