History 历史记录

概述

该插件用于实现图编辑的 撤销（Undo） 和 重做（Redo） 功能，通过记录用户操作的历史状态堆栈，支持在图交互过程中进行回溯或恢复操作。该插件为用户提供了完善的配置项和 API 。

使用场景

历史记录插件适用于所有涉及到图编辑的场景。

在线体验

createGraph(
  {
    data: { nodes: [{ id: 'node-1' }] },
    layout: { type: 'force' },
    node: {
      style: {
        size: 60,
        labelText: 'Drag Me!',
        labelPlacement: 'middle',
        labelFill: '#fff',
        fill: '#7e3feb',
      },
    },
    edge: { style: { stroke: '#8b9baf' } },
    behaviors: ['drag-element'],
    plugins: ['grid-line', { type: 'history', key: 'history' }],
  },
  { width: 600, height: 300 },
  (gui, graph) => {
    const options = {
      type: 'history',
      stackSize: 0,
    };
    const optionFolder = gui.addFolder('History Options');
    optionFolder.add(options, 'type').disable(true);
    optionFolder.add(options, 'stackSize', 0, 10, 1);
    optionFolder.onChange(({ property, value }) => {
      graph.updatePlugin({
        key: 'history',
        [property]: value,
      });
      graph.render();
    });

    const apiFolder = gui.addFolder('History API');
    const instance = graph.getPluginInstance('history');
    apiFolder.add(instance, 'undo');
    apiFolder.add(instance, 'redo');
    apiFolder.add(instance, 'clear');
  },
);

基本用法

在图配置中添加这一插件：

1. 快速配置（静态）

使用字符串形式直接声明，这种方式简洁但仅支持默认配置，且配置后不可动态修改：

const graph = new Graph({
  // 其他配置...
  plugins: ['history'],
});

2. 对象配置（推荐）

使用对象形式进行配置，支持自定义参数，且可以在运行时动态更新配置：

const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'history',
      key: 'history-1',
      stackSize: 10,
    },
  ],
});

配置项

属性	描述	类型	默认值
afterAddCommand	当一个命令被添加到 `Undo/Redo` 队列后被调用。`revert` 为 `true` 时表示撤销操作，为 `false` 时表示重做操作	(cmd: Command, revert: boolean) => void	-
beforeAddCommand	当一个命令被添加到 `Undo/Redo` 队列前被调用，如果该方法返回 `false`，那么这个命令将不会被添加到队列中。`revert` 为 `true` 时表示撤销操作，为 `false` 时表示重做操作	(cmd: Command, revert: boolean) => boolean \| void	-
executeCommand	执行命令时的回调函数	(cmd: Command) => void	-
stackSize	最多记录该数据长度的历史记录	number	0（不限制）

参数类型说明

`Command`

// 单条历史记录命令
interface Command {
  current: CommandData; // 当前数据
  original: CommandData; // 原始数据
  animation: boolean; // 是否开启动画
}
// 单条历史记录命令数据
interface CommandData {
  add: GraphData; // 新增的数据
  update: GraphData; // 更新的数据
  remove: GraphData; // 移除的数据
}
// 图数据
interface GraphData {
  nodes?: NodeData[]; // 节点数据
  edges?: EdgeData[]; // 边数据
  combos?: ComboData[]; // Combo 数据
}

API

history 插件提供了以下 API 供用户按需使用，调用插件方法的方式请参考插件总览文档

History.canRedo()

判断是否可以进行重做操作。如果重做堆栈中有记录，则返回 true，否则返回 false。

canRedo(): boolean;

示例：

const canRedo = historyInstance.canRedo();
if (canRedo) {
  console.log('可以进行重做操作');
} else {
  console.log('重做堆栈为空，无法重做');
}

History.canUndo()

判断是否可以进行撤销操作。如果撤销堆栈中有记录，则返回 true，否则返回 false。

canUndo(): boolean;

示例：

const canUndo = historyInstance.canUndo();
if (canUndo) {
  console.log('可以进行撤销操作');
} else {
  console.log('撤销堆栈为空，无法撤销');
}

History.clear()

清空历史记录，包括撤销和重做堆栈。

clear(): void;

示例：

historyInstance.clear();
console.log('历史记录已清空');

History.on()

监听历史记录事件，允许用户在特定事件发生时执行自定义逻辑。

on(event: Loosen/<HistoryEvent/>, handler: (e: { cmd?: Command | null }) => void): void;

参数类型说明：

HistoryEvent

enum HistoryEvent {
  UNDO = 'undo', // 当命令被撤销时
  REDO = 'redo', // 当命令被重做时
  CANCEL = 'cancel', // 当命令被取消时
  ADD = 'add', // 当命令被添加到队列时
  CLEAR = 'clear', // 当历史队列被清空时
  CHANGE = 'change', // 当历史队列发生变化时
}

Command
请参考前面的 Command 类型说明

示例：

historyInstance.on(HistoryEvent.UNDO, () => {
  console.log('执行了撤销操作');
});

History.redo()

执行重做操作，并返回插件实例。如果重做堆栈为空，则不执行任何操作。

redo(): History;

示例：

historyInstance.redo();
console.log('执行了重做操作');

History.undo()

执行撤销操作，并返回插件实例。如果撤销堆栈为空，则不执行任何操作。

undo(): History;

示例：

historyInstance.undo();
console.log('执行了撤销操作');

History.undoAndCancel()

执行撤销操作且不计入历史记录，并返回插件实例。注意，执行该操作会清空重做栈。

undoAndCancel(): History;

示例：

historyInstance.undoAndCancel();
console.log('执行了撤销并取消操作');

历史记录模式

该插件支持两种历史记录模式：

默认模式

默认模式下，每一次触发渲染后（比如更新元素数据后，用户主动执行 graph.draw() 方法触发渲染），插件会把渲染前和渲染后的数据记录下来并作为一次操作记录入栈。

自定义模式

场景描述

实际需求中，用户的一次图编辑操作可能涉及到多次渲染，比如，一次编辑操作中，首先把节点 A、B 展示出来，然后展示 A->B 的连线，这里就涉及到两次渲染（即用户需要进行两次 graph.draw() ），这种场景下，默认模式会入栈两次历史记录，分别是：

展示节点 A 和 B
展示 A->B 的连线

显然，实际业务中，一次操作，也应该只需一次撤销。

但这里在撤销本次操作时，用户需要调用两次 undo 方法，也就是需要进行两次撤销。

场景支持

为了支持这样的场景，G6 提供了一个批量控制器（ BatchController，可参考源码），在图实例上下文中提供了这个批量控制器实例。

历史记录插件则基于这个批量控制器，来实现自定义操作记录，代码示例如下：

const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'history',
      key: 'history',
    },
  ],
});

graph.context.batch.startBatch(); // 开始批量操作
graph.addNodeData(...); // 把节点 A、B 展示出来
graph.draw(); // 第一次触发渲染
graph.addEdgeData(...); // 把 A->B 连线展示出来
graph.draw(); // 第二次触发渲染
graph.context.batch.endBatch(); // 结束批量操作

示例中：

通过调用批量控制器实例的 startBatch 方法，告诉历史记录插件，现在开始进行批量操作，在批量操作没有结束前，不管触发多少次渲染，都不能进行历史记录入栈（历史记录插件会把每次触发渲染的变更数据记录下来）
在完成最后一次数据变更后，调用 endBatch() 方法，历史记录插件监听到批量操作完成，则把本次批量操作作为一次历史记录入栈

最终，用户只需要进行一次 undo 即可撤销。

代码示例

下面列举一些常见的案例，并给出相应的代码参考

撤销、重做按钮状态

实际业务场景中，可能需要自定义画布的工具栏，也就涉及到撤销和重做按钮的启禁用状态

const canUndo = false;
const canRedo = false;

const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'history',
      key: 'history',
    },
  ],
});
const historyInstance = graph.getPluginInstance('history');

historyInstance.on(HistoryEvent.CHANGE, () => {
  canUndo = historyInstance.canUndo();
  canRedo = historyInstance.canRedo();
});

示例中通过监听 HistoryEvent.CHANGE 事件，这个事件在历史队列发生变化时会触发，每次发生变化后，实时判断当前是否可以进行撤销和重做操作

判断是否允许命令进入队列

这里实现一个简单的场景：只有移除元素的操作才允许进入历史记录队列

const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'history',
      key: 'history',
      beforeAddCommand: (cmd) => {
        return (
          cmd.current.remove?.nodes?.length > 0 ||
          cmd.current.remove?.combos?.length > 0 ||
          cmd.current.remove?.edges?.length > 0
        );
      },
    },
  ],
});

示例中通过配置项 beforeAddCommand 来实现，判断 cmd.current.remove 里面是否存在被移除的元素

概述

使用场景

历史记录插件适用于所有涉及到图编辑的场景。

在线体验

createGraph(
  {
    data: { nodes: [{ id: 'node-1' }] },
    layout: { type: 'force' },
    node: {
      style: {
        size: 60,
        labelText: 'Drag Me!',
        labelPlacement: 'middle',
        labelFill: '#fff',
        fill: '#7e3feb',
      },
    },
    edge: { style: { stroke: '#8b9baf' } },
    behaviors: ['drag-element'],
    plugins: ['grid-line', { type: 'history', key: 'history' }],
  },
  { width: 600, height: 300 },
  (gui, graph) => {
    const options = {
      type: 'history',
      stackSize: 0,
    };
    const optionFolder = gui.addFolder('History Options');
    optionFolder.add(options, 'type').disable(true);
    optionFolder.add(options, 'stackSize', 0, 10, 1);
    optionFolder.onChange(({ property, value }) => {
      graph.updatePlugin({
        key: 'history',
        [property]: value,
      });
      graph.render();
    });

    const apiFolder = gui.addFolder('History API');
    const instance = graph.getPluginInstance('history');
    apiFolder.add(instance, 'undo');
    apiFolder.add(instance, 'redo');
    apiFolder.add(instance, 'clear');
  },
);

基本用法

在图配置中添加这一插件：

1. 快速配置（静态）

使用字符串形式直接声明，这种方式简洁但仅支持默认配置，且配置后不可动态修改：

const graph = new Graph({
  // 其他配置...
  plugins: ['history'],
});

2. 对象配置（推荐）

使用对象形式进行配置，支持自定义参数，且可以在运行时动态更新配置：

const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'history',
      key: 'history-1',
      stackSize: 10,
    },
  ],
});

配置项

属性	描述	类型	默认值
afterAddCommand	当一个命令被添加到 `Undo/Redo` 队列后被调用。`revert` 为 `true` 时表示撤销操作，为 `false` 时表示重做操作	(cmd: Command, revert: boolean) => void	-
beforeAddCommand	当一个命令被添加到 `Undo/Redo` 队列前被调用，如果该方法返回 `false`，那么这个命令将不会被添加到队列中。`revert` 为 `true` 时表示撤销操作，为 `false` 时表示重做操作	(cmd: Command, revert: boolean) => boolean \| void	-
executeCommand	执行命令时的回调函数	(cmd: Command) => void	-
stackSize	最多记录该数据长度的历史记录	number	0（不限制）

参数类型说明

`Command`

// 单条历史记录命令
interface Command {
  current: CommandData; // 当前数据
  original: CommandData; // 原始数据
  animation: boolean; // 是否开启动画
}
// 单条历史记录命令数据
interface CommandData {
  add: GraphData; // 新增的数据
  update: GraphData; // 更新的数据
  remove: GraphData; // 移除的数据
}
// 图数据
interface GraphData {
  nodes?: NodeData[]; // 节点数据
  edges?: EdgeData[]; // 边数据
  combos?: ComboData[]; // Combo 数据
}

API

history 插件提供了以下 API 供用户按需使用，调用插件方法的方式请参考插件总览文档

History.canRedo()

判断是否可以进行重做操作。如果重做堆栈中有记录，则返回 true，否则返回 false。

canRedo(): boolean;

示例：

const canRedo = historyInstance.canRedo();
if (canRedo) {
  console.log('可以进行重做操作');
} else {
  console.log('重做堆栈为空，无法重做');
}

History.canUndo()

判断是否可以进行撤销操作。如果撤销堆栈中有记录，则返回 true，否则返回 false。

canUndo(): boolean;

示例：

const canUndo = historyInstance.canUndo();
if (canUndo) {
  console.log('可以进行撤销操作');
} else {
  console.log('撤销堆栈为空，无法撤销');
}

History.clear()

清空历史记录，包括撤销和重做堆栈。

clear(): void;

示例：

historyInstance.clear();
console.log('历史记录已清空');

History.on()

监听历史记录事件，允许用户在特定事件发生时执行自定义逻辑。

on(event: Loosen/<HistoryEvent/>, handler: (e: { cmd?: Command | null }) => void): void;

参数类型说明：

HistoryEvent

enum HistoryEvent {
  UNDO = 'undo', // 当命令被撤销时
  REDO = 'redo', // 当命令被重做时
  CANCEL = 'cancel', // 当命令被取消时
  ADD = 'add', // 当命令被添加到队列时
  CLEAR = 'clear', // 当历史队列被清空时
  CHANGE = 'change', // 当历史队列发生变化时
}

Command
请参考前面的 Command 类型说明

示例：

historyInstance.on(HistoryEvent.UNDO, () => {
  console.log('执行了撤销操作');
});

History.redo()

执行重做操作，并返回插件实例。如果重做堆栈为空，则不执行任何操作。

redo(): History;

示例：

historyInstance.redo();
console.log('执行了重做操作');

History.undo()

执行撤销操作，并返回插件实例。如果撤销堆栈为空，则不执行任何操作。

undo(): History;

示例：

historyInstance.undo();
console.log('执行了撤销操作');

History.undoAndCancel()

执行撤销操作且不计入历史记录，并返回插件实例。注意，执行该操作会清空重做栈。

undoAndCancel(): History;

示例：

historyInstance.undoAndCancel();
console.log('执行了撤销并取消操作');

历史记录模式

该插件支持两种历史记录模式：

默认模式

自定义模式

场景描述

展示节点 A 和 B
展示 A->B 的连线

显然，实际业务中，一次操作，也应该只需一次撤销。

但这里在撤销本次操作时，用户需要调用两次 undo 方法，也就是需要进行两次撤销。

场景支持

为了支持这样的场景，G6 提供了一个批量控制器（ BatchController，可参考源码），在图实例上下文中提供了这个批量控制器实例。

历史记录插件则基于这个批量控制器，来实现自定义操作记录，代码示例如下：

const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'history',
      key: 'history',
    },
  ],
});

graph.context.batch.startBatch(); // 开始批量操作
graph.addNodeData(...); // 把节点 A、B 展示出来
graph.draw(); // 第一次触发渲染
graph.addEdgeData(...); // 把 A->B 连线展示出来
graph.draw(); // 第二次触发渲染
graph.context.batch.endBatch(); // 结束批量操作

示例中：

通过调用批量控制器实例的 startBatch 方法，告诉历史记录插件，现在开始进行批量操作，在批量操作没有结束前，不管触发多少次渲染，都不能进行历史记录入栈（历史记录插件会把每次触发渲染的变更数据记录下来）
在完成最后一次数据变更后，调用 endBatch() 方法，历史记录插件监听到批量操作完成，则把本次批量操作作为一次历史记录入栈

最终，用户只需要进行一次 undo 即可撤销。

代码示例

下面列举一些常见的案例，并给出相应的代码参考

撤销、重做按钮状态

实际业务场景中，可能需要自定义画布的工具栏，也就涉及到撤销和重做按钮的启禁用状态

const canUndo = false;
const canRedo = false;

const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'history',
      key: 'history',
    },
  ],
});
const historyInstance = graph.getPluginInstance('history');

historyInstance.on(HistoryEvent.CHANGE, () => {
  canUndo = historyInstance.canUndo();
  canRedo = historyInstance.canRedo();
});

示例中通过监听 HistoryEvent.CHANGE 事件，这个事件在历史队列发生变化时会触发，每次发生变化后，实时判断当前是否可以进行撤销和重做操作

判断是否允许命令进入队列

这里实现一个简单的场景：只有移除元素的操作才允许进入历史记录队列

const graph = new Graph({
  // 其他配置...
  plugins: [
    {
      type: 'history',
      key: 'history',
      beforeAddCommand: (cmd) => {
        return (
          cmd.current.remove?.nodes?.length > 0 ||
          cmd.current.remove?.combos?.length > 0 ||
          cmd.current.remove?.edges?.length > 0
        );
      },
    },
  ],
});

示例中通过配置项 beforeAddCommand 来实现，判断 cmd.current.remove 里面是否存在被移除的元素