Astro

Astro 默认不携带任何 JavaScript，并且在服务器端将所有组件渲染为静态 HTML。Wink Web 组件必须通过客户端的 <script> 标签加载。Astro 的岛屿架构使这变得非常简单。

@wink/elements npm package 安装并加载带有 TypeScript 类型的 CDN 包。

安装

npm install @wink/elements

在共享布局中加载

将加载脚本添加到基础布局中，以便在每个页面上运行：

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My Site</title>
  </head>
  <body>
    <slot />

    <script>
      import { load } from '@wink/elements';
      load({ clientId: import.meta.env.PUBLIC_WINK_CLIENT_ID });
    </script>
  </body>
</html>

在页面中使用

由于 Astro 组件是服务器渲染的，<wink-*> 标签会作为静态 HTML 输出。CDN 脚本会在页面浏览器加载时注册自定义元素：

---
import Layout from '../layouts/Layout.astro';
---

<Layout>
  <main>
    <wink-content-loader layout="HOTEL" id="YOUR_LAYOUT_ID" />
    <wink-lookup />
  </main>
</Layout>

在框架组件（岛屿）内使用

如果你在使用 React、Vue 或 Svelte 岛屿并搭配 Wink，按上述方式在布局中加载 @wink/elements，然后在岛屿组件内正常使用 <wink-*> 标签 —— 自定义元素会在岛屿水合时注册完成。

// src/components/HotelCard.tsx (React island)
export default function HotelCard({ layoutId }: { layoutId: string }) {
  // load() 已由布局调用 —— 这里渲染安全
  return <wink-content-loader layout="HOTEL" id={layoutId} />;
}

---
import HotelCard from '../components/HotelCard.tsx';
---
<HotelCard client:load layoutId="YOUR_LAYOUT_ID" />

环境变量

Astro 只会将以 PUBLIC_ 前缀开头的变量暴露给浏览器：

PUBLIC_WINK_CLIENT_ID=your-client-id