@libs-ui/components-color-picker

Component chọn màu sắc canvas-based với hỗ trợ đầy đủ HSL, RGB, HEX và alpha channel.

Giới thiệu

LibsUiComponentsColorPickerComponent là một standalone Angular component cung cấp giao diện color picker trực quan dựa trên HTML5 Canvas. Component cho phép người dùng chọn màu qua thanh Hue, vùng Saturation/Lightness, thanh Alpha và các ô nhập liệu RGB/HSL/HEX. Mọi thay đổi màu sắc được emit theo thời gian thực ở nhiều định dạng khác nhau.

Tính năng

• Canvas-based color picker với thanh Hue và vùng Saturation/Lightness
• Hỗ trợ Alpha channel (độ trong suốt 0–1)
• Emit màu ở nhiều định dạng: HEX, RGB, RGBA, HSL, HSLA, alpha
• Input fields cho từng kênh màu (R, G, B, H, S, L, Alpha, HEX)
• Preview màu real-time
• Nút copy mã màu HEX vào clipboard
• Tùy chỉnh kích thước các thanh color bar
• Bật/tắt từng nhóm input fields (RGB, HSL, HEX, Alpha)
• Kiểm soát có emit event khi khởi tạo component hay không
• OnPush Change Detection, Angular Signals, Standalone Component

Khi nào sử dụng

• Khi cần cho phép người dùng chọn màu sắc một cách trực quan
• Khi cần hỗ trợ nhiều định dạng màu (RGB, HSL, HEX) đồng thời
• Khi cần điều chỉnh độ trong suốt (alpha channel)
• Khi cần preview màu đã chọn real-time trước khi áp dụng
• Khi cần tùy chỉnh kích thước giao diện color picker để phù hợp với layout

Cài đặt

npm install @libs-ui/components-color-picker

Import

import { LibsUiComponentsColorPickerComponent } from '@libs-ui/components-color-picker';

// Interfaces và types nếu cần
import {
  IPickerCustomOptions,
  IOutputColorChangeMultipleType,
} from '@libs-ui/components-color-picker';

Ví dụ sử dụng

Cơ bản — Lắng nghe màu đã chọn dạng HEX

import { Component, signal } from '@angular/core';
import { LibsUiComponentsColorPickerComponent } from '@libs-ui/components-color-picker';

@Component({
  selector: 'app-basic-color-picker',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [LibsUiComponentsColorPickerComponent],
  template: `
    <libs_ui-components-color_picker
      (outColorChange)="handlerColorChange($event)"
    />
    <p>Màu đã chọn: <code>{{ selectedColor() }}</code></p>
  `,
})
export class BasicColorPickerComponent {
  protected selectedColor = signal<string>('#ff0000');

  protected handlerColorChange(event: string): void {
    event.stopPropagation?.();
    this.selectedColor.set(event);
  }
}

Với custom options — Alpha channel và HSL ẩn

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  IOutputColorChangeMultipleType,
  IPickerCustomOptions,
  LibsUiComponentsColorPickerComponent,
} from '@libs-ui/components-color-picker';

@Component({
  selector: 'app-custom-options-color-picker',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [LibsUiComponentsColorPickerComponent],
  template: `
    <libs_ui-components-color_picker
      [customOptions]="pickerOptions()"
      (outColorChange)="handlerColorChange($event)"
      (outColorChangeMultipleType)="handlerColorChangeMultiple($event)"
    />
    @if (colorOutput()) {
      <ul>
        <li>HEX: {{ colorOutput()!.hex }}</li>
        <li>RGB: {{ colorOutput()!.rgb }}</li>
        <li>RGBA: {{ colorOutput()!.rgba }}</li>
        <li>HSL: {{ colorOutput()!.hsl }}</li>
        <li>Alpha: {{ colorOutput()!.alpha }}</li>
      </ul>
    }
  `,
})
export class CustomOptionsColorPickerComponent {
  protected pickerOptions = signal<IPickerCustomOptions>({
    color: '#ff6b6b',
    showAlpha: true,
    showHex: true,
    showRgb: true,
    showHsl: false,
    format: 'hex',
  });

  protected colorOutput = signal<IOutputColorChangeMultipleType | null>(null);

  protected handlerColorChange(event: string): void {
    event.stopPropagation?.();
  }

  protected handlerColorChangeMultiple(event: IOutputColorChangeMultipleType): void {
    this.colorOutput.set(event);
  }
}

Tùy chỉnh kích thước bars — Picker nhỏ hơn

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
  IPickerCustomOptions,
  LibsUiComponentsColorPickerComponent,
} from '@libs-ui/components-color-picker';

@Component({
  selector: 'app-compact-color-picker',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [LibsUiComponentsColorPickerComponent],
  template: `
    <libs_ui-components-color_picker
      [customOptions]="compactOptions()"
      (outColorChange)="handlerColorChange($event)"
    />
  `,
})
export class CompactColorPickerComponent {
  protected compactOptions = signal<IPickerCustomOptions>({
    slBarSize: [300, 150],
    hueBarSize: [300, 16],
    alphaBarSize: [300, 16],
    showAlpha: true,
    showHex: true,
    showRgb: true,
    showHsl: false,
    color: '#3b82f6',
  });

  protected handlerColorChange(event: string): void {
    event.stopPropagation?.();
  }
}

Emit màu ngay khi khởi tạo component

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { LibsUiComponentsColorPickerComponent } from '@libs-ui/components-color-picker';

@Component({
  selector: 'app-emit-on-init-color-picker',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [LibsUiComponentsColorPickerComponent],
  template: `
    <libs_ui-components-color_picker
      [noEmitEventColorWhenInitComponent]="false"
      (outColorChange)="handlerColorChange($event)"
    />
  `,
})
export class EmitOnInitColorPickerComponent {
  protected handlerColorChange(event: string): void {
    event.stopPropagation?.();
    // Sẽ được gọi ngay khi component khởi tạo
  }
}

@Input()

| Input | Type | Default | Mô tả | Ví dụ | |---|---|---|---|---| | [customOptions] | IPickerCustomOptions | undefined | Tùy chỉnh toàn bộ options của color picker: kích thước bars, màu mặc định, format parse, hiển thị các nhóm input | [customOptions]="{ color: '#ff0000', showAlpha: true }" | | [noEmitEventColorWhenInitComponent] | boolean | true | Không emit event outColorChange và outColorChangeMultipleType khi component khởi tạo lần đầu. Set false để emit ngay khi init | [noEmitEventColorWhenInitComponent]="false" |

@Output()

| Output | Type | Mô tả | Handler TS | Binding HTML | |---|---|---|---|---| | (outColorChange) | string | Emit màu đã chọn dưới dạng HEX string (có alpha nếu showAlpha: true). Ví dụ: "#3b82f6" hoặc "#3b82f6ff" | handlerColorChange(event: string): void { event.stopPropagation?.(); this.color.set(event); } | (outColorChange)="handlerColorChange($event)" | | (outColorChangeMultipleType) | IOutputColorChangeMultipleType | Emit màu đã chọn ở tất cả các định dạng cùng lúc: hex, rgb, rgba, hsl, hsla và giá trị alpha số | handlerColorChangeMultiple(event: IOutputColorChangeMultipleType): void { event.stopPropagation?.(); this.colorOutput.set(event); } | (outColorChangeMultipleType)="handlerColorChangeMultiple($event)" |

Types & Interfaces

import {
  IPickerCustomOptions,
  IOutputColorChangeMultipleType,
} from '@libs-ui/components-color-picker';

IPickerCustomOptions

Interface để tùy chỉnh giao diện và hành vi của color picker. Tất cả các field đều là optional — chỉ truyền những gì muốn override so với giá trị mặc định.

interface IPickerCustomOptions {
  /** Kích thước vùng Saturation/Lightness [width, height]. Default: [420, 200] */
  slBarSize?: Array<number>;

  /** Kích thước thanh Hue [width, height]. Default: [420, 20] */
  hueBarSize?: Array<number>;

  /** Kích thước thanh Alpha [width, height]. Default: [420, 20] */
  alphaBarSize?: Array<number>;

  /** Hiển thị nhóm input HSL (H, S, L). Default: false */
  showHsl?: boolean;

  /** Hiển thị nhóm input RGB (R, G, B). Default: true */
  showRgb?: boolean;

  /** Hiển thị ô nhập HEX. Default: true */
  showHex?: boolean;

  /** Hiển thị thanh và ô nhập Alpha. Default: false */
  showAlpha?: boolean;

  /** Màu khởi tạo ban đầu — nhận HEX string, CSS color name, hoặc mảng [r, g, b] / [r, g, b, a]. Default: '#ff0000' */
  color?: string | Array<number>;

  /**
   * Format dùng để parse giá trị color input ban đầu khi gọi handlerColorChange nội bộ.
   * - 'color': Tự động parse từ nhiều format (mặc định)
   * - 'rgb' / 'rgba': Parse từ mảng [r, g, b] / [r, g, b, a]
   * - 'hsl' / 'hsla': Parse từ mảng [h, s, l] / [h, s, l, a]
   * - 'hex': Parse từ HEX string
   * Default: 'color'
   */
  format?: 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'hex' | 'color';
}

IOutputColorChangeMultipleType

Interface của object được emit qua outColorChangeMultipleType. Chứa màu đã chọn ở mọi định dạng phổ biến.

interface IOutputColorChangeMultipleType {
  /** HEX string. Ví dụ: "#3b82f6" hoặc "#3b82f6ff" khi có alpha */
  hex: string;

  /** CSS rgb(). Ví dụ: "rgb(59,130,246)" */
  rgb: string;

  /** CSS rgba(). Ví dụ: "rgba(59,130,246,1)" */
  rgba: string;

  /** CSS hsl(). Ví dụ: "hsl(217,91,60)" */
  hsl: string;

  /** CSS hsla(). Ví dụ: "hsla(217,91,60,1)" */
  hsla: string;

  /** Giá trị alpha trong khoảng 0–1. Ví dụ: 0.75 */
  alpha: number;
}

Lưu ý quan trọng

⚠️ Canvas API bắt buộc: Component dùng HTML5 Canvas để render vùng màu và các thanh bar. Cần chạy trên môi trường browser hỗ trợ Canvas API (không dùng được trong SSR/Node context).

⚠️ Không emit khi init mặc định: Mặc định noEmitEventColorWhenInitComponent = true, nghĩa là outColorChange và outColorChangeMultipleType sẽ không fired khi component mount lần đầu. Nếu cần nhận giá trị màu ngay khi hiển thị, truyền [noEmitEventColorWhenInitComponent]="false".

⚠️ Alpha chỉ hoạt động khi bật: Thanh alpha và ô nhập alpha chỉ render khi showAlpha: true trong customOptions. Khi showAlpha là false (mặc định), giá trị alpha luôn là 1 và HEX output không kèm alpha.

⚠️ HEX output có alpha khi showAlpha bật: Khi showAlpha: true, outColorChange emit HEX 8 ký tự dạng #rrggbbaa thay vì #rrggbb thông thường.

⚠️ customOptions không reactive sau init: customOptions được đọc một lần trong ngOnInit. Thay đổi object sau khi component đã mount sẽ không cập nhật giao diện picker. Nếu cần thay đổi dynamic, hãy destroy và tạo lại component.