cloud-web-corejs 1.0.54-dev.710 → 1.0.54-dev.712

package/src/components/xform/form-render/container-item/data-table-mixin.js

@@ -223,27 +223,42 @@ modules = {
     this.unregisterFromRefList();
   },
   methods: {
+    /*
+     * 数据约定：
+     * 1. formModel[fieldKeyName] 是提交与校验使用的表单数据；fieldModel 是 vxe-grid 的绑定数据。
+     * 2. _X_ROW_KEY 是前端稳定行主键，业务 id 在新增保存后可能被服务端替换。
+     * 3. 编辑表的临时增删改优先调用 VXE API，避免 setValue 全量重载导致行引用和编辑态丢失。
+     * 4. 树表提交使用扁平数据，VXE transform 模式内部同时维护树结构数据。
+     */
     initTableCustomEvent() {
       let tableConfig =
         this.handleCustomEvent(this.widget.options.tableConfig) || {};
       this.eventConfig = tableConfig.eventConfig || {};
     },
+    /** @param {Object} obj VXE 单元格参数。@returns {String|null} 状态项标签字段名。 */
     getTableColumnStatusWidgetLabelKey(obj) {
       let widget = this.getTableColumnWidget(obj);
       return widget ? this.getOptionItemLabelKey(widget) : null;
     },
+    /** @param {Object} widget 字段组件 schema。@returns {String} 选项值字段名。 */
     getOptionItemValueKey(widget) {
       if (widget?.options?.commonAttributeEnabled) {
         return widget.options.valueKey || "sn";
       }
       return widget.options.valueKey || "value";
     },
+    /** @param {Object} widget 字段组件 schema。@returns {String} 选项标签字段名。 */
     getOptionItemLabelKey(widget) {
       if (widget?.options?.commonAttributeEnabled) {
         return widget.options.labelKey || "value";
       }
       return widget.options.labelKey || "label";
     },
+    /**
+     * 获取当前行独立的列组件 schema；缺失时按列模板即时创建。
+     * @param {Object} obj VXE 单元格参数。
+     * @returns {Object|null}
+     */
     getTableColumnWidget(obj) {
       const rowKey = obj?.row?._X_ROW_KEY;
       const widget = obj?.column?.params?.widget;
@@ -259,6 +274,7 @@ modules = {
       }
       return rowSchema[widget.id] || null;
     },
+    /** @param {Object} obj VXE 单元格参数。@param {Object} item 状态选项。@returns {Boolean} */
     isShowColumnStatusWidget(obj, item) {
       let widget = this.getTableColumnWidget(obj);
       let valueKey = this.getOptionItemValueKey(widget);
@@ -266,10 +282,17 @@ modules = {
         obj.row[this.getTableColumnWidgetFieldKeyName(obj)] === item[valueKey]
       );
     },
+    /** @param {Object} obj VXE 单元格参数。@returns {String|null} 当前列绑定字段名。 */
     getTableColumnWidgetFieldKeyName(obj) {
       let widget = this.getTableColumnWidget(obj);
       return widget ? this.getFieldKeyName(widget) : null;
     },
+    /**
+     * 收集列组件的异步配置任务（脚本选项、公共属性字典等）。
+     * @param {Array} tableColumns 当前生效的列配置。
+     * @param {Object} options forceRefresh=true 时清除组件的同步完成标记。
+     * @returns {Promise[]} 可直接交给 Promise.all 的任务列表。
+     */
     collectColumnWidgetConfigRequests(tableColumns, options = {}) {
       const { forceRefresh = false } = options;
       const requests = [];
@@ -292,11 +315,13 @@ modules = {
       });
       return requests.filter(Boolean);
     },
+    /** @param {Object} widget 组件 schema。清除其远程选项同步标记。 */
     resetColumnWidgetSyncFlag(widget) {
       if (widget) {
         widget._syncInited = false;
       }
     },
+    /** @param {Object} columnRow 列配置。@param {Object} widget 组件 schema。同步列字段名。 */
     syncColumnWidgetFieldKey(columnRow, widget) {
       if (!widget || !columnRow?.prop) {
         return;
@@ -309,6 +334,7 @@ modules = {
         widget.options.name = prop;
       }
     },
+    /** @param {Array} tableColumns 当前列配置。将列字段名同步到展示和编辑组件。 */
     syncEffectiveColumnWidgetFieldKeys(tableColumns) {
       this.loodHandleColumns(tableColumns, (row) => {
         applyColumnMetaToColumnRow(row);
@@ -316,6 +342,11 @@ modules = {
         this.syncColumnWidgetFieldKey(row, row.editWidget);
       });
     },
+    /**
+     * 初始化列组件远程选项。
+     * @param {Function} callback 全部配置完成后的回调。
+     * @param {Object} options 可指定 columns 和 forceRefresh。
+     */
     initColumnWidgetConfig(callback, options = {}) {
       const tableColumns = options.columns ?? this.getEffectiveTableColumns();
       const requests = this.collectColumnWidgetConfigRequests(
@@ -330,6 +361,11 @@ modules = {
         callback && callback();
       }
     },
+    /**
+     * 重新加载列组件配置，并在完成后重建每行字段 schema。
+     * @param {Object} options 支持 columns、forceRefresh、success、fail、error。
+     * @returns {Promise<void>}
+     */
     refreshColumnWidgetConfig(options = {}) {
       const tableColumns = options.columns ?? this.getEffectiveTableColumns();
       const forceRefresh = options.forceRefresh !== false;
@@ -359,9 +395,11 @@ modules = {
         }
       });
     },
+    /** @param {Object} options 列组件刷新选项。@returns {Promise<void>} */
     reloadColumnWidgetOptions(options) {
       return this.refreshColumnWidgetConfig(options);
     },
+    /** @param {Object} widget 组件 schema。@param {Array} rows 远程选项数据。 */
     fillColumnWidgetOptionItems(widget, rows) {
       let widgetType = widget.type;
       let formScriptEnabledTypes = ["select", "checkbox", "radio"];
@@ -372,6 +410,12 @@ modules = {
       }
       widget._syncInited = true;
     },
+    /**
+     * 按组件配置加载脚本选项或公共属性字典。
+     * @param {Object} widget 组件 schema。
+     * @param {Function} callback 兼容保留参数。
+     * @returns {Promise|undefined}
+     */
     async handleColumnWidgetConfig(widget, callback) {
       if (!widget) return;
       let widgetType = widget.type;
@@ -428,6 +472,7 @@ modules = {
         });
       }
     },
+    /** 根据旧版 formatS/editFormatS 配置补建缺失的列组件 schema。 */
     initConfig() {
       let formRef = this.getFormRef();
       this.widget.options.tableColumns.forEach((row) => {
@@ -453,14 +498,17 @@ modules = {
         }
       });
     },
+    /** 按组件名称注册当前数据表实例，供表单脚本和其他组件查找。 */
     registerTableRefList() {
       this.sfRefList[this.widget.options.name] = this;
     },
+    /** @param {Object} row 行数据。@param {String} name 组件名。@returns {String} 行组件引用键。 */
     getRowRefKey(row, name) {
       let keyVal = row._X_ROW_KEY;
       let key = name + "_" + keyVal;
       return key;
     },
+    /** @param {Number} index 扁平数据行索引。@param {String} name 组件名。@returns {Object} 行组件 schema。 */
     getWidgetByTableRow(index, name) {
       // let target = this.getWidgetRefByTableRow(index, name)
       // let widget = target.field || target.widget;
@@ -470,22 +518,25 @@ modules = {
       let widget = this.getWidgetByTableRowData(row, name);
       return widget;
     },
+    /** @param {Number} index 扁平数据行索引。@param {String} name 组件名。@returns {Object} 组件实例。 */
     getWidgetRefByTableRow(index, name) {
       // let row = this.getGridTable().getTableData().fullData[index];
       let formRows = this.formModel[this.fieldKeyName];
       let row = formRows[index];
       return this.getWidgetRefByTableRowData(row, name);
     },
+    /** @param {Object} row 行数据。@param {String} name 组件名。@returns {Object} 行组件 schema。 */
     getWidgetByTableRowData(row, name) {
       let target = this.getWidgetRefByTableRowData(row, name);
       let widget = target.field || target.widget;
       return widget;
     },
+    /** @param {Object} row 行数据。@param {String} name 组件名。@returns {Object} 组件实例。 */
     getWidgetRefByTableRowData(row, name) {
       let key = this.getRowRefKey(row, name);
       return this.getWidgetRef(key);
     },
-
+    /** @param {Object} tableParam VXE 单元格参数。@returns {Object} 当前单元格组件实例。 */
     getWidgetRefByTableParam(tableParam) {
       let params = tableParam.column.params;
       let name = params.widget.options.name;
@@ -493,6 +544,7 @@ modules = {
       return this.getWidgetRefByTableRowData(tableParam.row, name);
       // return this.getWidgetRef(key);
     },
+    /** @param {Object} rowParam VXE 行参数。@param {Object} fieldWidget 可选组件模板。@returns {Object} 行级 schema。 */
     getRowWidget(rowParam, fieldWidget) {
       let row = rowParam.row;
       let params = rowParam.column.params;
@@ -500,6 +552,7 @@ modules = {
       let widget = this.fieldSchemaMap[row._X_ROW_KEY][widgetId];
       return widget;
     },
+    /** @param {String} name 组件名。@param {Function} callback 每行回调。 */
     loopHandleWidgetByName(name, callback) {
       let rows = this.getValue();
       rows.forEach((row, index) => {
@@ -510,6 +563,7 @@ modules = {
         }
       });
     },
+    /** @param {Object} rowParam VXE 行参数。@param {Object} fieldWidget 组件模板。@returns {Object} 动态组件绑定对象。 */
     getRowWidgetOption(rowParam, fieldWidget) {
       let widget = this.getRowWidget(rowParam, fieldWidget);
       let field = widget.category === "container" ? "widget" : "field";
@@ -518,16 +572,19 @@ modules = {
       };
       return option;
     },
+    /** @param {Object} rowParam VXE 行参数。@param {Object} fieldWidget 组件模板。@returns {String} 行组件渲染 key。 */
     getRowWidgetKey(rowParam, fieldWidget) {
       let widget = this.getRowWidget(rowParam, fieldWidget);
       let key = widget.id;
       return key;
     },
+    /** @returns {String} 由表单编码和组件名组成的唯一表格名称。 */
     getGridTableName() {
       let formCode = this.getFormRef().reportTemplate.formCode;
       let tableName = formCode + "_" + this.widget.options.name;
       return tableName;
     },
+    /** 将 fieldModel 当前内容同步到表单模型，并尽量保持原数组引用。 */
     updateFormField: function () {
       let rows = this.fieldModel || [];
       let formRows = this.formModel[this.fieldKeyName];
@@ -538,6 +595,7 @@ modules = {
         this.formModel[this.fieldKeyName] = rows;
       }
     },
+    /** @param {Array} val 已准备好的数据。初始化数据引用和行级 schema。 */
     initFieldSchema(val) {
       let rows = val || [];
       // 处理树结构数据排序
@@ -546,6 +604,7 @@ modules = {
       this.initRowIdData(true);
       this.initFieldSchemaData();
     },
+    /** @param {Array} val 外部传入数据。@returns {Array} 表单与 VXE 共用的标准化行。 */
     initValue(val) {
       // this.clearRowWidgets()
       let rows = this.normalizeTableRows(val || [], false);
@@ -557,7 +616,13 @@ modules = {
       this.fieldModel = rows;
       this.initRowIdData(true);
       this.initFieldSchemaData(true);
+      return rows;
     },
+    /**
+     * 将树表的扁平数据按父子关系排序；非树表原样返回。
+     * @param {Array} rows 原始行数据。
+     * @returns {Array|undefined} 根节点优先、子节点紧随父节点的扁平数组。
+     */
     handleTreeData(rows) {
       let isTreeTable = this.widget.options.isTreeTable;
       if (isTreeTable) {
@@ -602,6 +667,7 @@ modules = {
       }
       return rows;
     },
+    /** @param {*} parentId 父节点 id。@param {Map} nodeMap 节点映射。@param {String} parentField 父字段。@param {Array} sortedRows 输出数组。 */
     addChildNodes(parentId, nodeMap, parentField, sortedRows) {
       // 遍历所有节点，找出当前父节点的子节点
       for (let [id, node] of nodeMap.entries()) {
@@ -622,6 +688,12 @@ modules = {
         }
       }
     },
+    /**
+     * 补齐列字段和内部行主键。该方法会浅克隆每一行，不保留行对象引用。
+     * @param {Array} rows 待标准化数据。
+     * @param {Boolean} defaultValueEnabled 是否应用字段默认值。
+     * @returns {Array} 标准化后的新数组。
+     */
     normalizeTableRows(rows, defaultValueEnabled = false) {
       if (!Array.isArray(rows) || !rows.length) {
         return rows || [];
@@ -640,6 +712,11 @@ modules = {
         return nextRow;
       });
     },
+    /**
+     * 全量替换表格数据并重建行级 schema。
+     * 注意：该操作会触发 vxe-grid 重载，不用于编辑表的临时新增、保存或删除。
+     * @param {Array} val 新的完整数据集。
+     */
     setValue(val) {
       // console.log("rows:",val);
       this.clearRowWidgets();
@@ -652,13 +729,16 @@ modules = {
       this.initFieldSchemaData();
       // $grid.loadData(rows);
     },
+    /** @returns {Array} 表单模型中的当前扁平数据。 */
     getValue() {
       return this.formModel[this.fieldKeyName];
     },
+    /** @param {Object} widget 组件 schema。@returns {String} 组件实际绑定字段名。 */
     getFieldKeyName(widget) {
       let o = widget.options.name;
       return (widget.options.keyNameEnabled && widget.options.keyName) || o;
     },
+    /** @returns {String} 数据集必填校验提示。 */
     getDatasetRequiredHint() {
       if (this.widget.options.requiredHint) {
         return this.$t1(this.widget.options.requiredHint);
@@ -666,6 +746,7 @@ modules = {
       const label = this.$t1(this.widget.options.label || this.fieldKeyName);
       return this.$t1("[{label}]不能为空", { label });
     },
+    /** @returns {Boolean} 数据表整体必填校验是否通过。 */
     validateDatasetRequired() {
       if (!this.widget.options.required || this.widget.options.hidden) {
         return null;
@@ -676,6 +757,7 @@ modules = {
       }
       return this.getDatasetRequiredHint();
     },
+    /** @returns {Array} 当前参与单元格校验的数据。 */
     getValidationRows() {
       const formRows = this.formModel[this.fieldKeyName];
       if (Array.isArray(formRows) && formRows.length) {
@@ -687,6 +769,7 @@ modules = {
       }
       return [];
     },
+    /** @param {Object} row 行数据。@param {Array} rows 校验数据集。@param {Number} fallbackIndex 未匹配时索引。@returns {Number} */
     getValidationRowIndex(row, rows, fallbackIndex = 0) {
       if (!row || !Array.isArray(rows)) {
         return fallbackIndex;
@@ -703,6 +786,7 @@ modules = {
       const index = rows.indexOf(row);
       return index >= 0 ? index : fallbackIndex;
     },
+    /** @param {Object} column 列配置。@param {Boolean} isEditTable 是否编辑表。@param {Array} entries 输出数组。 */
     collectColumnValidateEntries(column, isEditTable, entries) {
       if (column.widget) {
         entries.push({
@@ -725,6 +809,7 @@ modules = {
         });
       }
     },
+    /** @param {Object} row 行数据。@param {Object} templateWidget 组件模板。@returns {Object} 当前行组件 schema。 */
     resolveRowFieldWidget(row, templateWidget) {
       if (!row || !templateWidget) {
         return templateWidget;
@@ -735,6 +820,7 @@ modules = {
       }
       return templateWidget;
     },
+    /** @param {Object} row 错误行。@param {String} propName 字段名。滚动并聚焦首个校验错误。 */
     locateValidationError(row, propName) {
       const $grid = this.getGridTable?.();
       if ($grid && row) {
@@ -748,6 +834,10 @@ modules = {
         renderForm.validateField(propName, () => {});
       }
     },
+    /**
+     * 按当前有效列逐单元格执行必填校验，并定位首个错误单元格。
+     * @returns {Promise<Boolean>} 全部通过时为 true。
+     */
     validateCellsRequired() {
       if (this.widget.options.hidden || this.designState) {
         return null;
@@ -819,12 +909,15 @@ modules = {
 
       return null;
     },
+    /** @param {Boolean} required 是否将整个数据表设为必填。 */
     setRequired(required) {
       this.$set(this.widget.options, "required", !!required);
     },
+    /** @param {Object} e 组件 schema。设计态选择当前组件。 */
     selectWidget: function (e) {
       this.designer.setSelected(e);
     },
+    /** @param {*} cellValue 单元格值。@param {String} formatS 格式编码。@param {Boolean} utcTransformEnabled 是否转换 UTC。@returns {*} */
     getFormatterValue(cellValue, formatS, utcTransformEnabled) {
       let value = cellValue;
       if (utcTransformEnabled && value != null && value !== "") {
@@ -873,6 +966,7 @@ modules = {
       }
       return value;
     },
+    /** @param {String} formatS 格式编码。@returns {Boolean} 是否由列层处理 UTC。 */
     isColumnLevelUtcFormat(formatS) {
       if (!formatS) {
         return true;
@@ -888,6 +982,7 @@ modules = {
         "modify_date",
       ].includes(formatS);
     },
+    /** @param {Object} column VXE 列配置。@returns {Boolean} 当前列是否启用 UTC 转换。 */
     getColumnUtcTransformEnabled(column) {
       const formatS = column.params?.formatS;
       if (!this.isColumnLevelUtcFormat(formatS)) {
@@ -898,6 +993,7 @@ modules = {
         column.params.columnConfig?.utcTransformEnabled
       );
     },
+    /** @param {Object} params VXE formatter 参数。@returns {*} 格式化后的单元格值。 */
     formatterValue: function ({ cellValue, row, column }) {
       if (cellValue === null || cellValue === undefined) return cellValue;
       if (!column.params) return cellValue;
@@ -909,15 +1005,19 @@ modules = {
       }
       return this.getFormatterValue(cellValue, formatS, utcTransformEnabled);
     },
+    /** @param {Object} e VXE 行参数。@returns {Number} 数据行索引。 */
     getRowIndex: function (e) {
       return this.widget.options.tableData.lastIndexOf(e);
     },
+    /** @returns {Array} 设计器保存的静态列配置。 */
     getTableColumns() {
       return this.widget.options.tableColumns || [];
     },
+    /** @returns {String} 动态列来源：none、script 或 api。 */
     getDynamicColumnSourceType() {
       return this.widget.options.dynamicColumnSourceType || "none";
     },
+    /** @returns {Array} 执行动态列脚本得到的原始列配置。 */
     getDynamicTableColumnsFromScript() {
       if (this.getDynamicColumnSourceType() !== "script") {
         return undefined;
@@ -932,6 +1032,7 @@ modules = {
       }
       return this.normalizeDynamicColumnResult(result);
     },
+    /** @param {*} result 动态列原始结果。@returns {Array} 统一后的列数组。 */
     normalizeDynamicColumnResult(result) {
       if (result === null || result === undefined) {
         return result;
@@ -948,6 +1049,12 @@ modules = {
       }
       return normalized;
     },
+    /**
+     * 按 dynamicColumnMode 合并设计期静态列与运行时动态列。
+     * @param {Array} staticColumns 设计器保存的列。
+     * @param {Array|Object} dynamicResult 动态列脚本或接口的返回结果。
+     * @returns {Array} 合并后的列配置。
+     */
     mergeDynamicTableColumns(staticColumns, dynamicResult) {
       const staticCols = staticColumns || [];
       if (dynamicResult === undefined || dynamicResult === null) {
@@ -967,6 +1074,11 @@ modules = {
       }
       return staticCols;
     },
+    /**
+     * 获取当前真正用于渲染的列；动态列可用时优先使用动态结果。
+     * @param {Boolean} forceDynamic 是否忽略初始化状态强制采用动态列。
+     * @returns {Array}
+     */
     getEffectiveTableColumns(forceDynamic = false) {
       const staticColumns = this.widget.options.tableColumns || [];
       const runtimeDynamic = this.dynamicTableColumns || [];
@@ -986,6 +1098,7 @@ modules = {
       }
       return staticColumns;
     },
+    /** @param {Array} tableColumns 列配置。为缺失组件的列补建 widget/editWidget。 */
     attachTableColumnWidgets(tableColumns) {
       if (!Array.isArray(tableColumns) || !tableColumns.length) {
         return tableColumns;
@@ -1005,12 +1118,14 @@ modules = {
       this.widget.options.tableColumns = savedColumns;
       return tableColumns;
     },
+    /** @param {Boolean} forceDynamic 是否强制动态列。@returns {Array} 已补齐组件的有效列。 */
     ensureEffectiveColumnWidgets(forceDynamic = false) {
       const effectiveColumns = this.getEffectiveTableColumns(forceDynamic);
       this.attachTableColumnWidgets(effectiveColumns);
       this.syncEffectiveColumnWidgetFieldKeys(effectiveColumns);
       this.afterDynamicColumnsCommonWidget(effectiveColumns);
     },
+    /** @param {Array} tableColumns 最终列配置。触发公共组件的动态列后处理。 */
     afterDynamicColumnsCommonWidget(tableColumns) {
       if (this.getDynamicColumnSourceType() === "none") return;
       const formRef = this.getFormRef();
@@ -1021,9 +1136,11 @@ modules = {
         }
       });
     },
+    /** @returns {Boolean} 首次初始化是否跳过动态列加载。 */
     shouldSkipDynamicColumnsOnInit() {
       return this.dynamicColumnsInitResolved && this.dynamicColumnsInitSkipped;
     },
+    /** @param {Object} columnConfig 列配置。@returns {Boolean} 列是否可见。 */
     getColumnVisible(columnConfig) {
       if (columnConfig.show === false) {
         return false;
@@ -1038,6 +1155,7 @@ modules = {
       }
       return true;
     },
+    /** @returns {Promise<Array>} 重建并重新加载当前有效列。 */
     applyTableColumnsReload() {
       this.ensureEffectiveColumnWidgets(true);
       const effectiveColumns = this.getEffectiveTableColumns(true);
@@ -1075,6 +1193,11 @@ modules = {
         );
       });
     },
+    /**
+     * 替换列配置并刷新 VXE 列、行 schema 和组件选项。
+     * @param {Array} tableColumns 新列配置。
+     * @returns {Promise<Array>} 实际应用到 VXE 的列配置。
+     */
     reloadTableColumns(tableColumns) {
       if (Array.isArray(tableColumns)) {
         this.dynamicTableColumns = [];
@@ -1082,12 +1205,19 @@ modules = {
       }
       return this.applyTableColumnsReload();
     },
+    /** @param {Array} tableColumns 新静态列。@returns {Promise<Array>} */
     setTableColumns(tableColumns) {
       return this.reloadTableColumns(tableColumns);
     },
+    /** @param {Array} tableColumns 新静态列。兼容旧版单数方法名。 */
     setTableColumn(tableColumns) {
       return this.setTableColumns(tableColumns);
     },
+    /**
+     * 写入动态列并应用到当前表格。
+     * @param {Array} tableColumns 动态列列表。
+     * @param {Object} options mode 控制 replace/append 等合并方式。
+     */
     setDynamicTableColumns(tableColumns, options = {}) {
       const { mode, deferReload } = options;
       return this.assignDynamicTableColumns(tableColumns, { mode }).then(
@@ -1102,9 +1232,11 @@ modules = {
         }
       );
     },
+    /** @returns {Promise<Array>} 根据最新显示条件刷新列。 */
     refreshColumnVisible() {
       return this.applyTableColumnsReload();
     },
+    /** @param {Object} options 动态列请求选项。@returns {Object} 接口请求数据。 */
     buildDynamicColumnRequestData(options = {}) {
       if (options.data !== undefined) {
         return options.data;
@@ -1140,6 +1272,7 @@ modules = {
         }
       );
     },
+    /** @param {Object} res 接口响应。@param {Object} options 解析配置。@returns {Array} 动态列。 */
     convertDynamicColumnResponse(res, options = {}) {
       const convertScript =
         options.convertScript ??
@@ -1151,6 +1284,11 @@ modules = {
       );
       return normalizeDynamicColumnList(items);
     },
+    /**
+     * 根据动态列来源（脚本或接口）加载列配置。
+     * @param {Object} options 请求参数及成功、失败回调。
+     * @returns {Promise<Array>} 解析并标准化后的动态列。
+     */
     loadDynamicColumns(options = {}) {
       const source = this.getDynamicColumnSourceType();
       if (source === "script") {
@@ -1179,6 +1317,7 @@ modules = {
         });
       });
     },
+    /** @returns {Promise<Boolean>} 当前初始化阶段是否需要加载动态列。 */
     resolveShouldInitDynamicColumns() {
       const source = this.getDynamicColumnSourceType();
       if (source === "none") {
@@ -1209,9 +1348,11 @@ modules = {
         return Promise.resolve(false);
       }
     },
+    /** @returns {Boolean} VXE 配置是否已完成初始化。 */
     isTableColumnGridInitialized() {
       return !!this.vxeOption;
     },
+    /** @param {Array} tableColumns 动态列。@param {Object} options 合并模式。@returns {Promise<Array>} */
     assignDynamicTableColumns(tableColumns, options = {}) {
       const { mode } = options;
       if (mode) {
@@ -1223,6 +1364,7 @@ modules = {
       this.ensureEffectiveColumnWidgets();
       return Promise.resolve(this.dynamicTableColumns);
     },
+    /** @param {Object} options 请求与回调配置。@returns {Promise<Object>} 包含响应和列数组。 */
     requestDynamicColumnsFromApi(options = {}) {
       const scriptCode =
         options.scriptCode ?? this.widget.options.dynamicColumnScriptCode;
@@ -1243,6 +1385,10 @@ modules = {
         return { res, columns };
       });
     },
+    /**
+     * 表格初始化前预加载动态列，保证首次创建 VXE 列时即使用最终配置。
+     * @returns {Promise<void>}
+     */
     bootstrapDynamicColumnsBeforeInit() {
       return this.resolveShouldInitDynamicColumns().then((shouldInit) => {
         this.dynamicColumnsInitResolved = true;
@@ -1259,6 +1405,7 @@ modules = {
         });
       });
     },
+    /** @returns {Promise} 在尚未预加载时尝试自动获取动态列。 */
     tryAutoLoadDynamicColumns() {
       if (
         this.dynamicColumnsPreloaded ||
@@ -1273,9 +1420,14 @@ modules = {
         return this.loadDynamicColumns({ isLoading: true }).catch(() => {});
       });
     },
+    /** @returns {Array} 组件配置中的静态 tableData。 */
     getTableData: function () {
       return this.widget.options.tableData;
     },
+    /**
+     * 重置查询表单，并按配置决定是否立即重新查询。
+     * @param {Object} options 可覆盖默认重置行为。
+     */
     resetForm(options) {
       let formData = this.formModel;
       let ignoreFields = options?.ignoreFields || [];
@@ -1291,6 +1443,7 @@ modules = {
         }
       });
     },
+    /** 执行查询表单搜索并重置到第一页。 */
     searchEvent() {
       this.getGridTable().commitProxy("reload");
     },
@@ -1298,6 +1451,7 @@ modules = {
       this.resetForm(options);
       this.getGridTable().commitProxy("reload");
     },
+    /** 查询区“搜索”按钮入口，先同步表单数据再发起查询。 */
     handleSearchClick() {
       if (this.widget.options.onSearchTable) {
         this.handleCustomEvent(this.widget.options.onSearchTable);
@@ -1305,6 +1459,7 @@ modules = {
       }
       this.searchEvent();
     },
+    /** 查询区“重置”按钮入口。 */
     handleResetClick() {
       if (this.widget.options.onResetTable) {
         this.handleCustomEvent(this.widget.options.onResetTable);
@@ -1312,6 +1467,12 @@ modules = {
       }
       this.resetEvent();
     },
+    /**
+     * 打开行编辑弹窗。
+     * @param {Object} row 当前行数据。
+     * @param {Object} param 传递给弹窗或脚本的附加参数。
+     * @param {Object} option 弹窗配置覆盖项。
+     */
     openEditDialog(row, param, option) {
       let formRef = this.getFormRef();
       let formConfig = this.formConfig;
@@ -1329,7 +1490,9 @@ modules = {
           ...option,
         });
     },
+    /** Excel 导入扩展入口，由具体业务按需覆盖。 */
     importExcel() {},
+    /** @param {Object} that 调用上下文。@param {String} tableRef 表格 ref。@returns {Object} VXE Grid 实例。 */
     getGrid(that, tableRef) {
       let $grid;
       if (Array.isArray(that.$refs[tableRef])) {
@@ -1339,12 +1502,14 @@ modules = {
       }
       return $grid;
     },
+    /** @returns {Object} 当前表格查询条件。 */
     getTableCondition: function () {
       if (this.widget.options.tableCondition) {
         let e = new Function(this.widget.options.tableCondition);
         return e.call(this);
       }
     },
+    /** @returns {Object} 查询区提交条件。 */
     getSearchCondition: function () {
       let extraAccessData = this.extraAccessData || {};
       let searchFormData = this.getSearchFormData();
@@ -1361,6 +1526,11 @@ modules = {
       };
       return conditions;
     },
+    /**
+     * 将设计器列转换成 VXE 列，挂载展示/编辑插槽及列级格式化配置。
+     * 同时收集行级组件模板，供 fieldSchemaMap 为每行克隆独立 schema。
+     * @returns {Array} VXE columns 配置。
+     */
     createColumns() {
       let rowWidgetList = [];
       let tableColumns = this.attachTableColumnWidgets(
@@ -1611,6 +1781,7 @@ modules = {
       return this.$baseLodash.cloneDeep(newColumns);
     },
     //begin
+    /** @param {Object} fieldWidget 选项组件 schema。@param {*} fieldModel 当前值。@returns {String} 展示标签。 */
     getOptionLabel(fieldWidget, fieldModel) {
       if (fieldModel === null) {
         return null;
@@ -1629,6 +1800,7 @@ modules = {
         return resultList.join(",");
       }
     },
+    /** @param {Object} fieldWidget 状态组件 schema。@param {*} fieldModel 当前值。@returns {String} 状态标签。 */
     getStatusOptionLabel(fieldWidget, fieldModel) {
       if (fieldModel === null || fieldModel === undefined) {
         return null;
@@ -1641,6 +1813,7 @@ modules = {
       );
       return statusItem ? this.$t1(statusItem[labelField]) : null;
     },
+    /** @param {Array} e 数据数组。@param {Function} t 匹配函数。@returns {*} 首个匹配项。 */
     findInArray: function (e, t) {
       if (!Array.isArray(e)) return -1;
       var i = -1;
@@ -2224,7 +2397,14 @@ modules = {
                         //导出
                         this.initExportFieldSchemaData(rows);
                       } else {
-                        this.initValue(rows);
+                        // VXE 与表单必须共用同一批标准化行，否则 _X_ROW_KEY 不一致，
+                        // 行虽能进入编辑态，但 editWidget 无法取得对应的行级 schema。
+                        rows = this.initValue(rows);
+                        if (res.objx?.records !== undefined) {
+                          res.objx.records = rows;
+                        } else {
+                          res.objx = rows;
+                        }
                       }
 
                       resolve(res);
@@ -2397,6 +2577,11 @@ modules = {
         });
       });
     },
+    /**
+     * 深度遍历分组列和叶子列。
+     * @param {Array} columns 列配置。
+     * @param {Function} callback 每个列节点的处理函数。
+     */
     loodHandleColumns(columns, callback) {
       let columnLoopDo = (t, e) => {
         callback && callback(t);
@@ -2412,10 +2597,12 @@ modules = {
       }
     },
 
+    /** @param {Array} list 数据列表。@param {String} field 数值字段。@returns {Number} 平均值。 */
     meanNum(list, field) {
       let count = this.sumNum(list, field);
       return this.$baseDiv(count, list.length);
     },
+    /** @param {Array} list 数据列表。@param {String} field 数值字段。@returns {Number} 合计值。 */
     sumNum(list, field) {
       let count = 0;
       list.forEach((item) => {
@@ -2423,6 +2610,7 @@ modules = {
       });
       return count;
     },
+    /** @returns {Object} 查询区当前字段值。 */
     getSearchFormData() {
       let map = { condition: [] };
       let formData = this.globalModel.formModel;
@@ -2468,10 +2656,12 @@ modules = {
       }
       return map;
     },
+    /** @returns {String} 当前列表请求 URL。 */
     getUrl() {
       let accessUrl = this.widget.options.accessUrl;
       return accessUrl || USER_PREFIX + `/form_ins/getFormInsData`;
     },
+    /** @returns {Array} 当前表格涉及的附件字段类型。 */
     getAttachmentType() {
       /* let vailColumns = this.widget.options.tableColumns.filter(
         (item) => item.prop && item.label
@@ -2492,6 +2682,7 @@ modules = {
       });
       return result;
     },
+    /** @returns {Array} 当前表格使用的三级表字段。 */
     getThirdtabm() {
       /* let vailColumns = this.widget.options.tableColumns.filter(
         (item) => item.prop && item.label
@@ -2518,6 +2709,10 @@ modules = {
       return result;
     },
 
+    /**
+     * 加载表格默认数据，统一处理分页结果、树排序、回调及行 schema 初始化。
+     * @param {Object} option 本次查询的覆盖配置。
+     */
     loadDefaultViewList(option) {
       let dataId = this.formDataId;
       let reportTemplate = this.getFormRef().reportTemplate;
@@ -2578,10 +2773,12 @@ modules = {
         },
       });
     },
+    /** @returns {Object} 当前表格脚本访问参数。 */
     getAccessParam() {
       if (!this.widget.options.formScriptParam) return;
       return this.handleCustomEvent(this.widget.options.formScriptParam);
     },
+    /** @returns {String} 当前列表查询脚本编码。 */
     getScriptCode() {
       let accessReturnType = this.widget.options.accessReturnType;
       let defaultScriptCode = "getList";
@@ -2593,6 +2790,12 @@ modules = {
       let scriptCode = this.widget.options.formScriptCode || defaultScriptCode;
       return scriptCode;
     },
+    /**
+     * 执行默认列表查询。
+     * @param {Object} reqData 查询请求数据。
+     * @param {Function} done VXE 代理查询完成回调。
+     * @param {Object} customParam 调用方附加参数。
+     */
     loadDefaultQueryList(reqData, done, customParam) {
       let reportTemplate = this.getFormRef().reportTemplate;
       let prefix = "/" + reportTemplate.serviceName;
@@ -2665,6 +2868,7 @@ modules = {
         },
       });
     },
+    /** @param {Boolean} flag 是否显示加载状态。重新加载当前表格数据。 */
     loadAccessData(flag) {
       if (
         this.formModel[this.fieldKeyName] &&
@@ -2688,6 +2892,7 @@ modules = {
         this.loadDefaultViewList();
       }
     },
+    /** @param {Object} item 参数配置。@param {*} dataId 主数据 id。@param {Object} billData 单据数据。@returns {Object} */
     getReqParam(item, dataId, billData) {
       let param = {};
       if (item.accessParam) {
@@ -2702,10 +2907,15 @@ modules = {
       }
       return param;
     },
+    /** @returns {String} 当前 vxe-grid 的 ref 名。 */
     getTableRef() {
       let tableRef = this.widget.id;
       return tableRef;
     },
+    /**
+     * 使用统一 Excel 导出器导出当前表格。
+     * @param {Object} option 导出参数；prefix 为空时自动使用当前服务前缀。
+     */
     exportData(option) {
       let tableRef = this.getTableRef();
       let serviceName = this.getFormRef().reportTemplate.serviceName;
@@ -2735,6 +2945,7 @@ modules = {
       });
       // this.deleteRowWidgets(row);
     },
+    /** @param {Object} widget 组件 schema。@returns {Boolean} 是否单值搜索组件。 */
     isSingerlSearch(widget) {
       let widgetType = widget?.type;
       let result =
@@ -2742,6 +2953,7 @@ modules = {
         (widgetType === "vabsearch" && !widget.options.multipleChoices);
       return result;
     },
+    /** @param {Object} widget 组件 schema。@param {Boolean} defaultValueEnabled 是否取默认值。@returns {*} 字段初始值。 */
     getColumnNullValue(widget, defaultValueEnabled) {
       if (!widget) return null;
       let nullValue = null;
@@ -2778,6 +2990,7 @@ modules = {
       }
       return nullValue;
     },
+    /** @param {Object} widget 组件 schema。@returns {Boolean} 是否表单字段组件。 */
     getIsFormWidget(widget) {
       let widgetTypes = ["baseAttachment"];
       let result = false;
@@ -2786,6 +2999,7 @@ modules = {
       }
       return result;
     },
+    /** @param {Object} widget 组件 schema。@param {Object} newData 目标行。@param {Boolean} defaultValueEnabled 是否取默认值。 */
     handleWidgetNullValue(widget, newData, defaultValueEnabled = true) {
       if (!widget || !newData) return;
       if (this.getIsFormWidget(widget)) {
@@ -2804,6 +3018,12 @@ modules = {
         }
       }
     },
+    /**
+     * 根据叶子列创建空行，并按展示/编辑组件补齐字段初始值。
+     * @param {Boolean} isEdit 是否优先采用 editWidget 配置。
+     * @param {Boolean} defaultValueEnabled 是否写入组件默认值。
+     * @returns {Object} 新行数据。
+     */
     createNewTableData(isEdit, defaultValueEnabled = true) {
       let newData = {};
       this.loodHandleColumns(this.widget.options.tableColumns, (item) => {
@@ -2832,6 +3052,11 @@ modules = {
       });
       return newData;
     },
+    /**
+     * 批量追加数据；field 存在时按该字段去重。
+     * @param {Array} rows 待追加数据。
+     * @param {String} field 可选的唯一性字段。
+     */
     addTableData(rows, field) {
       let $grid = this.getGridTable();
       let formDataModel = this.formModel;
@@ -2867,6 +3092,7 @@ modules = {
         this.handleWbs();
       });
     },
+    /** @param {Object} fieldWidget 组件 schema。@param {Object} obj VXE 单元格参数。@returns {String} 表单校验 prop。 */
     getColumnProp2(fieldWidget, obj) {
       let isQueryTable = this.widget.options.isQueryTable || false;
       let rowWidget = this.getRowWidget(obj, fieldWidget);
@@ -2888,6 +3114,7 @@ modules = {
       }
       return propName;
     },
+    /** @returns {Boolean} 是否满足表格勾选行要求。 */
     validateCheckRow() {
       let $grid = this.getGridTable();
       let checkRows = $grid.getCheckboxRecords(true);
@@ -2934,6 +3161,7 @@ modules = {
       });
       return !hasError;
     },
+    /** @param {Object} widget 组件 schema。@param {Object} row 行数据。@returns {String} 字段校验 prop。 */
     getColumnWidgetProp(widget, row) {
       if (!widget) return;
       let $grid = this.getGridTable();
@@ -2949,6 +3177,7 @@ modules = {
       let propName = fieldKeyName + "." + rowIndex + "." + property;
       return propName;
     },
+    /** @param {Object} obj VXE 单元格参数。@param {Boolean} isEdit 是否编辑插槽。@returns {String} 字段校验 prop。 */
     getColumnProp(obj, isEdit) {
       let sourceWidgetId = isEdit
         ? obj.column?.params?.editWidget?.id
@@ -2989,6 +3218,7 @@ modules = {
         return "false";
       }
     },
+    /** @param {Object} widget 组件 schema。@returns {Boolean} 是否搜索选择类组件。 */
     isVabsearchFlagWidget(widget) {
       let type = widget?.type;
       return (
@@ -2997,6 +3227,7 @@ modules = {
         type === "multiSearch"
       );
     },
+    /** @param {Object} e 组件 schema。@returns {String|undefined} 动态组件名称。 */
     getColumnWidgetName(e) {
       if (e && e.type) {
         if (e.category === "container") {
@@ -3006,16 +3237,20 @@ modules = {
         }
       }
     },
+    /** @returns {Object} 当前 VXE Grid 实例。 */
     getGridTable() {
       let $grid = this.$refs[this.getTableRef()];
       return $grid;
     },
+    /** @param {Object} e 容器组件 schema。@returns {String} 动态组件名称。 */
     getContainerWidgetName: function (e) {
       return "grid" === e.type ? "grid-item" : e.type + "-item";
     },
+    /** @param {Object} e 字段组件 schema。@returns {String} 动态组件名称。 */
     getWidgetName: function (e) {
       return (e.targetType || e.type) + "-widget";
     },
+    /** @param {Object} param VXE checkbox-change 参数。同步合并行选择并触发自定义事件。 */
     handleCheckboxChange(param) {
       let mergeRowEnabled = this.widget.options.mergeRowEnabled || false;
       let mergeRowKey = this.widget.options.mergeRowKey;
@@ -3038,6 +3273,7 @@ modules = {
       dataTableConfig.onCheckboxChange &&
         dataTableConfig.onCheckboxChange(param);
     },
+    /** @param {Object} param VXE checkbox-all 参数。触发全选自定义事件。 */
     handleCheckboxAll(param) {
       if (this.widget.options.onCheckboxAll) {
         let t = new Function("param", this.widget.options.onCheckboxAll);
@@ -3047,6 +3283,7 @@ modules = {
       let dataTableConfig = formRef.$attrs.dataTableOption || {};
       dataTableConfig.onCheckboxAll && dataTableConfig.onCheckboxAll(param);
     },
+    /** @param {Object} param VXE cell-dblclick 参数。执行配置的双击脚本。 */
     handleCellDblclick(param) {
       if (this.widget.options.onCellDblclick) {
         let t = new Function("param", this.widget.options.onCellDblclick);
@@ -3056,6 +3293,7 @@ modules = {
       let dataTableConfig = formRef.$attrs.dataTableOption || {};
       dataTableConfig.onCellDblclick && dataTableConfig.onCellDblclick(param);
     },
+    /** 清空高级查询条件并同步对应组件值。 */
     advancedClear() {
       let formModel = this.formModel;
       let searchColumns = this.getGridTable().params.searchColumns;
@@ -3070,12 +3308,17 @@ modules = {
       });
       // this.getGridTable().$forceUpdate();
     },
+    /** 查询字段设置确认后，将当前模型同步到表单。 */
     tableFormSettingConfirm() {
       let formModel = this.formModel;
       this.getFormRef().setFormData(formModel);
     },
 
     //editTable begin
+    /**
+     * 保存当前编辑行。成功后仅合并服务端字段，保留 VXE 行引用和 _X_ROW_KEY。
+     * @param {Object} obj VXE 插槽参数，必须包含 row 和 $table。
+     */
     async saveEditRow(obj) {
       let formRef = this.getFormRef();
       let formConfig = this.formConfig;
@@ -3149,6 +3392,7 @@ modules = {
         }
       });
     },
+    /** @param {*} dataId 行数据 id。@param {Function} callback 查询成功回调。加载保存后的完整行。 */
     getRowData(dataId, callback) {
       let reportTemplate = this.getFormRef()?.reportTemplate;
       let formCode = reportTemplate.formCode;
@@ -3173,17 +3417,27 @@ modules = {
         },
       });
     },
+    /** @param {Object} rowData 新行数据。@param {Object} obj 父行参数。@param {Boolean} toTop 是否插到顶部。 */
     addChildTreeRow(rowData, obj, toTop) {
       let toEnd = !toTop;
       this.addTreeRow(rowData, obj, toEnd, null);
     },
+    /** @param {Object} rowData 新行数据。@param {Boolean} toTop 是否插到顶部。新增一级节点。 */
     addTopTreeRow(rowData, toTop) {
       let toEnd = !toTop;
       this.addTreeRow(rowData, null, toEnd, null);
     },
+    /** @param {Object} rowData 新行数据。@param {Object} obj 目标行参数。新增同级节点。 */
     addSiblingTreeRow(rowData, obj) {
       this.addTreeRow(rowData, obj, null, true);
     },
+    /**
+     * 通过全量数据源新增普通树节点（非行编辑专用入口）。
+     * @param {Object} rowData 新节点初始值。
+     * @param {Object|null} obj 目标行的 VXE 参数；为空表示一级节点。
+     * @param {Boolean} toEnd 是否追加到同级末尾。
+     * @param {Boolean} toSibling 是否作为目标行的同级节点。
+     */
     addTreeRow(rowData, obj, toEnd, toSibling) {
       let isEditTable = this.widget.options.isEditTable || false;
       let parent = obj?.row;
@@ -3261,6 +3515,11 @@ modules = {
         });
       }
     },
+    /**
+     * 从普通树表删除节点及全部后代，并通过 setValue 重建树数据。
+     * 编辑表临时行应使用 removeEditRow，避免重载整表。
+     * @param {Object} obj VXE 行参数。
+     */
     removeTreeRow(obj) {
       let row = obj.row;
       let $grid = this.getGridTable();
@@ -3312,6 +3571,7 @@ modules = {
         this.handleWbs();
       });
     },
+    /** @param {String} authName 行按钮权限名。@returns {String|null} 完整权限编码。 */
     getTableRowAuthCode(authName) {
       if (!authName) {
         return null;
@@ -3322,6 +3582,7 @@ modules = {
       }
       return null;
     },
+    /** @param {String} authName 行按钮权限名。@returns {Boolean} 当前用户是否有权限。 */
     hasTableRowPermission(authName) {
       if (!authName) {
         return true;
@@ -3333,6 +3594,7 @@ modules = {
       let dispermissions = this.$store.getters.dispermissions;
       return !dispermissions.includes(authCode);
     },
+    /** @param {Object} obj VXE 单元格参数。@returns {Object} 行新增/编辑按钮配置。 */
     getEditTreeButtonGroupConfig(obj) {
       let columnConfig = obj?.column?.params?.columnConfig || {};
       let tableOptions = this.widget.options || {};
@@ -3343,18 +3605,23 @@ modules = {
         rowEditShow: columnConfig.rowEditShow,
       };
     },
+    /** @param {Object} obj VXE 单元格参数。@returns {String} 行新增权限名。 */
     getRowAddAuthName(obj) {
       return this.getEditTreeButtonGroupConfig(obj).rowAddAuthName;
     },
+    /** @param {Object} obj VXE 单元格参数。@returns {String} 行编辑权限名。 */
     getRowEditAuthName(obj) {
       return this.getEditTreeButtonGroupConfig(obj).rowEditAuthName;
     },
+    /** @param {Object} obj VXE 单元格参数。@returns {String|Function} 行新增显示脚本。 */
     getRowAddShow(obj) {
       return this.getEditTreeButtonGroupConfig(obj).rowAddShow;
     },
+    /** @param {Object} obj VXE 单元格参数。@returns {String|Function} 行编辑显示脚本。 */
     getRowEditShow(obj) {
       return this.getEditTreeButtonGroupConfig(obj).rowEditShow;
     },
+    /** @param {String|Function} script 显示条件脚本。@param {Object} obj VXE 行参数。@returns {Boolean} */
     isRowButtonShow(script, obj) {
       if (!script) {
         return true;
@@ -3362,12 +3629,14 @@ modules = {
       let result = this.handleCustomEvent(script, ["tableParam"], [obj]);
       return result !== false;
     },
+    /** @param {Object} obj VXE 行参数。@returns {Boolean} 是否显示行新增按钮。 */
     canShowRowAdd(obj) {
       return (
         this.hasTableRowPermission(this.getRowAddAuthName(obj)) &&
         this.isRowButtonShow(this.getRowAddShow(obj), obj)
       );
     },
+    /** @param {Object} obj VXE 行参数。@returns {Boolean} 是否显示行编辑按钮。 */
     canShowRowEdit(obj) {
       let isAddRow = !this.hasSaveRow(obj?.row);
       if (isAddRow) return true;
@@ -3376,6 +3645,7 @@ modules = {
         this.isRowButtonShow(this.getRowEditShow(obj), obj)
       );
     },
+    /** @param {Object} obj VXE 行参数。保存编辑前快照并激活该行。 */
     editRowEvent(obj) {
       if (!this.canShowRowEdit(obj)) {
         return false;
@@ -3387,9 +3657,18 @@ modules = {
       obj.$table.editCloneRow = this.$baseLodash.cloneDeep(obj.row);
       obj.$table.setActiveRow(row);
     },
+    /** @param {Object} rowData 新行数据。@param {Object} obj 目标行参数。新增可编辑同级行。 */
     addSiblingEditRow(rowData, obj) {
       this.addEditRow(rowData, obj, null, true);
     },
+    /**
+     * 新增可编辑行。编辑表使用 VXE insertAt 保持内部行引用，非编辑表走 setValue。
+     * @param {Object|null} rowData 新行初始值；null 表示使用默认空行。
+     * @param {Object|null} obj 目标行参数；树表中为空表示新增一级节点。
+     * @param {Boolean} toEnd 是否追加到末尾。
+     * @param {Boolean} toSibling 是否插入到目标行之后的同级位置。
+     * @returns {Boolean|undefined} 存在未保存行或无权限时返回 false。
+     */
     addEditRow(rowData, obj, toEnd, toSibling) {
       if (rowData == null && obj && !this.canShowRowAdd(obj)) {
         return false;
@@ -3515,6 +3794,12 @@ modules = {
       }
     },
     // setValue 会生成新的数据行并触发 vxe 异步重载，需等待内部行映射更新后再激活。
+    /**
+     * 数据源重载后按业务 id 找回 VXE 内部行并激活，避免使用失效的外部行引用。
+     * @param {Object} $grid VXE Grid 实例。
+     * @param {String|Number} rowId 业务行 id。
+     * @param {Number} retry 等待 VXE 行映射完成的重试次数。
+     */
     setActiveRowById($grid, rowId, retry = 0) {
       if (!$grid || rowId == null) {
         return;
@@ -3540,6 +3825,10 @@ modules = {
         $grid.setActiveRow(realRow);
       }
     },
+    /**
+     * 删除未保存的编辑行，不调用 setValue，避免整表重载和编辑状态抖动。
+     * @param {Object} obj VXE 行参数。
+     */
     async removeEditRow(obj) {
       let row = obj.row;
       let $grid = this.getGridTable();
@@ -3555,6 +3844,7 @@ modules = {
       this.handleWbs();
     },
     //editTable end
+    /** @returns {Object} 行查询通用的创建人信息配置。 */
     getHttpConfigForUser() {
       let defaultOption = {
         addCreateInfo: true,
@@ -3562,11 +3852,17 @@ modules = {
       };
       return defaultOption;
     },
+    /** @returns {Promise|undefined} 启用 WBS 时重算编码，否则不处理。 */
     handleWbs() {
       if (this.widget.options.wbsEnabled) {
         return this.updateWbs();
       }
     },
+    /**
+     * 按当前树顺序重算 WBS 编码，并同步回编辑表使用的扁平表单数据。
+     * 编辑树表必须读取 tableFullTreeData，因为 insertAt 新增的一级节点不一定进入 fullData。
+     * @returns {Promise} VXE 数据刷新结果。
+     */
     updateWbs() {
       let that = this;
       let $grid = that.getGridTable();
@@ -3605,6 +3901,10 @@ modules = {
       }
       return $grid.updateData();
     },
+    /**
+     * 将当前节点在同级节点中上移一位，并同步扁平表单数据与 WBS。
+     * @param {Object} obj VXE 行参数。
+     */
     moveUpRow(obj) {
       let row = obj.row;
       let $grid = this.getGridTable();
@@ -3649,6 +3949,10 @@ modules = {
         }
       }
     },
+    /**
+     * 将当前节点在同级节点中下移一位，并同步扁平表单数据与 WBS。
+     * @param {Object} obj VXE 行参数。
+     */
     moveDownRow(obj) {
       let row = obj.row;
       let $grid = this.getGridTable();
@@ -3694,6 +3998,7 @@ modules = {
       }
     },
 
+    /** @param {Object} obj VXE 行参数。打开当前层级的树节点排序弹窗。 */
     openSortRowDialog(obj) {
       let $grid = this.getGridTable();
       let parentField = $grid.treeConfig.parentField;
@@ -3711,6 +4016,7 @@ modules = {
       this.sortParentRow = sortParentRow;
       this.showTreeMoveDialog = true;
     },
+    /** @param {Array} rows 弹窗确认后的同级节点顺序。同步回表格数据。 */
     confirmTreeMoveDialog(rows) {
       if (this.widget.options.isEditTable) {
         let reportTemplate = this.getFormRef().reportTemplate;
@@ -3751,6 +4057,11 @@ modules = {
       }
     },
     // 通用行合并函数（将相同多列数据合并为一行）
+    /**
+     * 按配置字段计算连续相同值的纵向合并范围。
+     * @param {Object} tableParam VXE span-method 参数。
+     * @returns {Object|undefined} 包含 rowspan、colspan 的合并信息。
+     */
     mergeRowMethod(tableParam) {
       let { row, _rowIndex, column, visibleData } = tableParam;
       let mergeRowEnabled = this.widget.options.mergeRowEnabled || false;
@@ -3775,6 +4086,11 @@ modules = {
         // return { rowspan: 1, colspan: 1 }
       }
     },
+    /**
+     * 合并行算法的解构参数版本。
+     * @param {Object} tableParam 包含 row、_rowIndex、column、visibleData。
+     * @returns {Object|undefined} 合并范围。
+     */
     mergeRowMethod2({ row, _rowIndex, column, visibleData }) {
       const fields = ["key"];
       const cellValue = row[column.field];
@@ -3835,9 +4151,11 @@ modules = {
       newFieldSchema.id = fieldWidget.type + generateId()
       return newFieldSchema
     },*/
+    /** 清理行组件缓存的兼容入口，当前实现保留缓存。 */
     clearRowWidgets() {
       // this.widgetMap = {};
     },
+    /** @param {Object} row 行数据。删除该行注册的组件引用。 */
     deleteRowWidgets(row) {
       this.rowWidgetList.forEach((widget) => {
         let key = this.getRowRefKey(row, widget.options.name);
@@ -3847,10 +4165,15 @@ modules = {
     /**end*/
 
     //begin1
+    /** 重新生成行主键列表和全部行级 schema。 */
     initAllFieldSchema() {
       this.initRowIdData(true);
       this.initFieldSchemaData();
     },
+    /**
+     * 根据表单数据刷新行主键列表，并为缺少主键的行生成 _X_ROW_KEY。
+     * @param {Boolean} initFlag 初始化标记，保留给行变化事件扩展使用。
+     */
     initRowIdData(initFlag) {
       this.rowIdData.splice(0, this.rowIdData.length); //清除数组必须用splice，length=0不会响应式更新！！
       let subFormModel = this.formModel[this.fieldKeyName];
@@ -3868,6 +4191,10 @@ modules = {
         }*/
       }
     },
+    /**
+     * 为每一行创建独立字段 schema，避免组件状态在不同行之间共享。
+     * @param {Boolean} initFlag true 时忽略旧 schema 并全部重新创建。
+     */
     initFieldSchemaData(initFlag) {
       //初始化fieldSchemaData！！！
       /*if (this.widget.type !== 'sub-form') {
@@ -3910,6 +4237,7 @@ modules = {
         }
       }
     },
+    /** @returns {Array} VXE 当前完整列；实例未就绪时回退到配置列。 */
     getTableFullColumns() {
       let target = this.getGridTable();
       if (target?.getTableColumn) {
@@ -3920,6 +4248,12 @@ modules = {
       }
       return this.vxeOption?.columns || [];
     },
+    /**
+     * 递归提取分组表头下的叶子列。
+     * @param {Array} columns VXE 列树。
+     * @param {Array} result 递归累积数组。
+     * @returns {Array} 叶子列列表。
+     */
     collectLeafTableColumns(columns, result = []) {
       if (!Array.isArray(columns)) {
         return result;
@@ -3933,6 +4267,10 @@ modules = {
       });
       return result;
     },
+    /**
+     * 根据当前有效叶子列，为单行克隆展示组件、编辑组件和组合组件 schema。
+     * @returns {Object} 以原组件 id 为键的行级 schema 映射。
+     */
     createRowFieldSchemaMap() {
       let fullColumn = this.collectLeafTableColumns(
         this.getTableFullColumns(),
@@ -3964,6 +4302,7 @@ modules = {
       });
       return fieldSchemaMap2;
     },
+    /** @param {Number} rowIndex 可选插入位置。向旧版 fieldSchemaData 增加一行 schema。 */
     addToFieldSchemaData(rowIndex) {
       let fieldSchemas = [];
       this.widget.widgetList.forEach((swItem) => {
@@ -3977,16 +4316,19 @@ modules = {
       }
     },
 
+    /** @param {Number} rowIndex 行索引。从旧版 fieldSchemaData 删除 schema。 */
     deleteFromFieldSchemaData(rowIndex) {
       this.fieldSchemaData.splice(rowIndex, 1);
     },
 
+    /** @param {Object} fieldWidget 组件模板。@returns {Object} 带新 id 的深克隆 schema。 */
     cloneFieldSchema(fieldWidget) {
       let newFieldSchema = deepClone(fieldWidget);
       newFieldSchema.id = fieldWidget.type + generateId();
       return newFieldSchema;
     },
     //end1
+    /** @param {Array} rows 导出数据。为无行主键的数据创建临时 schema。 */
     initExportFieldSchemaData(rows) {
       if (!rows) return;
       //初始化fieldSchemaData！！！
@@ -3998,6 +4340,7 @@ modules = {
         fieldSchemaMap[row._X_ROW_KEY] = fieldSchemaMap2;
       }
     },
+    /** 注册 setFormData 等组件内部事件。 */
     initEventHandler() {
       if (this.designState) return;
       this.$on("setFormData", (o) => {
@@ -4005,11 +4348,17 @@ modules = {
         this.setValue(rows);
       });
     },
+    /** @param {Object} widget 组件 schema。@param {Array<String>} ignoreFields 忽略字段。@returns {Boolean} 是否处理禁用状态。 */
     isDisHandleWidget(widget, ignoreFields) {
       let flag1 = widget.options.hasOwnProperty("disabled");
       let flag2 = !ignoreFields || !ignoreFields.includes(widget.options.name);
       return flag1 && flag2;
     },
+    /**
+     * 批量设置表格内按钮、查询字段及单元格组件的禁用状态。
+     * @param {Boolean} disabled 是否禁用。
+     * @param {Array<String>} ignoreFields 不参与切换的字段名。
+     */
     setGridDisabled(disabled, ignoreFields) {
       if (!!this.widget.widgetList) {
         traverseAllWidgetsNew(this.widget.widgetList, (widget) => {
@@ -4068,6 +4417,12 @@ modules = {
         });
       }
     },
+    /**
+     * 设置指定数据行内组件的禁用状态。
+     * @param {Boolean} disabled 是否禁用。
+     * @param {Number} rowIndex 表单扁平数据中的行索引。
+     * @param {Array<String>} ignoreFields 不参与切换的字段名。
+     */
     setRowDisabled(disabled, rowIndex, ignoreFields) {
       let gsfFWList = [];
       let fieldListFn = (fw) => {
@@ -4105,13 +4460,16 @@ modules = {
       });
     },
     //xk begin
+    /** 禁用表格内全部可处理组件。 */
     disableGridForm() {
       this.setGridDisabled(true);
     },
+    /** 启用表格内全部可处理组件。 */
     enableGridForm() {
       this.setGridDisabled(false);
     },
     //xk end
+    /** @param {Array} rows 行数据。为缺失的列字段补入空值。 */
     handleNullValue(rows) {
       let newData = this.createNewTableData(true, false);
       let keys = Object.keys(newData);