Concepts.Undoing Overview 
准备中...
1. Overview
SMART datagrid格提供可以取消（Undo）或重做（Redo）用户输入或数据组修改等的选项。 数据修改可能会发生在网格和数据组级别。 在网格上，将会发生在用户修改或添加行的情况，而数据组的修改，将会发生在网格上提交编辑的数据被传递至数据组或直接调用数据组API的情况。
如果想在网格行编辑过程中实现取消或重做，就需要将GridBase.undoable指定为true。 而且，如果想在数据组实现取消或重做，就需要将DataSet.undoable指定为true。 一般来说，当为用户提供取消或重做UI时，将会把两种属性同时指定为true。 如果在运行过程中，变更undoable属性或调用DataSet.clearUndo、GridBase.clearUndo，就会空出Undo栈并重新开始Undo历史记录。
dataset.setUndoable(true);
grid.setUndoable(true);
如果实现取消或重做，用户就可以在运行时间通过输入Ctrl+Z和Ctrl+Y等标准输入键，运行取消和重做。 在脚本中，将会通过调用GridBase.undo、redo函数，运行取消和重做。 另外，可以通过调用GridBase.canUndo、canRedo，确认目前是否可以分别运行取消和重做。 如果变更canUndo、canRedo状态，就会触发onUndoStateChanged事件。
grid.onUndoStateChanged = function (grid, canUndo, canRedo) {
document.getElementById("btnUndo").disabled = !canUndo;
document.getElementById("btnRedo").disabled = !canRedo;
};
$("#btnUndo").click = function () {
grid.undo();
};
$("#btnReco").click = function () {
grid.redo();
};
维持Undo列表和Redo列表的方式，类似于处理一般文件应用。 当各个变更调用被添加到Undo栈并且调用Undo，下个Undo位置将会移动至上个变更调用。 如果移动至Undo栈底部，canUndo将会变成false。 Redo调用移动至与Undo相反的方向，并且重新运行至最近变更调用时点。 而且，如果没有在Undo栈的中间位置进行Redo，而是添加新的变更调用，相关位置到最近保管在栈中的Redo调用将会被清除。
2. 数据组编辑
如果数据组为undoable，将会在数据组的Undo栈， 管理可变更数据组的正式网格数据组和树数据组的所有方法。 也就是说，我们可以取消和重做数据组变更。 用户可以在运行时间使用Ctrl+Z和Ctrl+Y键，也可以直接调用undo和redo方法。
下列表格中，已有列出被管理在两个数据组中的方法。
| Method | UI | Description |
|---|---|---|
| clearRows | 全部清除现有行。 | |
| setRows | 全部清除现有行，并且添加新的行。 | |
| setXmlRows | 全部清除现有行，并且使用XML源，添加新的行。 | |
| setRowCount | 变更数据行的数量。 | |
| setValue | 变更一个行、一个字段的值。 | |
| updateRow | 变更一个行的值。 | |
| updateRows | 同时变更多个行的值。 | |
| updateXmlRows | 使用XML源，同时变更多个行的值。 | |
| updateValues | 变更符合条件的行的值。 | |
| deleteRow | 删除一个行。 | |
| deleteRows | 删除多个行。 | |
| insertRow | 插入一个行。 | |
| appendRow | 添加一个行到最后。 | |
| insertRows | 插入多个行。 | |
| insertXmlRows | 使用XML源，插入多个行。 | |
| appendRows | 添加多个行到最后。 | |
| appendXmlRows | 使用XML源，添加多个行到最后。 | |
| moveRow | 移动一个行到其他位置。 | |
| moveRows | 同时移动多个行到其他位置。 | |
| setRowState | 强行变更一个行的状态。 | |
| setRowStates | 同时强行变更多个行的状态。 | |
| clearRowStates | 重置所有行的状态。 | |
| restoreUpdatedStates | 恢复修改行的状态。 | |
| restoreUpdatedRows | 恢复修改行的值。 | |
| setRowTag | 设置一个行的标签。 | |
| setRowTags | 设置多个行的标签。 | |
| unsetRowTags | 清除一个行以上的标签。 | |
| clearRowTags | 清除所有行的标签。 |
| Method | UI | Description |
|---|---|---|
| clearRows | 全部清除现有行。 | |
| setRows | 全部清除现有行，并且添加新的行。 | |
| setXmlRows | 全部清除现有行，并且使用XML源，添加新的行。 | |
| setJsonRows | 全部清除现有行，并且使用JSON数组，添加新的行。 | |
| insertDataRows | 使用数组，插入新的行到指定位置。 | |
| insertJsonRows | 使用JSON数组，插入新的行到指定位置。 | |
| insertXmlRows | 使用XML源，插入新的行到指定位置。 | |
| appendDataRows | 使用数组，添加新的行到最后。 | |
| appendJsonRows | 使用JSON数组，添加新的行到最后。 | |
| appendXmlRows | 使用XML源，添加新的行到最后。 | |
| insertRow | 插入一个行到指定位置。 | |
| addRow | 添加一个行到最后。 | |
| insertRows | 插入多个行到指定位置。 | |
| addRows | 添加多个行到最后。 | |
| deleteRow | 删除一个行。 | |
| deleteRows | 同时删除多个行。 | |
| setValue | 修改一个行、一个字段的值。 | |
| updateRow | 修改一个行。 | |
| setRowTag | 设置一个行的标签。 | |
| setRowTags | 同时设置多个行的标签。 | |
| unsetRowTags | 清除指定行的标签。 | |
| clearRowTags | 清除所有行的标签。 | |
| setRowState | 强行变更一个行的状态。 | |
| setRowStates | 强行变更多个行的状态。 | |
| clearRowStates | 重置所有行的状态。 |
3. 网格行编辑
如果将网格的undoable指定为true，当用户在运行时间修改或添加行时，将会在网格Undo栈，管理单元格单位的编辑活动。 用户可以使用Ctrl+Z键和Ctrl+Y键，分别进行Undo和Redo。 而且，也可以直接调用undo、redo。 一般会按下列步骤进行。
- 当开始编辑时，将会创建网格Undo栈。
- 每次用户修改单元格时，编辑历史记录将会被添加到栈。
- 使用Ctrl+Z键而运行Undo。移动焦点到相关单元格。
- 使用Ctrl+Y键而运行Redo。移动焦点到相关单元格。
- 当使用Undo而返回最初编辑记录的状态下，如果输入Ctrl+Z键， 就会根据EditOptions.cancelWhenUndo设置，取消行编辑。
- 只有用户直接输入的编辑，才会被添加到栈。
- 当显示编辑器时，如果输入Ctrl+Z，就会运行编辑器级别的Undo， 并且，如果在与起始值相同的状态下，重新输入Ctrl+Z，就会运行Undo。
如同数据组的情况，如果网格Undo栈发生变化，就会触发onUndoStateChanged事件。 可以在这个事件内，确认能否运行Undo和Redo，也可以直接通过canUndo和canRedo而确认。
4. Group Action
当SMART datagrid格体现除基本提供的用户界面以外的、应用所需的特殊UI时，有必要通过同时调用两个以上的数据组方法，而使用户看作是一个调用。 也就是说，如果是需要只使用Ctrl+Z、Ctrl+Y键而运行Undo、Redo的情况，就可以使用GroupAction。
如下列代码，我们可以通过两种方法而创建和运行GroupAction。 首先，向数据组请求GroupAction，并且在返回的GroupAction，添加将要运行的方法。 此后，再向数据组请求运行GroupAciton即可。
// 请求新的group action
var ga = ds.createActionGroup();
// 添加变更操作
ga.updateRow(0, values);
ga.deleteRows([1, 2]);
ga.insertRow(1, newValues[0]);
ga.insertRow(2, newValues[1]);
// 请求运行。
ds.execute(ga);
类似于上述方式，可以通过使用数据组的beginActions和endActions而体现。 与createActionGroup不同的是， 如果不通过在beginActions和endActions之间隐式返回的GroupAction，就无法调用相关数据组的其他变更方法。
// 请求新的group action
ds.beginActions();
// 添加变更操作
ds.updateRow(0, values);
ds.deleteRows([1, 2]);
ds.insertRow(1, newValues[0]);
ds.insertRow(2, newValues[1]);
// 请求运行。
ds.endActions();
需要注意的是，GroupAction不是与数据库事务一同处理的。 也就是说，并不是包含在组中的所有变更请求都会被运行或失败。 发生失败之前的变更将会反映到数据组，并且到该时点为止的记录将会被保管在数据组栈。
5. Edit Actions
除用户编辑的数据单元格以外，还可以返回删除所选行以及清除选中区域的值。 而且，还可以返回使用AutoFill柄的数据编辑。
这些都会在内部通过单位编辑行为而定义，并且通过Undo/Redo栈而管理单位行为。 数据组的数据修改API函数，也是通过行为而管理的。
6. Bookmark
7. 例外处理
通常情况下，根据用户变更而被调用的方法，将会在运行变更之前，触发确认事件，并且在变更后，触发提交事件。 例如，GridDataSet.deleteRow将会在删除行之前，触发onRowDeleting事件， 而如果在事件处理器中明确返回Boolean false或抛出例外，就会中断删除操作。 而且，提交删除后，将会触发onRowDeleted事件。
如果DataSet为undoable，就需要考虑在连续运行和取消或重做等变更方法流程中，防止数据组发生歪曲的现象。 而且，需要尽量保存运行记录。 为此，SMART datagrid格体现相关例外的简明的政策。
- 运行中的例外
- 进行变更之前，如果在确认事件处理器中明确返回false，就会忽视变更，并且也不会添加到栈。
- 如果在确认事件处理器中抛出例外，就不会添加到栈，而是传递例外。
- 如果在提交事件处理器中抛出例外，就会添加到栈，并且传递例外。添加时点之后的所有运行记录，将会被清除。
- 如果在其他时点抛出例外，就不会添加到栈，并且将会从栈中清除当前时点以后的所有运行记录。
- 在正常运行的情况下，也会清除运行以后的栈。
- Undo/Redo中的例外
- 取消和重做过程中，将不会触发变更前确认事件。
- 只有当eventsOnStack被指定为true时，才会触发与变更前事件相配对的提交事件， 而如果在事件处理器中抛出例外，就只会传递例外，并且进行Undo/Redo。
- 将会时刻触发和同样处理其他提交事件。
- 如果在其他时点抛出例外，就会从这个时点开始，清除栈记录。
8. Group Action中的例外处理
如上述说明，对于最终用户，GroupAction只是一种单位行为，但数据组变更将会以包含在组中的请求单位而运行。
- 运行中的例外
- 当运行包含在组中的请求时，如果在提交事件中抛出例外，将会被整理为只包含之前的请求的组并且被包含在栈中， 同时将会传递例外。
- 如果在其他时点抛出例外，组将不会被包含在数据组的栈，并且从这个时点开始，数据组栈的记录也会被清除。 而且，将会传递例外。
- Undo/Redo中的例外
- 如果在各个运行中的提交事件中抛出例外，将会被整理为只包含之前的请求的组并进行Undo/Redo， 并且将会传递例外。
- 如果在提交事件以外抛出例外，就会从数据组栈中清除从这个组开始的所有数据，并且将会传递例外。
9. UI问题
因为"打开文件后开始编辑。"是一般的用户体验，所以DataSet的Undoable状态需要在尽量加载最初数据组后开始。 另外，根据情况，在上传已变更的数据组到服务器等之后， 通过调用DataSet.clearUndo或GridBase.clearUndo，空出Undo栈并重新开始，将会是比较适当的UI。
10. 性能问题
如果DataSet变成undoable状态，变更数据组的值的所有单位调用记录，基本上将会与复原所需信息一同储存到Undo栈。 其中，将会包含用于调用函数的参数和需要保管的值。 因此，需要注意的是，不去保管用户界面上的不必要的数据。 特别是，需要在加载初期数据组后允许undoable，并且在传送编辑数据组到服务器后，通过clearUndo而重置栈。
- See Also
- DataSet.undoable
- DataSet.clearUndo
- GridBase.undoable
- GridBase.clearUndo
- GridBase.undo
- GridBase.redo
- GridBase.canUndo
- GridBase.canRedo
- GridBase.onUndoStateChanged
- EditOptions.undoable
- EditOptions.deletable
- EditOptions.erasable
- EditOptions.cancelWhenUndo
- GridBase.deleteSelection
- GridBase.eraseSelection
- AutoFill
- Examples
- 取消和重做