@tmagic/editor 1.8.0-manmanyu.11 → 1.8.0-manmanyu.13

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-manmanyu.11",
+  "version": "1.8.0-manmanyu.13",
   "name": "@tmagic/editor",
   "type": "module",
   "sideEffects": [
@@ -58,11 +58,11 @@
     "moveable": "^0.53.0",
     "serialize-javascript": "^7.0.0",
     "sortablejs": "^1.15.6",
-    "@tmagic/design": "1.8.0-manmanyu.11",
-    "@tmagic/form": "1.8.0-manmanyu.11",
-    "@tmagic/stage": "1.8.0-manmanyu.11",
-    "@tmagic/utils": "1.8.0-manmanyu.11",
-    "@tmagic/table": "1.8.0-manmanyu.11"
+    "@tmagic/utils": "1.8.0-manmanyu.13",
+    "@tmagic/form": "1.8.0-manmanyu.13",
+    "@tmagic/table": "1.8.0-manmanyu.13",
+    "@tmagic/stage": "1.8.0-manmanyu.13",
+    "@tmagic/design": "1.8.0-manmanyu.13"
   },
   "devDependencies": {
     "@types/events": "^3.0.3",
@@ -76,7 +76,7 @@
     "type-fest": "^5.2.0",
     "typescript": "^6.0.3",
     "vue": "^3.5.38",
-    "@tmagic/core": "1.8.0-manmanyu.11"
+    "@tmagic/core": "1.8.0-manmanyu.13"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/components/CompareForm.vue

@@ -24,7 +24,6 @@ import { isEqual } from 'lodash-es';
 import { type CodeBlockContent, type DataSourceSchema, HookType, type MNode } from '@tmagic/core';
 import { type FormConfig, type FormState, type FormValue, MForm } from '@tmagic/form';
 
-import { useServices } from '@editor/hooks/use-services';
 import type { CompareCategory, CompareFormLoadConfig, Services } from '@editor/type';
 import { getCodeBlockFormConfig } from '@editor/utils/code-block';
 
@@ -76,18 +75,15 @@ const props = withDefaults(
      */
     loadConfig?: CompareFormLoadConfig;
     /** 编辑器服务集合，由调用方传入（不再通过 inject('services') 获取）。 */
-    services: Services;
+    services?: Services;
   }>(),
   {
     category: 'node',
     labelWidth: '120px',
-    services: () => useServices(),
     extendState: (state: FormState) => state,
   },
 );
 
-const { propsService, dataSourceService, codeBlockService, editorService } = props.services;
-
 provide('services', props.services);
 
 const config = ref<FormConfig>([]);
@@ -192,17 +188,21 @@ const mergedExtendState = (state: FormState) => {
  * 作为 ctx.defaultLoadConfig 透传给自定义 `loadConfig`，方便复用与二次加工。
  */
 const defaultLoadConfig = async (): Promise<FormConfig> => {
+  if (!props.services) {
+    return [];
+  }
+
   switch (props.category) {
     case 'node': {
       if (!props.type) {
         return [];
       }
       return removeStyleDisplayConfig(
-        await propsService.getPropsConfig(props.type, { node: props.value as unknown as MNode }),
+        await props.services.propsService.getPropsConfig(props.type, { node: props.value as unknown as MNode }),
       );
     }
     case 'data-source': {
-      const config = dataSourceService.getFormConfig(props.type || 'base');
+      const config = props.services.dataSourceService.getFormConfig(props.type || 'base');
       // 数据源表单外层 tab 的「数据定义」项 status 为 'fields'，tab-pane name 随之为 'fields'。
       // 未显式设置 active 时，Tabs 默认取 '0'，与 'fields' 不匹配会导致打开弹窗时无默认激活项，
       // 这里与 DataSourceConfigPanel 保持一致，默认激活「数据定义」tab。
@@ -210,7 +210,7 @@ const defaultLoadConfig = async (): Promise<FormConfig> => {
     }
     case 'code-block': {
       return getCodeBlockFormConfig({
-        paramColConfig: codeBlockService.getParamsColConfig(),
+        paramColConfig: props.services.codeBlockService.getParamsColConfig(),
         // 通过传入 dataSourceType 间接表达"是数据源代码块"——在对比场景下 props.dataSourceType
         // 由调用方按 step 上下文显式传入，未传则视为普通代码块，「执行时机」字段隐藏。
         isDataSource: () => Boolean(props.dataSourceType),
@@ -258,11 +258,9 @@ const formRef = useTemplateRef<InstanceType<typeof MForm>>('form');
  * - services：整个 useServices() 返回的服务集合；
  * - stage：当前 editorService.get('stage') 的最新值。
  */
-const stage = computed(() => editorService.get('stage'));
-
 watchEffect(() => {
-  if (formRef.value) {
-    formRef.value.formState.stage = stage.value;
+  if (formRef.value && props.services) {
+    formRef.value.formState.stage = props.services.editorService.get('stage');
     formRef.value.formState.services = props.services;
   }
 });

package/src/layouts/history-list/BucketTab.vue

@@ -1,7 +1,7 @@
 <template>
   <div v-if="!buckets.length" class="m-editor-history-list-empty">暂无操作记录</div>
   <template v-else>
-    <div class="m-editor-history-list-toolbar">
+    <div v-if="config.showClear !== false" class="m-editor-history-list-toolbar">
       <span class="m-editor-history-list-clear" :title="`清空${config.title}的历史记录`" @click="$emit('clear')"
         >清空</span
       >
@@ -38,7 +38,7 @@ defineOptions({
 
 defineProps<{
   /**
-   * 该类历史的整体渲染配置（title / prefix / describe* / isStep* / showInitial / gotoEnabled），
+   * 该类历史的整体渲染配置（title / prefix / describe* / isStep* / showInitial / gotoEnabled / showClear），
    * 由父组件按业务类型注入并整体透传给 Bucket，避免逐项透传多个 props。
    */
   config: HistoryBucketConfig<T>;

package/src/layouts/history-list/HistoryDiffDialog.vue

@@ -21,7 +21,7 @@
           </TMagicRadioGroup>
 
           <TMagicRadioGroup v-model="mode" size="small" class="m-editor-history-diff-dialog-mode">
-            <TMagicRadioButton value="before">与修改前对比</TMagicRadioButton>
+            <TMagicRadioButton value="before" :disabled="!hasValue">与修改前对比</TMagicRadioButton>
             <TMagicRadioButton value="current" :disabled="!hasCurrent">与当前对比</TMagicRadioButton>
           </TMagicRadioGroup>
         </div>
@@ -81,7 +81,6 @@ import { TMagicButton, TMagicDialog, TMagicRadioButton, TMagicRadioGroup, TMagic
 import type { FormState } from '@tmagic/form';
 
 import CompareForm from '@editor/components/CompareForm.vue';
-import { useServices } from '@editor/hooks/use-services';
 import CodeEditor from '@editor/layouts/CodeEditor.vue';
 import type { CompareCategory, CompareFormLoadConfig, DiffDialogPayload, Services } from '@editor/type';
 
@@ -92,7 +91,7 @@ defineOptions({
 const props = withDefaults(
   defineProps<{
     /** 编辑器服务集合，由调用方传入（不再通过 inject('services') 获取）。 */
-    services: Services;
+    services?: Services;
     /**
      * 来自 Editor 顶层的 `extendFormState`，用于扩展 MForm.formState。
      * 透传给 CompareForm，从而让差异对比时表单 item 中依赖业务上下文的
@@ -111,7 +110,6 @@ const props = withDefaults(
     compareFormState?: FormState;
   }>(),
   {
-    services: () => useServices(),
     width: '900px',
   },
 );
@@ -161,6 +159,23 @@ const dialogTitle = computed(() => (props.onConfirm ? '确认回滚' : '查看
 
 const hasCurrent = computed(() => payload.value?.currentValue !== undefined && payload.value?.currentValue !== null);
 
+/** 是否存在该步「修改后的值」：不存在（如仅删除）时「与修改前对比」无意义，置灰禁用。 */
+const hasValue = computed(() => payload.value?.value !== undefined && payload.value?.value !== null);
+
+/** 指定模式当前是否可用：before 依赖「修改后的值」，current 依赖「当前值」。 */
+const isModeAvailable = (m: DiffMode): boolean => (m === 'current' ? hasCurrent.value : hasValue.value);
+
+/**
+ * 计算 open 时的初始对比模式：
+ * - 调用方通过 payload.mode 指定且该模式可用时，优先使用指定模式；
+ * - 否则没有「修改后的值」但有当前值时（「与修改前对比」不可用），默认进入「与当前对比」；
+ * - 其余情况默认「与修改前对比」。
+ */
+const resolveInitialMode = (specified?: DiffMode): DiffMode => {
+  if (specified && isModeAvailable(specified)) return specified;
+  return !hasValue.value && hasCurrent.value ? 'current' : 'before';
+};
+
 /** 左侧（旧/参照）值 */
 const leftValue = computed<Record<string, any>>(() => {
   if (!payload.value) return {};
@@ -214,8 +229,9 @@ const targetText = computed(() => {
 
 const open = (p: DiffDialogPayload) => {
   payload.value = p;
-  // 每次打开按需重置默认模式：有当前值时优先「与当前对比」更贴近"看现在差什么"，否则回退到默认
-  mode.value = 'before';
+  // 每次打开按 payload 重置对比模式（hasValue / hasCurrent 依赖 payload，需先赋值）：
+  // 优先使用 payload.mode 指定的模式；不可用或未指定时按数据自动推断。
+  mode.value = resolveInitialMode(p.mode);
   // 默认回到表单对比形态，避免残留上一次选择的源码模式
   viewMode.value = 'form';
   visible.value = true;

package/src/layouts/history-list/HistoryListPanel.vue

@@ -313,10 +313,10 @@ const onCodeBlockGotoInitial = (id: string | number) => {
 /**
  * 「单步回滚」与「查看差异」的完整逻辑收敛到 useHistoryRevert，面板与业务方共用：
  * 二者均由 useHistoryRevert 内部按需动态挂载 HistoryDiffDialog，
- * 业务方亦可直接 import useHistoryRevert(services) 调用，无需自行挂载任何弹窗。
+ * 业务方亦可直接 import useHistoryRevert(options, services) 调用，无需自行挂载任何弹窗。
  */
 const { onPageRevert, onDataSourceRevert, onCodeBlockRevert, onPageDiff, onDataSourceDiff, onCodeBlockDiff } =
-  useHistoryRevert(services, { extendState: extendFormState, getPropsPanelFormState });
+  useHistoryRevert({ extendState: extendFormState, getPropsPanelFormState }, services);
 
 /**
  * 把内存中（已清空对应类别后的）历史状态重新写回 IndexedDB，

package/src/layouts/history-list/useHistoryRevert.ts

@@ -76,7 +76,7 @@ interface MountedDiffDialog {
 const mountHistoryDiffDialog = async (
   options: Pick<UseHistoryRevertOptions, 'appContext' | 'extendState'> &
     CustomDiffFormOptions & {
-      services: Services;
+      services?: Services;
       isConfirm?: boolean;
       onClose?: () => void;
     },
@@ -94,6 +94,7 @@ const mountHistoryDiffDialog = async (
     loadConfig: options.loadConfig,
     selfDiffFieldTypes: options.selfDiffFieldTypes,
     compareFormState: options.compareFormState,
+    width: options.width,
     onClose: options.onClose,
   });
   if (options.appContext) {
@@ -125,7 +126,7 @@ const confirmRevertWithDiffDialog = async (
   payload: DiffDialogPayload,
   options: Pick<UseHistoryRevertOptions, 'appContext' | 'extendState'> &
     CustomDiffFormOptions & {
-      services: Services;
+      services?: Services;
     },
 ): Promise<boolean> => {
   const { instance, destroy } = await mountHistoryDiffDialog({
@@ -147,7 +148,7 @@ const viewHistoryDiffDialog = async (
   payload: DiffDialogPayload,
   options: Pick<UseHistoryRevertOptions, 'appContext' | 'extendState'> &
     CustomDiffFormOptions & {
-      services: Services;
+      services?: Services;
     },
 ): Promise<void> => {
   // onClose 在用户关闭弹窗时才触发，此时 handle.destroy 早已赋值。
@@ -184,16 +185,15 @@ const viewHistoryDiffDialog = async (
  * ```ts
  * import { useHistoryRevert } from '@tmagic/editor';
  *
- * const { onPageRevert, onPageDiff } = useHistoryRevert(editorRef.value); // editorRef.value 即 Editor 暴露的 services
+ * const { onPageRevert, onPageDiff } = useHistoryRevert({}, editorRef.value); // editorRef.value 即 Editor 暴露的 services
  * await onPageRevert(index); // 弹出差异 / 二次确认弹窗后回滚
  * onPageDiff(index); // 弹出只读差异弹窗查看前后值差异
  * ```
  */
-export const useHistoryRevert = (services: Services, options: UseHistoryRevertOptions = {}) => {
-  const { editorService, dataSourceService, codeBlockService, historyService } = services;
+export const useHistoryRevert = (options: UseHistoryRevertOptions = {}, services?: Services) => {
   // 自动捕获调用方所在组件的 appContext（在 setup 中调用时），业务方亦可显式覆盖。
   const appContext = options.appContext ?? getCurrentInstance()?.appContext ?? null;
-  const { extendState, getPropsPanelFormState } = options;
+  const { extendState, getPropsPanelFormState, dialogWidth } = options;
 
   /** 目标数据已被删除、无法回滚时的统一提示。 */
   const showRevertTargetMissing = () => {
@@ -217,7 +217,13 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
    */
   const runRevert = (payload: DiffDialogPayload | null, extra?: CustomDiffFormOptions): Promise<boolean> => {
     if (payload) {
-      return confirmRevertWithDiffDialog(payload, { appContext, extendState, services, ...extra });
+      return confirmRevertWithDiffDialog(payload, {
+        appContext,
+        extendState,
+        services,
+        ...extra,
+        width: extra?.width ?? dialogWidth,
+      });
     }
     return confirmRevert();
   };
@@ -226,8 +232,8 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
     buildDiffPayload(
       {
         category: 'node',
-        groups: () => historyService.getHistoryGroups('page', editorService.get('page')?.id),
-        getCurrent: (id) => editorService.getNodeById(id) as Record<string, any> | null,
+        groups: () => services?.historyService.getHistoryGroups('page', services?.editorService.get('page')?.id) ?? [],
+        getCurrent: (id) => services?.editorService.getNodeById(id) as Record<string, any> | null,
         resolveType: (n, o) => n.type || o.type || '',
         resolveLabel: (n, o) => n.name || o.name || n.type || o.type || '',
       },
@@ -238,8 +244,8 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
     buildDiffPayload(
       {
         category: 'data-source',
-        groups: () => historyService.getHistoryGroups('dataSource'),
-        getCurrent: (id) => dataSourceService.getDataSourceById(`${id}`) as Record<string, any> | null,
+        groups: () => services?.historyService.getHistoryGroups('dataSource') ?? [],
+        getCurrent: (id) => services?.dataSourceService.getDataSourceById(`${id}`) as Record<string, any> | null,
         resolveType: (n, o) => n.type || o.type || 'base',
         resolveLabel: (n, o, id) => n.title || o.title || `${id}`,
       },
@@ -251,8 +257,8 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
     buildDiffPayload(
       {
         category: 'code-block',
-        groups: () => historyService.getHistoryGroups('codeBlock'),
-        getCurrent: (id) => codeBlockService.getCodeContentById(id) as Record<string, any> | null,
+        groups: () => services?.historyService.getHistoryGroups('codeBlock') ?? [],
+        getCurrent: (id) => services?.codeBlockService.getCodeContentById(id) as Record<string, any> | null,
         resolveLabel: (n, o, id) => n.name || o.name || `${id}`,
       },
       index,
@@ -266,17 +272,17 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
    * add（回滚即删除）即使目标已不在，也已达成「删除」目的，不视为失败。
    */
   const isPageRevertTargetMissing = (index: number): boolean => {
-    const step = historyService.getStepList('page', editorService.get('page')?.id)[index]?.step;
+    const step = services?.historyService.getStepList('page', services?.editorService.get('page')?.id)[index]?.step;
     if (!step) return false;
     if (step.opType === 'update') {
       return (step.diff ?? []).some((item) => {
         const id = item.newSchema?.id ?? item.oldSchema?.id;
-        return id !== undefined && !editorService.getNodeById(id, false);
+        return id !== undefined && !services?.editorService.getNodeById(id, false);
       });
     }
     if (step.opType === 'remove') {
       return (step.diff ?? []).some(
-        (item) => item.parentId !== undefined && !editorService.getNodeById(item.parentId, false),
+        (item) => item.parentId !== undefined && !services?.editorService.getNodeById(item.parentId, false),
       );
     }
     return false;
@@ -284,14 +290,14 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
 
   /** 数据源 update 步骤回滚时，对应数据源必须仍存在（已删除则无处写回旧值）。 */
   const isDataSourceRevertTargetMissing = (id: string | number, index: number): boolean => {
-    const step = historyService.getStepList('dataSource', id)[index]?.step;
-    return Boolean(step?.opType === 'update' && !dataSourceService.getDataSourceById(`${id}`));
+    const step = services?.historyService.getStepList('dataSource', id)[index]?.step;
+    return Boolean(step?.opType === 'update' && !services?.dataSourceService.getDataSourceById(`${id}`));
   };
 
   /** 代码块 update 步骤回滚时，对应代码块必须仍存在（已删除则无处写回旧值）。 */
   const isCodeBlockRevertTargetMissing = (id: string | number, index: number): boolean => {
-    const step = historyService.getStepList('codeBlock', id)[index]?.step;
-    return Boolean(step?.opType === 'update' && !codeBlockService.getCodeContentById(id));
+    const step = services?.historyService.getStepList('codeBlock', id)[index]?.step;
+    return Boolean(step?.opType === 'update' && !services?.codeBlockService.getCodeContentById(id));
   };
 
   const onPageRevert = (index: number) => {
@@ -300,7 +306,7 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
       return Promise.resolve(null);
     }
     return runRevert(buildPageDiffPayload(index), { compareFormState: getPropsPanelFormState?.() }).then((result) =>
-      result ? editorService.revertPageStep(index) : null,
+      result ? services?.editorService.revertPageStep(index) : null,
     );
   };
 
@@ -310,7 +316,7 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
       return Promise.resolve(null);
     }
     return runRevert(buildDataSourceDiffPayload(id, index)).then((result) =>
-      result ? dataSourceService.revert(id, index) : null,
+      result ? services?.dataSourceService.revert(id, index) : null,
     );
   };
 
@@ -320,7 +326,7 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
       return Promise.resolve(null);
     }
     return runRevert(buildCodeBlockDiffPayload(id, index)).then((result) =>
-      result ? codeBlockService.revert(id, index) : null,
+      result ? services?.codeBlockService.revert(id, index) : null,
     );
   };
 
@@ -335,6 +341,7 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
         appContext,
         extendState,
         services,
+        width: dialogWidth,
         compareFormState: getPropsPanelFormState?.(),
       });
     }
@@ -342,12 +349,12 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
 
   const onDataSourceDiff = (id: string | number, index: number): Promise<void> | void => {
     const payload = buildDataSourceDiffPayload(id, index);
-    if (payload) return viewHistoryDiffDialog(payload, { appContext, extendState, services });
+    if (payload) return viewHistoryDiffDialog(payload, { appContext, extendState, services, width: dialogWidth });
   };
 
   const onCodeBlockDiff = (id: string | number, index: number): Promise<void> | void => {
     const payload = buildCodeBlockDiffPayload(id, index);
-    if (payload) return viewHistoryDiffDialog(payload, { appContext, extendState, services });
+    if (payload) return viewHistoryDiffDialog(payload, { appContext, extendState, services, width: dialogWidth });
   };
 
   /**
@@ -374,6 +381,7 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
     const confirmed = await runRevert(revertOptions.diffPayload ?? null, {
       loadConfig: revertOptions.loadConfig,
       selfDiffFieldTypes: revertOptions.selfDiffFieldTypes,
+      width: revertOptions.width,
     });
     if (!confirmed) return null;
     return await revertOptions.revert();
@@ -384,7 +392,14 @@ export const useHistoryRevert = (services: Services, options: UseHistoryRevertOp
    * 可透传 `loadConfig` / `selfDiffFieldTypes`。payload 为 null（不可对比）时静默返回。
    */
   const viewDiff = (payload: DiffDialogPayload | null, extra?: CustomDiffFormOptions): Promise<void> | void => {
-    if (payload) return viewHistoryDiffDialog(payload, { appContext, extendState, services, ...extra });
+    if (payload)
+      return viewHistoryDiffDialog(payload, {
+        appContext,
+        extendState,
+        services,
+        ...extra,
+        width: extra?.width ?? dialogWidth,
+      });
   };
 
   return {

package/src/services/codeBlock.ts

@@ -85,6 +85,7 @@ class CodeBlock extends BaseService {
   public async setCodeDsl(codeDsl: CodeBlockDSL): Promise<void> {
     this.state.codeDsl = codeDsl;
     this.emit('code-dsl-change', this.state.codeDsl);
+    this.emit('change', this.state.codeDsl);
   }
 
   /**
@@ -199,6 +200,7 @@ class CodeBlock extends BaseService {
     }
 
     this.emit('addOrUpdate', id, codeDsl[id]);
+    this.emit('change', this.getCodeDsl());
   }
 
   /**
@@ -318,6 +320,8 @@ class CodeBlock extends BaseService {
 
       this.emit('remove', id);
     });
+
+    this.emit('change', this.getCodeDsl());
   }
 
   // #region AndGetHistoryId

package/src/services/dataSource.ts

@@ -147,6 +147,7 @@ class DataSource extends BaseService {
     }
 
     this.emit('add', newConfig);
+    this.emit('change', this.get('dataSources'));
 
     return newConfig;
   }
@@ -192,6 +193,7 @@ class DataSource extends BaseService {
       oldConfig,
       changeRecords,
     });
+    this.emit('change', this.get('dataSources'));
 
     return newConfig;
   }
@@ -220,6 +222,7 @@ class DataSource extends BaseService {
     }
 
     this.emit('remove', id);
+    this.emit('change', this.get('dataSources'));
   }
 
   // #region AndGetHistoryId

package/src/services/editor.ts

@@ -535,6 +535,10 @@ class Editor extends BaseService {
     }
 
     this.emit('add', newNodes);
+    this.emit('change', {
+      type: 'add',
+      data: newNodes.map((node) => ({ node, page: this.getPageOfNode(node.id) })),
+    });
 
     return Array.isArray(addNode) ? newNodes : newNodes[0];
   }
@@ -635,6 +639,9 @@ class Editor extends BaseService {
 
     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]))) {
@@ -670,6 +677,7 @@ class Editor extends BaseService {
     }
 
     this.emit('remove', nodes);
+    this.emit('change', { type: 'remove', data: changeItems });
   }
 
   public async doUpdate(
@@ -805,6 +813,10 @@ class Editor extends BaseService {
     }
 
     this.emit('update', updateData);
+    this.emit('change', {
+      type: 'update',
+      data: updateData.map((node) => ({ node, page: this.getPageOfNode(node.newNode.id) })),
+    });
     return Array.isArray(config) ? updateData.map((item) => item.newNode) : updateData[0].newNode;
   }
 
@@ -1046,6 +1058,11 @@ class Editor extends BaseService {
     }
 
     this.emit('move-layer', offset);
+    this.emit('change', {
+      type: 'move-layer',
+      data: [{ node, page: this.getPageOfNode(node.id) }],
+      offset,
+    });
   }
 
   /**
@@ -1225,6 +1242,12 @@ 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,
+    });
   }
 
   // #region AndGetHistoryId
@@ -1558,6 +1581,20 @@ class Editor extends BaseService {
     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 && (isPage(node) || isPageFragment(node))) return node as MPage | MPageFragment;
+    return null;
+  }
+
   private captureSelectionBeforeOp() {
     if (this.selectionBeforeOp) return;
     this.selectionBeforeOp = this.get('nodes').map((n) => n.id);

package/src/type.ts

@@ -1218,8 +1218,41 @@ export interface EditorEvents {
   'move-layer': [offset: number | LayerOffset];
   'drag-to': [data: { targetIndex: number; configs: MNode | MNode[]; targetParent: MContainer }];
   'history-change': [data: MPage | MPageFragment];
+  /**
+   * DSL 发生变更后统一触发，免去分别监听 add / remove / update / move-layer / drag-to。
+   * 回调参数为 {@link EditorChangeEvent}，按 `type` 区分操作类型并携带各自的操作内容（payload）
+   * 以及变更所在的当前 page（可能为 null）。撤销 / 重做内部同样会经由
+   * add / remove / update 触发本事件；如需区分「用户操作」与「撤销重做」请配合 `history-change`。
+   */
+  change: [event: EditorChangeEvent];
+}
+
+// #region EditorChangeEvent
+/** `change` 事件中单个变更项：变更的 node 及其所属的 page（可能为 null）。 */
+export interface EditorChangeItem {
+  node: MNode;
+  page: StoreState['page'];
 }
 
+/** `update` 类型变更项：node 为前后快照及 form 端变更记录，page 为其所属页面。 */
+export interface EditorUpdateChangeItem {
+  node: { newNode: MNode; oldNode: MNode; changeRecords?: ChangeRecord[] };
+  page: StoreState['page'];
+}
+
+/**
+ * {@link EditorEvents.change} 的回调参数：以 `type` 区分操作类型，并携带对应的操作内容。
+ * `data` 为本次变更的节点列表，每项包含 node 及其所属的 page（可能为 null）；
+ * `move-layer` 额外带层级偏移 `offset`，`drag-to` 额外带目标位置 `targetIndex` / `targetParent`。
+ */
+export type EditorChangeEvent =
+  | { type: 'add'; data: EditorChangeItem[] }
+  | { type: 'remove'; data: EditorChangeItem[] }
+  | { type: 'update'; data: EditorUpdateChangeItem[] }
+  | { type: 'move-layer'; data: EditorChangeItem[]; offset: number | LayerOffset }
+  | { type: 'drag-to'; data: EditorChangeItem[]; targetIndex: number; targetParent: MContainer };
+// #endregion EditorChangeEvent
+
 export interface HistoryEvents {
   change: [
     state: BaseStepValue | StepValue | CodeBlockStepValue | DataSourceStepValue,
@@ -1319,6 +1352,14 @@ export interface DiffDialogPayload {
   targetLabel?: string;
   /** 用于标题展示的目标 id */
   id?: string | number;
+  /**
+   * 指定打开时的初始对比模式：
+   * - before：该步骤修改前 vs 修改后
+   * - current：该步骤修改后 vs 当前最新值
+   * 不传时按是否存在「修改后的值」/「当前值」自动推断。
+   * 若指定的模式当前不可用（对应数据缺失），将回退到自动推断结果。
+   */
+  mode?: 'before' | 'current';
 }
 
 /**
@@ -1353,6 +1394,8 @@ export interface HistoryBucketConfig<T extends BaseStepValue = BaseStepValue> ex
   showInitial?: boolean;
   /** 是否支持「跳转到该记录」(goto)，默认 true。 */
   gotoEnabled?: boolean;
+  /** 是否展示顶部「清空」按钮，默认 true。无需提供清空能力的自定义历史可传 false。 */
+  showClear?: boolean;
 }
 
 export interface UseHistoryRevertOptions {
@@ -1373,6 +1416,12 @@ export interface UseHistoryRevertOptions {
    * 以保证两处 filterFunction 读取到一致的运行态上下文。
    */
   getPropsPanelFormState?: () => FormState | undefined;
+  /**
+   * 内置页面 / 数据源 / 代码块的差异 / 回滚确认弹窗默认宽度（透传给 TMagicDialog 的 `width`），
+   * 如 `'1200px'` / `'80%'`。缺省时使用弹窗内置默认宽度（900px）。
+   * 业务自有历史（`viewDiff` / `confirmAndRevert`）可在调用时通过各自入参的 `width` 单独覆盖。
+   */
+  dialogWidth?: string;
 }
 
 /**
@@ -1393,6 +1442,11 @@ export interface CustomDiffFormOptions {
    * 对比弹窗会用它覆盖 CompareForm 中同名扩展字段，避免上下文不一致。
    */
   compareFormState?: FormState;
+  /**
+   * 差异 / 确认回滚弹窗宽度（透传给 HistoryDiffDialog 的 TMagicDialog `width`），
+   * 如 `'1200px'` / `'80%'`。缺省时使用弹窗内置默认宽度（900px）。
+   */
+  width?: string;
 }
 
 /**