跳转到内容

组件与 Islands

Astro 中有两类容易混淆的组件:

  • Astro 组件,写在 .astro 文件里,适合 HTML-first 的 UI。
  • 框架组件,例如 React 或 Vue 组件,适合需要浏览器状态或浏览器 API 的局部。

这个区别很重要,因为导入一个组件并不意味着 Astro 会发送完整客户端应用。静态 UI 可以保持静态,需要交互的 UI 可以作为 island hydrate。

一个 Astro 组件包含 frontmatter 和模板:

---
const { title, tone = 'default' } = Astro.props;
---
<section class:list={['callout', `callout-${tone}`]}>
<h2>{title}</h2>
<slot />
</section>
<style>
.callout {
border: 1px solid var(--sl-color-gray-5);
border-radius: 0.5rem;
padding: 1rem;
}
</style>

frontmatter 在构建时或服务端运行,模板会变成 HTML。组件内样式默认会作用域化。

内容 wrapper、layout 区块、卡片、提示块、导航区域、metadata helper,以及不需要浏览器行为的 UI,都适合先用 Astro 组件。

Props 负责传数据,slots 负责传内容。

---
import Callout from '../components/Callout.astro';
---
<Callout title="默认快速" tone="info">
<p>Astro 先渲染 HTML,只 hydrate 你选择的部分。</p>
</Callout>

这个模式很适合文档:组件提供结构,页面仍然保持可读的内容。

当组件需要多个内容区域时,可以使用 named slots:

<FeatureCard>
<span slot="eyebrow">Routing</span>
<h2>文件变成 URL</h2>
<p>路由树直接体现在文件系统中。</p>
</FeatureCard>

不要把每个段落都变成组件。组件应该解决真实重复或让结构更清楚,而不是遮住内容本身。

当 UI 需要浏览器行为时,再使用框架组件:

  • combobox
  • 实时图表
  • 筛选面板
  • 拖拽交互
  • 媒体控制
  • 代码 playground
  • 登录后的应用小部件

Astro 可以通过集成使用 React、Vue、Svelte、Solid 等框架。一个项目可以使用多个框架,但这通常不是最简单的选择。每个框架都会带来依赖、约定和 bundle 成本。

框架组件只有加上 client directive 后,才会在浏览器中变成交互组件:

---
import SearchBox from '../components/SearchBox.jsx';
---
<SearchBox client:visible />

常见指令:

Directive行为适合场景
client:load尽快 hydrate首屏必须立即可用的控件
client:idle浏览器空闲时 hydrate不急着可用的小组件
client:visible进入视口时 hydrate页面下方的 demo 或 widget
client:media媒体查询匹配时 hydrate只在移动端或桌面端需要的交互
client:only只在客户端渲染无法服务端渲染的组件

选择满足体验要求的最轻指令。页面顶部的筛选器可能需要 client:load;几屏之后的示例通常更适合 client:visible。

Islands 架构让页面大部分保持静态,只把特定区域变成交互。不是让一个大应用接管整篇文档,而是在稳定 HTML 中放入小的 hydrated islands。

对于文档站,这很自然。读者和搜索引擎能先拿到内容,搜索、主题切换、复制按钮、playground 或图表可以独立加载。

这并不自动代表页面一定快。一个很大的 island 仍然会发送很多 JavaScript。Astro 的优势是边界清楚,你可以判断这段 JavaScript 是否值得。

需求优先选择
重复的静态页面区块Astro 组件
带统一 wrapper 的 Markdown 内容Astro 组件或 Starlight 组件
交互表单控件框架组件加 client:load 或 client:idle
页面下方的 demo框架组件加 client:visible
渲染时依赖 window 等浏览器 APIclient:only,或把浏览器代码放到 effect 中
全站应用状态重新判断 Astro 是否适合作为这个界面的中心
症状检查什么
React 组件显示了但点击没反应缺少 client:* directive
构建时报 window 未定义浏览器 API 在服务端渲染阶段执行了
页面发送太多 JavaScriptIsland 太大或 hydrate 太积极
组件样式意外影响其他页面本该 scoped 的样式写成了 global
每个区域都变成组件抽象遮住了内容,而不是简化内容