zp-figma-converter/README.md

Convert Figma designs to various code formats

# FIGMA - Figma Design to Code Converter

Công cụ chuyển đổi thiết kế Figma sang nhiều định dạng mã nguồn khác nhau, được viết bằng TypeScript.

## Cài đặt

### Cài đặt toàn cục từ npm

```bash
npm install -g zp-figma-converter
```

Sau khi cài đặt, bạn có thể sử dụng lệnh `figma` từ bất kỳ đâu trong terminal.

### Cài đặt từ mã nguồn

```bash
# Clone repository
git clone https://gitlab.zingplay.com/quangvd2/json2csd.git
cd json2csd

git checkout figma-converter

# Cài đặt dependencies
npm install

# Build project
npm run build

# Cài đặt toàn cục từ mã nguồn
npm link
```

## Cấu hình

1. Tạo file `.env` trong thư mục gốc của dự án của bạn:

```env
# Figma API Token - Bắt buộc
FIGMA_API_KEY=your_figma_api_key_here

# Figma API Base URL (tùy chọn)
FIGMA_API_BASE_URL=https://api.figma.com/v1
```

2. Cài đặt và cấu hình dotenv trong dự án của bạn:

```bash
npm install dotenv
```

3. Thêm đoạn code sau vào điểm khởi đầu của ứng dụng (ví dụ: index.js/ts):

```typescript
import * as dotenv from 'dotenv';
dotenv.config();
```

## Xây dựng

```bash
npm run build
```

## Sử dụng

### Cú pháp cơ bản

```bash
figma <output-format> <figma-file-key> [figma-node-id] [options]
```

### Chuyển đổi file Figma sang CSD (Cocos Studio)

```bash
figma-csd <figma-file-key>
```

### Chuyển đổi một node cụ thể của file Figma sang CSD

```bash
figma-csd <figma-file-key> <node-id>
```

### Chỉ định thư mục đầu ra

```bash
figma-csd <figma-file-key> -o ./my-output-dir
```

### Hiển thị thông tin chi tiết trong quá trình chuyển đổi

```bash
figma-csd <figma-file-key> -v
```

**Lưu ý**: Trước khi sử dụng, bạn cần:
1. Tạo file `.env` từ `.env.example`
2. Thêm Figma Access Token của bạn vào file `.env`

## Cấu trúc dự án

- `src/`: Thư mục chứa mã nguồn TypeScript
  - `figma/`: Chứa các thành phần liên quan đến API Figma
  - `converters/`: Chứa các bộ chuyển đổi sang các định dạng khác nhau
  - `utils/`: Tiện ích xử lý file, XML, etc.
- `output/`: Thư mục chứa file đầu ra
- `output/assets/`: Thư mục chứa hình ảnh được tải về từ Figma
- `dist/`: Thư mục chứa mã biên dịch

## Các định dạng đầu ra được hỗ trợ

- `csd`: Cocos Studio Document
- *Các định dạng khác sẽ được bổ sung trong tương lai*

## Chuyển đổi Figma sang CSD

### Các loại node Figma được hỗ trợ

- `RECTANGLE` → `ImageViewObjectData`
- `TEXT` → `TextObjectData`
- `FRAME` / `GROUP` → `PanelObjectData`
- `VECTOR` / `ELLIPSE` / `STAR` / `LINE` / `REGULAR_POLYGON` / `BOOLEAN` → `SpriteObjectData`
- Others → `SingleNodeObjectData`

### Cách lấy Figma Access Token

1. Đăng nhập vào tài khoản Figma của bạn
2. Truy cập Settings > Personal Access Tokens
3. Tạo token mới và lưu vào file `.env`

## Hướng dẫn mở rộng

### Thêm định dạng đầu ra mới

1. Tạo converter mới trong thư mục `src/converters/`
2. Đăng ký converter mới trong `FigmaConverter`
3. Cập nhật danh sách `SUPPORTED_FORMATS` trong file CLI
4. Cập nhật README với thông tin về định dạng mới

## Giấy phép

ISC