import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/vi/scripts/Classes/DesignFlags - Trình tạo Sprite cờ'/>

# Lớp DesignFlags

Lớp `DesignFlags` cung cấp một giải pháp tự động để tạo các sprite hình ảnh được tối ưu hóa từ một bộ sưu tập các biểu tượng cờ SVG. Nó xử lý việc hiển thị dựa trên canvas, tính toán bố cục lưới và tạo các tệp ánh xạ CSS để hiển thị biểu tượng hiệu quả bằng cách sử dụng định vị nền (background positioning).

> **Lưu ý**: Lớp này chỉ dành riêng cho việc sử dụng nội bộ bên trong kho lưu trữ dự án `dxt-ui`.

## Các tính năng chính

- **Tự động đóng gói Sprite** — Kết hợp nhiều tệp SVG riêng lẻ thành một sprite `.webp` duy nhất được tối ưu hóa.
- **Tạo CSS động** — Tự động tạo các lớp tiện ích với các giá trị `background-position` chính xác cho mỗi lá cờ.
- **Bố cục lưới có thể cấu hình** — Cho phép tùy chỉnh kích thước cờ và số lượng cột trong hình ảnh kết quả.
- **Hiển thị bằng Canvas** — Sử dụng xử lý hình ảnh hiệu suất cao để chuyển đổi và thu phóng mượt mà.
- **Duy trì tỷ lệ khung hình** — Đảm bảo cờ được căn giữa trong các ô lưới của chúng trong khi vẫn duy trì tỷ lệ thiết kế ban đầu.

## Khởi tạo

Để khởi tạo trình tạo, hãy chỉ định thư mục nguồn và tỷ lệ đầu ra mong muốn.

**Tham số:**
- `dir: string` — Đường dẫn thư mục nơi đặt các biểu tượng cờ `.svg` nguồn.
- `width: number` — Chiều rộng mục tiêu của một lá cờ trong sprite được tạo (mặc định: 96).
- `height: number` — Chiều cao mục tiêu của một lá cờ trong sprite được tạo (mặc định: 72).
- `columns: number` — Số lượng cột biểu tượng cần sắp xếp trong lưới sprite (mặc định: 12).

```typescript
import { DesignFlags } from '@dxtmisha/scripts'

const generator = new DesignFlags('assets/flags', 64, 48)
generator.make()
```

## Các phương thức

### Điều khiển

- `make(): Promise<void>` — Điều phối toàn bộ quy trình: đọc tệp, vẽ lên canvas, lưu hình ảnh và ghi tệp CSS.

### Thông tin

- `getLines(): number` — Tính toán tổng số hàng cần thiết trong lưới sprite dựa trên số lượng tệp và giới hạn cột.

## Các thao tác (Operations)

### Quy trình tạo

Khi `make()` được thực thi, lớp sẽ thực hiện các bước sau:
1. **Khám phá**: Quét thư mục nguồn để tìm các tệp `.svg` và khởi tạo kích thước lưới.
2. **Tính toán bố cục**: Xác định khoảng cách lát gạch (tiling) và lề căn giữa cho các kích thước cờ cụ thể.
3. **Vẽ Canvas**: Tải từng hình ảnh theo chu kỳ và vẽ nó lên canvas sprite tại tọa độ lưới đã tính toán.
4. **Thu thập dữ liệu**: Ghi lại tên và tọa độ của mỗi lá cờ để xây dựng dữ liệu ánh xạ.
5. **Xuất tài nguyên**: 
    - Lưu nội dung canvas dưới dạng hình ảnh `webp` trong thư mục `assets`.
    - Tạo tệp `flags.css` với các định nghĩa biến gốc và các lớp sửa đổi `--[name]` riêng lẻ.

### Triển khai kiểu dáng (Style Implementation)

CSS được tạo sử dụng một lớp tập trung `.ui-sys-flags` lưu trữ các biến kích thước và liên kết hình ảnh nền. Các bộ sửa đổi riêng lẻ (ví dụ: `.ui-sys-flags--vn`) sau đó cập nhật `background-position` để tách biệt các biểu tượng cụ thể, giảm thiểu các lệnh vẽ lại của trình duyệt và các yêu cầu HTTP.
