Scroll Overlay Component

Giới thiệu

scroll-overlay là một directive mạnh mẽ giúp tuỳ biến thanh cuộn (scrollbar) cho bất kỳ phần tử nào trong ứng dụng Angular. Directive này cung cấp giao diện thanh cuộn đẹp, có thể tuỳ chỉnh màu sắc, kích thước, hiệu ứng hover, và nhiều tuỳ chọn nâng cao khác.

Tính năng

• Tuỳ chỉnh màu sắc, chiều rộng, padding của thanh cuộn
• Hỗ trợ cả chiều ngang (X) và dọc (Y)
• Hiệu ứng hover cho track và thumb
• Ẩn/hiện scrollbar khi hover hoặc theo tuỳ chọn
• Hỗ trợ drag & drop thumb để cuộn
• Sự kiện scroll chi tiết (top, bottom, X, Y)
• Dễ dàng tích hợp vào bất kỳ container nào

Cài đặt

Cài đặt package qua npm hoặc yarn:

npm install @libs-ui/components-scroll-overlay

hoặc

yarn add @libs-ui/components-scroll-overlay

Sử dụng

Import directive

import { LibsUiComponentsScrollOverlayDirective } from '@libs-ui/components-scroll-overlay';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [LibsUiComponentsScrollOverlayDirective],
  template: `
    <div
      LibsUiComponentsScrollOverlayDirective
      style="width: 300px; height: 400px;">
      Nội dung dài ở đây...
    </div>
  `,
})
export class ExampleComponent {}

Ví dụ nâng cao với options

<div
  LibsUiComponentsScrollOverlayDirective
  [options]="{scrollbarWidth: 12, scrollbarColor: '#eee', scrollThumbColor: '#888', scrollYOpacity0: true}"
  style="width: 300px; height: 400px;">
  Nội dung dài ở đây...
</div>

API Reference

Inputs

| Input | Type | Mô tả | | ------------------- | --------------------- | ------------------------------------------------------------- | | options | IScrollOverlayOptions | Tuỳ chọn cấu hình thanh cuộn | | debugMode | boolean | Bật chế độ debug | | ignoreInit | boolean | Bỏ qua khởi tạo directive | | classContainer | string | Thêm class cho container bọc ngoài | | notShowScrollBarX | boolean | Không hiển thị thanh cuộn ngang | | notShowScrollBarY | boolean | Không hiển thị thanh cuộn dọc | | elementCheckScrollX | HTMLElement | Phần tử dùng để kiểm tra scroll X (mặc định là chính element) | | elementCheckScrollY | HTMLElement | Phần tử dùng để kiểm tra scroll Y (mặc định là chính element) | | elementScroll | HTMLElement | Phần tử thực hiện scroll (mặc định là chính element) |

Outputs

| Output | Type | Mô tả | | --------------- | ----- | ----------------------------------- | | outScroll | Event | Bắn ra khi scroll bất kỳ | | outScrollX | Event | Bắn ra khi scroll theo chiều ngang | | outScrollY | Event | Bắn ra khi scroll theo chiều dọc | | outScrollTop | Event | Bắn ra khi scroll tới đầu (top) | | outScrollBottom | Event | Bắn ra khi scroll tới cuối (bottom) |

Options (IScrollOverlayOptions)

| Thuộc tính | Type | Mô tả | | --------------------- | ------------------ | ----------------------------------------------- | | scrollbarWidth | number | Chiều rộng/thanh cuộn (px) | | scrollbarColor | string | Màu nền track | | scrollbarHoverColor | string | Màu nền track khi hover | | scrollThumbColor | string | Màu thumb | | scrollThumbHoverColor | string | Màu thumb khi hover | | scrollbarPadding | number | Padding của scrollbar | | scrollX | 'hidden'|'scroll' | Kiểu hiển thị scroll X ('hidden' hoặc 'scroll') | | scrollXOpacity0 | boolean | Ẩn track X khi không hover | | scrollY | 'hidden'|'scroll' | Kiểu hiển thị scroll Y ('hidden' hoặc 'scroll') | | scrollYOpacity0 | boolean | Ẩn track Y khi không hover |

Interface

export interface IScrollOverlayOptions {
  scrollbarWidth?: number;
  scrollbarColor?: string;
  scrollbarHoverColor?: string;
  scrollThumbColor?: string;
  scrollThumbHoverColor?: string;
  scrollbarPadding?: number;
  scrollX?: 'hidden' | 'scroll';
  scrollXOpacity0?: boolean;
  scrollY?: 'hidden' | 'scroll';
  scrollYOpacity0?: boolean;
}

Ví dụ sử dụng nâng cao

<!-- Scroll overlay với tuỳ chỉnh màu sắc và hiệu ứng ẩn/hiện -->
<div
  LibsUiComponentsScrollOverlayDirective
  [options]="{scrollbarWidth: 8, scrollbarColor: '#f3f4f6', scrollThumbColor: '#3b82f6', scrollThumbHoverColor: '#2563eb', scrollYOpacity0: true}"
  style="width: 250px; height: 350px;">
  <div style="height: 1000px;">Nội dung rất dài để test scroll overlay...</div>
</div>

Ghi chú

• Directive này hoạt động tốt với mọi phần tử có overflow.
• Có thể kết hợp nhiều options để đạt hiệu quả UI mong muốn.
• Để tuỳ chỉnh sâu hơn, hãy xem thêm code và các sự kiện output để tích hợp logic riêng.