哺乳期

@dugyu/luna-studio 是一个用于基于 Lynx 的预览和比较画布的可重复使用的多相配音层.

它包装了下列所需的渲染、布局、焦点和相互作用管道:

• 比较/焦点/分界线阶段安排
• 共享或每个阶段的主题应用
• 主机侧相位- 容器交互处理
• 嵌入式 Lynx 运行时调用转发
• 应用定义的焦点分辨率和全球道具注入

没错 没有 运送一个应用外壳.

以下的应用级部件暂不在此包外 :

• Studio
• MenuBar
• StudioFrame
• 键盘快捷键胶水
• 演示特定的运行时间处理
• 应用自主布局目录和商业元数据

如果您只需要单个设备框预览, 请使用 @dugyu/luna-stage 直接说.

安装

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的一部分.

快速启动

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 (
    <div className='size-full'>
      <Choreography
        bundleRoot='/bundles/'
        layout={layout}
        modeGrid={modeGrid}
        viewMode='compare'
        themeKey='lunaris-dark'
        interactionTarget='content'
      />
    </div>
  );
}

如果您主机更喜欢将资源池(入口/bundleRoot/主题默认)与每个模式的布局相分离的作者模式,您可以使用 resolveStudioLayout数字 :

import { resolveStudioLayout } from '@dugyu/luna-studio';
import type {
  ResolveStudioLayoutParams,
  StudioLayout,
  StudioStage,
} from '@dugyu/luna-studio';

const stagePool: Record<string, StudioStage> = {
  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 是一个阶段的资源/集合定义(资源定位器+默认值).

type StudioStage = {
  id: string;
  entry: string;
  theme: LunaThemeKey;
  bundleRoot?: string;
  focusKey?: string;
};

注释:

• entry 财务报告和审定财务报表 bundleRoot 是用于定位 Lynx 捆绑的资源定位器.
• theme 财务报告和审定财务报表 focusKey 是布局解析时使用的相位默认值.

StudioResolvedStage

StudioResolvedStage 是编舞层所消耗的每阶段数据边界.

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 并带有该模式的主机侧重置功能.

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) (中文(简体) ).

type StudioLayout = Record<
  'compare' | 'focus' | 'lineup',
  StudioStageSlice[]
>;

StudioResolvedLayout

StudioResolvedLayout 包含每个内置演示模式的一个阶段列表.

type StudioResolvedLayout = Record<
  'compare' | 'focus' | 'lineup',
  StudioResolvedStage[]
>;

modeGrid 当主机需要由网格驱动容器布局时,可以选择提供每种模式的网格尺寸.

StudioViewMode

StudioViewMode 选择哪个布局切片活动.

互动模式

InteractionParams

InteractionParams 是编舞回调使用的常态交互信封.

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

接收常规的舞蹈互动信封.

type OnInteraction = (interaction: InteractionParams) => unknown;

当您想要一个地方观察主机侧相位- 容器交互和嵌入式内容回调时, 请将此作为主要的高级别回调 。 混凝土原始载荷作为 interaction.containerEvent 或者说 interaction.runtimeCall,取决于 interaction.target。 。 。 .

onLynxRuntimeCall

接收嵌入式 Lynx 内容释放的原始运行时调用 .

type OnLynxRuntimeCall = (call: LynxRuntimeCall) => unknown;

type LynxRuntimeCall = {
  entry: string;
  channel: string;
  name: string;
  data: unknown;
};

仅当您需要 Lynx 桥 / RPC 直接召回时使用, 而不是普通的 onInteraction 抽象化.

这使得软件包表面运行时间保持中性 :

• 无低水平 moduleName 渗出
• channel 仍然是主机源标识符
• 应用特定解释留在软件包之外

resolveFocusKey

resolveFocusKey 将正常的相互作用映射到一个阶段 focusKey。 。 。 .

type FocusKeyResolver = (
  interaction: InteractionParams,
) => string | undefined;

这是通用编舞互动和企业特有重点语义之间的应用自有桥梁.

buildStageGlobalProps

buildStageGlobalProps 让主机为每个渲染的阶段获取特定应用 Lynx 全球道具.

type StageGlobalPropsBuilder = (params: {
  stage: StudioStage;
  viewMode: StudioViewMode;
  activeFocusKey: string;
  focusKey: string | undefined;
}) => Record<string, unknown> | undefined;

与重点有关的两个领域的作用不同:

• activeFocusKey 是当前全舞曲的主动焦点特性.
• focusKey 是特定 stage 目前正在进行.

换句话说, activeFocusKey 回答“当前哪些焦点目标正在活动中?” focusKey 回答"这个特定阶段属于哪个焦点目标?".

这使得获得舞台-局部道具变得容易,例如:

• 现阶段是否为积极/重点阶段
• 哪些共享组件或语义密钥目前活跃于其他编程中
• 取决于已实现阶段和全球焦点状态的应用程序专用旗帜

Choreography API 密码

Choreography 是这套计划中的主要公共内容.

内部,它包裹 ChoreographyView,它是负责布局,焦点状态,相互作用正常化,以及Lynx相位接线的下层渲染器.

type ChoreographyProps = Omit<ChoreographyViewProps, 'mode'> & {
  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 融合