可嵌入小组件

创建和管理适用于您网站的可嵌入小组件。小组件提供现成的占星功能 UI 组件，只需一个脚本标签即可集成到任何网页中。

所需模块

所有小组件端点均需要为您的组织启用 module:embeddable-widgets 模块。

小组件类型

以下小组件类型根据您的活动模块可用：

类型	描述	所需模块
`natal`	交互式本命盘	`natal:calc`
`synastry`	合盘比较	`synastry:calc`
`transit`	行运星盘叠加	`transit:calc`
`composite`	复合关系盘	`composite:calc`
`moonphase`	月相显示	`moonphase:calc`
`daily-horoscope`	所有星座的每日运势	`module:daily-report`
`numerology`	数字学档案表单	`module:numerology`
`compatibility`	太阳星座相容性	`compatibility:calc`
`moon-calendar`	月度月亮日历	`moon-calendar:calc`

小组件管理

列出小组件

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"

创建小组件

小组件使用 JSON:API 格式创建：

bash

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

更新小组件

bash

curl -X PATCH "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "widgets",
      "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"

小组件响应

json

{
    "data": {
        "type": "widgets",
        "id": "wgt_abc123",
        "attributes": {
            "name": "My Natal Chart Widget",
            "widgetType": "natal",
            "allowedDomains": ["example.com", "www.example.com"],
            "embedCode": "<script src=\"https://cdn.astroapi.cloud/widget.js\" data-widget-id=\"wgt_abc123\"></script>",
            "customization": {
                "language": "en",
                "layout": "card",
                "colors": {
                    "primary": "#5b2d8e",
                    "background": "#ffffff",
                    "text": "#1a1a1a"
                },
                "widgetOptions": {
                    "showAspects": true,
                    "showPoints": true,
                    "showHouses": true,
                    "chartSize": 500,
                    "theme": "light"
                }
            },
            "createdAt": "2024-06-15T12:00:00Z",
            "updatedAt": "2024-06-15T12:00:00Z"
        }
    }
}

重新生成 API 密钥

重新生成小组件的嵌入式 API 密钥。如果密钥已泄露，请使用此功能：

bash

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

密钥轮换

重新生成密钥后，使用旧密钥的现有嵌入将立即停止工作。您无需更新嵌入代码——小组件 ID 保持不变。

可用小组件选项

根据您的活动模块获取您组织可用的小组件类型：

bash

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

响应

json

{
    "data": {
        "availableTypes": ["natal", "moonphase", "daily-horoscope"],
        "planFeatures": {
            "canRemoveBranding": false,
            "canUseCustomLogo": false,
            "canUseCustomCss": true,
            "maxDomains": 5
        }
    }
}

计划功能

功能	描述
`canRemoveBranding`	是否可以隐藏 AstroAPI 品牌标识
`canUseCustomLogo`	是否可以使用自定义 Logo 替代默认标识
`canUseCustomCss`	是否可以向小组件注入自定义 CSS
`maxDomains`	每个小组件允许的最大域名数量

自定义对象

customization 对象控制小组件的外观和行为：

json

{
    "colors": {
        "primary": "#5b2d8e",
        "secondary": "#a07cc5",
        "background": "#ffffff",
        "text": "#1a1a1a",
        "border": "#e0e0e0"
    },
    "fonts": {
        "family": "Inter, sans-serif",
        "size": "14px"
    },
    "borders": {
        "radius": "8px",
        "width": "1px"
    },
    "spacing": {
        "padding": "16px",
        "gap": "12px"
    },
    "shadows": {
        "card": "0 2px 8px rgba(0,0,0,0.1)"
    },
    "layout": "card",
    "interaction": {
        "allowUserInput": true,
        "showTooltips": true
    },
    "branding": {
        "showPoweredBy": true,
        "logoUrl": null
    },
    "language": "en",
    "customCss": ".astroapi-widget { font-weight: 500; }",
    "widgetOptions": {
        "showAspects": true,
        "showPoints": true,
        "showHouses": true,
        "chartSize": 500,
        "theme": "light"
    }
}

自定义字段

字段	类型	描述
`colors.primary`	string	主要强调色（十六进制）
`colors.secondary`	string	次要强调色（十六进制）
`colors.background`	string	小组件背景色（十六进制）
`colors.text`	string	主文本颜色（十六进制）
`colors.border`	string	边框颜色（十六进制）
`fonts.family`	string	CSS font-family 值
`fonts.size`	string	基础字体大小（CSS 值）
`borders.radius`	string	卡片和输入框的边框圆角（CSS 值）
`borders.width`	string	边框宽度（CSS 值）
`spacing.padding`	string	内部填充（CSS 值）
`spacing.gap`	string	元素间距（CSS 值）
`shadows.card`	string	卡片元素的 CSS box-shadow
`layout`	string	小组件布局样式（见下方）
`interaction.allowUserInput`	boolean	是否允许用户输入自己的出生数据
`interaction.showTooltips`	boolean	悬停时显示工具提示
`branding.showPoweredBy`	boolean	显示"Powered by AstroAPI"徽章
`branding.logoUrl`	string \| null	自定义 Logo URL（需要 `canUseCustomLogo`）
`language`	string	显示语言代码
`customCss`	string \| null	自定义 CSS 注入（需要 `canUseCustomCss`）
`widgetOptions.showAspects`	boolean	在星盘上显示相位线
`widgetOptions.showPoints`	boolean	在星盘上显示行星符号
`widgetOptions.showHouses`	boolean	在星盘上显示宫位分割
`widgetOptions.chartSize`	number	星盘大小（像素）
`widgetOptions.theme`	string	颜色主题（`"light"` 或 `"dark"`）

布局选项

值	描述
`compact`	最小空间，适合侧边栏
`card`	带阴影的圆角卡片（默认）
`full`	全宽，无边框
`minimal`	无背景，无边框

嵌入小组件

创建小组件后，从响应中复制 embedCode 并粘贴到您网站的 HTML 中：

html

<!-- Place this where you want the widget to appear -->
<div id="astroapi-widget-container"></div>

<!-- Load the widget script -->
<script
    src="https://cdn.astroapi.cloud/widget.js"
    data-widget-id="wgt_abc123">
</script>

域名白名单

小组件仅在 allowedDomains 中列出的域名上加载。请确保添加您计划嵌入小组件的所有域名（包括 www 变体）。

可嵌入小组件 ​

小组件类型 ​

小组件管理 ​

列出小组件 ​

获取小组件 ​

创建小组件 ​

更新小组件 ​

删除小组件 ​

小组件响应 ​

重新生成 API 密钥 ​

可用小组件选项 ​

响应 ​

计划功能 ​

自定义对象 ​

自定义字段 ​

布局选项 ​

嵌入小组件 ​

可嵌入小组件

小组件类型

小组件管理

列出小组件

获取小组件

创建小组件

更新小组件

删除小组件

小组件响应

重新生成 API 密钥

可用小组件选项

响应

计划功能

自定义对象

自定义字段

布局选项

嵌入小组件