跳转到内容

@astrojs/ react

Astro 集成 为你的 React 组件实现渲染和客户端水合。

Astro 包含了一个 astro add 命令,用于自动设置官方集成。如果你愿意,可以改为手动安装集成

要安装 @astrojs/react,请在你的项目目录下运行以下命令并根据提示操作:

终端窗口
npx astro add react

如果你遇到任何问题,请随时在 GitHub 上向我们报告并尝试下面的手动安装步骤。

首先,安装 @astrojs/react 包:

终端窗口
npm install @astrojs/react

大多数包管理器也会安装相关的对等依赖。如果在启动 Astro 时看到 Cannot find package 'react'(或类似)的警告,你需要安装 reactreact-dom

终端窗口
npm install react react-dom @types/react @types/react-dom

然后,使用 integrations 属性将此集成应用到你的 astro.config.* 文件中:

astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
export default defineConfig({
// ...
integrations: [react()],
});

然后添加下面的代码到 tsconfig.json 文件中。

tsconfig.json
{
"extends": "astro/tsconfigs/strict",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist"],
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "react"
}
}

要在 Astro 中使用你的第一个 React 组件,请前往我们的UI 框架文档。你将了解:

  • 📦 框架组件如何被加载,
  • 💧 客户端水合选项,以及
  • 🤝 有机会将不同的框架混合和嵌套

@astrojs/react 集成提供了两个函数:withState()getActionState() 来与 Astro Actions 一起使用。

这些函数与 React 的 useActionState() 钩子一起使用,用于在触发表单提交时读取和更新客户端状态。

类型: (action: FormFn<T>) => (state: T, formData: FormData) => FormFn<T>

添加于: @astrojs/react@4.4.0

你可以将 withState() 和你想要触发的 action 传递给 React 的 useActionState() hook 作为表单 action 函数。下面的示例将 like action 传递给增加计数器,并将初始状态设为 0 个点赞。

Like.tsx
import { actions } from 'astro:actions';
import { withState } from '@astrojs/react/actions';
import { useActionState } from "react";
export function Like({ postId }: { postId: string }) {
const [state, action, pending] = useActionState(
withState(actions.like),
{ data: 0, error: undefined }, // 初始点赞和错误
);
return (
<form action={action}>
<input type="hidden" name="postId" value={postId} />
<button disabled={pending}>{state.data} ❤️</button>
</form>
);
}

withState() 函数会将 action 的类型与 React 的期望匹配,并保留用于渐进增强的元数据,使其即使在用户设备禁用 JavaScript 时也能正常工作。

类型: (context: ActionAPIContext) => Promise<T>

添加于: @astrojs/react@4.4.0

你可以在 action handler 中通过 getActionState() 访问 useActionState() 存储的状态。它接受 Astro API 上下文,并可选地对结果应用类型。

下面的示例获取计数器中当前的点赞数的值,类型为 number,以便创建一个递增的 like action:

actions.ts
import { defineAction, type SafeResult } from 'astro:actions';
import { z } from 'astro:schema';
import { getActionState } from '@astrojs/react/actions';
export const server = {
like: defineAction({
input: z.object({
postId: z.string(),
}),
handler: async ({ postId }, ctx) => {
const { data: currentLikes = 0, error } = await getActionState<SafeResult<any, number>>(ctx);
// 处理错误
if (error) throw error;
// 写入数据库
return currentLikes + 1;
},
})
};

当你在同一个项目中使用多个 JSX 框架(React、Preact、Solid)时,Astro 需要确定每个组件应该使用哪个 JSX 框架的转换器(transformation)。如果你只向你的项目中添加了一个 JSX 框架集成,那么就不需要额外的配置。

使用 include(必填)和 exclude(可选)配置选项来指定哪些文件属于哪个框架。为你使用的每个框架提供一个文件或/和文件夹数组。通配符可用于包含多个文件路径。

我们建议将每个框架的组件放在同一个文件夹中(例如 /components/react//components/solid/),以便更容易地指定你的包含内容,但这不是必需的:

astro.config.mjs
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';
export default defineConfig({
// 启用多个框架来支持所有不同类型的组件。
// 如果你只使用一个 JSX 框架,则不需要 `include`!
integrations: [
preact({
include: ['**/preact/*'],
}),
react({
include: ['**/react/*'],
}),
solid({
include: ['**/solid/*'],
}),
],
});

从 Astro 组件传递给 React 组件的子元素将被解析为普通字符串,而不是 React 节点。

例如,下面的 <ReactComponent /> 只会接收一个子元素:

---
import ReactComponent from './ReactComponent';
---
<ReactComponent>
<div>one</div>
<div>two</div>
</ReactComponent>

如果你正在使用一个期望能传递多个子元素的库,例如将某些元素放置在不同的位置,你可能会遇到问题。

你可以设置实验性标志 experimentalReactChildren,告诉 Astro 将子元素始终作为 React 虚拟 DOM 节点传递给 React。虽然这样做会有一些运行时成本,但有助于保持兼容性。

你可以在 React 集成的配置中启用此选项:

astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
export default defineConfig({
// ...
integrations: [
react({
experimentalReactChildren: true,
}),
],
});

默认情况下,Astro 会流式传输 React 组件的输出。但是,你可以通过启用 experimentalDisableStreaming 选项来禁用该行为。这对于为不能很好地与流式传输一起使用的库(如某些 CSS-in-JS 解决方案)提供支持来说,特别有用。

要禁用你项目中的所有 React 组件的流式传输,请使用 experimentalDisableStreaming: true 来配置 @astrojs/react

astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
export default defineConfig({
// ...
integrations: [
react({
experimentalDisableStreaming: true,
})
]
});

更多集成

UI 框架

SSR 适配器

其他集成

贡献 社区 赞助