可嵌入小组件

创建和管理适用于您网站的可嵌入小组件。小组件是针对单个占星功能的现成 UI 组件：出生数据表单、月亮日历、每日运势星座选择器等。您可以在仪表板中或通过本 API 进行配置，然后用一个脚本标签将其放置到任意页面上。

两套 API，两种密钥

管理 API（/api/widgets）用于创建和配置小组件，使用您的常规 API 密钥。
小组件 API（/api/widget-api）由 SDK 从访客浏览器中调用，使用小组件自己的密钥。该密钥仅限于对应的那一个小组件，因此可以安全地写在页面中。

小组件类型

您可以创建哪些小组件类型，取决于您组织已启用的模块。GET /api/widgets/options 会列出对您可用的类型。

类型	描述	所需模块
`natal`	出生数据表单，含星盘、天体位置和相位	`module:natal`
`synastry`	两份出生数据表单、合盘星盘和交互相位	`module:natal`, `module:synastry`
`transit`	出生数据加行运时刻，双轮星盘	`module:natal`, `module:transits`
`composite`	两份出生数据表单、组合中点盘	`module:natal`, `module:composite`
`moonphase`	当前月相及照明比例	`module:moon`
`daily-horoscope`	星座选择器与今日运势	`module:daily-report`
`numerology`	姓名与出生日期表单，含核心数字	`module:numerology`
`compatibility`	两个人的数字学相容性得分	`module:numerology`, `module:compatibility`
`moon-calendar`	月度日历，含月相、月出和月落	`module:moon`

小组件管理

所有管理端点均采用 JSON:API 格式，资源类型为 widget。

列出小组件

bash

curl "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key"

获取小组件

bash

curl "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

创建小组件

bash

curl -X POST "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "widget",
      "attributes": {
        "name": "My Natal Chart Widget",
        "widgetType": "natal",
        "allowedDomains": ["example.com", "www.example.com"],
        "customization": {
          "language": "en",
          "layout": { "variant": "card" },
          "colors": {
            "primary": "#5b2d8e",
            "background": "#ffffff",
            "text": "#1a1a1a"
          },
          "widgetOptions": {
            "showAspects": true,
            "showPoints": true,
            "showHouses": true,
            "chartSize": "medium",
            "theme": "auto"
          }
        }
      }
    }
  }'

创建请求的响应是唯一一次返回完整小组件 API 密钥（apiKey）的机会。请妥善保存，或稍后重新生成；其他所有响应只会包含 apiKeyPrefix。

json

{
    "data": {
        "type": "widget",
        "id": "wgt_abc123",
        "attributes": {
            "name": "My Natal Chart Widget",
            "widgetType": "natal",
            "customization": { "...": "as sent, merged with defaults when served" },
            "allowedDomains": ["example.com", "www.example.com"],
            "enabled": true,
            "createdAt": "2026-06-15T12:00:00.000Z",
            "updatedAt": "2026-06-15T12:00:00.000Z",
            "apiKey": "wk_live_...",
            "apiKeyPrefix": "wk_live_abc1"
        },
        "relationships": {
            "organization": { "data": { "type": "organization", "id": "org_..." } }
        }
    }
}

更新小组件

PATCH 接受 name、enabled、allowedDomains 和 customization 的任意子集。自定义配置会被整体替换，因此请发送完整的对象。

bash

curl -X PATCH "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "widget",
      "id": "wgt_abc123",
      "attributes": {
        "name": "Updated Widget Name",
        "customization": { "language": "nl" }
      }
    }
  }'

删除小组件

bash

curl -X DELETE "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

重新生成小组件 API 密钥

bash

curl -X POST "https://api.astroapi.cloud/api/widgets/wgt_abc123/regenerate-key" \
  -H "X-Api-Key: your-api-key"

返回带有全新 apiKey 的小组件。请用新密钥更新您网站上的嵌入代码；小组件 ID 保持不变。

可用小组件选项

bash

curl "https://api.astroapi.cloud/api/widgets/options" \
  -H "X-Api-Key: your-api-key"

json

{
    "data": {
        "type": "widget-options",
        "id": "org_...",
        "attributes": {
            "plan": "Gold",
            "organizationModules": ["module:natal", "module:moon"],
            "availableWidgetTypes": ["natal", "moonphase", "moon-calendar"],
            "features": {
                "canRemoveBranding": false,
                "canUseCustomLogo": false,
                "canUseCustomCss": false,
                "maxDomains": 5
            },
            "allWidgetTypes": [
                {
                    "id": "natal",
                    "name": "Natal Chart",
                    "requiredModules": ["module:natal"],
                    "displayOptions": { "showChartSize": true, "showAspects": true, "showPoints": true }
                }
            ]
        }
    }
}

计划功能

功能	描述
`canRemoveBranding`	允许将 `branding.showPoweredBy` 设为 `false`
`canUseCustomLogo`	允许设置 `branding.logoUrl` 和 `branding.companyName`
`canUseCustomCss`	`customCss` 会随小组件一并下发
`maxDomains`	每个小组件的 `allowedDomains` 最大数量，或 `"unlimited"`

自定义对象

所有字段均为可选；未填写的部分会在下发小组件时用下面的默认值补全。颜色为 CSS 颜色字符串，尺寸为以像素为单位的数字。

json

{
    "colors": {
        "primary": "#6366f1",
        "secondary": "#8b5cf6",
        "background": "#ffffff",
        "surface": "#f8fafc",
        "text": "#1e293b",
        "textSecondary": "#64748b",
        "border": "#e2e8f0",
        "error": "#ef4444",
        "success": "#22c55e",
        "accent": "#f59e0b"
    },
    "fonts": {
        "family": "Inter, system-ui, sans-serif",
        "sizeBase": 16,
        "sizeHeading": 24,
        "sizeSmall": 12,
        "weightNormal": 400,
        "weightBold": 600
    },
    "borders": { "radius": 8, "width": 1, "style": "solid" },
    "spacing": { "padding": 16, "margin": 16 },
    "shadows": { "preset": "sm", "custom": null },
    "layout": { "variant": "card" },
    "interaction": {
        "tooltipEnabled": true,
        "animationsEnabled": true,
        "clickThroughEnabled": false,
        "clickThroughUrl": null
    },
    "chartSettings": {},
    "labels": {},
    "language": "en",
    "branding": { "showPoweredBy": true, "logoUrl": null, "companyName": null },
    "customCss": null,
    "widgetOptions": {
        "showAspects": true,
        "showPoints": true,
        "showHouses": true,
        "chartSize": "medium",
        "theme": "light"
    },
    "numerologyOptions": {
        "showLifePath": true,
        "showExpression": true,
        "showSoulUrge": true,
        "showPersonality": true,
        "showBirthday": true,
        "showPersonalCycles": true
    },
    "dailyHoroscopeOptions": { "autoRefresh": false },
    "moonCalendarOptions": {
        "showMoonrise": true,
        "showMoonset": true,
        "showIllumination": true,
        "showPhaseEmoji": true,
        "highlightFullMoon": true,
        "highlightNewMoon": true
    },
    "compatibilityOptions": {
        "showScore": true,
        "showDescription": true,
        "showLifePaths": true
    }
}

自定义字段

字段	类型	描述
`colors.*`	string	十种 CSS 颜色，以 CSS 变量的形式应用于小组件
`fonts.family`	string	CSS `font-family` 值
`fonts.sizeBase` / `sizeHeading` / `sizeSmall`	number	字号（像素）
`fonts.weightNormal` / `weightBold`	number	字重
`borders.radius` / `width`	number	像素；用于输入框、按钮和卡片布局
`borders.style`	string	`solid`、`dashed`、`dotted` 或 `none`
`spacing.padding` / `margin`	number	像素；卡片布局和紧凑布局使用 `padding`
`shadows.preset`	string	`none`、`sm`、`md`、`lg` 或 `xl`（卡片布局）
`shadows.custom`	string \| null	覆盖预设的 CSS `box-shadow`
`layout.variant`	string	参见布局变体
`interaction.tooltipEnabled`	boolean	行星行、相位行和日历日期上的悬停工具提示
`interaction.animationsEnabled`	boolean	入场动画；对偏好减少动态效果的访客始终关闭
`interaction.clickThroughEnabled`	boolean	将渲染出的星盘变为指向 `clickThroughUrl` 的链接
`interaction.clickThroughUrl`	string \| null	在新标签页中打开
`chartSettings`	object	叠加在默认星盘主题之上的局部星盘主题：各星座、天体点和相位的颜色、线宽、`showDegrees`、`showRetrograde` 等
`labels`	object	覆盖任意标签键；参见语言与标签
`language`	string	13 种受支持语言代码之一
`branding.showPoweredBy`	boolean	设为 `false` 需要 `canRemoveBranding`
`branding.logoUrl` / `companyName`	string \| null	需要 `canUseCustomLogo`
`customCss`	string \| null	为小组件注入到页面中；需要 `canUseCustomCss`
`widgetOptions.showAspects` / `showPoints`	boolean	在星盘下方显示相位表和位置表
`widgetOptions.showHouses`	boolean	在星盘上显示宫位编号
`widgetOptions.chartSize`	string \| number	`small`（300）、`medium`（450）、`large`（600）或以像素为单位的宽度
`widgetOptions.theme`	string	`light`、`dark`、`cosmic`、`custom` 或 `auto`
`numerologyOptions.*`	boolean	数字学小组件显示哪些数字
`dailyHoroscopeOptions.autoRefresh`	boolean	预留
`moonCalendarOptions.*`	boolean	日历日期显示哪些细节，以及高亮哪些月相
`compatibilityOptions.*`	boolean	得分环、描述文字和生命灵数

布局变体

值	描述
`card`	带边框的面板，使用配置的圆角、内边距和阴影（默认）
`compact`	内边距减半、字号略小，适合侧边栏
`full`	横向铺满，仅保留上下内边距
`minimal`	完全没有外框，一切样式继承自页面

主题

light、dark 和 cosmic 是面板与边框的固定配色。auto 默认使用浅色配色，当访客的系统偏好深色时切换为深色配色。custom 不设置任何配色，完全依赖您的 colors。在所有主题中，您设置的十个 colors 都优先于配色方案。

语言与标签

SDK 内置了 en、nl、de、fr、es、es-419、it、pt、pt-BR、tr、ru、ja 和 zh-CN 的标签。地区变体中未覆盖的内容会回退到其基础语言。labels 在所选语言之上覆盖单个字符串，例如：

json

{ "language": "nl", "labels": { "calculateButton": "Bereken mijn horoscoop" } }

语言也可以按页面设置：脚本标签上的 data-lang="de"，或页面 URL 中的 ?lang=de，二者都优先于已保存的语言。

嵌入小组件

SDK 由 https://widgets.astroapi.cloud/sdk.js 提供。仪表板的嵌入标签页会生成下面两段代码，并自动填入您的 ID。

自动初始化

html

<script
  src="https://widgets.astroapi.cloud/sdk.js"
  data-widget-id="wgt_abc123"
  data-api-key="your-widget-api-key"
  data-api-url="https://api.astroapi.cloud"
></script>
<div id="astro-widget-wgt_abc123"></div>

可选属性：data-container="#my-element" 可将小组件渲染到默认 div 以外的位置，data-lang="nl" 可覆盖语言。

编程方式

html

<script src="https://widgets.astroapi.cloud/sdk.js"></script>
<div id="my-widget"></div>
<script>
  AstroWidget.create({
    widgetId: "wgt_abc123",
    apiKey: "your-widget-api-key",
    apiBaseUrl: "https://api.astroapi.cloud",
    container: "#my-widget",
    language: "nl",
    defaultValues: {
      dateTime: "1990-06-15T14:30:00",
      latitude: 52.3676,
      longitude: 4.9041,
      timezone: "Europe/Amsterdam",
      placeName: "Amsterdam"
    },
    onLoad: () => console.log("Widget loaded"),
    onResult: (result) => console.log("Result", result),
    onError: (err) => console.error(err)
  }).then((widget) => {
    // widget.type, widget.getResult(), widget.setBirthData(), widget.calculate(), widget.destroy()
  });
</script>

defaultValues.dateTime 按 timezone 中的当地时间解读；表单会原样显示您给出的时间。

实例 API

成员	描述
`id`, `type`	小组件 ID 和小组件类型
`getResult()`	最新的结果，无论是访客计算的还是 `calculate()` 计算的
`setBirthData(data)`	`calculate()` 所使用的出生数据
`calculate()`	通过脚本执行计算并显示结果。支持 `natal`、`transit`（按当前时刻）、`moonphase` 和 `moon-calendar`（当月）；其他类型需要访客输入，调用会以错误 reject
`destroy()`	卸载小组件

对于所有小组件类型，小组件每显示一次结果都会触发 onResult。AstroWidget.version 会返回 SDK 的构建版本。

域名

allowedDomains 限制小组件 API 密钥可以在哪些位置使用，校验依据是浏览器请求的 Origin。支持子域名通配符（*.example.com），并且 www. 会被视同为主域名。列表为空时，密钥在任何域名上都能使用，因此请在发布嵌入代码之前先填好它。

小组件 API

以下是 SDK 代表访客调用的端点。列出它们是为了方便您针对某个小组件构建自己的前端；SDK 是参考实现。

认证方式是在 X-Api-Key 中传入小组件 API 密钥。仪表板中的预览则改用会话。

端点	请求体	小组件类型
`GET /api/widget-api/config/:widgetId`	—	任意类型；公开端点，返回 `widgetType` 和合并后的 `customization`
`POST /api/widget-api/natal/:widgetId`	`{ birthData }`	`natal`
`POST /api/widget-api/synastry/:widgetId`	`{ person1, person2 }`	`synastry`
`POST /api/widget-api/transit/:widgetId`	`{ birthData, transitDateTime, transitTimezone? }`	`transit`
`POST /api/widget-api/composite/:widgetId`	`{ person1, person2 }`	`composite`
`POST /api/widget-api/moonphase/:widgetId`	`{ date?, latitude? }`	`moonphase`
`POST /api/widget-api/daily-horoscope/:widgetId`	`{ zodiacSign, date? }`	`daily-horoscope`
`POST /api/widget-api/numerology/:widgetId`	`{ fullName, birthYear, birthMonth, birthDay }`	`numerology`
`POST /api/widget-api/compatibility/:widgetId`	`{ person1, person2 }`（姓名和出生日期各字段）	`compatibility`
`POST /api/widget-api/moon-calendar/:widgetId`	`{ year, month, latitude?, longitude?, timezone? }`	`moon-calendar`
`GET /api/widget-api/geocoding/search/:widgetId?q=&limit=&lang=`	—	任意类型；用于出生数据表单的地点搜索

星盘类小组件的 birthData、person1 和 person2 形如 { dateTime, latitude, longitude, timezone, placeName? }，其中 dateTime 是 timezone 中的当地时间（1990-06-15T14:30:00）。为其他类型的小组件调用某个端点会返回 400；已停用的小组件返回 403；来自 allowedDomains 之外域名的请求返回 403 DOMAIN_NOT_ALLOWED。

后续步骤

将小组件添加到您的网站 — WordPress、Wix、Squarespace、Shopify 和 Webflow 的分步说明
星盘渲染 — chartSettings 接受的主题对象
AI 聊天机器人 — 聊天机器人有自己的可嵌入小组件

可嵌入小组件 ​

小组件类型 ​

小组件管理 ​

列出小组件 ​

获取小组件 ​

创建小组件 ​

更新小组件 ​

删除小组件 ​

重新生成小组件 API 密钥 ​

可用小组件选项 ​

计划功能 ​

自定义对象 ​

自定义字段 ​

布局变体 ​

主题 ​

语言与标签 ​

嵌入小组件 ​

自动初始化 ​

编程方式 ​

实例 API ​

域名 ​

小组件 API ​

后续步骤 ​

可嵌入小组件

小组件类型

小组件管理

列出小组件

获取小组件

创建小组件

更新小组件

删除小组件

重新生成小组件 API 密钥

可用小组件选项

计划功能

自定义对象

自定义字段

布局变体

主题

语言与标签

嵌入小组件

自动初始化

编程方式

实例 API

域名

小组件 API

后续步骤