事件支持

ReportSheet 提供可以在报告数据更改或提交时绑定的数据输入事件。

使用这些数据输入事件，SpreadJS 使您能够验证所有数据更改或在数据输入期间取消操作。您还可以接收服务器的反馈结果，然后在 UI 中查看结果。

您可以使用 getChanges 方法获取报告表的更新并在数据输入模式下插入和删除记录更改。以下代码示例返回报告表的更新和删除更改。

const report = spread.addSheetTab(0, "Report", GC.Spread.Sheets.SheetType.reportSheet);
report.renderMode("Design");
const templateSheet = report.getTemplate();
templateSheet.setTemplateCell(0, 0, {
	binding: "Orders[orderId]",
	type: "Group",
});
templateSheet.setTemplateCell(0, 1, {
    binding: "Orders[customerId]",
    type: "Group",
});
templateSheet.setDataEntrySetting([{
    name: "Write Back Rule 1",
    tableName: "Orders",
    fields: [
        { dbColumnName: "orderId", formula: "A1", isPrimary: true },
        { dbColumnName: "customerId", formula: "B1" },
    ],
    includeUnmodified: false,
    skipRecordWithEmptyValue: false
 }]);
report.renderMode("Preview");

// 在 UI 中执行以下操作将触发事件。
report.updateCellValue(0, 1, "test");
report.addRecordAt(1, 0);
report.updateCellValue(2, 0, 111);
report.updateCellValue(2, 1, "test2");
report.deleteRecordAt(3, 0);
report.getChanges(); // 一个删除记录和两个使用 "Write Back Rule 1" dataEntrySetting 的更新记录。

type=warning
注意：
getChanges 方法仅收集数据输入 WriteBackRule 中的单元格值。信息将从报告表单元格中收集值。然而，如果 WriteBackRule 的字段值不是单元格，字段信息将为 undefined，实体将显示收集到的整个记录值
getChanges 方法返回 WriteBackRule 收集的所有记录。如果没有更改，它将返回包含空记录和已删除记录的 WriteBackRule

ReportSheet 支持以下数据输入事件：

ReportSheetDataChanging 和 ReportSheetDataChanged

ReportSheetDataChanging：此事件在 ReportSheet 通过更新、插入或删除操作更改时发生。它允许验证或取消数据操作。
ReportSheetDataChanged：此事件在 ReportSheet 数据通过更新、插入或删除操作更改后发生。它允许将数据更改提交到服务器。

以下示例使用了 ReportSheetDataChanging 和 ReportSheetDataChanged 事件。

const report = spread.addSheetTab(0, "Report", GC.Spread.Sheets.SheetType.reportSheet);
report.renderMode("Design");
const templateSheet = report.getTemplate();
templateSheet.setTemplateCell(0, 0, {
   binding: "Orders[orderId]",
   type: "Group",
   showCollapseButton: true
});
templateSheet.setTemplateCell(0, 1, {
   binding: "Orders[customerId]",
   type: "Group",
});
templateSheet.setDataEntrySetting([{
   name: "Write Back Rule 1",
   tableName: "Orders",
   fields: [
       { dbColumnName: "orderId", formula: "A1", isPrimary: true },
       { dbColumnName: "customerId", formula: "B1" },
   ],
   includeUnmodified: false,
   skipRecordWithEmptyValue: false
}]);

report.bind(GC.Spread.Sheets.Events.ReportSheetDataChanging, (event, args) => {
    let { type, row, col, oldValue, newValue } = args;
    if (allowChange(oldValue, newValue)) { // 用户在此验证此更改操作。
        console.log(`Changing row: ${row}, col: ${col} from ${oldValue} to ${newValue}`);
    } else {
        args.cancel = true; // 用户在此取消此操作。
    }
});
report.bind(GC.Spread.Sheets.Events.ReportSheetDataChanged, (event, args) => {
    let changes = report.getChanges(); // 用户可以在此获取所有报告更改。
    if (needSubmit(changes)) {
        report.submit(); // 提交更改。
    } else {
        report.refresh(); // 恢复报告。
    }
});
// UI 中的数据输入操作。
report.renderMode("Preview");
report.updateCellValue(0, 1, "test");
report.addRecordAt(1, 0);
report.updateCellValue(2, 0, 111);
report.updateCellValue(2, 1, "test2");
report.deleteRecordAt(3, 0);

type=warning
注意：
如果在编辑单元格值时 oldValue 与 newValue 相同，则 ReportSheetDataChanging 和 ReportSheetDataChanged 事件不会触发
在 UI 中执行的操作，如更新单元格（例如按删除键、粘贴、重置值）、添加记录或删除记录将触发 ReportSheetDataChanging 和 ReportSheetDataChanged 事件

ReportSheetRecordsSubmitting 和 ReportSheetRecordsSubmitted

ReportSheetRecordsSubmitting：此事件在 ReportSheet 提交更改到服务器之前发生。它允许对所有数据更改进行最终验证或取消操作。
ReportSheetRecordsSubmitted：此事件在 ReportSheet 提交更改到服务器之后发生。它允许用户提供提交结果的 UI 反馈。

以下示例使用了 ReportSheetRecordsSubmitting 和 ReportSheetRecordsSubmitted 事件。

const report = spread.addSheetTab(0, "Report", GC.Spread.Sheets.SheetType.reportSheet);
report.renderMode("Design");
const templateSheet = report.getTemplate();
templateSheet.setTemplateCell(0, 0, {
   binding: "Orders[orderId]",
   type: "Group",
   showCollapseButton: true
});
templateSheet.setTemplateCell(0, 1, {
   binding: "Orders[customerId]",
   type: "Group",
});
templateSheet.setDataEntrySetting([{
   name: "Write Back Rule 1",
   tableName: "Orders",
   fields: [
       { dbColumnName: "orderId", formula: "A1", isPrimary: true },
       { dbColumnName: "customerId", formula: "B1" },
   ],
   includeUnmodified: false,
   skipRecordWithEmptyValue: false
}]);
// 对于某些希望在提交到服务器之前验证数据的用户，可以使用 `ReportSheetRecordsSubmitting` 事件。
reportsheet.bind(GC.Spread.Sheets.Events.ReportSheetRecordsSubmitting, (event, args) => {
    let changes = args.sheet.getChanges(); // 获取报告表的所有更改。
    for (let change of changes) {
        let { records, deleteRecords, rule } = change;
        let updateRecordsData = records.map((r) => r.entity), deleteRecordsData = deleteRecords.map((r) => r.entity);
        let tableName = rule.tableName;
        if (isInvalidData(updateRecordsData, tableName)) { // 用户验证数据。
            // 取消报告表提交操作。
            args.cancel = true;
            break;
        }
    }
});
// 对于某些希望自定义提交结果回调的用户，可以使用 `ReportSheetRecordsSubmitted` 事件获取成功和失败的结果。
reportsheet.bind(GC.Spread.Sheets.Events.ReportSheetRecordsSubmitted, (event, args) => {
    let { updateSuccessRecords, deleteSuccessRecords, updateFailedRecords, deleteFailedRecords } = args;
    for (let record of updateFailedRecords) {
        for (let fieldKey in record.info) {
            if (record.info.hasOwnproperty(fieldKey)) {
                let recordDetail = record.info[fieldKey];
                if (recordDetail.state === "updated") {
                    // 用户控制台输出失败的详细信息。
                    console.log(`Updated failed in row: ${recordDetail.row} col: ${recordDetail.col}, oldValue: ${recordDetail.oldValue}, reason is ${record.reason}`);
                }
            }
        }
    }
});
// UI 中的数据输入操作。
report.renderMode("Preview");
report.updateCellValue(0, 1, "test");
report.addRecordAt(1, 0);
report.updateCellValue(2, 0, 111);
report.updateCellValue(2, 1, "test2");
report.deleteRecordAt(3, 0);
report.submit();

type=warning
注意：在提交报告时，ReportSheetRecordsSubmitting 事件将始终触发。然而，如果更改记录和删除记录均为空白，则 ReportSheetRecordsSubmitted 事件将不会触发。