データ操作イベント

レポートシートには、レポートデータの変更や更新時に発生するイベントが用意されています。これらのイベントにより、データ変更を検証したり、データ入力中に操作をキャンセルしたりできます。また、サーバーからのフィードバック結果を受信し、その結果を確認することもできます。

レポートシートのデータの変更や挿入、削除の更新情報を取得するには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(); // 1 つの削除レコードと 2 つの更新レコード (「Write Back Rule 1」を使用)

type=warning
メモ：
getChanges メソッドは、データ操作設定の更新ルール（Write Back Rule）で設定したセル値のみを取得します。ただし、更新ルールのフィールド値がセルでない場合、フィールド情報は未定義になり、エンティティには収集されたレコード全体の値が表示されます。
getChanges メソッドは、更新ルールによって収集されたすべてのレコードを返します。変更がない場合は、空のレコードを含んだ更新ルールと削除されたレコードを返します。

レポートシートでは、次のデータ入力イベントがサポートされています。

ReportSheetDataChanging および ReportSheetDataChanged

ReportSheetDataChanging：このイベントは、レポートシートのデータが更新、挿入、または削除によって変更されるときに発生します。これにより、データ操作のを検証やキャンセルをすることができます。
ReportSheetDataChanged：このイベントは、レポートシートのデータが更新、挿入、または削除によって変更された後に発生します。これにより、データの変更をサーバーに送信できます。

次のサンプルコードは、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：このイベントは、レポートシートが変更をサーバーに送信するときに発生します。これにより、すべてのデータ変更の最終検証や操作のキャンセルが可能になります。
ReportSheetRecordsSubmitted：このイベントは、レポートシートが変更をサーバーに送信した後に発生します。これにより、サーバーから送信された結果を取得できます。

次のサンプルコードは、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
} ]);
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(`行の更新に失敗しました: ${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 イベントは発生しません。