` 大小和适合/尺度。 倒计时 `StageContainer` → `baseWidth`。 。 。 . |
| `height` | `number` | —— 说 | 显取观相大小. 驱动两种 `
` 大小和适合/尺度。 倒计时 `StageContainer` → `baseHeight`。 。 。 . |
| `fit` | `'contain' | 'cover'` | `'contain'` | 合适的模式. |
| `alignX` | `'left' | 'center' | 'right'` | `'center'` | 视野内帧水平对齐. 单位 `cover` 模式还决定了裁剪锚地. |
| `alignY` | `'top' | 'center' | 'bottom'` | `'center'` | 视野内帧垂直对齐. 单位 `cover` 模式还决定了裁剪锚地. |
| `placeX` | `'left' | 'center' | 'right'` | `alignX` | 在取景口内横向放置内部锚. 覆盖到从对齐解析位置 . |
| `placeY` | `'top' | 'center' | 'bottom'` | `alignY` | 在取景口内垂直放置内部锚. 覆盖到从对齐解析位置 . |
| `zoom` | `number` | `1` | 在合适的顶部增加缩放系数 . |
| `panX` | `number` | `0` | 沿X(px)进行屏幕-空间翻译. |
| `panY` | `number` | `0` | 沿Y(px)进行屏幕-空间翻译. |
| `className` | `string` | —— 说 | 适用于大纲层. |
| `style` | `CSSProperties` | —— 说 | 适用于大纲层. |
| `onClick` | `MouseEventHandler` | —— 说 | —— 说 |
### `StageContainer`
通过测量其DOM大小 `ResizeObserver` 并给孩子提供宽度/高度 `Stage` 组件通过上下文.
添加粘贴、边框或布局样式到 `StageContainer` 自由——测量的内容框是什么 `Stage` 适合,所以编织的作品 作为预期的视觉边框周围的帧.
避免设置 `transform`, (中文(简体) ), `filter`, (中文(简体) ), `perspective`, (中文(简体) ), `backdrop-filter`,或 `contain: paint/layout/strict` 打开 `StageContainer` ——这些设置了被夹住的块 `position: fixed` 舞台上的后代.
#### 道具
| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `fallbackWidth` | `number` | `0` | 在第一次测量之前使用. |
| `fallbackHeight` | `number` | `0` | 在第一次测量之前使用. |
继承所有 `
` HTML 属性 (`className`, (中文(简体) ), `style`(见a/c.5/49/70,附件).
### `LynxStage`
将 Lynx 捆绑成 DOM 容器的核心组件 .
| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `entry` | `string` | —— 说 | Lynx包的条目名 . |
| `bundleRoot` | `string` | `'/'` | 使用的资源根 `entry` 找到包裹 常态化到永远结束 `/` 在 URL 解析之前. |
| `resolveBundleSrc` | `function` | —— 说 | 可选的钩子, 用于构建最终捆绑的 URL 。 接收已规范 `bundleRoot` (总是结束于 `/`) (中文(简体) ). |
| `globalProps` | `Record
` | —— 说 | 注射到Lynx运行时间的全球道具. |
| `groupId` | `number` | `7` | 共享Lynx工人团体ID. |
| `onNativeModulesCall` | `function` | —— 说 | 从 Lynx 运行时间召回本地模块呼叫 . |
| `onReady` | `function` | —— 说 | 当视图成功渲染时调用 . |
| `onError` | `function` | —— 说 | 在加载或渲染过程中发生错误时召回 . |
### `LunaLynxStage`
扩展 `LynxStage` 带有 LUNA 主题属性.
| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `lunaTheme` | `LunaThemeKey` | `'luna-light'` | LUNA主题密钥( 如:. `'luna-light'`) (中文(简体) ). |
| `extraGlobalProps` | `Record` | —— 说 | 新增全球道具. |
| _(其他人员)_ | | | 全体 `LynxStage` 道具( 除外) `globalProps`) (中文(简体) ). |
### `MotionStage`
动画设备框架. 扩展 `Stage`其基础道具有弹簧驱动的过渡和透视相机模型.
`MotionStage` 内部建议 `MotionStageContainer` 用于响应的大小和布局动画. 当独立化时,它会回落到基线大小,你可以通过 `width` 编号 : `height` `MotionValue` 道具来.
#### 道具
| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `baseWidth` | `number` | `375` | 以像素为单位设计基线宽度. |
| `baseHeight` | `number` | `812` | 以像素设计基线高度. |
| `width` | `MotionValue` | —— 说 | 覆盖取景口宽度( 从上下文) 。 对于高级病例. |
| `height` | `MotionValue` | —— 说 | 覆盖取景口高度( 从上下文) 。 对于高级病例. |
| `fit` | `'contain' | 'cover'` | `'contain'` | 合适的模式。 忽略当 `fitProgress` 已经设定. |
| `fitProgress` | `number` | —— 说 | `0–1` 混入了被子和被子, 由一泉驱动. |
| `zoom` | `number` | `1` | 额外的缩放系数 . |
| `panX` | `number` | `0` | 沿X(px)进行屏幕-空间翻译. |
| `panY` | `number` | `0` | 沿Y(px)进行屏幕-空间翻译. |
| `world` | `{ x?, y?, z? }` | `{ x:0, y:0, z:0 }` | 世界空间位置. `+Z` 面向观众. |
| `focalLength` | `number` | —— 说 | 透视焦距 (px). 矫形术. |
| `alignX` | `'left' | 'center' | 'right'` | `'center'` | 视野内帧水平对齐. |
| `alignY` | `'top' | 'center' | 'bottom'` | `'center'` | 视野内帧垂直对齐. |
| `fitTransition` | `SpringOptions` | —— 说 | 春天来 `fit` 编号 : `fitProgress`。 。 。 . |
| `zoomTransition` | `SpringOptions` | —— 说 | 春天来 `zoom`。 。 。 . |
| `panTransition` | `SpringOptions` | —— 说 | 用于合并屏幕-空间翻译的春天(`panX/Y` + 预测 `world.x/y`) (中文(简体) ). |
| `maskColor` | `string` | `'transparent'` | 重叠口罩颜色. |
| `maskOpacity` | `number` | `0` | 重叠口罩不透明(动画). |
| `contentInteractive` | `boolean` | `false` | 帧子是否收到指针事件. |
| `className` | `string` | —— 说 | 适用于大纲层. |
| `style` | `MotionStyle` | —— 说 | 适用于大纲层. |
### `MotionStageContainer`
运动意识等同 `StageContainer`提供 `MotionValue` 宽度/ 重至子 `MotionStage` 组件通过上下文。 处理布局动画并从中取出父缩放 `transformTemplate` 在过渡期间保持视觉大小的准确性.
必须是作为孩子 `` 用于挂载/卸载动画工作.
#### 道具
| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `layoutId` | `string` | —— 说 | 跨挂载/卸载布局动画匹配的独特ID 。 要求. |
| `onLayoutMeasure` | `(box: Box) => void` | —— 说 | 从 `motion`。当布局框被测量时调用. |
| `onLayoutAnimationStart` | `() => void` | —— 说 | 从 `motion`。当布局动画开始时调用. |
| `onLayoutAnimationComplete` | `() => void` | —— 说 | 从 `motion`。当布局动画完成时调用. |
继承所有 `motion.div` 道具( 除外) `transformTemplate`页:1.
### `MotionPresentation`
一个零大小的以弹性为中心的主锚来包接 `AnimatePresence propagate` 为后人挂载/卸载动画.
**使用时 :** 项是动态添加/删除的,需要挂载/卸载动画.
**跳过时 :** 组件总是挂载的,或者只需要状态过渡动画.
继承所有 `motion.div` 道具( r)`variants`, (中文(简体) ), `initial`, (中文(简体) ), `animate`, (中文(简体) ), `exit`, (中文(简体) ), `transition`(见a/c.5/49/70,附件).
## 用法实例
### 运动: 无挂载/卸载
```tsx
import { MotionStage, MotionStageContainer } from '@dugyu/luna-stage/motion';
;
```
### 动画: 有挂载/卸载动画
```tsx
import { AnimatePresence } from 'motion/react';
import {
MotionStage,
MotionStageContainer,
MotionPresentation,
} from '@dugyu/luna-stage/motion';
const variants = {
initial: { opacity: 0, x: -300 },
animate: { opacity: 1, x: 0 },
exit: { opacity: 0, x: 300 },
};
{items.map(item => (
))}
;
```
### 透视旋转木马
沿圆弧排列相框. `+Z` 面向观众,所以物体在 `z < 0` 更远处出现:
```tsx
const theta = (index - mid) * (Math.PI / 9); // 20° apart
const world = {
x: Math.sin(theta) * radius,
z: -Math.cos(theta) * radius, // negative = further from viewer
};
;
```
### 整形比较布局
奥米 `focalLength` (或设置为 `0`——所有帧均以等比例制作,而不论 `world.z`数字 :
```tsx
;
```
## 构成部分表
| 构成部分 | 入境点 | 说明 |
| --- | --- | --- |
| `Stage` | `.` | 静态设备框架 |
| `StageContainer` | `.` | 自动计量容器,通过上下文提供大小 |
| `LynxStage` | `./lynx` | Core Lynx 捆绑渲染器( 无 LUNA 环球) |
| `LunaLynxStage` | `./lynx` | `LynxStage` + LUNA 主题道具注射 |
| `MotionStage` | `./motion` | 有透视相机的动画设备框架 |
| `MotionStageContainer` | `./motion` | 布局动画包装; 提供 `MotionValue` 大小 |
| `MotionPresentation` | `./motion` | 上山/下山过渡管弦乐团 |
## 钩子
| 导出 | 入境点 | 说明 |
| --- | --- | --- |
| `useEventCallback` | `.` | 固定的回调,总是调用最新的 `fn` |
| `useIsClient` | `.` | SSR 安全客户端挂载检测 |
| `useContainerResize` | `.` | 通过 `ResizeObserver` |
| `useMergedRefs` | `.` | 将多个 refs 合并到单个元素 |
| `useIsomorphicLayoutEffect` | `.` | 安保部门安全 `useLayoutEffect` |
| `useLynxStage` | `./lynx` | 用于管理 Lynx 运行时间和生命周期的核心钩 |
## SSS / SSG 说明
`LynxStage` 财务报告和审定财务报表 `LunaLynxStage` 为: **只有客户端**它们使 `null` 在服务器上挂载,只在水分化后挂载.
## 捆绑和资产公约
- 默认情况下, 捆绑文件遵循命名模式 `*.web.bundle`。 。 。 .
- `bundleRoot` 由默认解析器规范为后继斜线.
- 默认解析的 URL : `${bundleRoot}${entry}.web.bundle`。 。 。 .
- 使用 `resolveBundleSrc` 当您的主机需要不同的文件命名规则或完整的 URL 组成 .
## 变形公用事业
职能 `src/utils/transform.ts` 是零依赖性纯函数,可安全复制到其他项目.
| 函数 | 说明 |
| --- | --- |
| `computeScaleRange(input)` | 回返 `{ contain, cover }` 比额表因数 |
| `lerpFitScale(range, t)` | 封面和封面之间的内插 |
| `computeFrameOffset(input)` | 回返 `{ offsetX, offsetY }` cSS 转换 |
| `computeDepthScale(focalLength, worldZ)` | 视角深度尺度 `f / (f - z)` |
| `computeScreenTranslation(input)` | 项目世界 XY + 屏幕平板 最终翻译 |
将适应/规模纳入 `lynx-view` 容器: 副本 `computeScaleRange`, (中文(简体) ), `lerpFitScale`,以及 `computeFrameOffset`修复 `lynx-view` 时间 `baseWidth × baseHeight`,通过 CSS 应用计算过的变换,并通过设计基线像素尺寸 `browserConfig` 而不是容器的大小.
## 常见问题
### @dugyu/luna-stage 是什么？
L\.U\.N\.A项目的阶段系统和展示组件
### 如何安装 @dugyu/luna-stage？
在项目目录运行 npm install @dugyu/luna-stage，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @dugyu/luna-stage 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @dugyu/luna-stage 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @dugyu/luna-stage 可以商用吗？
@dugyu/luna-stage 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。
### @dugyu/luna-stage 的下载量有多少？
根据 npm 官方下载统计，@dugyu/luna-stage 在 2026/10/13 – 2026/11/11 这 30 天内被下载 5,523 次，日均约 184 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @dugyu/luna-stage 还在维护吗？
最新版本 0\.2\.2 发布于 2026/05/17（5 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/05/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。