@libs-ui/components-process-bar-circle

Component hiển thị tiến trình dạng vòng tròn (Circular Progress Bar) trực quan, hỗ trợ tùy biến kích thước, màu sắc và nhãn hiển thị.

Giới thiệu

LibsUiComponentsProcessBarCircleComponent là một giải pháp hiển thị tiến trình dạng SVG hình tròn. Nó nhẹ, có khả năng mở rộng cao và cho phép tùy chỉnh sâu về giao diện thông qua hệ thống Input dựa trên cấu hình (config object).

Tính năng

• ✅ SVG-based: Độ sắc nét cao trên mọi độ phân giải.
• ✅ Cấu hình linh hoạt: Thay đổi kích thước (size), độ dày (stroke width), màu sắc (color) dễ dàng.
• ✅ Smooth Animations: Chuyển đổi mượt mà khi giá trị phần trăm thay đổi.
• ✅ Label Control: Tùy chọn hiển thị hoặc ẩn nhãn phần trăm ở giữa vòng tròn.
• ✅ OnPush Change Detection: Tối ưu hóa hiệu suất render.
• ✅ Angular Signals: Tận dụng cơ chế phản ứng mới của Angular.

Khi nào sử dụng

• Hiển thị phần trăm hoàn thành của một tác vụ cụ thể.
• Biểu diễn số liệu thống kê (ví dụ: dung lượng lưu trữ đã dùng).
• Làm bộ chỉ báo tải (loading indicator) có trạng thái.
• Trang trí dashboard với các biểu đồ tiến trình nhỏ gọn.

Cài đặt

# npm
npm install @libs-ui/components-process-bar-circle

# yarn
yarn add @libs-ui/components-process-bar-circle

Import

import { LibsUiComponentsProcessBarCircleComponent } from '@libs-ui/components-process-bar-circle';

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

Ví dụ

Cơ bản

<libs_ui-components-process_bar-circle [config]="{ percent: 75 }" />

Tùy chỉnh kích thước và màu sắc

<libs_ui-components-process_bar-circle
  [config]="{
    percent: 45,
    size: 150,
    strokeWidth: 12,
    color: '#10b981',
    backgroundColor: '#ecfdf5',
    labelClass: 'text-xl font-bold text-emerald-600'
  }" />

API

libs_ui-components-process_bar-circle

Inputs

| Property | Type | Default | Description | | ---------- | ---------------------------- | ------------ | --------------------------------------- | | [config] | IProcessBarCircleInterface | Bắt buộc | Đối tượng cấu hình cho vòng tiến trình. |

Types & Interfaces

export interface IProcessBarCircleInterface {
  /** Phần trăm hoàn thành (0-100) */
  percent: number;
  /** Kích thước của vòng tròn (px), mặc định 100 */
  size?: number;
  /** Độ dày của đường tiến trình (px), mặc định 8 */
  strokeWidth?: number;
  /** Màu của đường tiến trình, mặc định #3b82f6 (Blue 500) */
  color?: string;
  /** Màu nền của vòng tròn, mặc định #f1f5f9 (Slate 100) */
  backgroundColor?: string;
  /** Có hiển thị chữ số phần trăm ở giữa không, mặc định true */
  showLabel?: boolean;
  /** Class CSS tùy chỉnh cho nhãn phần trăm */
  labelClass?: string;
  /** Class CSS tùy chỉnh cho container */
  classInclude?: string;
}

Hidden Logic

1. SVG Calculations

Component tự động tính toán các thuộc tính SVG (stroke-dasharray, stroke-dashoffset) dựa trên size và strokeWidth để đảm bảo vòng tròn luôn căn giữa và không bị cắt mất viền khi thay dổi độ dày.

2. Transition Smoothing

Sử dụng CSS transitions trên thuộc tính stroke-dashoffset giúp việc cập nhật giá trị tiến trình diễn ra mượt mà mà không cần đến logic JavaScript phức tạp.

Demo

# Xem demo trực tiếp
npx nx serve core-ui

Truy cập: http://localhost:4200/process-bar/circle

License

MIT