# @dugyu/luna-studio 中文文档 规范地址：https://npmcn.com/package/%40dugyu/luna-studio/ 版本：0\.2\.0 npm 元数据更新时间：2026-05-17T15:39:49.336Z 中文译文更新时间：2026-11-13T00:02:30.239Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dugyu/luna-studio 原文对照：https://npmcn.com/package/%40dugyu/luna-studio/?lang=original 项目主页：https://github.com/Dugyu/lunarium/tree/main/packages/luna-studio#readme 源码仓库：https://github.com/Dugyu/lunarium ## 关键信息（来自 npm 元数据） - 包体积（解压后）：103 kB，46 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：2 个 - peer 依赖：@lynx-js/web-core \>=0\.20\.0，motion \>=12\.23\.16，react \>=18\.0\.0 - 首次发布：2026-05-06T13:57:49.565Z - 最新版本发布：2026-05-17T15:39:49.027Z - 近 30 天下载量：5519（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：6（近 12 个月 6 个） ## 中文简介 用于L.U.N.A项目的可再利用多相相交织层 ## 安装 ```sh npm install @dugyu/luna-studio ``` 也可以使用：`pnpm add @dugyu/luna-studio`、`yarn add @dugyu/luna-studio`、`bun add @dugyu/luna-studio` ## README # 哺乳期 `@dugyu/luna-studio` 是一个用于基于 Lynx 的预览和比较画布的可重复使用的多相配音层. 它包装了下列所需的渲染、布局、焦点和相互作用管道: - 比较/焦点/分界线阶段安排 - 共享或每个阶段的主题应用 - 主机侧相位- 容器交互处理 - 嵌入式 Lynx 运行时调用转发 - 应用定义的焦点分辨率和全球道具注入 没错 **没有** 运送一个应用外壳. 以下的应用级部件暂不在此包外 : - `Studio` - `MenuBar` - `StudioFrame` - 键盘快捷键胶水 - 演示特定的运行时间处理 - 应用自主布局目录和商业元数据 如果您只需要单个设备框预览, 请使用 [`@dugyu/luna-stage`](https://npmcn.com/package/%40dugyu/luna-stage) 直接说. ## 安装 ```sh npm i @dugyu/luna-studio @lynx-js/web-core motion react ``` `luna-studio` 取决于 `@dugyu/luna-stage` 内部用于渲染原始,并期望 Lynx Web 运行时间可通过 `@lynx-js/web-core`。 。 。 . ## 公共 API 目前公共出口 `@dugyu/luna-studio` 按构成部分和类型分类: - 构成部分 - `Choreography` - 工作室模型类型 - `StudioStage` - `StudioStageSlice` - `StudioResolvedStage` - `ResolveStudioLayoutParams` - `StageGlobalPropsBuilder` - `StudioGridSpec` - `StudioLayout` - `StudioResolvedLayout` - `StudioModeGrid` - `StudioViewMode` - `LunaThemeKey` - `LunaThemeMode` - `LunaThemeVariant` - 舞蹈类型 - `ChoreographyBaseProps` - `ChoreographyProps` - `ChoreographyInteractionProps` - `ChoreographyViewProps` - `InteractionParams` - `InteractionTarget` - `FocusKeyResolver` - 林克斯桥类型 - `LynxRuntimeCall` - 帮助者 - `resolveStudioLayout` - `indexResolvedLayout` - `getPayloadString` `ChoreographyView` 财务报告和审定财务报表 `StudioLynxStage` 软件包内部作为内部执行层存在,但它们不是公共组成部分API的一部分. ## 快速启动 ```tsx import { Choreography } from '@dugyu/luna-studio'; import type { StudioModeGrid, StudioResolvedLayout } from '@dugyu/luna-studio'; const modeGrid: StudioModeGrid = { compare: { cols: 2, rows: 1 }, focus: { cols: 3, rows: 1 }, lineup: { cols: 3, rows: 1 }, }; const layout: StudioResolvedLayout = { compare: [ { id: 'button-light', entry: 'ActButton', theme: 'luna-light', focusKey: 'button', style: { gridColumn: '1 / span 1', gridRow: '1 / span 1' }, }, { id: 'button-dark', entry: 'ActButton', theme: 'luna-dark', focusKey: 'button', style: { gridColumn: '2 / span 1', gridRow: '1 / span 1' }, }, ], focus: [ { id: 'button-focus', entry: 'ActButton', theme: 'luna-light', focusKey: 'button', style: { gridColumn: '2 / span 1', gridRow: '1 / span 1' }, }, ], lineup: [ { id: 'button-lineup', entry: 'ActButton', theme: 'lunaris-dark', focusKey: 'button', style: { gridColumn: '2 / span 1', gridRow: '1 / span 1' }, }, ], }; export function Demo() { return (
); } ``` 如果您主机更喜欢将资源池(入口/bundleRoot/主题默认)与每个模式的布局相分离的作者模式,您可以使用 `resolveStudioLayout`数字 : ```ts import { resolveStudioLayout } from '@dugyu/luna-studio'; import type { ResolveStudioLayoutParams, StudioLayout, StudioStage, } from '@dugyu/luna-studio'; const stagePool: Record = { Button: { id: 'Button', entry: 'ActButton', theme: 'luna-light' }, }; const layoutSpec: StudioLayout = { compare: [{ id: 'Button', style: { gridColumn: '1 / 2', gridRow: '1 / 2' } }], focus: [{ id: 'Button', style: { gridColumn: '1 / 2', gridRow: '1 / 2' } }], lineup: [{ id: 'Button', style: { gridColumn: '1 / 2', gridRow: '1 / 2' } }], }; const resolvedLayout = resolveStudioLayout( { stagePool, layoutSpec, } satisfies ResolveStudioLayoutParams, ); ``` ## 核心概念 ### `StudioStage` `StudioStage` 是一个阶段的资源/集合定义(资源定位器+默认值). ```ts type StudioStage = { id: string; entry: string; theme: LunaThemeKey; bundleRoot?: string; focusKey?: string; }; ``` 注释: - `entry` 财务报告和审定财务报表 `bundleRoot` 是用于定位 Lynx 捆绑的资源定位器. - `theme` 财务报告和审定财务报表 `focusKey` 是布局解析时使用的相位默认值. ### `StudioResolvedStage` `StudioResolvedStage` 是编舞层所消耗的每阶段数据边界. ```ts type StudioResolvedStage = { id: string; className?: string; style?: CSSProperties; bundleRoot?: string; focusKey?: string; entry: string; theme: LunaThemeKey; }; ``` 注释: - `id` 是用于布局、运动和相互作用关联的稳定阶段身份. - `className` 财务报告和审定财务报表 `style` 适用于舞台容器. - `bundleRoot` 可在每个阶段提供;否则 `Choreography.bundleRoot` 可能起到东道方级倒计时的作用. - 应用特定元数据应生活在应用本地扩展类型中,而不是重新开放公众 `StudioResolvedStage` 合同. ### `StudioStageSlice` `StudioStageSlice` 是一个阶段的每个模式布局投影。 上面提到一个游泳池舞台 `id` 并带有该模式的主机侧重置功能. ```ts type StudioStageSlice = { id: string; className?: string; style?: CSSProperties; theme?: LunaThemeKey; focusKey?: string; }; ``` 注释: - 切片标识必须是独有的 `StudioViewMode`。 。 。 . `Choreography` 使用已解决的 `stage.id` 作为稳定的渲染特性(反应键、 运动布局 ID, 并释放) `interaction.stageId`) (中文(简体) ). - 使同样的Lynx `entry` 多次, 定义多次 `StudioStage` 不同集合项目 `id` 数值相同 `entry`。 。 。 . ### `StudioLayout` `StudioLayout` 是三种内置显示模式的作者版式规格。 每个项目逐一提及 `id` 并带有主机侧覆(例如, `className`, (中文(简体) ), `style`, (中文(简体) ), `theme`, (中文(简体) ), `focusKey`) (中文(简体) ). ```ts type StudioLayout = Record< 'compare' | 'focus' | 'lineup', StudioStageSlice[] >; ``` ### `StudioResolvedLayout` `StudioResolvedLayout` 包含每个内置演示模式的一个阶段列表. ```ts type StudioResolvedLayout = Record< 'compare' | 'focus' | 'lineup', StudioResolvedStage[] >; ``` `modeGrid` 当主机需要由网格驱动容器布局时,可以选择提供每种模式的网格尺寸. ### `StudioViewMode` `StudioViewMode` 选择哪个布局切片活动. | 模式 | 行为 | | --- | --- | | `compare` | 将多个阶段相并列并允许每个阶段的主题 | | `focus` | 提出一个强调3D焦点的共同主题 | | `lineup` | 在分队安排中创建共享主题 | ## 互动模式 ### `InteractionParams` `InteractionParams` 是编舞回调使用的常态交互信封. ```ts type InteractionParams = | { target: 'stage'; stageId: string; entry: string; payload?: unknown; containerEvent: MouseEvent | PointerEvent; } | { target: 'content'; stageId: string; entry: string; payload?: unknown; runtimeCall: LynxRuntimeCall; }; ``` 注释: - `target: 'stage'` 表示交互作用归于主机-侧相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 `containerEvent`。 。 。 . - `target: 'content'` 表示该相互作用归因于嵌入式 Lynx 内容;原始 Lynx 运行时有效载荷作为 `runtimeCall`。 。 。 . - `containerEvent.type` 区分主机侧点击/指针变体. - `runtimeCall.name` 区分内容边交互类型 `onNativeModulesCall`。 。 。 . ### `interactionTarget` `interactionTarget` 控制首先接收指针交互的层 : - `'content'`: 嵌入式 Lynx 内容是交互式的 - `'stage'`: 外相容器是交互式的 ### `onInteraction` 接收常规的舞蹈互动信封. ```ts type OnInteraction = (interaction: InteractionParams) => unknown; ``` 当您想要一个地方观察主机侧相位- 容器交互和嵌入式内容回调时, 请将此作为主要的高级别回调 。 混凝土原始载荷作为 `interaction.containerEvent` 或者说 `interaction.runtimeCall`,取决于 `interaction.target`。 。 。 . ### `onLynxRuntimeCall` 接收嵌入式 Lynx 内容释放的原始运行时调用 . ```ts type OnLynxRuntimeCall = (call: LynxRuntimeCall) => unknown; type LynxRuntimeCall = { entry: string; channel: string; name: string; data: unknown; }; ``` 仅当您需要 Lynx 桥 / RPC 直接召回时使用, 而不是普通的 `onInteraction` 抽象化. 这使得软件包表面运行时间保持中性 : - 无低水平 `moduleName` 渗出 - `channel` 仍然是主机源标识符 - 应用特定解释留在软件包之外 ### `resolveFocusKey` `resolveFocusKey` 将正常的相互作用映射到一个阶段 `focusKey`。 。 。 . ```ts type FocusKeyResolver = ( interaction: InteractionParams, ) => string | undefined; ``` 这是通用编舞互动和企业特有重点语义之间的应用自有桥梁. ### `buildStageGlobalProps` `buildStageGlobalProps` 让主机为每个渲染的阶段获取特定应用 Lynx 全球道具. ```ts type StageGlobalPropsBuilder = (params: { stage: StudioStage; viewMode: StudioViewMode; activeFocusKey: string; focusKey: string | undefined; }) => Record | undefined; ``` 与重点有关的两个领域的作用不同: - `activeFocusKey` 是当前全舞曲的主动焦点特性. - `focusKey` 是特定 `stage` 目前正在进行. 换句话说, `activeFocusKey` 回答“当前哪些焦点目标正在活动中?” `focusKey` 回答"这个特定阶段属于哪个焦点目标?". 这使得获得舞台-局部道具变得容易,例如: - 现阶段是否为积极/重点阶段 - 哪些共享组件或语义密钥目前活跃于其他编程中 - 取决于已实现阶段和全球焦点状态的应用程序专用旗帜 ## `Choreography` API 密码 `Choreography` 是这套计划中的主要公共内容. 内部,它包裹 `ChoreographyView`,它是负责布局,焦点状态,相互作用正常化,以及Lynx相位接线的下层渲染器. ```ts type ChoreographyProps = Omit & { viewMode?: StudioViewMode; }; ``` 行为说明: - `viewMode` 默认为 `'compare'` - `themeKey` 默认为 `'lunaris-dark'` - `interactionTarget` 默认为 `'content'` - `focusKey` 直接从解决阶段读取 `layout` (即来自 `StudioResolvedLayout` 阶段项目) - `bundleRoot` 每一阶段的资源来源都来自 `layout` - `layout` 需要,并且应该已经完全由主机应用程序解决 ## 范围 此套件涵盖可重复使用的编舞层 : - 公共舞蹈类型和数据模型 - 网格驱动多阶段布局和重点展示 - 正常阶段/内容交互处理 - 内部 `ChoreographyView` 渲染器 - lynx 内部运行时间适配器 `Choreography` 这个软件包是 **没有** 规定: - 顶级 `Studio` shell 组件 - 内建演示布局数据 - 应用铬等 `MenuBar` - 应用级键盘绑定 - 演示特定运行时间事件解析 - a 公众 `lynx-stage` 子路径导出 ## 预定消费者 使用 `@dugyu/luna-studio` 当您需要可重复使用的多相编舞层时, 但想要保留您的应用程序外壳, 排版数据, 商业语义, 以及处理本地的事件 : - 嵌入多个 Lynx 条目的文档站点 - 设计系统比较画布 - 需要舞台- 容器交互和 Lynx 运行时回调的应用程序主机 - 未来 `lynx-website` 融合 ## 常见问题 ### @dugyu/luna-studio 是什么？ 用于L\.U\.N\.A项目的可再利用多相相交织层 ### 如何安装 @dugyu/luna-studio？ 在项目目录运行 npm install @dugyu/luna-studio，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@lynx-js/web-core（\>=0\.20\.0）、motion（\>=12\.23\.16）、react（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @dugyu/luna-studio 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @dugyu/luna-studio 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @dugyu/luna-studio 可以商用吗？ @dugyu/luna-studio 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @dugyu/luna-studio 的下载量有多少？ 根据 npm 官方下载统计，@dugyu/luna-studio 在 2026/10/13 – 2026/11/11 这 30 天内被下载 5,519 次，日均约 184 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dugyu/luna-studio 还在维护吗？ 最新版本 0\.2\.0 发布于 2026/05/17（5 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/05/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。