TurboGrid API - 简体中文

方法数据配置项事件生命周期

turbogrid


                            // 全局方式
                            const TG = window.turbogrid;
                            const { Grid, Util } = window.turbogrid;
                            // CJS
                            const TG = require("turbogrid");
                            const { Grid, Util } = require("turbogrid");
                            // ESM
                            import TG from "turbogrid";
                            import { Grid, Util } from "turbogrid";

Grid(container)

为指定容器创建一个新的 Grid 实例。

container 参数可以是 CSS 选择器、DOM 元素，或包含 container 属性的配置对象。


                            // 选择器
                            const grid = new Grid(".container");
                            // 或 DOM 元素
                            const container = document.querySelector(".container");
                            const grid = new Grid(container);
                            // 或包含 container 的配置对象
                            const grid = Grid({
                                container,
                                ... 其他选项
                            });

方法

setData(data)

设置表格数据。详细结构请参见数据结构。

data 对象会读取 columns、rows、rowsLength 和 options。rowsLength 适用于已知总行数但数据尚未全部加载完成的场景。


                            grid.setData({
                                columns: [],
                                rows: []
                            });

getData()

返回当前表格数据对象。


                            const data = grid.getData();

setDataSnapshot(data)

从普通快照数据加载内容，会移除私有 tg_* 字段，并重新构建 rows 和 columns 的规范化树结构状态。


                            grid.setDataSnapshot(data);

getItemSnapshot(item[, keysSettings])

返回行或列条目的净化快照数据。

未传 keysSettings 时会移除私有字段；传入 keysSettings 时，值为 true 的键会被显式保留，值为 false 的键会被排除。


                            const rowSnapshot = grid.getItemSnapshot(rowItem);
                            const rowSnapshot2 = grid.getItemSnapshot(rowItem, {
                                id: true,
                                name: true
                            });

setOption(options)

设置一个或多个表格选项。可用配置请参见配置项。

同时支持 setOption(optionKey, optionValue) 和 setOption(optionsObject) 两种调用形式。


                            // 设置多个选项
                            grid.setOption({
                                optionKey1: optionValue1,
                                optionKey2: optionValue2
                            });
                            // 设置单个选项
                            grid.setOption(optionKey, optionValue);

getOption([name])

传入 name 时返回对应选项值；未传入时返回完整配置对象。

查询未知配置键时返回 undefined。


                            // 获取全部选项
                            const options = grid.getOption();
                            // 获取单个选项
                            const optionValue = grid.getOption(optionKey);

setFormatter(formatters)

注册或覆盖 Grid 格式化器。

同时支持 setFormatter(type, handler) 和 setFormatter(formatterMap)。已注册的处理函数执行时，this 指向当前 grid 实例。


                            // 设置多个格式化器
                            grid.setFormatter({
                                string: function(value, rowItem, columnItem, cellNode) {
                                    return value;
                                }
                            });

                            // 设置单个格式化器
                            grid.setFormatter("string", formatterHandler);

内置单元格格式化器：string、number、date、icon、blank、checkbox、tree、null

内置表头格式化器：header

格式化器签名：


                            function(value, rowItem, columnItem, cellNode) { 
                                // value 经过 null 格式化器处理后传入
                                // 获取原始值：
                                const originalValue = rowItem[columnItem.id];
                                const rowIndex = rowItem.tg_index;
                                const columnIndex = columnItem.tg_index;
                                // 使用默认格式化器返回结果：
                                const defaultFormatter = this.getDefaultFormatter("[formatter-name]");
                                return defaultFormatter(value + " new text", rowItem, columnItem, cellNode)
                            }

示例格式化器

getFormatter(type)

返回指定类型已注册的格式化函数，并绑定到当前 grid 实例。


                            const stringFormatter = grid.getFormatter("string");

getDefaultFormatter([type])

返回指定类型的内置格式化函数。

当指定类型不存在时，会回退到内置的 string 格式化器。


                            const treeFormatter = grid.getDefaultFormatter("tree");

bind(eventType, handler[, options])

为表格绑定事件处理函数。支持的事件类型请参见事件。

eventType 可以是单个事件名、由空格分隔的多个事件名，或事件名到处理函数的对象映射。也支持 `onUpdated.demo` 这类带命名空间的事件名。

可通过 options 传入诸如 { once: true } 之类的监听配置。


                            grid.bind("onUpdated", function(e, d){
                                //console.log(d);
                            });

示例事件

once(eventType, handler)

绑定一个只执行一次的处理函数，首次触发后会自动移除。

支持与 bind 相同的 eventType 传参形式。


                            grid.once("onUpdated", function(e, eventData){
                                //console.log(eventData);
                            });

unbind([eventType][, handler][, options])

移除之前绑定到表格上的事件处理函数。

不传参数时会移除全部处理函数；传入事件名或命名空间时移除匹配项；同时传入 eventType 和 handler 时移除指定绑定。


                            grid.unbind();
                            grid.unbind("onUpdated");
                            grid.unbind("onUpdated", handler);

trigger(eventType, eventData)

触发一个事件，并使用传入的事件数据调用所有已绑定处理函数。

处理函数的第一个参数是事件对象，第二个参数是 eventData。


                            this.trigger(eventType, eventData);

getAllEvents()

返回全部支持的事件类型。


                            const allEventTypes = grid.getAllEvents();

示例事件

render()

基于当前数据、配置和格式化器调度一次渲染。

同一个事件循环中的重复调用会被合并，因此适合在批量更新后调用。


                            grid.render();

rerender()

强制完整重建表格结构并重新渲染。


                            grid.rerender();

resize([w, [h]])

重新计算布局，并可选择应用新的尺寸。

支持 resize()、resize(width, height) 和 resize(styleMap) 三种形式，其中 styleMap 会直接应用到 grid holder。


                            grid.resize();
                            grid.resize(600, 400);

示例尺寸调整

destroy()

销毁 Grid 实例，并移除生成的 DOM、观察器和事件绑定。


                            grid.destroy();

getColumnItem(columnIndex) getColumnItemById(id) getColumnItemBy(key, value) getRowItem(rowIndex) getRowItemById(id) getRowItemBy(key, value)

rowIndex 和 columnIndex 参数支持以下几种传入形式：

如果参数是 Number，Grid 会按索引查找对应的行或列。这是推荐且性能最高的方式。也支持负索引，例如 -1 表示最后一项。
如果参数是 String，Grid 会遍历所有项，查找匹配的行或列 id。
如果参数是 Object，Grid 会检查以下属性：

如果对象包含 tg_index 属性，Grid 会优先按索引查找行或列。
如果对象包含 String 类型的 id 属性，Grid 会遍历所有项，查找匹配的 id。


                            const columnItem = grid.getColumnItem(columnIndex);
                            const columnItemById = grid.getColumnItemById("id_123");
                            const rowItem = grid.getRowItem(rowIndex);
                            const rowItemById = grid.getRowItemById("id_123");
                            const rowItem = grid.getRowItem(123);
                            const rowItem = grid.getRowItem("id_123");
                            const rowItem = grid.getRowItemBy("id", "id_123");
                            const rowItem = grid.getRowItemBy("key", "value");

showLoading() hideLoading() setLoading(loading)

显示、隐藏或自定义内置加载遮罩。

loading 可以是普通内容、DOM 节点、接收 loading 容器的工厂函数，或默认 loading 的配置对象，例如 { size, color, fast }。


                            grid.showLoading();
                            grid.hideLoading();
                            grid.setLoading("加载中...");
                            grid.setLoading(function(container) {
                                return document.createElement("div");
                            });

示例显示/隐藏加载态

showMask([styleMap]) hideMask()

显示或隐藏用于阻止交互的遮罩层。

可传入 styleMap 覆盖遮罩层样式，例如 opacity 或 backgroundColor。


                            grid.showMask();
                            grid.showMask({
                                opacity: 0.3
                            });

                            grid.hideMask();

示例显示/隐藏加载态

expandAllRows() collapseAllRows() toggleAllRows()

展开、折叠或切换所有树形行。


                            grid.expandAllRows();
                            grid.collapseAllRows();
                            grid.toggleAllRows();

示例行折叠/展开

expandRow(rowIndex) collapseRow(rowIndex) toggleRow(rowIndex)

展开、折叠或切换指定行。

如果目标行是一个尚未加载 subs 的分组行，expandRow 可能会触发 onRowSubsRequest，用于按需加载子行。


                            grid.expandRow(rowIndex);
                            grid.collapseRow(rowIndex);
                            grid.toggleRow(rowIndex);

示例行折叠/展开

expandRowLevel(level)

展开到指定树层级的行。


                            grid.expandRowLevel(level);

示例行折叠/展开

exportData([keysSettings])

返回适合导出的 columns 和 rows 数据，会移除私有字段，并可通过 keysSettings 过滤字段。

在 keysSettings 中，值为 true 表示强制保留该字段，值为 false 表示排除该字段。


                            const exportedData = grid.exportData();
                            const exportedData = grid.exportData({
                                the_key_need: true,
                                key_key_no_need: false
                            });

示例导出

setRowSubs(rowIndex, subs)

替换指定父行的子行数据。

传入 subs 数组后会立即更新该行的树结构，并将父行标记为已展开。


                            const subs = [{name:"row1"},{name:"row2"}];
                            grid.setRowSubs(rowIndex, subs);

示例动态加载子项

setColumns(columnList)

替换当前顶层列数据，并触发一次完整 rerender。


                            const columns = [{id:"name", name:"名称"}];
                            grid.setColumns(columns);

setRows(rowList)

使用新的行列表替换当前顶层 rows。

当只有行树发生变化时使用 setRows；如果列或 options 也需要一起替换，应使用 setData。


                            const rows = [{name:"row1"},{name:"row2"}];
                            grid.setRows(rows);

示例动态设置行

getRows() getColumns() getViewRows() getViewColumns([all]) getViewRowItem(viewRowIndex) getViewColumnItem(viewColumnIndex)

getRows 和 getColumns 返回源数据中的顶层列表。

view index 指经过筛选、折叠、排序以及列显隐处理后的当前可见顺序索引。

getViewColumns(true) 还会把当前可见的分组列一并包含在返回结果中。


                            const rows = grid.getRows();
                            const columns = grid.getColumns();
                            const viewRows = grid.getViewRows();
                            const viewColumns = grid.getViewColumns();
                            const viewRowItem = grid.getViewRowItem(0);
                            const viewColumnItem = grid.getViewColumnItem(0);

addRow(rowInfo[, parent, position, scrollTo = true]) deleteRow(rowIndex)

新增一行，或删除一行/多行。

parent 可以是行对象、行索引或行 id；position 用于指定插入到父节点子列表中的位置；scrollTo 默认为 true，会自动滚动到新增行。


                            grid.addRow({
                                id: "id1",
                                name: "行项目"
                            });
                            grid.addRow(["行 1", "行 2"]);
                            grid.addRow(["行 1", "行 2"], parentIndex);
                            grid.addRow("插入到前面的一行","level_0", 0);
                            grid.deleteRow(2);
                            grid.deleteRow([1, 2]);

示例行新增/删除

moveRowsToTop(rowList) moveRowsUp(rowList) moveRowsDown(rowList) moveRowsToBottom(rowList) moveSelectedRowsToTop() moveSelectedRowsUp() moveSelectedRowsDown() moveSelectedRowsToBottom() moveRows(rowList, offset)

offset：小于 0 时向上移动，大于 0 时向下移动。

rowList 可以是单行或行列表。offset 为 0，或 rowList 已包含全部可见行时，本次移动会被忽略。


                            grid.moveRowsToTop(["row_id1", "row_id2"]);
                            grid.moveRowsUp(["row_id1", "row_id2"]);
                            grid.moveRowsDown(["row_id1", "row_id2"]);
                            grid.moveRowsToBottom(["row_id1", "row_id2"]);
    
                            grid.moveSelectedRowsToTop();
                            grid.moveSelectedRowsUp();
                            grid.moveSelectedRowsDown();
                            grid.moveSelectedRowsToBottom();

                            grid.moveRows(["row_id"], -1);
                            grid.moveRows(["row_id"], -2);
                            grid.moveRows("row_id", 1);

示例行移动

selectAll([selected = true])

选中全部可选行，或清空全部选中状态。

在单选模式下，selectAll(true) 不会生效。


                            grid.selectAll();
                            grid.selectAll(false);

示例行选择

setRowSelected(rowInfo[, settings])

更新一行或多行的选中状态。

在多选模式下，只传 false 可清空全部选中；第二个参数传 false 可取消指定行的选中；传入带 Shift 的事件对象时，会以上一次选中行为起点执行范围选择。


                            grid.setRowSelected(rowIndex);
                            grid.setRowSelected(rowIndex, false);
                            grid.setRowSelected(false);

示例行选择

getSelectedRow() getSelectedRows()

getSelectedRow 返回第一条已选中的行，未选中时返回 null。

getSelectedRows 始终返回数组，并按选中顺序排序。


                            const selectedRow = grid.getSelectedRow();
                            const selectedRows = grid.getSelectedRows();

示例行选择

setRowHover(rowIndex, hover)

设置指定行是否处于悬停状态。


                            grid.setRowHover(rowIndex, true);
                            grid.setRowHover(rowIndex, false);

示例中间冻结

setRowState(rowIndex, state, value = true)

设置自定义行状态，并在已渲染的行节点上切换 CSS 类 tg-[state]。


                            grid.setRowState(rowIndex, "selected", true);
                            grid.setRowState(rowIndex, "warning", true);
                            grid.setRowState(rowIndex, "warning", false);

setSortColumn(sortColumn) removeSortColumn()

setSortColumn 支持与 getColumnItem 相同的传参形式。

对同一列重复调用 setSortColumn 会切换 sortAsc；removeSortColumn 用于清除当前排序状态。


                            grid.setSortColumn(sortColumn);
                            grid.removeSortColumn();

示例行排序

setColumnWidth(columnIndex, width)

在运行时更新列宽。

width 会被取整并限制为不小于 0，同时同步更新该列的 width、minWidth 和 maxWidth。


                            grid.setColumnWidth(columnIndex, width);

示例列宽调整

showColumn(columnIndex) hideColumn(columnIndex)

显示或隐藏一个或多个列。

支持与 getColumnItem 相同的传参形式，也支持传入列表。


                            grid.showColumn(columnIndex);
                            grid.hideColumn(columnIndex);
                            grid.showColumn([1, 3]);
                            grid.hideColumn([1, 3]);

示例显示/隐藏列

addColumn(columnInfo[, parent, position, scrollTo = true]) deleteColumn(columnIndex)

新增列，或删除一列/多列。

parent 可以是列对象、列索引或列 id；position 用于指定插入到父节点子列表中的位置；scrollTo 默认为 true，会自动滚动到新增列。


                            grid.addColumn({
                                id: "id1",
                                name: "列项目"
                            });
                            grid.addColumn(["列 1", "列 2"]);
                            grid.addColumn(["列 1", "列 2"], parentIndex);
                            grid.addColumn("插入到前面的列","level_0",0);
                            grid.deleteColumn(2);
                            grid.deleteColumn([1, 2]);

示例列新增/删除

scrollToRow(rowIndex) scrollToFirstRow() scrollToLastRow() scrollToColumn(columnIndex) scrollToFirstColumn() scrollToLastColumn(end) scrollToCell(rowIndex, columnIndex)

直接滚动到指定的行、列或单元格。

scrollToLastColumn(end) 默认会跳过末尾用于占位的 blank 列；当 end 为 true 时会滚动到真正的最末尾。


                            grid.scrollToRow(rowIndex);
                            grid.scrollToColumn(columnIndex);
                            grid.scrollToCell(rowIndex, columnIndex);

示例滚动

scrollRowIntoView(rowIndex) scrollColumnIntoView(columnIndex) scrollCellIntoView(rowIndex, columnIndex)

滚动最小必要距离，使目标行、列或单元格进入可视区域。


                            grid.scrollRowIntoView(rowIndex);
                            grid.scrollColumnIntoView(columnIndex);
                            grid.scrollCellIntoView(rowIndex, columnIndex);

示例滚动

setScrollTop(top) setScrollLeft(left) getScrollTop() getScrollLeft()

设置或获取当前滚动位置。


                            grid.setScrollTop(200);
                            grid.setScrollLeft(200);
                            const st = grid.getScrollTop();
                            const sl = grid.getScrollLeft();

示例滚动

updateRow(rowIndex[, rowData]) updateCell(rowIndex, columnIndex[, cellValue]) update() flushBody() flushSort() flushRow(viewRowIndex) flushRowFrom(viewRowIndex) flushColumn(viewColumnIndex) flushColumnFrom(viewColumnIndex) flushCell(viewRowIndex, viewColumnIndex)

updateRow 支持将部分 rowData 合并到现有行数据中。

updateCell 会按常规的行列定位规则解析 rowIndex 和 columnIndex。省略 rowData 或 cellValue 时，会基于现有数据重新渲染对应内容。

flushBody 会清空所有行渲染缓存。flushSort 会清理排序后使用的行缓存。

flushRow、flushRowFrom、flushColumn、flushColumnFrom 和 flushCell 使用的都是 view 索引（tg_view_index），而不是源数据索引。


                            grid.update();
                            grid.flushBody();
                            grid.flushSort();
                            grid.flushRow(viewRowIndex);
                            grid.flushRowFrom(viewRowIndex);
                            grid.flushColumn(viewColumnIndex);
                            grid.flushColumnFrom(viewColumnIndex);
                            grid.flushCell(viewRowIndex, viewColumnIndex);
                            grid.updateRow(rowIndex);
                            grid.updateRow(rowIndex, rowData);
                            grid.updateCell(rowIndex, columnIndex);
                            grid.updateCell(rowIndex, columnIndex, cellValue);

示例刷新

getScrollbarWidth()

没有垂直滚动条时返回 0；当 hasVScroll 为 true 时，返回 scrollbarSize。

getScrollbarHeight()

没有水平滚动条时返回 0；当 hasHScroll 为 true 时，返回 scrollbarSize。


                            const sbw = grid.getScrollbarWidth();
                            const sbh = grid.getScrollbarHeight();

getScrollViewWidth() getScrollViewHeight()

滚动视口尺寸 = 滚动面板尺寸 - 滚动条尺寸。


                            const svw = grid.getScrollViewWidth();
                            const svh = grid.getScrollViewHeight();

getScrollPaneWidth() getScrollPaneHeight()

滚动面板尺寸 = 滚动视口尺寸 + 滚动条尺寸。


                            const spw = grid.getScrollPaneWidth();
                            const sph = grid.getScrollPaneHeight();

getColumnsLength(total)

默认返回当前可见列数量；传入 true 时包含隐藏列。


                            const len = grid.getColumnsLength();
                            const totalLen = grid.getColumnsLength(true);

getRowsLength(total)

默认返回当前可见行数量；传入 true 时包含被折叠或过滤掉的行。


                            const len = grid.getRowsLength();
                            const totalLen = grid.getRowsLength(true);

getRowsHeight()

返回所有行渲染后的总高度。


                            const totalHeight = grid.getRowsHeight();

getRowHeight(rowIndex)

返回指定行的计算高度。


                            const rowHeight = grid.getRowHeight(rowIndex);

getViewport()

返回当前可见行和列的索引范围。


                            const viewport = grid.getViewport();
                            // { rows, columns }

find(selector[, container])

使用 CSS 选择器查找表格根节点内部的元素。

传入 container 时，可将查询范围限制在 grid 内部的某个特定节点下。


                            const nodes = grid.find(".selector-name");

getRowNodes(rowIndex)

返回指定行当前已渲染的 DOM 节点集合。

返回值是 Query 集合，适合处理同一行同时出现在多个 pane 中的情况。


                            const rowNodes = grid.getRowNodes(rowIndex);

getCellNode(rowIndex, columnIndex) getCellValue(rowItem, columnItem)

返回已渲染的单元格节点，或解析单元格原始值。

getCellValue 返回的是 rowItem[columnItem.id]，即格式化前的原始值。


                            const cellNode = grid.getCellNode(rowIndex, columnIndex);
                            const cellValue = grid.getCellValue(rowItem, columnItem);

getHeaderItemNode(columnIndex)

返回指定列对应的表头项节点。

支持与 getColumnItem 相同的传参形式。


                            const headerItemNode = grid.getHeaderItemNode(columnIndex);

getColumnHeaderNode(columnIndex)

返回指定列对应的表头容器节点。

支持与 getColumnItem 相同的传参形式。


                            const columnHeaderNode = grid.getColumnHeaderNode(columnIndex);

forEachColumn(callback) forEachRow(callback)

遍历每一列或每一行，并调用传入的回调函数。

回调函数会收到 (item, index, parent) 三个参数，对应当前节点、索引和父节点。


                            grid.forEachColumn(function(column, index, parent) {
                                //
                            });
                            grid.forEachRow(function(row, index, parent) {
                                //
                            });

isRowSelectable(rowItem)

返回该行在当前规则下是否可被选中。


                            const rowItem = grid.getRowItem(rowIndex);
                            if (grid.isRowSelectable(rowItem)) {
                                console.log("可选中");
                            }

isRowLeaf(rowItem)

返回该行是否为叶子节点。

highlightKeywordsFilter(rowItem, columns, keywords)

用于 rowFilter 和 highlightKeywords 的关键字匹配与高亮辅助方法。

columns 应为列 id 列表，keywords 会先按空白字符拆分后再逐个匹配。


                            grid.setOption({
                                rowFilter: function(rowItem) {
                                    return this.highlightKeywordsFilter(rowItem, ["name", "type"], "foo bar");
                                }
                            });

onNextUpdated(handler)

为下一次 onUpdated 事件注册一个一次性处理函数。

等价于对 onUpdated 绑定一个只执行一次的监听器。


                            grid.onNextUpdated(function(e, eventData){
                                //console.log(eventData);
                            });

数据

columns 和 rows 使用相同的数据结构（JSON / 树形结构）：


                                    [{
                                        name: "项目 1",
                                        subs: [{
                                            name : "项目 2",
                                            subs: [{
                                                name : "项目 3",
                                                subs: [{
                                                    ...
                                                }]
                                            }, ...]
                                        }, ...]
                                    }, ...]


                            const data = {
                                columns : [...],
                                rows : [...]
                            };
                            grid.setData(data);

columns

可用列字段请参见 columnProps。


                            const columns = [{
                                id:"c1",
                                type : "string",
                                name:"列名 1"
                            }, {
                                id : "c2",
                                type : "number",
                                name : "列名 2"
                            }, {
                                id: "c3",
                                name: "列名 3",
                                subs: [{
                                    id: "c3_s1",
                                    name: "列名 3-1"
                                }, {
                                    id: "c3_s2",
                                    name: "列名 3-2"
                                }]
                            }];

rows

可用行字段请参见 rowProps。


                            const rows = [{
                                id : "r1",
                                name : "行名 1",
                                c1 : "字符串值 1",
                                c2 : 1,
                                c3_s1 : "值 3 - 1",
                                c3_s2 : "值 1 - 2"
                            }, {
                                id : "r2",
                                type : "group",
                                name : "行名 2",
                                c1 : "字符串值 2",
                                c2 : "值 2",
                                c3_s1 : "值 3 - 1",
                                c3_s2 : "值 1 - 2",
                                subs : [{
                                    id : "r3",
                                    type : "holding",
                                    name : "行名 3",
                                    c1 : "字符串值 3",
                                    c2 : 3,
                                    c3_s1 : "值 3 - 1",
                                    c3_s2 : "值 1 - 2"
                                }]
                            }];

options

应用 data 中携带的 options。这些值的优先级高于 setOption。


                            const data = {
                                options : {
                                    sortField : "name"
                                },
                                columns : columns,
                                rows : rows
                            };
                            grid.setData(data);

rowsLength

在不直接提供 rows、但已知总行数时支持按需懒加载。


                                const data = {
                                    columns: columns,
                                    rowsLength: 50000
                                };
                                grid.setData(data);

示例动态加载行

配置项

className = "tg-turbogrid"

自定义作为 Grid 命名空间的根 CSS 类名。


                        grid.setOption({
                            className: "my-grid-class-name"
                        });

theme = "[theme-name]"

设置主题名称。可选值：default、lightblue、dark。

示例主题

rowHeight = 32

设置默认行高，单位为像素。

示例行高

rowCacheLength = 0 columnCacheLength = 0

控制在可视区域外额外渲染多少行和列作为缓存。

示例行/列缓存

autoHeight = false

自动调整表格高度，使其适配当前可见内容。

示例自动高度

headerVisible = true

显示或隐藏表头区域。

示例显示/隐藏表头

collapseAllVisible = true collapseAllOnInit = null

控制是否显示全部折叠操作，以及是否在初始化时执行。

示例行折叠/展开

selectVisible = false selectAllVisible = true selectAllOnInit = null

控制是否显示选择相关 UI，以及是否在初始化时全选行。

对于 selectAllOnInit：true 表示全选，false 表示取消全选，null 表示保持当前状态不变。

selectMultiple = true

示例行选择

rowNumberVisible = false

显示或隐藏内置行号列。

示例行号

rowNotFound = ''

设置空状态内容。支持空字符串、字符串、DOM 元素或函数。

示例空结果提示

rowDragCrossLevel = true

控制拖拽行是否允许跨层级移动。支持布尔值，或返回允许落点列表的函数。

示例行拖拽

rowMoveCrossLevel = true

控制行移动相关 API 是否允许跨层级移动。

示例行移动

sortField = ""

指定排序比较时使用的字段。

sortAsc = true

true 为升序，false 为降序。

sortBlankValueBottom = true

控制空值在排序时的位置。

true 表示空值行始终排在表格底部。

false 表示降序时空值排到底部，升序时空值排到顶部。

sortOnInit = false

为 true 时，Grid 会在初始化时按 sortField 排序。

sortIndicator = "h"

设置排序指示器样式："h" 或 "v"。

sortComparers = {defaultSortComparers}

提供自定义排序比较函数。

示例行排序

rowFilter rowFilteredSort = null

在渲染前过滤行，并可选择对过滤结果进行排序。

示例行过滤

columnTypes = {...}

定义预设列类型，以及 id 到类型的映射关系。

rowProps =


                                {

                                    //selected: 布尔值
                                    //collapsed: 布尔值
                                
                                    //selectable : true
                                    //exportable: true
                                
                                    //sortFixed: [布尔值, 字符串 "top"]
                                
                                    // 自定义行样式
                                    //classMap : [字符串, 数组, 对象]
                                    //styleMap : [字符串, 数组, 对象]
                                    //[columnId]ClassMap: [字符串, 数组, 对象]
                                    //[columnId]StyleMap: [字符串, 数组, 对象]
                                
                                    // 用于类名的行类型，例如 group
                                    //type: 字符串
                                
                                    //formatter: [字符串, 函数]
                                
                                    //height: 数字
                                
                                    //subs: 数组
                                }

columnProps =


                                {

                                    // 显示表头时必填
                                    name: '',

                                    // 用于读取行数据的字段键
                                    //id: 字符串

                                    // 预期为字符串，例如："string"、"number"、"date" 等
                                    //type: 字符串

                                    // formatter 通常是函数，也可以是类似 type 的字符串
                                    // 优先级高于 type
                                    // 用于单元格格式化
                                    //formatter: [字符串, 函数]
                                    //headerFormatter: [字符串, 函数]

                                    // 排序时使用的比较函数 function(a, b, options)
                                    //comparer: [字符串, 函数]

                                    // left（默认）| center | right
                                    //align: 字符串

                                    // 自定义列样式
                                    //classMap: [字符串, 数组, 对象]
                                    //styleMap: [字符串, 数组, 对象]
                                    //headerClassMap: [字符串, 数组, 对象]
                                    //headerStyleMap: [字符串, 数组, 对象]

                                    //sortable: true
                                    //resizable: true
                                    //exportable: true

                                    //private: false

                                    // 列宽调整时常用
                                    minWidth: 81,
                                    maxWidth: 300

                                    //width: 数字
                                    //height: 数字

                                    //subs: 数组
                                    
                                }

frozenColumn = -1 frozenRow = -1 frozenBottom = false frozenRight = false frozenColumnMax = 10 frozenRowMax = 10 frozenRowHoverable = false

配置冻结行和冻结列。frozenRowHoverable 用于开启冻结行的悬停样式和悬停事件。

示例冻结

scrollbarSize = 12 scrollbarSizeH = null scrollbarSizeV = null

设置滚动条基础厚度。

scrollbarRound = false

启用圆角滚动条样式。

scrollbarFade = false

启用滚动条淡入淡出效果。

scrollbarFadeTimeout = 1000

设置淡出滚动条隐藏前的延迟时间。

scrollbarType = "auto"

设置滚动条预设：auto 或 mobile，其中 mobile 会启用淡出效果并将尺寸设为 6。

scrollPaneMinWidth = 30

设置滚动面板的最小宽度。

scrollPaneGradient = false

在滚动面板边缘启用渐变遮罩。

示例滚动条

rowDragVisible = false rowDragColumn = {...}

启用内置行拖拽手柄，并配置拖拽列。

rowNumberWidth = 36 rowNumberFilter = null rowNumberColumn = {...}

配置内置行号列。

selectColumn = {...} blankColumn = {...}

配置用于选择和布局填充的内置私有列。

highlightKeywords = {...}

配置匹配关键字的提取方式，以及高亮标记的包裹方式。

textKey = "tg_text_" textGenerator = null highlightKey = "tg_highlight_" highlightPre = "<mark>" highlightPost = "</mark>"

textSelectable = false

允许在表格单元格内选中文本。

bindWindowResize = false

绑定 window resize，并自动调用 resize。

bindContainerResize = false

使用 ResizeObserver 监听容器尺寸变化，并自动调用 resize。

示例尺寸调整

cellResizeObserver = null

过滤需要监听尺寸变化的单元格。依赖 ResizeObserver。

示例行高

事件

事件类型	事件数据	示例
onUpdated onFirstUpdated	`对象：viewport`	示例事件
onHeaderUpdated	`对象：{ node: headerNode }`	示例事件
onSort	`对象：{ e, columnItem, node: headerItemNode }`	示例行排序
onColumnAdded onColumnRemoved	`数组：[columnItem ...]`	示例列新增/删除
onColumnWidthChanged	`对象：columnItem`	示例事件
onRowAdded onRowRemoved	`数组：[rowItem ...]`	示例行新增/删除
onRowExpanded onRowCollapsed	`对象：rowItem`	示例事件
onRowSubsRequest	`对象：rowItem`	示例动态加载子项
onRowDragged	`对象：{ e, rowItem }`	示例行拖拽
onRowDropped	`对象：{ rowItem, dragFrom, dragIndex, dropInto, dropIndex }`	示例行拖拽
onRowMoved	`数组：[rowItem ...]`	示例行移动
onRowMouseEnter onRowMouseLeave	`对象：{ e, rowItem }`	示例事件
onSelectChanged	`数组：[rowItem ...]`	示例行选择
onCellUpdated	`对象：{ value, rowItem, columnItem, node: cellNode }`	示例事件
onCellMouseEnter onCellMouseLeave	`对象：{ e, rowItem, columnItem, rowNode, cellNode }`	示例事件
onClick onDblClick onContextMenu onMouseOver onMouseOut	`// 表头区域对象：{ e, columnItem, headerNode } // 主体区域对象：{ e, rowItem, columnItem, rowNode, cellNode }`	示例事件
onTouchStart onTouchMove onTouchEnd	`// 表头区域对象：{ e, columnItem?, headerNode? } // 主体区域对象：{ e, rowItem?, columnItem?, rowNode?, cellNode? }`	示例触摸
onScroll	`对象：{ scrollLeft, scrollTop }`	示例滚动
onScrollStateChanged	`对象：{ hasHScroll, hasVScroll }`	示例事件
onMouseWheel	`对象：{ e, deltaX, deltaY }`	示例滚动
onResize	`对象：{ previous: 对象, width: 数字, height: 数字 }`	示例尺寸调整
onLayout	`对象：{ previous: 对象, headerWidth: 数字, headerHeight: 数字, bodyWidth: 数字, bodyHeight: 数字, scrollbarWidth: 数字, scrollbarHeight: 数字 }`	示例尺寸调整
onKeyDown	`对象：{ e }`	示例事件
onDestroy	无	示例刷新

生命周期

阶段	子阶段		负载	可用能力
创建	在容器内创建样式和 DOM 结构。应用初始数据。应用初始配置。注册初始格式化器。绑定初始事件处理函数。		低	加载相关 API	`const grid = new Grid(container); grid.setData(data); grid.setOption(options); grid.setFormatter(formatters); grid.bind("[事件类型]", handler);`
渲染	初始化配置		低	全部 API	`grid.render(); grid.rerender();`
	渲染表头		中
	渲染主体	渲染行	中
	渲染主体	渲染单元格	高
更新	更新表格主体。更新一行或多行。更新一个或多个单元格。				`grid.update(); grid.updateRow(rowIndex, rowData); grid.updateCell(rowIndex, columnIndex, cellValue);`
销毁	移除全部内容		低	无	`grid.destroy();`

“tg” 是 Grid 的前缀和内部命名空间。

常见 CSS 类名：


                            .tg-pane {}
                            .tg-body{}
                            .tg-row{}
                            .tg-cell{}

常见私有属性：


                            //rowItem.tg_index
                            //rowItem.tg_level
                            //rowItem.tg_group

调用 exportData() 或 getItemSnapshot() 时，这些私有属性会被移除。

行属性 (rowItem.tg_*)

属性	类型	说明
tg_index	Number	行在完整数据树中的全局索引（包含不可见行）。
tg_view_index	Number	行在可见列表中的索引。仅对可见行设置。
tg_sub_index	Number	在父节点 subs 数组中的索引（包含不可见行）。
tg_list_index	Number	在同一父节点的可见子列表中的索引。
tg_parent	Object \| undefined	指向父行的引用。根级行为 undefined。
tg_level	Number	在树形层级中的嵌套深度。根级行为 0。
tg_group	Boolean	如果行拥有 subs 数组（即分组/父节点），则为 true。
tg_subs_length	Number	行的 subs 数组中直接子节点的数量。
tg_frozen	Boolean	如果行处于冻结区域，则为 true。
tg_invisible	Boolean	如果行通过 hideRow() 或 invisible 属性被隐藏，则为 true。
tg_filtered	Boolean	如果行被 rowFilter 函数过滤隐藏，则为 true。
tg_row_number	String \| Number	显示用行号（不适用时为空字符串）。
tg_selected_index	Number	行被选中的顺序索引。
tg_top	Number	行渲染时的顶部偏移位置（像素）。
tg_height	Number	行的实际渲染高度（像素）。

列属性 (columnItem.tg_*)

属性	类型	说明
tg_index	Number	列在完整列树中的全局索引。
tg_view_index	Number	列在可见列表中的索引。仅对可见列设置。
tg_sub_index	Number	在父分组的 subs 数组中的索引。
tg_list_index	Number	在同一父分组的可见子列表中的索引。
tg_parent	Object \| undefined	指向父列分组的引用。顶级列为 undefined。
tg_group	Boolean	如果列拥有 subs 数组（即表头分组），则为 true。
tg_subs_length	Number	分组中直接子列的数量。
tg_frozen	Boolean	如果列处于冻结区域，则为 true。
tg_invisible	Boolean	如果列通过 hideColumn() 或 invisible 属性被隐藏，则为 true。
tg_width	Number	列的实际渲染宽度（像素）。
tg_left	Number	列的左侧偏移位置（像素）。
tg_height	Number	列表头单元格的高度（像素）。
tg_layer	Number	表头布局的反向层级索引（0 = 最底层）。用于分组表头。

使用示例：


                            grid.setFormatter({
                                string: function(value, rowItem, columnItem, cellNode) {
                                    // 访问行属性
                                    const rowIndex = rowItem.tg_index;
                                    const level = rowItem.tg_level;
                                    const isFrozen = rowItem.tg_frozen;
                                    const isGroup = rowItem.tg_group;

                                    // 访问列属性
                                    const columnIndex = columnItem.tg_index;
                                    const columnWidth = columnItem.tg_width;

                                    return value;
                                }
                            });

                            grid.setOption({
                                rowFilter: function(rowItem) {
                                    // 冻结行始终可见
                                    if (rowItem.tg_frozen) {
                                        return true;
                                    }
                                    return rowItem.name.includes(keywords);
                                }
                            });