optimize GridRowItem comment.

2024-02-20 15:39:21 +08:00 · 2024-02-20 15:39:21 +08:00 · 0e0b46830e
commit 0e0b46830e
parent 45205cd63d
4 changed files with 508 additions and 416 deletions
--- a/lib/ui/grid/column.js
+++ b/lib/ui/grid/column.js
@ -7,12 +7,12 @@ import { Dropdown } from "../dropdown";
 import { convertCssStyle } from "../extension";
 import { createDateInput, formatDate, setDateValue, getDateValue } from "../date";
 // definition
-import { DropdownOptions, GridItemBooleanCallback, GridDropdownSourceCallback, DateFormatterCallback, GridSourceItem, GridItemWrapper, Grid } from "./grid";
+import { GridRowItem, DropdownOptions, GridItemBooleanCallback, GridDropdownSourceCallback, DateFormatterCallback, GridSourceItem, GridItemWrapper, Grid } from "./grid";

 /**
 * @ignore
 * @callback DropExpandedCallback
- * @param {Map<string, ValueItem>} item - 行数据对象
+ * @param {GridRowItem} item - 行数据对象
 * @param {Dropdown} drop - 下拉框对象
 * @this GridColumnDefinition
 */
--- a/lib/ui/grid/grid.js
+++ b/lib/ui/grid/grid.js
@ -66,14 +66,29 @@ let r = lang;
 * @property {boolean} [__checked] - 已选中
 */

+/**
+ * 键值对象
+ * @ignore
+ * @template T
+ * @typedef KeyMap
+ * @type {{[key: string]: T}}
+ */
+
+/**
+ * 行数据对象
+ * @typedef GridRowItem
+ * @type {KeyMap<ValueItem>}
+ * @property {(ValueItem | any)} {key} - 数据属性
+ */
+
 /**
 * 行数据包装接口
 * @typedef GridItemWrapper
- * @property {Map<string, ValueItem>} values - 真实数据对象
- * @property {Map<string, GridSourceItem[]>} source - 下拉数据源缓存对象
+ * @property {GridRowItem} values - 真实数据对象
+ * @property {KeyMap<GridSourceItem[]>} source - 下拉数据源缓存对象
 * @property {number} __index - 行索引
 * @property {number} __offset - 批量删除时暂存的索引偏移量
- * @property {Map<string, boolean>} __editing - 列正在编辑
+ * @property {KeyMap<boolean>} __editing - 列正在编辑
 * @property {boolean} __changed - 行数据是否发生改变
 * @property {boolean} __expanded - 行是否已展开
 * @property {GridExpandableObject} __expandable_object - 行扩展对象
@ -89,7 +104,7 @@ let r = lang;
 /**
 * 行数据可用性回调函数
 * @callback GridItemBooleanCallback
- * @param {Map<string, ValueItem>} item - 行数据对象
+ * @param {GridRowItem} item - 行数据对象
 * @returns {boolean} 返回是否可用
 * @this GridColumnDefinition
 */
@ -97,17 +112,17 @@ let r = lang;
 /**
 * 行数据过滤回调函数
 * @callback GridItemFilterCallback
- * @param {Map<string, ValueItem>} item - 行数据对象
+ * @param {GridRowItem} item - 行数据对象
 * @param {boolean} editing - 是否处于编辑状态
 * @param {HTMLElement} [body] - Grid 控件的 `<tbody>` 部分
- * @returns {any} - 返回过滤后的显示或编辑值
+ * @returns {ValueItem} - 返回过滤后的显示或编辑值
 * @this GridColumnDefinition
 */

 /**
 * 行数据处理回调函数
 * @callback GridItemObjectCallback
- * @param {Map<string, ValueItem>} item - 行数据对象
+ * @param {GridRowItem} item - 行数据对象
 * @returns {any} 返回任意对象
 * @this GridColumnDefinition
 */
@ -115,7 +130,7 @@ let r = lang;
 /**
 * 行数据字符串回调函数
 * @callback GridItemStringCallback
- * @param {Map<string, ValueItem>} item - 行数据对象
+ * @param {GridRowItem} item - 行数据对象
 * @returns {string} 返回字符串
 * @this GridColumnDefinition
 */
@ -131,15 +146,15 @@ let r = lang;
 /**
 * 行数据排序回调函数
 * @callback GridItemSortCallback
- * @param {Map<string, ValueItem>} a - 对比行数据1
- * @param {Map<string, ValueItem>} b - 对比行数据2
+ * @param {GridRowItem} a - 对比行数据1
+ * @param {GridRowItem} b - 对比行数据2
 * @returns {number} 返回大小对比结果
 */

 /**
 * 下拉列表数据源回调函数
 * @callback GridDropdownSourceCallback
- * @param {Map<string, ValueItem>} item - 行数据对象
+ * @param {GridRowItem} item - 行数据对象
 * @returns {GridSourceItem[]} 行下拉列表数据源
 */

@ -196,14 +211,14 @@ let r = lang;
 * * `string` 则以该值为关键字从行数据中取值作为判断条件
 * * `GridItemBooleanCallback` 则调用如下回调，以返回值作为判断条件
 * @property {GridColumnDefinition} enabled.{this} - 上下文为列定义对象
- * @property {Map<string, ValueItem>} enabled.item - 行数据对象
+ * @property {GridRowItem} enabled.item - 行数据对象
 * @property {boolean} enabled.{returns} - 返回是否启用
 * @property {GridItemFilterCallback} [filter] - 单元格取值采用该函数返回的值
 * @property {GridColumnDefinition} filter.{this} - 上下文为列定义对象
- * @property {Map<string, ValueItem>} filter.item - 行数据对象
+ * @property {GridRowItem} filter.item - 行数据对象
 * @property {boolean} filter.editing - 是否处于编辑状态
 * @property {HTMLElement} [filter.body] - Grid 控件的 `<tbody>` 部分
- * @property {any} filter.{returns} - 返回过滤后的显示或编辑值
+ * @property {ValueItem} filter.{returns} - 返回过滤后的显示或编辑值
 * @property {string} [text] - 单元格以该值填充内容，忽略filter与关键字属性
 * @property {boolean} [visible=true] - 列是否可见
 * @property {boolean} [resizable=true] - 列是否允许调整宽度
@ -216,21 +231,21 @@ let r = lang;
 * @property {any} [totalCss] - 合计行样式（仅在重建合计行元素时读取）
 * @property {(any | GridItemObjectCallback)} [style] - 单元格样式（填充行列数据时读取），支持直接返回样式对象或调用函数返回（若赋值则忽略 [styleFilter]{@linkcode GridColumnDefinition#styleFilter}）
 * @property {GridColumnDefinition} style.{this} - 上下文为列定义对象
- * @property {Map<string, ValueItem>} style.item - 行数据对象
+ * @property {GridRowItem} style.item - 行数据对象
 * @property {any} style.{returns} - 返回样式对象
 * @property {(@deprecated)} [styleFilter] - **已过时**<br/>_根据返回值填充单元格样式（填充行列数据时读取）_
 * @property {(string | GridItemStringCallback)} [background] - 设置单元格背景色（填充行列数据时读取），支持直接设置颜色字符串或调用函数返回（若赋值则忽略 [bgFilter]{@linkcode GridColumnDefinition#bgFilter}）
 * @property {GridColumnDefinition} background.{this} - 上下文为列定义对象
- * @property {Map<string, ValueItem>} background.item - 行数据对象
+ * @property {GridRowItem} background.item - 行数据对象
 * @property {string} background.{returns} - 返回单元格背景色字符串
 * @property {(@deprecated)} [bgFilter] - **已过时**<br/>_根据返回值设置单元格背景色_
- * @property {Map<string, Function>} [events] - 给单元格元素附加事件（事件函数上下文为数据行对象）
+ * @property {KeyMap<Function>} [events] - 给单元格元素附加事件（事件函数上下文为数据行对象）
 * @property {Function} events.{event} - 事件回调函数
- * @property {Map<string, ValueItem>} events.{event}.{this} - 上下文为行数据对象
+ * @property {GridRowItem} events.{event}.{this} - 上下文为行数据对象
 * @property {Event} events.{event}.e - 事件参数
 * @property {(any | GridItemObjectCallback)} [attrs] - 根据返回值设置单元格元素的附加属性，允许直接设置对象也支持调用如下函数返回对象
 * @property {GridColumnDefinition} attrs.{this} - 上下文为列定义对象
- * @property {Map<string, ValueItem>} attrs.item - 行数据对象
+ * @property {GridRowItem} attrs.item - 行数据对象
 * @property {any} attrs.{returns} - 返回附加属性对象
 * @property {boolean} [allowFilter=false] - 是否允许进行列头过滤
 * @property {any[]} [filterValues] - 过滤值的数组
@ -240,12 +255,12 @@ let r = lang;
 * @property {GridColumnDefinition} filterSource.col - 列定义对象
 * @property {ValueItem[]} filterSource.{returns} - 返回过滤器的数据数组
 * @property {GridItemSortCallback} [sortFilter] - 自定义列排序函数
- * @property {Map<string, ValueItem>} sortFilter.a - 对比行数据1
- * @property {Map<string, ValueItem>} sortFilter.b - 对比行数据2
+ * @property {GridRowItem} sortFilter.a - 对比行数据1
+ * @property {GridRowItem} sortFilter.b - 对比行数据2
 * @property {number} sortFilter.{returns} - 返回大小对比结果
 * @property {DropdownOptions} [dropOptions] - 列为下拉列表类型时以该值设置下拉框的参数
 * @property {(GridSourceItem[] | Promise<GridSourceItem[]> | GridDropdownSourceCallback)} [source] - 列为下拉列表类型时以该值设置下拉列表数据源，支持返回异步对象，也支持如下函数返回
- * @property {Map<string, ValueItem>} source.item - 行数据对象
+ * @property {GridRowItem} source.item - 行数据对象
 * @property {GridSourceItem[]} source.{returns} - 返回行下拉列表数据源
 * @property {boolean} [sourceCache=false] - 下拉列表数据源是否缓存结果（即行数据未发生变化时仅从source属性获取一次值）
 * @property {("fa-light" | "fa-regular" | "fa-solid")} [iconType=fa-light] - 列为图标类型时以该值设置图标样式
@ -256,7 +271,7 @@ let r = lang;
 * @property {any} dateValueFormatter.{returns} - 返回格式化后的结果
 * @property {(string | GridItemStringCallback)} [tooltip] - 额外设置单元格的 tooltip，支持直接使用字符串或者调用如下函数
 * @property {GridColumnDefinition} tooltip.{this} - 上下文为列定义对象
- * @property {Map<string, ValueItem>} tooltip.item - 行数据对象
+ * @property {GridRowItem} tooltip.item - 行数据对象
 * @property {string} tooltip.{returns} - 返回额外 tooltip 字符串
 * @example
 *  [
@ -484,7 +499,7 @@ class GridColumnDefinition {
    bgFilter;
    /**
     * 给单元格元素附加事件（事件函数上下文为数据行对象）
-     * @type {Map<string, Function>}
+     * @type {KeyMap<Function>}
     * @ignore
     */
    events;
@ -588,7 +603,7 @@ class GridColumnDefinition {
    /**
     * 单元格发生变化时触发
     * @event
-     * @param {Map<string, ValueItem>} item - 行数据对象
+     * @param {GridRowItem} item - 行数据对象
     * @param {(boolean | string | number)} value - 修改后的值
     * @param {(boolean | string | number)} oldValue - 修改前的值
     * @param {any} [e] - 列修改事件传递过来的任意对象
@ -621,7 +636,7 @@ class GridColumnDefinition {
    /**
     * 列为下拉框类型时在下拉列表展开时触发的事件
     * @event
-     * @param {Map<string, ValueItem>} item - 行数据对象
+     * @param {GridRowItem} item - 行数据对象
     * @param {Dropdown} drop - 下拉框对象
     * @this GridColumnDefinition
     */
@ -688,7 +703,7 @@ const GridColumnDirection = {
 /**
 * 扩展行生成回调函数
 * @callback GridExpandableObjectCallback
- * @param {Map<string, ValueItem>} item - 行数据对象
+ * @param {GridRowItem} item - 行数据对象
 * @returns {GridExpandableObject} 返回扩展行对象
 * @this Grid
 */
@ -717,7 +732,7 @@ const GridColumnDirection = {
 * <img src="./assets/grid.jpg" alt="Grid"/>
 * @class
 * @property {GridColumnDefinition[]} columns - 列定义的数组
- * @property {Map<string, ValueItem>} [total] - 合计行数据
+ * @property {GridRowItem} [total] - 合计行数据
 * @property {any} [langs] - 多语言资源对象
 * @property {string} [langs.all=( All )]
 * @property {string} [langs.ok=OK]
@ -752,7 +767,7 @@ const GridColumnDirection = {
 * @property {boolean} [expandable=false] - 是否支持点击扩展
 * @property {GridExpandableObjectCallback} [expandableGenerator] - 扩展行生成器
 * @property {Grid} expandableGenerator.{this} - 上下文为 Grid
- * @property {Map<string, ValueItem>} expandableGenerator.item - 行数据对象
+ * @property {GridRowItem} expandableGenerator.item - 行数据对象
 * @property {GridExpandableObject} expandableGenerator.{returns} - 返回扩展行对象
 * @example <caption>基础示例</caption>
 *  <div id="grid"></div>
@ -888,13 +903,13 @@ export class Grid {
        rowCount: -1,
        /**
         * 列类型缓存字典
-         * @type {Map<string, GridColumn>}
+         * @type {KeyMap<GridColumn>}
         * @private
         */
        colTypes: {},
        /**
         * 列属性字典
-         * @type {Map<string, GridColumnAttr>}
+         * @type {KeyMap<GridColumnAttr>}
         * @private
         */
        colAttrs: {
@ -1029,7 +1044,7 @@ export class Grid {
    columns = [];
    /**
     * 合计行数据
-     * @type {Map<string, ValueItem>}
+     * @type {GridRowItem}
     * @ignore
     */
    total = null;
@ -1311,7 +1326,7 @@ export class Grid {
    /**
     * 扩展行展开时触发的事件
     * @event
-     * @param {Map<string, ValueItem>} item - 行数据对象
+     * @param {GridRowItem} item - 行数据对象
     * @param {GridExpandableObject} expandableObject - 由 [expandableGenerator]{@linkcode Grid#expandableGenerator} 产生的行扩展对象
     * @param {HTMLElement} expandableObject.element - 扩展行元素
     * @this Grid
@ -1320,7 +1335,7 @@ export class Grid {
    /**
     * 扩展行收缩时触发的事件
     * @event
-     * @param {Map<string, ValueItem>} item - 行数据对象
+     * @param {GridRowItem} item - 行数据对象
     * @param {GridExpandableObject} expandableObject - 由 [expandableGenerator]{@linkcode Grid#expandableGenerator} 产生的行扩展对象
     * @param {HTMLElement} expandableObject.element - 扩展行元素
     * @this Grid
@ -1396,7 +1411,7 @@ export class Grid {
    /**
     * 返回所有数据的数据（未过滤）
     * @readonly
-     * @type {Array<Map<string, ValueItem>>}
+     * @type {GridRowItem[]}
     */
    get allSource() { return this._var.source?.map(s => s.values) }

@ -1412,7 +1427,7 @@ export class Grid {

    /**
     * 获取已过滤的数据数组，或者设置数据并刷新列表
-     * @type {Array<Map<string, ValueItem>>}
+     * @type {GridRowItem[]}
     */
    get source() { return this._var.currentSource?.map(s => s.values) }
    set source(list) {
@ -1442,7 +1457,7 @@ export class Grid {
    /**
     * 设置单行数据
     * @param {number} index - 行索引
-     * @param {Map<string, ValueItem>} item - 待设置的行数据对象
+     * @param {GridRowItem} item - 待设置的行数据对象
     */
    setItem(index, item) {
        if (this._var.currentSource == null) {
@ -1463,9 +1478,9 @@ export class Grid {

    /**
     * 添加行数据
-     * @param {Map<string, ValueItem>} item - 待添加的行数据值
+     * @param {GridRowItem} item - 待添加的行数据值
     * @param {number} [index] - 待添加的行索引
-     * @returns {Map<string, ValueItem>} 返回已添加的行数据
+     * @returns {GridRowItem} 返回已添加的行数据
     */
    addItem(item, index) {
        if (this._var.currentSource == null) {
@ -1501,9 +1516,9 @@ export class Grid {

    /**
     * 批量添加行数据
-     * @param {Array<Map<string, ValueItem>>} array - 待添加的行数据数组
+     * @param {GridRowItem[]} array - 待添加的行数据数组
     * @param {number} [index] - 待添加的行索引
-     * @returns {Array<Map<string, ValueItem>>} 返回已添加的行数据数组
+     * @returns {GridRowItem[]} 返回已添加的行数据数组
     */
    addItems(array, index) {
        if (this._var.currentSource == null) {
@ -1545,7 +1560,7 @@ export class Grid {
    /**
     * 删除行数据
     * @param {number} index - 待删除的行索引
-     * @returns {Map<string, ValueItem>} 返回已删除的行数据
+     * @returns {GridRowItem} 返回已删除的行数据
     */
    removeItem(index) {
        if (this._var.currentSource == null) {
@ -1573,7 +1588,7 @@ export class Grid {
    /**
     * 批量删除行数据
     * @param {number[]} [indexes] - 待删除的行索引数组，未传值时删除所有行
-     * @returns {Array<Map<string, ValueItem>>} 返回已删除的行数据数组
+     * @returns {GridRowItem[]} 返回已删除的行数据数组
     */
    removeItems(indexes) {
        if (this._var.currentSource == null) {
@ -1913,7 +1928,7 @@ export class Grid {

    /**
     * 设置数据列表，该方法为 [source]{@linkcode Grid#source} 属性的语法糖
-     * @param {Array<Map<string, ValueItem>>} source - 待设置的数据列表
+     * @param {GridRowItem[]} source - 待设置的数据列表
     */
    setData(source) {
        this.source = source;
@ -3277,7 +3292,7 @@ export class Grid {

    /**
     * @private
-     * @param {any} item 
+     * @param {GridRowItem} item 
     * @param {boolean} editing 
     * @param {GridColumnDefinition} col 
     * @returns {any}
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@ -1,7 +1,7 @@
 {
  "name": "ui-lib",
  "private": true,
-  "version": "0.0.1",
+  "version": "1.0.1",
  "type": "module",
  "files": [
    "dist"
@ -32,10 +32,10 @@
    "clean-jsdoc-theme": "^4.2.17",
    "docdash": "^2.0.2",
    "jsdoc": "^4.0.2",
-    "postcss-preset-env": "^9.3.0",
-    "sass": "^1.70.0",
-    "typedoc": "^0.25.7",
-    "vite": "^5.0.12",
+    "postcss-preset-env": "^9.4.0",
+    "sass": "^1.71.0",
+    "typedoc": "^0.25.8",
+    "vite": "^5.1.3",
    "vite-plugin-externals": "^0.6.2"
  }
 }