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

<Meta title='@dxtmisha/vi/figma-code/Classes/FigmaStorage - Làm việc với bộ nhớ tài liệu'/>

# Lớp `FigmaStorage`

Một lớp bọc cấp cao cho các API `setPluginData` và `getPluginData` của Figma. Nó cho phép lưu trữ dữ liệu có cấu trúc trực tiếp trong tài liệu Figma, theo cách toàn cục (`figma.root`) hoặc đính kèm với các node cụ thể. Dữ liệu này được chia sẻ giữa tất cả người dùng cộng tác trên tệp.

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

- **Lưu trữ theo node cụ thể** — Dữ liệu có thể được liên kết với bất kỳ node Figma nào (Frame, Group, v.v.) hoặc gốc của tài liệu.
- **Truy cập chung** — Không giống như bộ nhớ client, dữ liệu plugin được lưu bên trong tệp `.fig` và được đồng bộ hóa giữa tất cả người dùng.
- **Quản lý thực thể** — Lớp sử dụng cơ chế lưu tạm nội bộ để đảm bảo rằng các lệnh gọi lặp lại cho cùng một khóa trên cùng một node sẽ trả về cùng một thực thể.
- **Tự động tuần tự hóa** — Xử lý việc chuyển đổi JSON cho các cấu trúc dữ liệu phức tạp một cách minh bạch.

## Khởi tạo

Truy cập một thực thể bằng cách sử dụng các phương thức tĩnh. Bạn có thể cung cấp một node gốc hoặc một ID node.

```typescript
import { FigmaStorage } from '@dxtmisha/figma-code'

// Lấy thực thể cho toàn bộ tài liệu
const globalStorage = FigmaStorage.getInstance<object>('app-settings')

// Lấy thực thể cho một node cụ thể bằng ID
const nodeStorage = await FigmaStorage.getInstanceById<string>('element-name', '1:123')
```

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

### Truy cập dữ liệu

Các phương thức để quản lý dữ liệu được lưu trữ trong tài liệu.

- `get(defaultValue?: T | (() => T)): T | undefined` — Truy xuất dữ liệu. Thiết lập giá trị mặc định nếu bộ nhớ đang trống.
- `set(value?: T | (() => T)): T | undefined` — Cập nhật dữ liệu và trả về giá trị mới.
- `remove(): this` — Xóa dữ liệu plugin cho khóa đã chỉ định trên node.

### Quản lý thực thể (Tĩnh)

Các phương thức để truy xuất các thực thể của lớp.

- `static getInstance<T>(name: string, item: UiFigmaNode): FigmaStorage<T>` — Trả về một thực thể cho một node cụ thể.
- `static getInstanceById<T>(name: string, id?: string): Promise<FigmaStorage<T>>` — Lấy một thực thể một cách bất đồng bộ bằng ID node.
