# Thành phần Web

`@astroway/ui` là một tập hợp các custom element thông thường: bạn chỉ cần đặt thẻ trên trang, và nó sẽ tự vẽ chính nó. Các biểu đồ được vẽ bởi [`@astroway/render`](https://www.npmjs.com/package/@astroway/render), cùng một mã code đứng sau `/v1/render/*`, vì vậy bánh xe trên trang của bạn sẽ khớp với bánh xe mà API trả về.

Gói đang ở **bản alpha** (`0.1.0-alpha.1`): tên các thuộc tính có thể thay đổi trước khi đạt phiên bản 1.0. Trang gói: [npm](https://www.npmjs.com/package/@astroway/ui), mã: [GitHub](https://github.com/astroway/astroway-ui).

## Cài đặt

Với CDN, không cần build:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@astroway/ui/dist/cdn/index.js"></script>
<aw-moon-phase></aw-moon-phase>
```

Hoặc với npm, nhập tất cả các phần tử hoặc chỉ những phần tử cần thiết. Gói hiện đang ở bản alpha, vì vậy hãy yêu cầu thẻ này:

```bash
npm install @astroway/ui@alpha
```

```js
```

## Ba cách cung cấp dữ liệu cho phần tử

**A. Dữ liệu của bạn.** Bạn thực hiện yêu cầu trên máy chủ của mình bằng khóa của riêng mình và chuyển JSON cho phần tử. Không có yêu trình nào từ trình duyệt của người truy cập, vì vậy bất kỳ khóa nào cũng được.

```js
document.querySelector('aw-natal-wheel').data = chart; // data з відповіді /v1/chart
```

Mẫu máy chủ có thể ghi cùng một JSON vào thuộc tính:

```php
<aw-natal-wheel data='<?= htmlspecialchars(json_encode($chart), ENT_QUOTES) ?>'></aw-natal-wheel>
```

**B. Không cần khóa.** Các phần tử trên `/v1/public/*` không cần khóa. Chúng chia sẻ ngân sách công khai của người truy cập, 30 đơn vị mỗi giờ từ một IP; khi ngân sách này hết, phần tử sẽ ghi lại cần chờ bao lâu.

```html
<aw-moon-phase lang="uk"></aw-moon-phase>
<aw-horoscope sign="leo" period="daily"></aw-horoscope>
<aw-tarot-spread spread="three-card"></aw-tarot-spread>
```

**C. Khóa cho trình duyệt.** Các phần tử trên các endpoint có khóa sẽ lấy khóa `pk_`, được tạo cho trang web của bạn: danh sách tên miền, hạn mức tín dụng và phạm vi endpoint là bắt buộc khi tạo. Xem phần "Khóa cho trình duyệt" trên trang [xác thực](/authentication/). Khóa bí mật `aw_` bị từ chối trước khi yêu cầu được thực hiện.

```html
<aw-natal-wheel api-key="pk_live_..." date="1990-05-15" time="14:30"
  latitude="50.45" longitude="30.52" timezone-offset="3"></aw-natal-wheel>
```

Đối với các phần tử này trong phạm vi khóa, cần có `chart`, và thêm `chinese/zodiac/animal` nếu bạn đặt `aw-chinese-sign`. Các tên miền được kiểm tra theo host: khóa cho `example.com` cũng hoạt động trên `http://example.com:8080`.

## React và Next.js

React 19 render custom elements trực tiếp. Có hai điểm khác biệt so với HTML thông thường:

- React lấy `key` về cho mình, vì vậy hãy truyền khóa dưới dạng `api-key`.
- Trên trang với server-side rendering, hãy truyền dữ liệu cho phương thức A dưới dạng chuỗi. React từ chối các đối tượng trong quá trình render trên server và không hiển thị chúng trong quá trình hydrate.

```tsx
'use client';

  return <aw-natal-wheel data={JSON.stringify(chart)} />;
}
```

Các module có thể được nhập trên máy chủ: thẻ xuất hiện như HTML thông thường và được render, ngay khi trình duyệt tải phần tử.

## Các phần tử

| Phần tử | Phương thức | Nguồn |
|---|---|---|
| `aw-natal-wheel` | A/C | `/v1/chart` |
| `aw-aspect-grid` | A/C | `/v1/chart` |
| `aw-planet-table` | A/C | `/v1/chart` |
| `aw-moon-phase` | A/B | `/v1/public/moon-phase` |
| `aw-planet-of-day` | A/B | `/v1/public/planet-of-day` |
| `aw-horoscope` | A/B | `/v1/public/horoscope/{daily,weekly,monthly}` |
| `aw-tarot-card`, `aw-tarot-spread` | A/B | `/v1/public/tarot/*` |
| `aw-sign-matrix` | A/B | `/v1/public/compatibility/matrix` |
| `aw-synastry-score` | A/B | `/v1/public/synastry` |
| `aw-chinese-sign` | A/C | `/v1/chinese/zodiac/animal` + `/v1/public/chinese/zodiac/texts` |

Các phần tử có một biểu đồ trên trang (bánh xe, bảng và lưới với cùng dữ liệu sinh) thực hiện một yêu cầu duy nhất cho tất cả.

`aw-aspect-grid` ở kích thước gốc có chiều rộng khoảng 560px. Trong cột hẹp hơn, nó sẽ thu nhỏ và nhãn của các khía cạnh sẽ trở nên nhỏ; thuộc tính `scroll` giữ nguyên kích thước đầy đủ với cuộn ngang.

## Ngôn ngữ, chủ đề, lỗi

- `lang` chấp nhận bất kỳ ngôn ngữ nào trong [21 ngôn ngữ](/languages/), mặc định lấy từ `<html lang>` của trang. Tên đến từ các bảng `localized` trong API.
- `theme="dark"` chuyển đổi giao diện; màu sắc được thiết lập bởi các biến CSS `--aw-accent`, `--aw-fg`, `--aw-bg`, `--aw-bg-soft`, `--aw-border`.
- Mỗi phần tử gửi sự kiện `aw-error` với `{ kind, message }`, trong đó `kind` là `error`, `rate-limited` hoặc `key`.