arthub-table 0.0.6 → 0.1.0-beta.2

package/README.md

@@ -252,6 +252,285 @@ git tag v1.0.1
 git push origin v1.0.1
 ```
 
+## Table CRUD Operations — Best Practices
+
+> This section documents how to perform Create, Read, Update, Delete operations on cells, rows, and columns using the DataGrid component.
+
+### Core Concepts
+
+| Concept                | Description                                                                              |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `ref="datagrid"`       | The Vue template ref to access the DataGrid component instance                           |
+| `datagrid.value?.grid` | The underlying core `DataGrid` engine (for advanced low-level API)                       |
+| `loadData(data)`       | Re-render all rows with new data; resets editor and selection state                      |
+| `reload()`             | Recalculate table dimensions and scroll positions (after structural changes)             |
+| `markDirty()`          | Lightweight: flags the canvas for repaint on the next animation frame                    |
+| Vue Watcher            | Modifying `columns` or `data` refs automatically triggers `loadColumns()` + `loadData()` |
+
+---
+
+### 1. Update a Single Cell
+
+Use `grid.setData(value, { colIndex, rowIndex })` to write a value into a specific cell by its column and row index.
+
+```ts
+const grid = (datagrid.value as any)?.grid;
+
+// Update cell at row 0, column 2
+grid.setData("New Value", { colIndex: 2, rowIndex: 0 });
+
+// Trigger canvas repaint
+grid.markDirty();
+```
+
+> **Note:** `setData()` respects `readonly` columns. The cell's `originalValue` is preserved for change tracking.
+
+---
+
+### 2. Update an Entire Column
+
+Loop through all data rows and call `cell.setData()` on each cell object:
+
+```ts
+const grid = (datagrid.value as any)?.grid;
+const colIndex = 2; // Target column index
+
+gridData.value.forEach((_row, rowIndex) => {
+  if (_row.isGroup || _row.isSeparateRow) return; // Skip group/separator rows
+  const cell = grid.body.getCell(colIndex, rowIndex);
+  if (cell) {
+    cell.setData(`Col_Value_${rowIndex}`);
+  }
+});
+
+grid.markDirty();
+```
+
+---
+
+### 3. Batch Update a Rectangular Area
+
+Use `grid.batchSetData({ colIndex, rowIndex, value })` where `value` is a 2D array:
+
+```ts
+const grid = (datagrid.value as any)?.grid;
+
+// Write a 3-row × 2-column block starting at [row=0, col=1]
+grid.batchSetData({
+  colIndex: 1,
+  rowIndex: 0,
+  value: [
+    ["A1", "B1"],
+    ["A2", "B2"],
+    ["A3", "B3"],
+  ],
+});
+
+grid.markDirty();
+```
+
+---
+
+### 4. Update Rows by `rowKey` Match (Partial Update)
+
+Use `updateData(data)` to merge updates into existing rows matched by the `rowKey` field (default `"id"`):
+
+```ts
+datagrid.value?.updateData([
+  { id: 1, emp_name: "Updated Name 1", emp_no: "001" },
+  { id: 3, job_name: "Updated Job 3" },
+]);
+```
+
+> **Behavior:** Only the fields you provide will be updated. Other fields in the row are unchanged. This does NOT trigger a full reload; it updates in-place.
+
+---
+
+### 5. Refresh the Visible Area
+
+There are two levels of refresh:
+
+| Method                     | When to Use                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `grid.markDirty()`         | After data-only changes (cell values). Lightweight, uses `requestAnimationFrame`.                 |
+| `datagrid.value?.reload()` | After structural changes (columns added/removed, row heights changed). Full resize + recalculate. |
+
+```ts
+// Lightweight repaint
+const grid = (datagrid.value as any)?.grid;
+grid.markDirty();
+
+// Full reload (after structural changes)
+await nextTick();
+datagrid.value?.reload();
+```
+
+---
+
+### 6. Add a Row
+
+Append a new row object to the data array and call `loadData()`:
+
+```ts
+const newRow = {
+  _rowId: `row_${Date.now()}`,
+  id: gridData.value.length + 1,
+};
+
+// Dynamically fill all column keys with default values
+for (const col of columns.value) {
+  if (col.key && !(col.key in newRow)) {
+    newRow[col.key] = col.type === "number" ? 0 : "";
+  }
+}
+
+gridData.value.push(newRow);
+datagrid.value?.loadData(gridData.value);
+```
+
+> **Grouped mode:** Insert the row at the correct position within `groupedDataCache`, then filter and reload. See the `onAddRow()` handler in `App.vue` for a complete example.
+
+---
+
+### 7. Delete a Row
+
+Remove the row from the data array and reload:
+
+```ts
+const indexToDelete = gridData.value.findIndex(
+  (row) => !row.isGroup && !row.isSeparateRow,
+);
+
+if (indexToDelete >= 0) {
+  gridData.value.splice(indexToDelete, 1);
+  datagrid.value?.loadData(gridData.value);
+}
+```
+
+---
+
+### 8. Add a Column
+
+Add a new column definition to the `columns` ref. The Vue watcher will automatically trigger `loadColumns()` + `loadData()`:
+
+```ts
+const newCol = {
+  title: "New Column",
+  key: "new_col",
+  size: "small",
+  align: "left",
+};
+
+// Insert at a specific position
+const newColumns = [...columns.value];
+newColumns.splice(insertIndex, 0, newCol);
+columns.value = newColumns;
+
+// Fill data for the new column
+gridData.value.forEach((row, i) => {
+  if (!row.isGroup) {
+    row[newCol.key] = `Value_${i}`;
+  }
+});
+```
+
+---
+
+### 9. Delete a Column
+
+Remove the column from the `columns` ref:
+
+```ts
+const colIndexToDelete = columns.value.findIndex(
+  (col) => col.key === "target_key",
+);
+
+if (colIndexToDelete >= 0) {
+  const newColumns = [...columns.value];
+  newColumns.splice(colIndexToDelete, 1);
+  columns.value = newColumns;
+}
+```
+
+---
+
+### 10. Read Data
+
+| Method                                  | Returns     | Description                             |
+| --------------------------------------- | ----------- | --------------------------------------- |
+| `datagrid.value?.getData()`             | `RowData[]` | All row data with merged cell values    |
+| `datagrid.value?.getCheckedRows()`      | `RowData[]` | Rows where checkbox is checked          |
+| `datagrid.value?.getChangedRows()`      | `RowData[]` | Rows that have been modified since load |
+| `grid.body.getRowData(rowIndex)`        | `RowData`   | A single row by index                   |
+| `grid.body.getCell(colIndex, rowIndex)` | `Cell`      | A single cell object                    |
+
+```ts
+// Get all data
+const allData = datagrid.value?.getData();
+
+// Get changed rows only
+const changedRows = datagrid.value?.getChangedRows();
+
+// Get a single cell's value
+const grid = (datagrid.value as any)?.grid;
+const cell = grid.body.getCell(2, 0);
+console.log(cell.value); // Current cell value
+```
+
+---
+
+### 11. Validation
+
+```ts
+// Validate all cells
+datagrid.value?.validate((valid) => {
+  if (!valid) {
+    const errors = datagrid.value?.getValidations();
+    console.log("Validation errors:", errors);
+  }
+});
+
+// Validate only changed rows
+datagrid.value?.validateChanged((valid) => {
+  /* ... */
+});
+
+// Set external validation errors (matched by rowKey)
+datagrid.value?.setValidations([
+  { id: 1, emp_name: "Name is required", emp_no: "Invalid number" },
+  { id: 3, job_name: "Job name too long" },
+]);
+
+// Clear all validations
+datagrid.value?.clearValidations();
+```
+
+---
+
+### 12. Undo / Redo
+
+Built-in keyboard shortcuts:
+
+| Shortcut                 | Action         |
+| ------------------------ | -------------- |
+| `Ctrl+Z` / `Cmd+Z`       | Undo last edit |
+| `Ctrl+Y` / `Cmd+Shift+Z` | Redo last undo |
+
+> History is automatically tracked for `doneEdit()`, `pasteData()`, `autofillData()`, and `clearSelectedData()` operations. Max 20 history entries.
+
+---
+
+### Complete Example
+
+See `App.vue` for interactive demonstrations of all these patterns. The toolbar includes buttons for:
+
+- **✏️ 更新单个格子** — Single cell update via `grid.setData()`
+- **📝 更新整列** — Column-wide update via `cell.setData()` loop
+- **📋 批量更新区域** — Batch area update via `grid.batchSetData()`
+- **🔄 刷新可见区域** — Canvas repaint via `grid.markDirty()`
+- **➕ 新增一行 / ➕ 新增一列** — Dynamic row/column addition
+- **🗑️ 删除首行 / 🗑️ 删除末列** — Row/column deletion
+
 ## License
 
 [MIT](LICENSE)