@tmagic/editor 1.8.0-manmanyu.8 → 1.8.0

package/src/services/editor.ts

@@ -16,7 +16,7 @@
  * limitations under the License.
  */
 
-import { reactive, toRaw } from 'vue';
+import { nextTick, reactive, toRaw } from 'vue';
 import { cloneDeep, isEmpty, isEqual, isObject, mergeWith, uniq } from 'lodash-es';
 
 import type { Id, MApp, MContainer, MNode, MPage, MPageFragment, TargetOptions } from '@tmagic/core';
@@ -30,7 +30,9 @@ import {
   guid,
   isPage,
   isPageFragment,
+  isPageOrFragment,
   setValueByKeyPath,
+  traverseNode,
 } from '@tmagic/utils';
 
 import BaseService from '@editor/services//BaseService';
@@ -47,11 +49,14 @@ import type {
   EditorNodeInfo,
   HistoryOpSource,
   HistoryOpType,
+  NodeInvalidInfo,
+  NodeInvalidSource,
   PastePosition,
   StepDiffItem,
   StepValue,
   StoreState,
   StoreStateKey,
+  UpdateOptions,
 } from '@editor/type';
 import { canUsePluginMethods, LayerOffset, Layout } from '@editor/type';
 import {
@@ -79,6 +84,10 @@ import { beforePaste, getAddParent } from '@editor/utils/operator';
 
 type MoveItem = { node: MNode; parent: MContainer; pageForOp: { name: string; id: Id } | null };
 
+/** 历史插回时把记录的下标收敛到 [0, length]，越界（含未记录）一律追加到末尾 */
+const clampIndex = (index: number | undefined, length: number): number =>
+  typeof index === 'number' && index >= 0 && index <= length ? index : length;
+
 /**
  * 把「变更前后节点快照」列表归一成 update 类型的 {@link StepDiffItem} 列表，供 {@link StepValue.diff} 使用。
  * `changeRecords` 来自 form 端的 propPath/value 列表，撤销/重做时只对这些 propPath 做局部更新；
@@ -104,18 +113,29 @@ class Editor extends BaseService {
     stageLoading: true,
     highlightNode: null,
     modifiedNodeIds: new Map(),
+    invalidNodeIds: new Map(),
     pageLength: 0,
     pageFragmentLength: 0,
     disabledMultiSelect: false,
     alwaysMultiSelect: false,
   });
   private selectionBeforeOp: Id[] | null = null;
+  /**
+   * 操作前的节点校验错误快照，与 selectionBeforeOp 同时在 captureSelectionBeforeOp 中捕获，
+   * 供 pushOpHistory 写入 step.extra.invalidNodeIdsBefore，用于撤销时还原到「操作前」的错误状态。
+   */
+  private invalidNodeIdsBeforeOp: Map<Id, NodeInvalidInfo> | null = null;
   /**
    * 最近一次 pushOpHistory 写入的历史记录 uuid。
    * 供 *AndGetHistoryId 系列方法在调用普通操作后取回本次产生的历史记录 id；
    * 普通操作不会读取它，调用前由 *AndGetHistoryId 重置为 null。
    */
   private lastPushedHistoryId: string | null = null;
+  /**
+   * 上一次 doAdd 的插入记忆：nodeId 为插入的节点，selectedId 为当时的选中节点。
+   * 仅在选中节点未变化时复用（连续 add / doNotSelect / 批量粘贴），选中变化后自动失效，无需手动清理。
+   */
+  private lastAdded: { selectedId: Id; nodeId: Id } | null = null;
 
   constructor() {
     super(
@@ -127,7 +147,7 @@ class Editor extends BaseService {
 
   /**
    * 设置当前指点节点配置
-   * @param name 'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'pageLength' | 'pageFragmentLength
+   * @param name 'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'invalidNodeIds' | 'pageLength' | 'pageFragmentLength
    * @param value MNode
    * @param options.historySource 设置 root 时，本次变更写入历史记录的「操作来源」（仅 name === 'root' 时生效）
    */
@@ -180,12 +200,15 @@ class Editor extends BaseService {
       }
 
       this.emit('root-change', value as StoreState['root'], preValue as StoreState['root'], options);
+
+      // 整体替换 DSL 后，清理不再存在于新 DSL 中的失效节点错误记录，避免残留误报。
+      this.pruneInvalidNodeIds();
     }
   }
 
   /**
    * 获取当前指点节点配置
-   * @param name  'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'pageLength' | 'pageFragmentLength'
+   * @param name  'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'invalidNodeIds' | 'pageLength' | 'pageFragmentLength'
    * @returns MNode
    */
   public get<K extends StoreStateKey>(name: K): StoreState[K] {
@@ -260,7 +283,7 @@ class Editor extends BaseService {
   public isOnDifferentPage(node: MNode): boolean {
     const currentPageId = this.get('page')?.id;
     if (currentPageId === undefined || currentPageId === null) return false;
-    if (isPage(node) || isPageFragment(node)) {
+    if (isPageOrFragment(node)) {
       return `${node.id}` !== `${currentPageId}`;
     }
     const nodePage = this.getNodeInfo(node.id, false).page;
@@ -391,7 +414,7 @@ class Editor extends BaseService {
     this.set('highlightNode', null);
   }
 
-  public async doAdd(node: MNode, parent: MContainer): Promise<MNode> {
+  public async doAdd(node: MNode, parent: MContainer, _options: DslOpOptions = {}): Promise<MNode> {
     const root = this.get('root');
 
     if (!root) throw new Error('root为空');
@@ -401,17 +424,20 @@ class Editor extends BaseService {
 
     if (!curNode) throw new Error('当前选中节点为空');
 
-    if ((parent.type === NodeType.ROOT || curNode?.type === NodeType.ROOT) && !(isPage(node) || isPageFragment(node))) {
+    if ((parent.type === NodeType.ROOT || curNode?.type === NodeType.ROOT) && !isPageOrFragment(node)) {
       throw new Error('app下不能添加组件');
     }
 
-    if (parent.id !== curNode.id && !(isPage(node) || isPageFragment(node))) {
-      const index = parent.items.indexOf(curNode);
-      parent.items?.splice(index + 1, 0, node);
-    } else {
-      // 新增节点添加到配置中
-      parent.items?.push(node);
-    }
+    // 连续 add 时接在上一个新增节点之后，否则接在当前选中节点之后；
+    // 锚点节点可能已不在 items 中（被删 / DSL 整体替换），回退到当前选中节点，都不在则追加到末尾
+    const anchorId = this.lastAdded?.selectedId === curNode.id ? this.lastAdded.nodeId : curNode.id;
+    const anchorIndex = isPageOrFragment(node)
+      ? -1
+      : Math.max(getNodeIndex(anchorId, parent), getNodeIndex(curNode.id, parent));
+    const insertIndex = anchorIndex < 0 ? parent.items.length : anchorIndex + 1;
+
+    parent.items.splice(insertIndex, 0, node);
+    this.lastAdded = { selectedId: curNode.id, nodeId: node.id };
 
     const layout = await this.getLayout(toRaw(parent), node as MNode);
     node.style = getInitPositionStyle(node.style, layout);
@@ -421,6 +447,7 @@ class Editor extends BaseService {
       parent: cloneDeep(parent),
       parentId: parent.id,
       root: cloneDeep(root),
+      index: insertIndex,
     });
 
     const newStyle = fixNodePosition(node, parent, stage);
@@ -439,24 +466,23 @@ class Editor extends BaseService {
    * 向指点容器添加组件节点
    * @param addConfig 将要添加的组件节点配置
    * @param parent 要添加到的容器组件节点配置，如果不设置，默认为当前选中的组件的父节点
-   * @param options 可选配置
-   * @param options.doNotSelect 添加后是否不更新当前选中节点（默认 false，添加后会选中新增的节点）
-   * @param options.doNotSwitchPage 添加后是否不切换当前页面（默认 false；新增页面 / 跨页新增时为 true 会跳过会引发页面切换的选中操作）
-   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
+   * @param options 可选配置，见 {@link DslOpOptions}
    * @returns 添加后的节点
    */
   public async add(
     addNode: AddMNode | MNode[],
     parent?: MContainer | null,
-    {
+    options: DslOpOptions = {},
+  ): Promise<MNode | MNode[]> {
+    this.captureSelectionBeforeOp();
+
+    const {
       doNotSelect = false,
       doNotSwitchPage = false,
       doNotPushHistory = false,
       historyDescription,
       historySource,
-    }: DslOpOptions = {},
-  ): Promise<MNode | MNode[]> {
-    this.captureSelectionBeforeOp();
+    } = options;
 
     const stage = this.get('stage');
 
@@ -472,17 +498,15 @@ class Editor extends BaseService {
       addNodes.push(...addNode);
     }
 
-    const newNodes = await Promise.all(
-      addNodes.map((node) => {
-        const root = this.get('root');
-        if ((isPage(node) || isPageFragment(node)) && root) {
-          return this.doAdd(node, root);
-        }
-        const parentNode = parent ?? getAddParent(node);
-        if (!parentNode) throw new Error('未找到父元素');
-        return this.doAdd(node, parentNode);
-      }),
-    );
+    // 必须串行：每个节点的插入位置依赖上一个已插入的节点，并行时插入顺序会受
+    // doAdd 前置耗时（如异步 beforeDoAdd 插件钩子）影响而错乱
+    const newNodes: MNode[] = [];
+    for (const node of addNodes) {
+      const root = this.get('root');
+      const parentNode = isPageOrFragment(node) && root ? root : (parent ?? getAddParent(node));
+      if (!parentNode) throw new Error('未找到父元素');
+      newNodes.push(await this.doAdd(node, parentNode, options));
+    }
 
     if (newNodes.length > 1) {
       // 多选时只要任一新增节点位于非当前页面，触发的 multiSelect 就会引起页面切换
@@ -511,7 +535,7 @@ class Editor extends BaseService {
       }
     }
 
-    if (!(isPage(newNodes[0]) || isPageFragment(newNodes[0]))) {
+    if (!isPageOrFragment(newNodes[0])) {
       const pageForOp = this.getNodeInfo(newNodes[0].id, false).page;
       if (!doNotPushHistory) {
         const parentId = (this.getParentById(newNodes[0].id, false) ?? this.get('root'))!.id;
@@ -535,6 +559,18 @@ class Editor extends BaseService {
     }
 
     this.emit('add', newNodes);
+    this.emit('change', {
+      type: 'add',
+      data: newNodes.map((node) => ({ node, page: this.getPageOfNode(node.id) })),
+      historySource,
+      doNotPushHistory,
+    });
+
+    // 页面 / 页面片新增不入历史栈（见上方 isPageOrFragment 分支），这里合并补发一次结构变更通知
+    const addedPages = newNodes.filter((node) => isPageOrFragment(node)) as (MPage | MPageFragment)[];
+    if (addedPages.length) {
+      historyService.notifyPageStructureChange({ add: addedPages, remove: [] });
+    }
 
     return Array.isArray(addNode) ? newNodes : newNodes[0];
   }
@@ -554,12 +590,14 @@ class Editor extends BaseService {
 
     if (typeof index !== 'number' || index === -1) throw new Error('找不要删除的节点');
 
-    parent.items?.splice(index, 1);
     const stage = this.get('stage');
-    stage?.remove({ id: node.id, parentId: parent.id, root: cloneDeep(root) });
+    const currentPage = this.get('page');
+    const isDeletingCurrentPage = isPageOrFragment(node) && !!currentPage && `${currentPage.id}` === `${node.id}`;
+
+    parent.items?.splice(index, 1);
 
     // 始终清理已删除节点在 state 中的残留引用：
-    // - 即使后续会调用 selectDefault / select(parent) 覆盖，跳过这些调用（doNotSelect / doNotSwitchPage）时也不能让 state 持有已删除节点
+    // - 即使后续会调用 select 覆盖，跳过这些调用（doNotSelect / doNotSwitchPage）时也不能让 state 持有已删除节点
     const selectedNodes = this.get('nodes');
     const removedSelectedIndex = selectedNodes.findIndex((n: MNode) => `${n.id}` === `${node.id}`);
     if (removedSelectedIndex !== -1) {
@@ -567,38 +605,44 @@ class Editor extends BaseService {
       nextSelected.splice(removedSelectedIndex, 1);
       this.set('nodes', nextSelected);
     }
-    if (isPage(node) || isPageFragment(node)) {
-      const currentPage = this.get('page');
-      if (currentPage && `${currentPage.id}` === `${node.id}`) {
-        this.set('page', null);
-      }
-    }
-
-    const selectDefault = async (pages: MNode[]) => {
-      if (pages[0]) {
-        await this.select(pages[0]);
-        stage?.select(pages[0].id);
-      } else {
-        this.selectRoot();
-      }
-    };
 
+    const removeData = { id: node.id, parentId: parent.id, root: cloneDeep(root) };
     const rootItems = root.items || [];
-
-    if (isPage(node)) {
-      this.state.pageLength -= 1;
-
-      // 删除页面后默认会切到首个剩余页面（selectDefault），doNotSwitchPage 时跳过这次自动切换
-      if (!doNotSelect && !doNotSwitchPage) {
-        await selectDefault(rootItems);
+    // 删非当前页时画布不应该变动，所以只有删的是当前页才重新选中
+    const shouldReselect = isDeletingCurrentPage && !doNotSelect && !doNotSwitchPage;
+    // 还有剩余页面才能切过去，否则退回选中 root
+    const shouldSwitchPage = shouldReselect && rootItems.length > 0;
+
+    if (isPageOrFragment(node)) {
+      if (isPage(node)) {
+        this.state.pageLength -= 1;
+      } else {
+        this.state.pageFragmentLength -= 1;
       }
-    } else if (isPageFragment(node)) {
-      this.state.pageFragmentLength -= 1;
 
-      if (!doNotSelect && !doNotSwitchPage) {
-        await selectDefault(rootItems);
+      if (shouldSwitchPage) {
+        // runtime 收到页面删除时会销毁当前渲染的 page 实例，必须先把画布切到剩余页面再通知删除，
+        // 否则画布会被清空，且要等下一次 updatePageId 才能恢复。
+        // nextTick 用于等 Stage 的 page watch 把新页面 id 同步给 runtime。
+        await this.select(rootItems[0]);
+        stage?.select(rootItems[0].id);
+        await nextTick();
+        stage?.remove(removeData);
+      } else {
+        // page 置空会让 Workspace 卸载 Stage 并销毁 renderer，删除通知必须在卸载前发出，
+        // 且不能 await：runtime 未 ready 时 getRuntime 的监听会随 destroy 一起被移除，永远不会 resolve
+        stage?.remove(removeData);
+
+        if (shouldReselect) {
+          // 页面已全部删完
+          this.selectRoot();
+        } else if (isDeletingCurrentPage) {
+          this.set('page', null);
+        }
       }
     } else {
+      stage?.remove(removeData);
+
       if (!doNotSelect) {
         await this.select(parent);
         stage?.select(parent.id);
@@ -621,23 +665,18 @@ class Editor extends BaseService {
    * @param options.doNotSwitchPage 删除后是否不切换当前页面（默认 false；删除页面 / 页面片段时为 true 会跳过自动切换到首个剩余页面）
    * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    */
-  public async remove(
-    nodeOrNodeList: MNode | MNode[],
-    {
-      doNotSelect = false,
-      doNotSwitchPage = false,
-      doNotPushHistory = false,
-      historyDescription,
-      historySource,
-    }: DslOpOptions = {},
-  ): Promise<void> {
+  public async remove(nodeOrNodeList: MNode | MNode[], options: DslOpOptions = {}): Promise<void> {
+    const { doNotPushHistory = false, historyDescription, historySource } = options;
     this.captureSelectionBeforeOp();
 
     const nodes = Array.isArray(nodeOrNodeList) ? nodeOrNodeList : [nodeOrNodeList];
 
+    // 删除后节点已从树中移除，无法再反查所属 page，这里在删除前先逐个捕获用于 `change` 事件
+    const changeItems = nodes.map((node) => ({ node, page: this.getPageOfNode(node.id) }));
+
     const removedItems: StepDiffItem<MNode>[] = [];
     let pageForOp: { name: string; id: Id } | null = null;
-    if (!(isPage(nodes[0]) || isPageFragment(nodes[0]))) {
+    if (!isPageOrFragment(nodes[0])) {
       for (const n of nodes) {
         const { parent, node: curNode, page } = this.getNodeInfo(n.id, false);
         if (parent && curNode) {
@@ -654,7 +693,10 @@ class Editor extends BaseService {
       }
     }
 
-    await Promise.all(nodes.map((node) => this.doRemove(node, { doNotSelect, doNotSwitchPage })));
+    await Promise.all(nodes.map((node) => this.doRemove(node, options)));
+
+    // 删除节点时同步清理其（含子树）的校验错误记录；置于 pushOpHistory 之前，使历史快照与本次删除对齐。
+    this.removeInvalidNodesBySubtree(nodes);
 
     if (removedItems.length > 0 && pageForOp) {
       if (!doNotPushHistory) {
@@ -670,12 +712,20 @@ class Editor extends BaseService {
     }
 
     this.emit('remove', nodes);
+    this.emit('change', { type: 'remove', data: changeItems, historySource, doNotPushHistory });
+
+    // 页面 / 页面片删除不入历史栈（见上方 isPageOrFragment 分支），这里合并补发一次结构变更通知
+    const removedPages = nodes.filter((node) => isPageOrFragment(node)) as (MPage | MPageFragment)[];
+    if (removedPages.length) {
+      historyService.notifyPageStructureChange({ add: [], remove: removedPages });
+    }
   }
 
   public async doUpdate(
     config: MNode,
-    { changeRecords = [], historySource }: { changeRecords?: ChangeRecord[]; historySource?: HistoryOpSource } = {},
+    data: UpdateOptions = {},
   ): Promise<{ newNode: MNode; oldNode: MNode; changeRecords?: ChangeRecord[] }> {
+    const { changeRecords = [], historySource, replace = false } = data;
     const root = this.get('root');
     if (!root) throw new Error('root为空');
 
@@ -687,9 +737,14 @@ class Editor extends BaseService {
 
     const node = toRaw(info.node);
 
-    let newConfig = await toggleFixedPosition(toRaw(config), node, info.path, this.getLayout);
+    // replace=true 时跳过 toggleFixedPosition / mergeWith / setChildrenLayout，直接用传入配置整节点替换
+    let newConfig = replace
+      ? cloneDeep(toRaw(config))
+      : await toggleFixedPosition(toRaw(config), node, info.path, this.getLayout);
 
-    newConfig = mergeWith(cloneDeep(node), newConfig, editorNodeMergeCustomizer);
+    if (!replace) {
+      newConfig = mergeWith(cloneDeep(node), newConfig, editorNodeMergeCustomizer);
+    }
 
     if (!newConfig.type) throw new Error('配置缺少type值');
 
@@ -710,10 +765,12 @@ class Editor extends BaseService {
 
     if (!parentNodeItems || typeof index === 'undefined' || index === -1) throw new Error('更新的节点未找到');
 
-    const newLayout = await this.getLayout(newConfig);
-    const layout = await this.getLayout(node);
-    if (Array.isArray(newConfig.items) && newLayout !== layout) {
-      newConfig = setChildrenLayout(newConfig as MContainer, newLayout);
+    if (!replace) {
+      const newLayout = await this.getLayout(newConfig);
+      const layout = await this.getLayout(node);
+      if (Array.isArray(newConfig.items) && newLayout !== layout) {
+        newConfig = setChildrenLayout(newConfig as MContainer, newLayout);
+      }
     }
 
     parentNodeItems[index] = newConfig;
@@ -727,7 +784,7 @@ class Editor extends BaseService {
     }
 
     // 只有被更新节点正好是当前选中页面时才同步 state.page，避免「更新非当前页」误将编辑器切到该页
-    if (isPage(newConfig) || isPageFragment(newConfig)) {
+    if (isPageOrFragment(newConfig)) {
       const currentPage = this.get('page');
       if (currentPage && `${currentPage.id}` === `${newConfig.id}`) {
         this.set('page', newConfig as MPage | MPageFragment);
@@ -747,26 +804,20 @@ class Editor extends BaseService {
    * 更新节点
    * update后会触发依赖收集，收集完后会掉stage.update方法
    * @param config 新的节点配置，配置中需要有id信息
-   * @param data 额外数据
-   * @param data.changeRecords 单节点 form 端变更记录（多节点场景下被忽略，使用 changeRecordList）
-   * @param data.changeRecordList 多节点 form 端变更记录列表，按 config 数组同序对应每个节点；优先级高于 changeRecords
-   * @param data.doNotPushHistory 是否不写入历史记录（默认 false）
-   * @param data.historyDescription 入栈时附带的人类可读描述，用于历史面板展示（不影响 undo/redo 行为）
+   * @param data 额外数据，见 {@link UpdateOptions}
    * @returns 更新后的节点配置
    */
-  public async update(
-    config: MNode | MNode[],
-    data: {
-      changeRecords?: ChangeRecord[];
-      changeRecordList?: ChangeRecord[][];
-      doNotPushHistory?: boolean;
-      historyDescription?: string;
-      historySource?: HistoryOpSource;
-    } = {},
-  ): Promise<MNode | MNode[]> {
+  public async update(config: MNode | MNode[], data: UpdateOptions = {}): Promise<MNode | MNode[]> {
     this.captureSelectionBeforeOp();
 
-    const { doNotPushHistory = false, changeRecordList, changeRecords, historyDescription, historySource } = data;
+    const {
+      doNotPushHistory = false,
+      changeRecordList,
+      changeRecords,
+      historyDescription,
+      historySource,
+      invalidInfo,
+    } = data;
 
     const nodes = Array.isArray(config) ? config : [config];
 
@@ -775,10 +826,13 @@ class Editor extends BaseService {
     const updateData = await Promise.all(
       nodes.map((node, index) => {
         const recordsForNode = changeRecordList ? (changeRecordList[index] ?? []) : (changeRecords ?? []);
-        return this.doUpdate(node, { changeRecords: recordsForNode, historySource });
+        return this.doUpdate(node, { ...data, changeRecords: recordsForNode });
       }),
     );
 
+    // 校验错误信息在 pushOpHistory 之前落库，保证历史快照包含本次变更对应的错误状态。
+    this.applyInvalidInfo(config, invalidInfo);
+
     if (updateData[0].oldNode?.type !== NodeType.ROOT) {
       const curNodes = this.get('nodes');
       if (curNodes.length) {
@@ -805,6 +859,12 @@ class Editor extends BaseService {
     }
 
     this.emit('update', updateData);
+    this.emit('change', {
+      type: 'update',
+      data: updateData.map((node) => ({ node, page: this.getPageOfNode(node.newNode.id) })),
+      historySource,
+      doNotPushHistory,
+    });
     return Array.isArray(config) ? updateData.map((item) => item.newNode) : updateData[0].newNode;
   }
 
@@ -1046,6 +1106,13 @@ class Editor extends BaseService {
     }
 
     this.emit('move-layer', offset);
+    this.emit('change', {
+      type: 'move-layer',
+      data: [{ node, page: this.getPageOfNode(node.id) }],
+      offset,
+      historySource,
+      doNotPushHistory,
+    });
   }
 
   /**
@@ -1074,7 +1141,7 @@ class Editor extends BaseService {
     }: DslOpOptions = {},
   ): Promise<MNode | MNode[]> {
     const isBatch = Array.isArray(config);
-    const configs = (isBatch ? config : [config]).filter((item) => !(isPage(item) || isPageFragment(item)));
+    const configs = (isBatch ? config : [config]).filter((item) => !isPageOrFragment(item));
 
     if (configs.length === 0) {
       throw new Error('没有可移动的节点');
@@ -1225,6 +1292,14 @@ class Editor extends BaseService {
     }
 
     this.emit('drag-to', { targetIndex, configs, targetParent });
+    this.emit('change', {
+      type: 'drag-to',
+      data: configs.map((node) => ({ node, page: this.getPageOfNode(node.id) })),
+      targetIndex,
+      targetParent,
+      historySource,
+      doNotPushHistory,
+    });
   }
 
   // #region AndGetHistoryId
@@ -1260,13 +1335,7 @@ class Editor extends BaseService {
   /** 等价于 {@link update}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
   public async updateAndGetHistoryId(
     config: MNode | MNode[],
-    data: {
-      changeRecords?: ChangeRecord[];
-      changeRecordList?: ChangeRecord[][];
-      doNotPushHistory?: boolean;
-      historyDescription?: string;
-      historySource?: HistoryOpSource;
-    } = {},
+    data: UpdateOptions = {},
   ): Promise<DslOpWithHistoryIdsResult<MNode | MNode[]>> {
     this.lastPushedHistoryId = null;
     const result = await this.update(config, data);
@@ -1519,6 +1588,7 @@ class Editor extends BaseService {
     this.set('stage', null);
     this.set('highlightNode', null);
     this.set('modifiedNodeIds', new Map());
+    this.set('invalidNodeIds', new Map());
     this.set('pageLength', 0);
   }
 
@@ -1532,6 +1602,62 @@ class Editor extends BaseService {
     this.get('modifiedNodeIds').clear();
   }
 
+  /**
+   * 记录（或覆盖）某个节点在指定来源（属性表单 / 样式表单）上的校验错误信息。
+   * @param id 节点 id
+   * @param source 错误来源：'props'（属性表单）| 'style'（样式表单）
+   * @param message 错误文案（可能是包含 <br> 的 HTML）
+   */
+  public setInvalidNode(id: Id, source: NodeInvalidSource, message: string) {
+    const map = this.get('invalidNodeIds');
+    const info: NodeInvalidInfo = { ...(map.get(id) || {}) };
+    info[source] = message;
+    map.set(id, info);
+    this.emit('invalid-node-change', map);
+  }
+
+  /**
+   * 删除节点的校验错误记录。
+   * @param id 节点 id
+   * @param source 指定来源则仅删除该来源；不传则删除该节点全部来源的错误
+   */
+  public deleteInvalidNode(id: Id, source?: NodeInvalidSource) {
+    const map = this.get('invalidNodeIds');
+    if (!map.has(id)) return;
+
+    if (!source) {
+      map.delete(id);
+    } else {
+      const info: NodeInvalidInfo = { ...(map.get(id) || {}) };
+      delete info[source];
+      if (info.props || info.style) {
+        map.set(id, info);
+      } else {
+        map.delete(id);
+      }
+    }
+
+    this.emit('invalid-node-change', map);
+  }
+
+  /** 获取当前存在校验错误的节点错误 Map（key 为节点 id） */
+  public getInvalidNodeIds(): Map<Id, NodeInvalidInfo> {
+    return this.get('invalidNodeIds');
+  }
+
+  /** 获取指定节点的校验错误信息 */
+  public getInvalidNodeInfo(id: Id): NodeInvalidInfo | undefined {
+    return this.get('invalidNodeIds').get(id);
+  }
+
+  /** 清空全部校验错误记录 */
+  public resetInvalidNodeId() {
+    const map = this.get('invalidNodeIds');
+    if (map.size === 0) return;
+    map.clear();
+    this.emit('invalid-node-change', map);
+  }
+
   public usePlugin(options: AsyncHookPlugin<AsyncMethodName, Editor>): void {
     super.usePlugin(options);
   }
@@ -1554,13 +1680,92 @@ class Editor extends BaseService {
     return super.emit(eventName, ...args);
   }
 
+  /**
+   * 应用一次属性面板提交携带的校验错误信息（在写入历史记录之前调用，使历史快照与本次变更对齐）。
+   * - invalidInfo 为空（调用方未携带）：认为本次更新对应的节点已无校验错误，清除其全部来源的错误；
+   * - error 非空则记录错误，为空则清除对应来源的错误。
+   */
+  private applyInvalidInfo(
+    config: MNode | MNode[],
+    invalidInfo?: { id: Id; source: NodeInvalidSource; error?: string },
+  ) {
+    if (!invalidInfo) {
+      // 调用方未携带 invalidInfo：本次更新对应节点不应再保留校验错误，清除其全部来源。
+      const ids = (Array.isArray(config) ? config : [config])
+        .map((node) => node.id)
+        .filter((id): id is Id => id !== undefined);
+      ids.forEach((id) => this.deleteInvalidNode(id));
+      return;
+    }
+    const { id, source, error } = invalidInfo;
+    if (error) {
+      this.setInvalidNode(id, source, error);
+    } else {
+      this.deleteInvalidNode(id, source);
+    }
+  }
+
+  /** 删除被移除节点（含其子树）的校验错误记录，避免残留误报 */
+  private removeInvalidNodesBySubtree(nodes: MNode[]) {
+    const map = this.get('invalidNodeIds');
+    if (map.size === 0) return;
+
+    let changed = false;
+    nodes.forEach((node) => {
+      traverseNode(node, (n) => {
+        if (n.id !== undefined && map.delete(n.id)) {
+          changed = true;
+        }
+      });
+    });
+
+    if (changed) {
+      this.emit('invalid-node-change', map);
+    }
+  }
+
+  /** 清理不在当前 DSL 中的失效节点错误记录（用于整体替换 root 后） */
+  private pruneInvalidNodeIds() {
+    const map = this.get('invalidNodeIds');
+    if (map.size === 0) return;
+
+    let changed = false;
+    for (const id of [...map.keys()]) {
+      if (!this.getNodeById(id, false)) {
+        map.delete(id);
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      this.emit('invalid-node-change', map);
+    }
+  }
+
   private addModifiedNodeId(id: Id) {
     this.get('modifiedNodeIds').set(id, id);
   }
 
+  /**
+   * 获取指定节点所属的页面 / 页面片：
+   * - 普通节点返回其所在的 page；
+   * - 节点本身就是 page / pageFragment 时返回它自己；
+   * - 找不到时返回 null。
+   * 供 `change` 事件携带「变更节点对应的 page」（而非编辑器当前选中页）。
+   */
+  private getPageOfNode(id: Id): MPage | MPageFragment | null {
+    const { node, page } = this.getNodeInfo(id, false);
+    if (page) return page;
+    if (node && isPageOrFragment(node)) return node as MPage | MPageFragment;
+    return null;
+  }
+
   private captureSelectionBeforeOp() {
     if (this.selectionBeforeOp) return;
     this.selectionBeforeOp = this.get('nodes').map((n) => n.id);
+    // 与选区快照同步捕获「操作前」的校验错误状态；因 applyInvalidInfo 会在 pushOpHistory 前修改 invalidNodeIds，
+    // 必须在此（操作最开始）留存操作前快照，供 undo 还原。
+    this.invalidNodeIdsBeforeOp = new Map(this.get('invalidNodeIds'));
   }
 
   /**
@@ -1579,6 +1784,10 @@ class Editor extends BaseService {
     const nextMap = new Map(nextPages.map((p) => [`${p.id}`, p]));
     const indexInItems = (root: MApp, id: Id) => (root.items ?? []).findIndex((item) => `${item.id}` === `${id}`);
 
+    // 收集本次整体替换中增删的页面，循环结束后合并为一次结构变更通知（避免逐页派发多个事件）
+    const addedPages: (MPage | MPageFragment)[] = [];
+    const removedPages: (MPage | MPageFragment)[] = [];
+
     nextPages.forEach((nextPage) => {
       const prevPage = prevMap.get(`${nextPage.id}`);
       if (!prevPage) {
@@ -1588,6 +1797,7 @@ class Editor extends BaseService {
           { newSchema: cloneDeep(toRaw(nextPage)), parentId: nextRoot.id, index: indexInItems(nextRoot, nextPage.id) },
           source,
         );
+        addedPages.push(nextPage);
       } else if (!isEqual(toRaw(prevPage), toRaw(nextPage))) {
         this.pushPageDiffStep(
           'update',
@@ -1606,8 +1816,13 @@ class Editor extends BaseService {
           { oldSchema: cloneDeep(toRaw(prevPage)), parentId: preRoot.id, index: indexInItems(preRoot, prevPage.id) },
           source,
         );
+        removedPages.push(prevPage);
       }
     });
+
+    if (addedPages.length || removedPages.length) {
+      historyService.notifyPageStructureChange({ add: addedPages, remove: removedPages });
+    }
   }
 
   /**
@@ -1667,6 +1882,9 @@ class Editor extends BaseService {
         selectedBefore: this.selectionBeforeOp ?? [],
         selectedAfter: this.get('nodes').map((n) => n.id),
         modifiedNodeIds: new Map(this.get('modifiedNodeIds')),
+        // 方向性双快照：undo 还原「操作前」错误状态，redo 还原「操作后」错误状态。
+        invalidNodeIdsBefore: new Map(this.invalidNodeIdsBeforeOp ?? this.get('invalidNodeIds')),
+        invalidNodeIdsAfter: new Map(this.get('invalidNodeIds')),
       },
       diff,
     };
@@ -1679,16 +1897,19 @@ class Editor extends BaseService {
     const historyId = pushed ? step.uuid : null;
     this.lastPushedHistoryId = historyId;
     this.selectionBeforeOp = null;
+    this.invalidNodeIdsBeforeOp = null;
     return historyId;
   }
 
   /**
    * 应用历史操作（撤销 / 重做）
    *
-   * 所有 DSL 修改都走 `editor.add / remove / update`，并通过 `doNotPushHistory` 阻止再次入栈、
-   * `doNotSelect / doNotSwitchPage` 让选区由方法末尾的统一逻辑兜底。
+   * 删除 / 更新类修改走 `editor.remove / update`，并通过 `doNotPushHistory` 阻止再次入栈、
+   * `doNotSelect / doNotSwitchPage` 让选区由方法末尾的统一逻辑兜底；
+   * 「重新插回节点」（撤销 remove / 重做 add）需按 step 记录的 parentId / index 精确还原，
+   * 不走 this.add，由手工 splice + stage.add 完成后补发等价的 add / change 事件（见 emitHistoryInsertEvents）。
    *
-   * 注意：这些公开方法会发出 add / remove / update 事件，业务侧若需要区分"用户操作"与"撤销重做触发"，
+   * 注意：这些路径都会发出 add / remove / update / change 事件，业务侧若需要区分"用户操作"与"撤销重做触发"，
    * 请监听 `history-change` 事件配合判断。
    *
    * @param step 操作记录
@@ -1701,7 +1922,14 @@ class Editor extends BaseService {
     const stage = this.get('stage');
     if (!root) return;
 
-    const commonOpts = { doNotSelect: true, doNotSwitchPage: true, doNotPushHistory: true } as const;
+    // 撤销/重做内部复用 add/remove/update，透传被应用 step 上记录的 source，
+    // 使其触发的 change 事件同样携带「历史来源」
+    const commonOpts = {
+      doNotSelect: true,
+      doNotSwitchPage: true,
+      doNotPushHistory: true,
+      historySource: step.source,
+    } as const;
 
     switch (step.opType) {
       case 'add': {
@@ -1717,46 +1945,56 @@ class Editor extends BaseService {
           }
         } else {
           // 重做 add：按记录的 parentId / index 把节点重新插回父容器。
-          // 按目标 index 升序逐个插入，先小后大避免索引漂移
+          // 按目标 index 升序逐个插入，先小后大避免索引漂移。
+          // 不走 this.add：doAdd 依赖当前选中节点（无选区时直接抛错），且只能插到选中节点之后 / 末尾，
+          // 无法按 step 记录的 parentId / index 精确还原，还会重算 style 破坏已记录的终态位置。
           const sorted = [...items].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+          const addedNodes: MNode[] = [];
           for (const { newSchema, parentId, index } of sorted) {
             if (!newSchema || parentId === undefined) continue;
             const parent = this.getNodeById(parentId, false) as MContainer | null;
             if (parent?.items) {
-              if (typeof index === 'number' && index >= 0 && index < parent.items.length) {
-                parent.items.splice(index, 0, cloneDeep(newSchema));
-              } else {
-                parent.items.push(cloneDeep(newSchema));
-              }
+              const addedNode = cloneDeep(newSchema);
+              const insertIndex = clampIndex(index, parent.items.length);
+              parent.items.splice(insertIndex, 0, addedNode);
+              addedNodes.push(addedNode);
               await stage?.add({
                 config: cloneDeep(newSchema),
                 parent: cloneDeep(parent),
                 parentId: parent.id,
                 root: cloneDeep(root),
+                index: insertIndex,
               });
             }
           }
+          this.emitHistoryInsertEvents(addedNodes, step.source);
         }
         break;
       }
       case 'remove': {
         const items = step.diff ?? [];
         if (reverse) {
-          // 撤销 remove：按原 index 升序逐个插回（先小后大避免索引漂移）
+          // 撤销 remove：按原 index 升序逐个插回（先小后大避免索引漂移）；不走 this.add 的原因同上
           const sorted = [...items].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+          const addedNodes: MNode[] = [];
           for (const { oldSchema, parentId, index } of sorted) {
             if (!oldSchema || parentId === undefined) continue;
             const parent = this.getNodeById(parentId, false) as MContainer | null;
             if (parent?.items) {
-              parent.items.splice(index ?? parent.items.length, 0, cloneDeep(oldSchema));
+              const addedNode = cloneDeep(oldSchema);
+              const insertIndex = clampIndex(index, parent.items.length);
+              parent.items.splice(insertIndex, 0, addedNode);
+              addedNodes.push(addedNode);
               await stage?.add({
                 config: cloneDeep(oldSchema),
                 parent: cloneDeep(parent),
                 parentId,
                 root: cloneDeep(root),
+                index: insertIndex,
               });
             }
           }
+          this.emitHistoryInsertEvents(addedNodes, step.source);
         } else {
           // 重做 remove：再删一次
           for (const { oldSchema } of items) {
@@ -1796,7 +2034,7 @@ class Editor extends BaseService {
             return cloneDeep(reverse ? oldNode : newNode);
           });
         if (configs.length) {
-          await this.update(configs, { doNotPushHistory: true });
+          await this.update(configs, { doNotPushHistory: true, historySource: step.source });
         }
         break;
       }
@@ -1804,6 +2042,15 @@ class Editor extends BaseService {
 
     this.set('modifiedNodeIds', step.extra?.modifiedNodeIds ?? new Map());
 
+    // 还原校验错误标记：因 undo/redo 复用同一 step，需按方向取「操作前 / 操作后」快照——
+    // undo(reverse=true) 还原到操作前的错误状态（撤销一个「校验失败」的改动后错误消失），
+    // redo(reverse=false) 还原到操作后的错误状态（重做后错误恢复）。
+    // 浅拷贝一份以隔离历史快照，避免后续 set/deleteInvalidNode 反向污染 step.extra。
+    const invalidToRestore =
+      (reverse ? step.extra?.invalidNodeIdsBefore : step.extra?.invalidNodeIdsAfter) ?? new Map();
+    this.set('invalidNodeIds', new Map(invalidToRestore));
+    this.emit('invalid-node-change', this.get('invalidNodeIds'));
+
     const page = toRaw(this.get('page'));
     if (page) {
       const selectIds = (reverse ? step.extra?.selectedBefore : step.extra?.selectedAfter) ?? [];
@@ -1826,6 +2073,22 @@ class Editor extends BaseService {
   private selectedConfigExceptionHandler(config: MNode | Id): EditorNodeInfo {
     return resolveSelectedNode(config, (id) => this.getNodeInfo(id), this.state.root?.id);
   }
+
+  /**
+   * 撤销 remove / 重做 add 通过手工 splice 按 step 记录的 parentId / index 精确还原节点（不走 this.add，原因见调用处注释），
+   * 这里补齐与 this.add 等价的 add / change 事件，保证撤销/重做路径的事件行为与正向操作一致。
+   */
+  private emitHistoryInsertEvents(nodes: MNode[], source?: HistoryOpSource) {
+    if (!nodes.length) return;
+    this.emit('add', nodes);
+    this.emit('change', {
+      type: 'add',
+      data: nodes.map((node) => ({ node, page: this.getPageOfNode(node.id) })),
+      historySource: source,
+      // 撤销/重做本身不再写入历史记录
+      doNotPushHistory: true,
+    });
+  }
 }
 
 export type EditorService = Editor;