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, 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, mã: GitHub.

Cài đặt

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

<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:

npm install @astroway/ui@alpha

import '@astroway/ui';               // усі елементи
import '@astroway/ui/natal-wheel';   // або один

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.

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:

<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.

<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. Khóa bí mật aw_ bị từ chối trước khi yêu cầu được thực hiện.

<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.

'use client';
import '@astroway/ui/natal-wheel';
import '@astroway/ui/jsx'; // типи для тегів <aw-*> у TypeScript

export default function Chart({ chart }: { chart: unknown }) {
  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ữ, 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.