基础概念

PtahJs 是一个分层的低代码引擎。理解各核心包之间的关系，有助于更准确地使用运行时和设计器能力。

架构概览

text

@ptahjs/ui-vue
  Vue 集成层
  组件、渲染器、启动工具

@ptahjs/designer
  设计时层
  命令、历史记录、拖拽、编辑能力

@ptahjs/runtime
  运行时层
  schema 编译、查询、生命周期、热键

@ptahjs/kernel
  核心状态层
  IRGraph、变更跟踪、订阅、资源系统

Kernel

@ptahjs/kernel 是最底层的包，负责维护 DSL 树的核心状态，也就是 IRGraph。

主要职责：

维护 IRGraph
跟踪状态版本变化
异步通知订阅者
支持批量更新
管理共享资源系统

通常业务层直接使用的是 Runtime，不是 Kernel。

IRGraph

IRGraph 是编译后的页面结构，会按不同 section 建立索引，方便高效查询。

Section	说明
`scenesById`	场景映射
`modulesById`	模块映射
`childrenIdsByParentId`	父子关系映射
`eventsById`	事件映射
`eventIdsByOwnerId`	按 owner 分组的事件 ID
`sceneIdOrder`	场景顺序
`subSchemasById`	子 Schema 映射

当调用 runtime.schema(data) 时，页面 JSON 会被编译到这个结构里。

Runtime

@ptahjs/runtime 在 Kernel 之上补充了业务层 API。

schema(data)：将页面 schema 编译到 IRGraph
查询方法：如 getSceneIds()、getSceneById(id)、getModuleById(id)
当前选中状态：如 setCurrentSceneId()、setCurrentModuleId()
lifecycleChain：同步钩子链
hotkeys：快捷键能力

runtime.schema(pageJson);

const sceneIds = runtime.getSceneIds();
const module = runtime.getModuleById('module-123');

Designer

@ptahjs/designer 在 Runtime 之上提供设计时编辑能力。

基于命令的编辑
撤销与重做
内置拖拽系统
模块剪贴板
导出页面 schema

const moduleId = designer.addModule({
    type: 'UiButton',
    parentId: 'scene-1',
    index: 0,
});

designer.updateModule({
    id: moduleId,
    patch: { props: { label: '按钮' } },
});

designer.undo();

LifecycleChain

runtime.lifecycleChain 是同步处理管线。

通过 addStep(type, fn) 注册步骤
按注册顺序执行
返回 undefined 表示沿用上一步结果

import { LIFECYCLE_TYPE } from '@ptahjs/kernel';

runtime.lifecycleChain.addStep(LIFECYCLE_TYPE.BEFORE_TRANSFORM_DATA, (schema) => {
    return schema;
});

资源系统

资源系统用于存放渲染器配置、模块 schema、参数组件等共享配置。

import { RESOURCE_TYPE } from '@ptahjs/kernel';

const config = runtime.getResource(RESOURCE_TYPE.RENDERER_CONFIG);

场景与模块

场景是顶层页面单元，模块是放置在场景或其他模块内部的组件实例。

典型结构：

text

Page Schema
- Scene 1
  - UiHeader
  - UiGrid
    - Slot: default
      - UiButton
- Scene 2
- Modal 1

事件流

PtahJs 里的事件不是 DOM Event 对象，而是流程定义。事件归属于某个场景或模块，由运行时流程器执行。

ui-vue

@ptahjs/ui-vue 是 Vue 集成层。

启动工具：useRuntimeApp()、useDesignerApp()
Vue 插件：createPtah()
内置组件：Preview、DesignerRoot、ScenesWidget、ModulesWidget、WorkspaceWidget、ParameterWidget、EventsWidget

更多内容见 API 参考。

基础概念 ​

架构概览 ​

Kernel ​

IRGraph ​

Runtime ​

Designer ​

LifecycleChain ​

资源系统 ​

场景与模块 ​

事件流 ​

ui-vue ​