@libs-ui/components-minimap

Thêm bản đồ thu nhỏ (Minimap) cho các vùng chứa có nội dung lớn hoặc cuộn.

Giới thiệu

LibsUiComponentsMinimapDirective là một standalone directive giúp tạo ra một trải nghiệm chuyển hướng trực quan cho người dùng trong các bảng vẽ (canvas), sơ đồ hoặc các vùng nội dung rộng lớn. Nó tự động theo dõi thay đổi trong DOM và đồng bộ hóa vị trí cuộn giữa nội dung chính và bản đồ thu nhỏ.

Tính năng

• ✅ Standalone Directive: Dễ dàng tích hợp vào bất kỳ phần tử nào có thuộc tính cuộn.
• ✅ Đồng bộ hai chiều: Cuộn nội dung chính cập nhật Minimap, kéo viewport trên Minimap cập nhật nội dung chính.
• ✅ Theo dõi thay đổi: Sử dụng MutationObserver để tự động cập nhật hình ảnh trên Minimap khi nội dung thay đổi.
• ✅ Tùy biến cao: Cho phép cấu hình vị trí, kích thước, màu sắc và z-index của cả Minimap và Viewport.
• ✅ Hỗ trợ Scale: Khả năng nhận diện tỷ lệ phóng to/thu nhỏ của nội dung để hiển thị chính xác.

Khi nào sử dụng

• Khi có các vùng chứa nội dung lớn vượt quá kích thước màn hình (sơ đồ, bản đồ văn phòng, editor đồ họa).
• Khi người dùng cần cái nhìn tổng quan về cấu trúc nội dung và khả năng di chuyển nhanh chóng đến các vùng cụ thể.
• Thay thế hoặc hỗ trợ cho thanh cuộn truyền thống trên các giao diện phức tạp.

Cài đặt

# npm
npm install @libs-ui/components-minimap

# yarn
yarn add @libs-ui/components-minimap

Import

import { LibsUiComponentsMinimapDirective } from '@libs-ui/components-minimap';

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

Ví dụ

Cơ bản

<div
  class="w-full h-[500px] overflow-auto"
  LibsUiComponentsMinimapDirective>
  <!-- Nội dung lớn ở đây -->
  <div class="w-[2000px] h-[2000px]">...</div>
</div>

Với cấu hình Styles và Controls

<div
  class="scroll-container"
  LibsUiComponentsMinimapDirective
  [styleImageElement]="{ bottom: 20, right: 20, width: 200, height: 120 }"
  [styleRectangleElement]="{ border: '2px solid #3b82f6' }"
  (outFunctionControls)="controls = $event">
  ...
</div>

<button (click)="controls.toggle()">Bật/Tắt Minimap</button>

API

[LibsUiComponentsMinimapDirective]

Inputs

| Property | Type | Default | Description | | ----------------------------- | --------------------- | -------------------------------------- | ---------------------------------------------------- | | [elementScroll] | HTMLElement | Host Element | Phần tử đích để theo dõi cuộn (nếu khác host). | | [styleImageElement] | IMiniMapStyleConfig | undefined | Cấu hình phong cách và vị trí cho khung Minimap. | | [styleRectangleElement] | IMiniMapStyleConfig | undefined | Cấu hình cho khung Viewport trên Minimap. | | [timerStartDrawMinimap] | number | 250 | Thời gian chờ (ms) trước khi bắt đầu vẽ Minimap. | | [classNameFlagElementScale] | string | 'libs-ui-minimap-flag-element-scale' | Class name để xác định phần tử chứa scale transform. |

Outputs

| Property | Type | Description | | ----------------------- | --------------------------------------- | ---------------------------------------------------- | | (outFunctionControls) | EventEmitter<IMiniMapFunctionControl> | Phát ra bộ điều khiển để điều khiển Minimap từ code. |

Methods (via Controls)

| Method | Parameters | Description | | ---------- | ---------- | ------------------------------- | | show() | - | Hiển thị Minimap. | | hidden() | - | Ẩn Minimap. | | toggle() | - | Chuyển đổi trạng thái hiển thị. |

Types & Interfaces

export interface IMiniMapStyleConfig {
  zIndex?: number;
  border?: string;
  borderRadius?: number;
  background?: string;
  top?: number;
  left?: number;
  bottom?: number;
  right?: number;
  width?: number;
  height?: number;
  x?: number;
  y?: number;
}

export interface IMiniMapFunctionControl {
  show: () => void;
  hidden: () => void;
  toggle: () => void;
}

Công nghệ

| Technology | Purpose | | ---------------- | ------------------------- | | Angular 18+ | Framework chính | | Angular Signals | Quản lý trạng thái nội bộ | | MutationObserver | Theo dõi thay đổi DOM | | DOM Cloning | Tạo hình ảnh thu nhỏ |

License

MIT