add more comments

lib/ui/grid/grid.js

@@ -63,6 +63,7 @@ let r = lang;
  * @typedef ValueItem
  * @property {any} Value - 值
  * @property {string} DisplayValue - 显示值
+ * @property {boolean} [__checked] - 已选中
  */
 
 /**
@@ -70,6 +71,12 @@ let r = lang;
  * @typedef GridItemWrapper
  * @property {Map<string, ValueItem>} values - 真实数据对象
  * @property {Map<string, GridSourceItem[]>} source - 下拉数据源缓存对象
+ * @property {number} __index - 行索引
+ * @property {number} __offset - 批量删除时暂存的索引偏移量
+ * @property {Map<string, boolean>} __editing - 列正在编辑
+ * @property {boolean} __changed - 行数据是否发生改变
+ * @property {boolean} __expanded - 行是否已展开
+ * @property {GridExpandableObject} __expandable_object - 行扩展对象
  */
 
 /**
@@ -226,6 +233,7 @@ let r = lang;
  * @property {Map<string, ValueItem>} attrs.item - 行数据对象
  * @property {any} attrs.{returns} - 返回附加属性对象
  * @property {boolean} [allowFilter=false] - 是否允许进行列头过滤
+ * @property {any[]} [filterValues] - 过滤值的数组
  * @property {boolean} [filterAllowNull=false] - 是否区分 `null` 与空字符串
  * @property {(ValueItem[] | GridColumnFilterSourceCallback)} [filterSource] - 自定义列过滤器的数据源，允许调用如下函数
  * @property {Grid} filterSource.{this} - 上下文为 Grid
@@ -362,7 +370,7 @@ class GridColumnDefinition {
     /**
      * 列对齐方式
      * @type {("left" |"center" | "right")}
-     * @default left
+     * @default "left"
      * @private
      */
     align;
@@ -493,6 +501,12 @@ class GridColumnDefinition {
      * @private
      */
     allowFilter;
+    /**
+     * 过滤值的数组
+     * @type {any[]}
+     * @private
+     */
+    filterValues;
     /**
      * 是否区分 `null` 与空字符串
      * @type {boolean}
@@ -534,7 +548,7 @@ class GridColumnDefinition {
     /**
      * 列为图标类型时以该值设置图标样式
      * @type {("fa-light" | "fa-regular" | "fa-solid")}
-     * @default fa-light
+     * @default "fa-light"
      * @private
      */
     iconType;
@@ -679,6 +693,22 @@ const GridColumnDirection = {
  * @this Grid
  */
 
+/**
+ * @typedef GridColumnAttr
+ * @property {boolean} dragging - 列正在拖拽
+ * @property {number} offset - 列拖拽偏移
+ * @property {Function} mousemove - 拖拽或调整大小移动回调函数
+ * @property {Function} mouseup - 拖拽或调整大小鼠标释放回调函数
+ * @property {number} resizing - 列临时大小
+ * @property {boolean} sizing - 列已进入修改大小的状态
+ * @property {boolean} autoResize - 列需要自动调整大小
+ * @property {any} style - 列样式对象
+ * @property {ValueItem[]} filterSource - 列过滤面板数据源
+ * @property {number} filterHeight - 列过滤面板高度
+ * @property {number} filterTop - 列过滤面板滚动头部间距
+ * @private
+ */
+
 /**
  * Grid 控件基础类
  * 
@@ -686,6 +716,43 @@ const GridColumnDirection = {
  * 函数调用流程图<br/>
  * <img src="./assets/grid.jpg" alt="Grid"/>
  * @class
+ * @property {GridColumnDefinition[]} columns - 列定义的数组
+ * @property {Map<string, ValueItem>} [total] - 合计行数据
+ * @property {any} [langs] - 多语言资源对象
+ * @property {string} [langs.all=( All )]
+ * @property {string} [langs.ok=OK]
+ * @property {string} [langs.reset=Reset]
+ * @property {string} [langs.cancel=Cancel]
+ * @property {string} [langs.null=( Null )]
+ * @property {string} [langs.addLevel=Add Level]
+ * @property {string} [langs.deleteLevel=Delete Level]
+ * @property {string} [langs.copyLevel=Copy Level]
+ * @property {string} [langs.asc=Ascending]
+ * @property {string} [langs.desc=Descending]
+ * @property {string} [langs.column=Column]
+ * @property {string} [langs.order=Order]
+ * @property {string} [langs.sort=Sort]
+ * @property {string} [langs.requirePrompt=All sort criteria must have...]
+ * @property {string} [langs.duplicatePrompt={column} is being sorted more than once...]
+ * @property {number} [virtualCount=100] - 行数大于等于该值则启用虚模式
+ * @property {number} [rowHeight=36] - 表格行高
+ * @property {string} [filterIcon=filter] - 列头过滤图标，旧版本样式（横着三个点）需修改为 `"ellipsis-h"`
+ * @property {number} [extraRows=0] - 列表底部留出额外的空白行
+ * @property {number} [filterRowHeight=30] - 过滤条件列表的行高
+ * @property {number} [height] - 列表高度值，为 0 时列表始终显示全部内容（自增高），为非数字或者小于 0 则根据容器高度来确定虚模式的渲染行数
+ * @property {boolean} [multiSelect=false] - 是否允许多选
+ * @property {boolean} [fullrowClick=true] - 为 `false` 时只有点击在单元格内才会选中行
+ * @property {boolean} [tooltipDisabled=false] - 单元格 tooltip 是否禁用
+ * @property {boolean} [headerVisible=true] - 列头是否显示
+ * @property {(Window | HTMLElement)} [window=global] - 监听事件的窗口载体
+ * @property {number} [sortIndex=-1] - 排序列的索引
+ * @property {GridColumnDirection} [sortDirection=GridColumnDirection.Ascending] - 排序方式，正数升序，负数倒序
+ * @property {GridColumnSortDefinition[]} [sortArray] - 排序列数组
+ * @property {boolean} [expandable=false] - 是否支持点击扩展
+ * @property {GridExpandableObjectCallback} [expandableGenerator] - 扩展行生成器
+ * @property {Grid} expandableGenerator.{this} - 上下文为 Grid
+ * @property {Map<string, ValueItem>} expandableGenerator.item - 行数据对象
+ * @property {GridExpandableObject} expandableGenerator.{returns} - 返回扩展行对象
  * @example <caption>基础示例</caption>
  *  <div id="grid"></div>
  * @example
@@ -820,25 +887,14 @@ export class Grid {
         rowCount: -1,
         /**
          * 列类型缓存字典
+         * @type {Map<string, GridColumn>}
          * @private
-         * @property {GridColumn} {key} - 关键字对应列的类型缓存对象
          */
         colTypes: {},
         /**
          * 列属性字典
+         * @type {Map<string, GridColumnAttr>}
          * @private
-         * @property {any} {key} - 关键字对应列的拖拽、调整大小暂存对象
-         * @property {boolean} {key}.dragging - 列正在拖拽
-         * @property {number} {key}.offset - 列拖拽偏移
-         * @property {Function} {key}.mousemove - 拖拽或调整大小移动回调函数
-         * @property {Function} {key}.mouseup - 拖拽或调整大小鼠标释放回调函数
-         * @property {number} {key}.resizing - 列临时大小
-         * @property {boolean} {key}.sizing - 列已进入修改大小的状态
-         * @property {boolean} {key}.autoResize - 列需要自动调整大小
-         * @property {any} {key}.style - 列样式对象
-         * @property {ValueItem[]} {key}.filterSource - 列过滤面板数据源
-         * @property {number} {key}.filterHeight - 列过滤面板高度
-         * @property {number} {key}.filterTop - 列过滤面板滚动头部间距
          */
         colAttrs: {
             /**
@@ -967,138 +1023,219 @@ export class Grid {
     /**
      * 列定义的数组
      * @type {GridColumnDefinition[]}
+     * @private
      */
     columns = [];
     /**
      * 合计行数据
      * @type {Map<string, ValueItem>}
+     * @private
      */
     total = null;
     /**
      * 多语言资源对象
-     * @type {any}
-     * @property {string} [all=( All )]
-     * @property {string} [ok=OK]
-     * @property {string} [reset=Reset]
-     * @property {string} [cancel=Cancel]
-     * @property {string} [null=( Null )]
-     * @property {string} [addLevel=Add Level]
-     * @property {string} [deleteLevel=Delete Level]
-     * @property {string} [copyLevel=Copy Level]
-     * @property {string} [asc=Ascending]
-     * @property {string} [desc=Descending]
-     * @property {string} [column=Column]
-     * @property {string} [order=Order]
-     * @property {string} [sort=Sort]
-     * @property {string} [requirePrompt=All sort criteria must have a column specified. Check the selected sort criteria and try again.]
-     * @property {string} [duplicatePrompt={column} is being sorted more than once. Delete the duplicate sort criteria and try again.]
+     * @private
      */
-    langs = {};
+    langs = {
+        /**
+         * @type {string}
+         * @default "( All )"
+         * @private
+         */
+        all: null,
+        /**
+         * @type {string}
+         * @default "OK"
+         * @private
+         */
+        ok: null,
+        /**
+         * @type {string}
+         * @default "Reset"
+         * @private
+         */
+        reset: null,
+        /**
+         * @type {string}
+         * @default "Cancel"
+         * @private
+         */
+        cancel: null,
+        /**
+         * @type {string}
+         * @default "( Null )"
+         * @private
+         */
+        null: null,
+        /**
+         * @type {string}
+         * @default "Add Level"
+         * @private
+         */
+        addLevel: null,
+        /**
+         * @type {string}
+         * @default "Delete Level"
+         * @private
+         */
+        deleteLevel: null,
+        /**
+         * @type {string}
+         * @default "Copy Level"
+         * @private
+         */
+        copyLevel: null,
+        /**
+         * @type {string}
+         * @default "Ascending"
+         * @private
+         */
+        asc: null,
+        /**
+         * @type {string}
+         * @default "Descending"
+         * @private
+         */
+        desc: null,
+        /**
+         * @type {string}
+         * @default "Column"
+         * @private
+         */
+        column: null,
+        /**
+         * @type {string}
+         * @default "Order"
+         * @private
+         */
+        order: null,
+        /**
+         * @type {string}
+         * @default "Sort"
+         * @private
+         */
+        sort: null,
+        /**
+         * @type {string}
+         * @default "All sort criteria must have a column specified. Check the selected sort criteria and try again."
+         * @private
+         */
+        requirePrompt: null,
+        /**
+         * @type {string}
+         * @default "{column} is being sorted more than once. Delete the duplicate sort criteria and try again."
+         * @private
+         */
+        duplicatePrompt: null
+    };
     /**
      * 行数大于等于该值则启用虚模式
      * @type {number}
      * @default 100
+     * @private
      */
     virtualCount = 100;
     /**
      * 表格行高
      * @type {number}
      * @default 36
+     * @private
      */
     rowHeight = 36;
     /**
      * 列头过滤图标，旧版本样式（横着三个点）需修改为 `ellipsis-h`
      * @type {string}
-     * @default filter
+     * @default "filter"
+     * @private
      */
     filterIcon = 'filter';
-    /**
-     * 文本行高
-     * @type {number}
-     * @default 24
-     */
-    lineHeight = 24;
     /**
      * 列表底部留出额外的空白行
      * @type {number}
      * @default 0
+     * @private
      */
     extraRows = 0;
     /**
      * 过滤条件列表的行高
      * @type {number}
      * @default 30
+     * @private
      */
     filterRowHeight = 30;
     /**
      * 列表高度值，为 0 时列表始终显示全部内容（自增高），为非数字或者小于 0 则根据容器高度来确定虚模式的渲染行数
      * @type {number | null}
+     * @private
      */
     height;
     /**
      * 是否允许多选
      * @type {boolean}
      * @default false
+     * @private
      */
     multiSelect = false;
     /**
      * 为 `false` 时只有点击在单元格内才会选中行
      * @type {boolean}
      * @default true
+     * @private
      */
     fullrowClick = true;
     /**
      * 单元格 tooltip 是否禁用
      * @type {boolean}
      * @default false
+     * @private
      */
     tooltipDisabled = false;
     /**
      * 列头是否显示
      * @type {boolean}
      * @default true
+     * @private
      */
     headerVisible = true;
     /**
      * 监听事件的窗口载体
      * @type {(Window | HTMLElement)}
      * @default window
+     * @private
      */
-    window = global;
+    window;
     /**
      * 排序列的索引
      * @type {number}
      * @default -1
+     * @private
      */
     sortIndex = -1;
     /**
      * 排序方式，正数升序，负数倒序
      * @type {GridColumnDirection}
      * @default GridColumnDirection.Ascending
+     * @private
      */
     sortDirection = GridColumnDirection.Ascending;
     /**
      * 排序列数组
      * @type {GridColumnSortDefinition[]}
      * @default null
-     * @property {string} column - 排序列的关键字
-     * @property {("asc" | "desc")} order - 升序或降序
+     * @private
      */
     sortArray = null;
     /**
      * 是否支持点击扩展
      * @type {boolean}
      * @default false
+     * @private
      */
     expandable;
     /**
      * 扩展行生成器
      * @type {GridExpandableObjectCallback}
-     * @property {Grid} {this} - 上下文为 Grid
-     * @property {Map<string, ValueItem>} item - 行数据对象
-     * @property {GridExpandableObject} {returns} - 返回扩展行对象
-     * @property {number} {returns}.index - 行索引
-     * @property {HTMLElement} {returns}.element - 扩展行元素
+     * @private
      */
     expandableGenerator;
 
@@ -1268,8 +1405,6 @@ export class Grid {
     /**
      * 获取已过滤的数据数组，或者设置数据并刷新列表
      * @type {Array<Map<string, ValueItem>>}
-     * @property {any} Value - 值
-     * @property {string} DisplayValue - 显示值
      */
     get source() { return this._var.currentSource?.map(s => s.values) }
     set source(list) {
@@ -1283,7 +1418,7 @@ export class Grid {
             return {
                 __index: index,
                 values: it
-            }
+            };
         });
         this._var.source = list;
         this._refreshSource(list);
@@ -1635,9 +1770,6 @@ export class Grid {
      * @param {HTMLElement} [container=.ctor#container] - 父容器元素，若未传值则采用构造方法中传入的父容器元素
      */
     init(container = this._var.parent) {
-        this._var.el = null;
-        this._var.refs = {};
-        this._var.rendering = true;
         if (container == null) {
             throw new Error('no specified parent.');
         }
@@ -1648,6 +1780,12 @@ export class Grid {
             }
             container = ele;
         }
+        if (!Array.isArray(this.columns)) {
+            throw new Error('no specified column definitions.');
+        }
+        this._var.el = null;
+        this._var.refs = {};
+        this._var.rendering = true;
         this._var.parent = container;
         this._var.isFirefox = /Firefox\//i.test(navigator.userAgent);
         const grid = createElement('div', 'ui-grid');
@@ -3520,6 +3658,7 @@ export class Grid {
         }
         const index = indexOfParent(e.currentTarget) - (this.expandable ? 1 : 0);
         const cx = getClientX(e);
+        const window = this.window ?? global;
         const clearEvents = attr => {
             for (let event of ['mousemove', 'mouseup']) {
                 if (Object.prototype.hasOwnProperty.call(attr, event)) {