historyService方法

reset

• 详情：

  重置全部历史记录（包括页面节点栈、代码块栈、数据源栈），并重置当前页面 id / canRedo / canUndo

resetPage

• 详情：

  重置当前页面的历史记录状态（清空当前页面id，重置 canRedo/canUndo）

resetState

• 详情：

  重置历史记录全部内部状态（清空 pageId、pageSteps、canRedo、canUndo、codeBlockState、dataSourceState）

changePage

• 参数：

  • {MPage | MPageFragment} page
  查看 MPage / MPageFragment 类型定义

  export interface MPage extends MContainer {
    /** 页面类型 */
    type: NodeType.PAGE;
  }

  export interface MPageFragment extends MContainer {
    /** 页面类型 */
    type: NodeType.PAGE_FRAGMENT;
  }

• 详情：

  按页面切换历史堆栈

push

• 参数：

  • {StepValue} state
  查看 StepValue 及关联类型定义

  export interface StepValue {
    /** 页面信息 */
    data: { name: string; id: Id };
    opType: HistoryOpType;
    /** 操作前选中的节点 ID，用于撤销后恢复选择状态 */
    selectedBefore: Id[];
    /** 操作后选中的节点 ID，用于重做后恢复选择状态 */
    selectedAfter: Id[];
    modifiedNodeIds: Map<Id, Id>;
    /** opType 'add': 新增的节点 */
    nodes?: MNode[];
    /** opType 'add': 父节点 ID */
    parentId?: Id;
    /** opType 'add': 每个新增节点在父节点 items 中的索引 */
    indexMap?: Record<string, number>;
    /** opType 'remove': 被删除的节点及其位置信息 */
    removedItems?: { node: MNode; parentId: Id; index: number }[];
    /**
     * opType 'update': 变更前后的节点快照
     *
     * `changeRecords` 来自 form 端的 propPath/value 列表，撤销/重做时只对这些 propPath 做局部更新；
     * 缺省（未传 / 空数组）才退化为整节点替换。
     */
    updatedItems?: { oldNode: MNode; newNode: MNode; changeRecords?: ChangeRecord[] }[];
    /**
     * 调用方可选传入的人类可读描述（如「调整按钮颜色」），用于历史面板展示。
     * 不影响 undo/redo 行为；缺省时面板会根据节点 / propPath 自动生成描述。
     */
    historyDescription?: string;
    /**
     * 操作途径：标记本次变更由哪条交互入口触发，取值见 {@link HistoryOpSource}
     * （画布 / 树面板 / 组件面板 / 配置面板 / 源码编辑器 / 右键菜单 / 工具栏 / 快捷键 / 回滚 / 接口 等）。
     * 仅用于历史面板展示与业务埋点，不影响 undo/redo 行为；缺省时面板视为「未知」。
     */
    source?: HistoryOpSource;
    /**
     * 入栈时间戳（毫秒）。在 historyService.push 时自动写入（若调用方未指定），仅用于历史面板展示。
     */
    timestamp?: number;
  }

  export type HistoryOpType = 'add' | 'remove' | 'update';

  /**
   * 历史记录的「操作途径」——标记本次变更由哪条交互入口触发，仅用于历史面板展示 / 业务埋点，
   * 不影响 undo/redo 行为。缺省（未传）时 UI 视为「未知」。
   *
   * - `stage`：画布（拖拽 / 缩放 / 排序等舞台直接操作）
   * - `tree`：树形面板（图层 / 数据源 / 代码块等树形结构里的拖拽 / 菜单操作）
   * - `component-panel`：组件面板（左侧组件列表点击 / 拖拽新增组件）
   * - `props`：配置面板表单（属性表单字段编辑）
   * - `code`：源码编辑器（配置面板「源码」面板里直接编辑 JSON/代码后保存）
   * - `stage-contextmenu`：画布右键菜单（舞台上节点的右键上下文菜单）
   * - `tree-contextmenu`：树面板右键菜单（图层 / 数据源 / 代码块等树形列表上的右键上下文菜单）
   * - `toolbar`：工具栏菜单（顶部导航工具栏按钮）
   * - `shortcut`：键盘快捷键
   * - `rollback`：历史回滚（历史面板里对某条历史「回滚」，反向应用为一条新记录，类 git revert）
   * - `api`：代码 / 接口调用（程序化触发）
   * - `ai`：AI 生成 / 智能助手触发的变更
   * - `unknown`：未知来源
   *
   * 通过 `(string & {})` 允许业务侧扩展自定义途径字符串，同时保留内置值的自动补全。
   */
  export type HistoryOpSource =
    | 'stage'
    | 'tree'
    | 'component-panel'
    | 'props'
    | 'code'
    | 'stage-contextmenu'
    | 'tree-contextmenu'
    | 'toolbar'
    | 'shortcut'
    | 'rollback'
    | 'api'
    | 'ai'
    | 'unknown'
    | (string & {});

  export type Id = string | number;

  export type MNode = MComponent | MContainer | MIteratorContainer | MPage | MApp | MPageFragment;

  export interface ChangeRecord {
    propPath?: string;
    value: any;
  }

• 返回：

  • {StepValue | null}

• 详情：

  添加一条历史记录

  TIP

  opType: 'update' 的每个 updatedItems[i] 上可携带 changeRecords，用于撤销 / 重做时仅按 propPath 局部更新对应字段，避免整节点替换冲掉同节点上的其它无关变更；不带 changeRecords 时退化为整节点替换（如 sort / moveLayer / 拖动等纯快照场景）。

  StepValue 上的 historyDescription / source 仅用于历史面板展示与埋点，不影响 undo/redo 行为。

undo

• 返回：

  • {StepValue | null}

• 详情：

  撤销当前操作。opType: 'update' 时，若 updatedItems[i].changeRecords 存在，会按 propPath 从 oldNode 取值做局部回滚；否则用 oldNode 整节点替换。

redo

• 返回：

  • {StepValue | null}

• 详情：

  恢复到下一步。opType: 'update' 时，若 updatedItems[i].changeRecords 存在，会按 propPath 从 newNode 取值做局部重做；否则用 newNode 整节点替换。

pushCodeBlock

• 参数：

  • {Id} codeBlockId 代码块 id
  • {Object} payload
    • {CodeBlockContent | null} oldContent 变更前的代码块内容；新增时为 null
    • {CodeBlockContent | null} newContent 变更后的代码块内容；删除时为 null
    • {ChangeRecord[]} changeRecords 可选；form 端 propPath/value 变更列表，撤销/重做时若有则按 propPath 局部更新；缺省（或空数组）才退化为整内容替换
    • {string} historyDescription 可选；人类可读描述，用于历史面板展示；不影响 undo/redo 行为
    • {HistoryOpSource} source 可选；操作途径，用于历史面板展示与埋点；不影响 undo/redo 行为
  查看 CodeBlockStepValue 及关联类型定义

  /**
   * 代码块历史记录条目。按 codeBlock.id 分组保存到 historyState.codeBlockState。
   * - 新增：oldContent = null，newContent = 新内容
   * - 更新：oldContent / newContent 都为对应内容
   * - 删除：newContent = null，oldContent = 删除前内容
   */
  export interface CodeBlockStepValue {
    /** 关联的代码块 id */
    id: Id;
    /** 变更前的代码块内容，新增时为 null */
    oldContent: CodeBlockContent | null;
    /** 变更后的代码块内容，删除时为 null */
    newContent: CodeBlockContent | null;
    /**
     * form 端 propPath/value 列表。撤销/重做时若有则按 propPath 局部更新；
     * 缺省才退化为整内容替换。新增/删除场景通常无 changeRecords。
     */
    changeRecords?: ChangeRecord[];
    /** 调用方可选传入的人类可读描述，用于历史面板展示；不影响 undo/redo 行为。 */
    historyDescription?: string;
    /** 操作途径：标记本次变更由哪条交互入口触发，取值见 {@link HistoryOpSource}；仅用于历史面板展示与埋点，不影响 undo/redo 行为。 */
    source?: HistoryOpSource;
    /** 入栈时间戳（毫秒），入栈时自动写入，仅用于历史面板展示。 */
    timestamp?: number;
  }

  /**
   * 历史记录的「操作途径」——标记本次变更由哪条交互入口触发，仅用于历史面板展示 / 业务埋点，
   * 不影响 undo/redo 行为。缺省（未传）时 UI 视为「未知」。
   *
   * - `stage`：画布（拖拽 / 缩放 / 排序等舞台直接操作）
   * - `tree`：树形面板（图层 / 数据源 / 代码块等树形结构里的拖拽 / 菜单操作）
   * - `component-panel`：组件面板（左侧组件列表点击 / 拖拽新增组件）
   * - `props`：配置面板表单（属性表单字段编辑）
   * - `code`：源码编辑器（配置面板「源码」面板里直接编辑 JSON/代码后保存）
   * - `stage-contextmenu`：画布右键菜单（舞台上节点的右键上下文菜单）
   * - `tree-contextmenu`：树面板右键菜单（图层 / 数据源 / 代码块等树形列表上的右键上下文菜单）
   * - `toolbar`：工具栏菜单（顶部导航工具栏按钮）
   * - `shortcut`：键盘快捷键
   * - `rollback`：历史回滚（历史面板里对某条历史「回滚」，反向应用为一条新记录，类 git revert）
   * - `api`：代码 / 接口调用（程序化触发）
   * - `ai`：AI 生成 / 智能助手触发的变更
   * - `unknown`：未知来源
   *
   * 通过 `(string & {})` 允许业务侧扩展自定义途径字符串，同时保留内置值的自动补全。
   */
  export type HistoryOpSource =
    | 'stage'
    | 'tree'
    | 'component-panel'
    | 'props'
    | 'code'
    | 'stage-contextmenu'
    | 'tree-contextmenu'
    | 'toolbar'
    | 'shortcut'
    | 'rollback'
    | 'api'
    | 'ai'
    | 'unknown'
    | (string & {});

  export interface CodeBlockContent {
    /** 代码块名称 */
    name: string;
    /** 代码块内容 */
    content: ((...args: any[]) => any) | Function;
    /** 参数定义 */
    params: CodeParam[] | [];
    /** 注释 */
    desc?: string;
    /** 扩展字段 */
    [propName: string]: any;
  }

  export interface ChangeRecord {
    propPath?: string;
    value: any;
  }

• 返回：

  • {CodeBlockStepValue | null} 入栈失败（未传 id）时返回 null

• 详情：

  推入一条代码块变更记录。与页面 / 节点完全无关，按 codeBlockId 维度独立一份 UndoRedo 栈， 栈实例存放在 historyService.state.codeBlockState[codeBlockId]。

  入栈成功后会触发 code-block-history-change 事件。

  TIP

  codeBlockService.setCodeDslByIdSync 与 codeBlockService.deleteCodeDslByIds 内部已经 自动调用本方法，业务代码通常无需手动调用。

undoCodeBlock

• 参数：

  • {Id} codeBlockId

• 返回：

  • {CodeBlockStepValue | null} 栈不存在或已无可撤销记录时返回 null

• 详情：

  撤销指定代码块的最近一次变更。成功时会触发 code-block-history-change 事件。 拿到 step 后由调用方根据 step.oldContent 写回 codeBlockService（本方法不会自动回放）。

redoCodeBlock

• 参数：

  • {Id} codeBlockId

• 返回：

  • {CodeBlockStepValue | null} 栈不存在或已无可重做记录时返回 null

• 详情：

  重做指定代码块的下一次变更。成功时会触发 code-block-history-change 事件。

canUndoCodeBlock

• 参数：

  • {Id} codeBlockId

• 返回：

  • {boolean}

• 详情：

  指定代码块当前是否可撤销。栈不存在时返回 false。

canRedoCodeBlock

• 参数：

  • {Id} codeBlockId

• 返回：

  • {boolean}

• 详情：

  指定代码块当前是否可重做。栈不存在时返回 false。

pushDataSource

• 参数：

  • {Id} dataSourceId 数据源 id
  • {Object} payload
    • {DataSourceSchema | null} oldSchema 变更前的数据源 schema；新增时为 null
    • {DataSourceSchema | null} newSchema 变更后的数据源 schema；删除时为 null
    • {ChangeRecord[]} changeRecords 可选；form 端 propPath/value 变更列表，撤销/重做时若有则按 propPath 局部更新；缺省（或空数组）才退化为整 schema 替换
    • {string} historyDescription 可选；人类可读描述，用于历史面板展示；不影响 undo/redo 行为
    • {HistoryOpSource} source 可选；操作途径，用于历史面板展示与埋点；不影响 undo/redo 行为
  查看 DataSourceStepValue 及关联类型定义

  /**
   * 数据源历史记录条目。按 dataSource.id 分组保存到 historyState.dataSourceState。
   * - 新增：oldSchema = null，newSchema = 新 schema
   * - 更新：oldSchema / newSchema 都为对应 schema
   * - 删除：newSchema = null，oldSchema = 删除前 schema
   */
  export interface DataSourceStepValue {
    /** 关联的数据源 id */
    id: Id;
    /** 变更前的数据源 schema，新增时为 null */
    oldSchema: DataSourceSchema | null;
    /** 变更后的数据源 schema，删除时为 null */
    newSchema: DataSourceSchema | null;
    /**
     * form 端 propPath/value 列表。撤销/重做时若有则按 propPath 局部更新；
     * 缺省才退化为整 schema 替换。新增/删除场景通常无 changeRecords。
     */
    changeRecords?: ChangeRecord[];
    /** 调用方可选传入的人类可读描述，用于历史面板展示；不影响 undo/redo 行为。 */
    historyDescription?: string;
    /** 操作途径：标记本次变更由哪条交互入口触发，取值见 {@link HistoryOpSource}；仅用于历史面板展示与埋点，不影响 undo/redo 行为。 */
    source?: HistoryOpSource;
    /** 入栈时间戳（毫秒），入栈时自动写入，仅用于历史面板展示。 */
    timestamp?: number;
  }

  /**
   * 历史记录的「操作途径」——标记本次变更由哪条交互入口触发，仅用于历史面板展示 / 业务埋点，
   * 不影响 undo/redo 行为。缺省（未传）时 UI 视为「未知」。
   *
   * - `stage`：画布（拖拽 / 缩放 / 排序等舞台直接操作）
   * - `tree`：树形面板（图层 / 数据源 / 代码块等树形结构里的拖拽 / 菜单操作）
   * - `component-panel`：组件面板（左侧组件列表点击 / 拖拽新增组件）
   * - `props`：配置面板表单（属性表单字段编辑）
   * - `code`：源码编辑器（配置面板「源码」面板里直接编辑 JSON/代码后保存）
   * - `stage-contextmenu`：画布右键菜单（舞台上节点的右键上下文菜单）
   * - `tree-contextmenu`：树面板右键菜单（图层 / 数据源 / 代码块等树形列表上的右键上下文菜单）
   * - `toolbar`：工具栏菜单（顶部导航工具栏按钮）
   * - `shortcut`：键盘快捷键
   * - `rollback`：历史回滚（历史面板里对某条历史「回滚」，反向应用为一条新记录，类 git revert）
   * - `api`：代码 / 接口调用（程序化触发）
   * - `ai`：AI 生成 / 智能助手触发的变更
   * - `unknown`：未知来源
   *
   * 通过 `(string & {})` 允许业务侧扩展自定义途径字符串，同时保留内置值的自动补全。
   */
  export type HistoryOpSource =
    | 'stage'
    | 'tree'
    | 'component-panel'
    | 'props'
    | 'code'
    | 'stage-contextmenu'
    | 'tree-contextmenu'
    | 'toolbar'
    | 'shortcut'
    | 'rollback'
    | 'api'
    | 'ai'
    | 'unknown'
    | (string & {});

  export interface ChangeRecord {
    propPath?: string;
    value: any;
  }

• 返回：

  • {DataSourceStepValue | null} 入栈失败（未传 id）时返回 null

• 详情：

  推入一条数据源变更记录。与页面 / 节点完全无关，按 dataSourceId 维度独立一份 UndoRedo 栈， 栈实例存放在 historyService.state.dataSourceState[dataSourceId]。

  入栈成功后会触发 data-source-history-change 事件。

  TIP

  dataSourceService.add / update / remove 内部已经自动调用本方法，业务代码通常无需手动调用。

undoDataSource

• 参数：

  • {Id} dataSourceId

• 返回：

  • {DataSourceStepValue | null}

• 详情：

  撤销指定数据源的最近一次变更。成功时会触发 data-source-history-change 事件。 拿到 step 后由调用方根据 step.oldSchema 写回 dataSourceService（本方法不会自动回放）。

redoDataSource

• 参数：

  • {Id} dataSourceId

• 返回：

  • {DataSourceStepValue | null}

• 详情：

  重做指定数据源的下一次变更。成功时会触发 data-source-history-change 事件。

canUndoDataSource

• 参数：

  • {Id} dataSourceId

• 返回：

  • {boolean}

• 详情：

  指定数据源当前是否可撤销。栈不存在时返回 false。

canRedoDataSource

• 参数：

  • {Id} dataSourceId

• 返回：

  • {boolean}

• 详情：

  指定数据源当前是否可重做。栈不存在时返回 false。

destroy

• 详情：

  销毁