# @aura3d/react 中文文档

规范地址：https://npmcn.com/package/%40aura3d/react/

版本：4\.7\.0
npm 元数据更新时间：2026-10-31T13:50:03.741Z
中文译文更新时间：2026-10-31T14:56:19.267Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aura3d/react
原文对照：https://npmcn.com/package/%40aura3d/react/?lang=original
项目主页：https://aura3d.auraone.ai/
源码仓库：https://github.com/auraoneai/aura3d

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：60.6 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^19\.0\.0 \|\| ^18\.0\.0，@aura3d/engine ^4\.7\.0
- 首次发布：2026-06-06T02:14:34.310Z
- 最新版本发布：2026-10-31T13:39:51.235Z
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

用于安装带有类型资产、相机、灯光、效果和产品查看器场景构建器的Aura3D场景的React组件和帮助器。

## 安装

```sh
npm install @aura3d/react
```

也可以使用：`pnpm add @aura3d/react`、`yarn add @aura3d/react`、`bun add @aura3d/react`

## README

# @aura3d /反应

`@aura3d/react` 拥有用于安装Aura3D场景的React组件和助手 与键入资产，相机，灯光，效果和产品查看器场景构建器。

## 公共API

-   `AuraCanvas`：挂载的React画布组件 `createAuraApp`,向前 诊断/选项，并在卸载时处理应用程序。
-   `Scene`：背景、相机、时间轴等的说明性场景包装 诊断选项。
-   `Model`类型模型节点声明 `AuraAssetRef<"model">`.
-   `Camera`：轨道，多利，跟随，或透视相机声明。
-   `Lights`：工作室，环境，方向和点光声明。
-   `Effect`：雾、花、雨的效果声明。
-   `buildSceneFromChildren`：将支持的React子节点转换为 `AuraSceneBuilder`.
-   `productViewerScene`：用于类型资产产品查看器的方便构建器 现场。
-   `useAuraApp` / `AuraAppContext`：安装 `AuraApp` (未定义,直到 山)。来检测“canvas外” `useAuraApp() !== undefined`.
-   `useAuraFrame(callback, priority?)`：游戏循环优先顺序 扇形分布在一个共享上 `app.onFrame` 订阅，在卸载时已清理。
-   `AuraCanvas` 事件道具(`onPointerDown/Move/Up`， `onHover`): canvas-level 具有卸载清理功能的DOM侦听器。搭配 `eventInteractionNodes(target)` 因此，F4拾取堆栈被占用- DOM处理程序单独不拾取。
-   `createAuraAssetResource` / `useAuraAsset` / `resourceForDescriptors`： 悬架兼容的资产边界 `preloadAll` 语义 （每个记录ok/失败的证据；失败抛出到错误边界）。 `<Model suspendOnLoad fallback>` 在类型资产预加载时挂起。
-   Drei-pattern配方（测试片段，而不是深度，也不是奇偶校验）： `cameraControlsRecipe`， `environmentPresetRecipe`， `transformGizmoRecipe`.
-   `R3F_TO_AURA_MIGRATION_TABLE`： R3F→auracanva映射的进口商。

## 状态:实验

在beat-three.js PRD （WP-K.6）中审计。测试内容：场景构建来源 子节点、框架调度程序、资产资源、食谱和迁移表 （`tests/unit/react-adapter/`的渲染树 `AuraCanvas` (一个帆布; 子节点在应用提供商内部渲染；声明性节点不添加DOM)。固定 在那次审计中，孩子们经常被解读为场景，但从来没有渲染过，所以 `useAuraFrame`， `useAuraApp` 和 `<Model suspendOnLoad>` 在一个 `AuraCanvas` 从来没有跑;应用程序会被销毁并重新创建 父类用内联子类、处理程序或内联 `onReady`. `AuraCanvas` 现在只有当建成的场景， `diagnostics`， `pixelRatio`， `autoStart` 或者 `resize` 改变。

还没被证实，所以包裹还在 `experimental`：挂载、处理和监听 在一个真实的浏览器中清理（需要一个远程的剧作家收据），React StrictMode 双挂载和服务器渲染挂载场景。

## R3F迁移说明

`R3F_TO_AURA_MIGRATION_TABLE` 将习惯的R3F映射到覆盖的aurcanvas 表面(画布，网格/模型，灯光，相机，效果， `useFrame`， `useThree`， `useLoader`/悬念，网格事件，drei轨道控制/环境/ TransformControls)。这是一个映射，而不是一个r3f奇偶声明 （`R3F_MIGRATION_NOT_PARITY`）. 三公司迁移实验室检测 `@react-three/fiber` / `@react-three/drei` 源和点在这里，和 文档CSS2D/CSS3D手动映射(`CSS2D_CSS3D_MANUAL_MAP`）。

## 包边

这个包包装了根 `@aura3d/engine` React应用的公共API。它 不能替换类型化的资产管道：模型道具应该使用生成的 `assets.name` 引用，而不是原始的GLB url或猜测的资产id。

## 常见问题

### @aura3d/react 是什么？

用于安装带有类型资产、相机、灯光、效果和产品查看器场景构建器的Aura3D场景的React组件和帮助器。

### 如何安装 @aura3d/react？

在项目目录运行 npm install @aura3d/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0 \|\| ^18\.0\.0）、@aura3d/engine（^4\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aura3d/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aura3d/react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aura3d/react 可以商用吗？

@aura3d/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aura3d/react 还在维护吗？

最新版本 4\.7\.0 发布于 2026/10/31（2 天前）；至今共发布 47 个版本，其中过去 12 个月发布了 47 个；首次发布于 2026/06/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。