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

<Meta title='@dxtmisha/vi/functional/# Hook làm việc với API'/>

# Hook làm việc với API

Một tập hợp các công cụ để tương tác hiệu quả với backend, được tích hợp hoàn toàn với **Vue 3 (Composition API)**.

## Đặc điểm

Nhiệm vụ chính của các công cụ này là tự động hóa các tác vụ thông thường: theo dõi trạng thái tải (`loading`), xử lý lỗi và đồng bộ hóa dữ liệu giữa các phần khác nhau của giao diện. Tất cả các hook đều hỗ trợ các tham số phản hồi, cho phép tạo ra các yêu cầu động tự động cập nhật khi các bộ lọc đầu vào hoặc đường dẫn thay đổi.

## Các công cụ hiện có

- `useApiRef` — Truy xuất dữ liệu phản hồi (GET) với tính năng tự động chạy và lưu trữ trong `ref`.
- `useApiRequest` — Hook cơ bản để thực hiện thủ công bất kỳ yêu cầu HTTP nào (trả về phương thức `send`).
- `useApiPost / Put / Delete` — Các lớp vỏ chuyên dụng cho các thay đổi (tạo, cập nhật, xóa).
- `useApiManagementRef` — Bộ điều phối toàn diện, kết hợp các yêu cầu GET, tìm kiếm, định dạng và thay đổi thành một chu kỳ duy nhất.

## Cách làm việc với chúng

Để hiển thị dữ liệu đơn giản, chỉ cần sử dụng `useApiRef`. Bạn không cần phải gọi hàm tải một cách thủ công — yêu cầu sẽ tự động được thực hiện ngay khi bạn truy cập vào thuộc tính `data`. Nếu đường dẫn API là một tham chiếu phản hồi (ref), hook sẽ tự theo dõi sự thay đổi của nó và tải dữ liệu mới.

```typescript
import { useApiRef } from '@dxtmisha/functional'

// Dữ liệu sẽ tự động tải khi truy cập vào data
const { data, loading } = useApiRef('api/profile')
```

Nếu bạn cần thực hiện một hành động dựa trên sự kiện (ví dụ: lưu biểu mẫu), các hook thay đổi (mutation) sẽ được sử dụng. Chúng trả về một phương thức `send` có thể được gọi trong trình xử lý sự kiện và một cờ `loading` để chặn các nút bấm.

```typescript
import { useApiPost } from '@dxtmisha/functional'

const { send, loading } = useApiPost('api/save')

const onSave = async () => {
  await send({ data: { name: 'Dxt' } })
}
```

## useApiManagementRef

Cách tiếp cận mạnh mẽ nhất là sử dụng `useApiManagementRef`. Đây là một trung tâm hoàn chỉnh để quản lý dữ liệu trong các giao diện phức tạp (ví dụ: trong bảng). Nó liên kết yêu cầu GET với các thay đổi: ngay khi bạn thực hiện thành công `sendDelete` hoặc `sendPost`, bộ điều phối sẽ tự gọi `reset()` cho danh sách chính và dữ liệu trên màn hình sẽ tự động cập nhật.

### Các khả năng chính:
- **Tự động hóa**: Đồng bộ hóa hoàn toàn giữa việc đọc và thay đổi dữ liệu.
- **Tích hợp**: Bao gồm chức năng tìm kiếm (`useSearchRef`) và định dạng (`useFormattersRef`).
- **Skeleton**: Hỗ trợ các trình giữ chỗ (placeholder) trong quá trình tải để ngăn chặn thay đổi bố cục.
- **Linh hoạt**: Cấu hình các đường dẫn và chuyển đổi riêng lẻ cho từng loại yêu cầu (GET, POST, PUT, DELETE).

```typescript
import { ref } from 'vue'
import { useApiManagementRef } from '@dxtmisha/functional'

const search = ref('')
const { 
  list, 
  sendPost, 
  sendDelete 
} = useApiManagementRef(
  { path: 'api/items' },      // Theo dõi GET
  undefined,                  // Bộ định dạng
  { columns: ['name'], value: search }, // Tìm kiếm trực tiếp
  { path: 'api/items/add' },  // Cấu hình POST
  undefined,
  { path: 'api/items/delete' } // Cấu hình DELETE
)

// Sau khi gọi sendDelete(), danh sách chính 'list' sẽ TỰ ĐỘNG cập nhật!
```

Kiến trúc này cho phép bạn mô tả logic làm việc với dữ liệu một cách khai báo, tập trung vào cấu hình yêu cầu thay vì quản lý thủ công các trạng thái tải và cập nhật danh sách.
