From 3d2c0e7a972466467722c0a8f522eabf65ab2e71 Mon Sep 17 00:00:00 2001 From: Tsanie Date: Tue, 20 Feb 2024 10:11:59 +0800 Subject: [PATCH] add more comments --- lib/ui/grid/grid.js | 245 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 192 insertions(+), 53 deletions(-) diff --git a/lib/ui/grid/grid.js b/lib/ui/grid/grid.js index c54ae6b..7edb7e2 100644 --- a/lib/ui/grid/grid.js +++ b/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} values - 真实数据对象 * @property {Map} source - 下拉数据源缓存对象 + * @property {number} __index - 行索引 + * @property {number} __offset - 批量删除时暂存的索引偏移量 + * @property {Map} __editing - 列正在编辑 + * @property {boolean} __changed - 行数据是否发生改变 + * @property {boolean} __expanded - 行是否已展开 + * @property {GridExpandableObject} __expandable_object - 行扩展对象 */ /** @@ -226,6 +233,7 @@ let r = lang; * @property {Map} 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 = { * 函数调用流程图
* Grid * @class + * @property {GridColumnDefinition[]} columns - 列定义的数组 + * @property {Map} [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} expandableGenerator.item - 行数据对象 + * @property {GridExpandableObject} expandableGenerator.{returns} - 返回扩展行对象 * @example 基础示例 *
* @example @@ -820,25 +887,14 @@ export class Grid { rowCount: -1, /** * 列类型缓存字典 + * @type {Map} * @private - * @property {GridColumn} {key} - 关键字对应列的类型缓存对象 */ colTypes: {}, /** * 列属性字典 + * @type {Map} * @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} + * @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} item - 行数据对象 - * @property {GridExpandableObject} {returns} - 返回扩展行对象 - * @property {number} {returns}.index - 行索引 - * @property {HTMLElement} {returns}.element - 扩展行元素 + * @private */ expandableGenerator; @@ -1268,8 +1405,6 @@ export class Grid { /** * 获取已过滤的数据数组，或者设置数据并刷新列表 * @type {Array>} - * @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)) {