Tangram Grid 使用说明

目录

概述

Tangrid Grid是基于Tangram 的一个Grid的控件,它易于使用,功能可拔插,非常方便的扩展出功能,性能优异。能兼容IE6。

功能列表

已经实现的功能
  • 基本的表格数据展现,提供方法将json数据加载到grid中
  • 宽度自适应,设置表格宽度/高度 高度自适应高度,自动拉伸,也可以设置最小高度
  • ajax请求数据数据,分页,支持集成自定义分页控件,能适应不同的ajax请求数据
  • 表格单元格格式自定义,转换器,支持checkbox列
  • Ajax请求时支持遮罩,也可以自定义遮罩
  • 点击列头字段排序
  • 基本事件绑定,行选择,hover ,点击
  • 新增行/修改行/删除行
  • 列宽可以拖动
  • 列头分组
扩展功能(插件实现)
  • 行可以通过拖放改变顺序(使用说明)
  • 列可以通过拖放改变顺序(使用说明)
  • 可编辑表格,支持常见的编辑类型,文本框,下拉框等,支持自定义编辑。(使用说明)
  • 子表格,点击某单元格出现一块区域显示子数据,可以是表格,也可以是自定义内容(使用说明)
  • 冻结列,列比较多的时候出现横向滚动条,可以冻结左边的n列,这些列不随横向滚动条滚动 (使用说明)
  • 数据显示的分组,统计,以及扩展机制,主要是扩展统计方法,支持从ajax请求结果读取统计数据,也支持javascript做简单统计。(使用说明)
  • Treegrid,将表格的某个列显示成树形结构,并支持延迟加载使用说明
  • 大数据量解决方案,延迟呈现,或者延迟加载
  • 键盘事件支持,支持键盘事件,光标操作等使用说明
  • 页内排序使用说明

一些约定

基本使用,方法,配置参数,事件,事件参数
  • 基本使用:

    控件的实例化统一用下面格式:

    								var gridInstance = new baidu.ui.Grid({
    									element:"firsttangramgrid" // other options
    								});
    								
  • 方法:

    方法是指Grid实例的方法,调用方式统一为:

    								gridInstance.fn(parameter);
    								
  • 配置参数:

    配置参数是指Grid实例化时参数中的配置,Grid实例化参数为一个json,该json的可以约定为配置参数,没有特别指出,参数均可默认:

    配置参数中onXXXX为配置事件监听:

    								var gridInstance = new baidu.ui.Grid({
    									element:"gridid",
    									onSelect:function(e,data){//在ajax请求时触发
    										//e为event对象
    										//data 为事件参数,参见该select事件
    									},
    									onBeforeRequest:function(e,data){
    										//onBeforeXXX事件中,可以读写事件参数data
    										//return false; //如果在onBeforeXXX方法中返回false,将会阻止事件的触发
    									}
    								});
    								
  • 事件,事件参数:

    事件是指Grid本身触发的事件,事件通过监听的方式:

    								gridInstance.addEventListener("select",function(e,data){//在行选择时触发
    									//e 是event对象
    									//data 是事件参数,在事件处理中可以读/写事件参数,参数格式应事件类型而异
    								});

    事件的命名约定:beforeXXX事件通常在事件真正执行事件前触发。

    								gridInstance.addEventListener("beforerequest",function(e,data){//在ajax请求前触发
    									//e 是event对象
    									//data 是事件参数,在事件处理中可以读/写事件参数,参数格式应事件类型而异
    									//e.returnValue=false;//如果在事件监听中将event.returnValue=false。事件的默认动作将会阻止
    								});
  • 事件的执行顺序

    事件约定的执行顺序是:beforeXXX事件监听->配置参数中的onBeforeXXXX方法->事件本身动作->事件XXX监听动作->配置参数中的onXXXX方法

    beforeXXX事件监听,配置参数中的onBeforeXXXX方法中阻止了默认动作的触发,后面的事件将不会执行

    beforeXXX事件以及配置参数是否存在以文档的配置参数事件为准

  • this的指向

    非特别说明,方法中的this均指向Grid的实例

  • 其他

    使用Grid控件时不支持直接访问控件内部DOM

配置参数

element

必选参数,DOM的id,确保DOM id在实例化Grid前已经存在

height

必选参数,数字。表格的高度

autoHeight

自动计算高度,默认为false。一旦设置为自动高度,height将最为Grid的最小高度。当表格数据小于height时,Grid将使用最小高度,否则将根据数据高度自动适应。

docktop

可以在表格顶部添加自定义html,例如表格标题,html的内容(不是绝对定位)将于表格一起计算高度和宽度

				var gridInstance = new baidu.ui.Grid({
					docktop:"

自定义表格标题

" //other options });

columns

必选参数,数组,定义列模型

				//不分组列头
				var gridInstance = new baidu.ui.Grid({
					columns:[
						{field:'id',width:30,renderer:'checkbox'},
						{field:'name',header:"机器名称",fix:true},
						{field:'creator',header:"创建人",width:200},
						{field:'dataKey',header:"dataKey",width:400,align:"right",renderer:function(data){return data.cellvalue+"-formated";}},
						{field:'lastVersion',header:"lastVersion",width:200},
						{field:'createTime',header:"创建时间",width:180}
					]// other options
				});
				
				//分组列头
				var gridInstance = new baidu.ui.Grid({
					columns:[
						{field:'id',width:30,renderer:'checkbox',disableBy:function(){return Math.random()>0.5;}},
						{field:'name',header:"机器名称",width:200,fix:true},
						{header:"机器信息",columns:[
							{field:'creator',header:"创建人",width:100},
							{field:'dataKey',header:"dataKey",width:400,align:"right",renderer:function(data){return data.cellvalue+"-formated";}},
							{field:'lastVersion',header:"lastVersion",width:200}
						]},
						{field:'createTime',header:"创建时间",width:180,resizable:false,sortable:false}
					]// other options
				});
				

列配置属性

selectMode

行选择类型:0-为不选择,1-单选,2-多选,默认为0

selectBy

selectBy 初始选中是否选中字段或者判断函数,如果是字段名,则判断该字段是否为true/1/"1",如果是函数,函数接收参数{rowdata:rowdata,rowIndex:rowIndex}。
仅在selectMode!=0时作用,初始选中行不会触发select事件
selectMode==1时,最多只需选中一行

clickToSelect

点击行任何内容选中行,默认为true,如果设置为false,只有点击checkbox才能选中行

hoverhighlight

鼠标滑过行是否高亮,默认为true

strip

是否隔行变色,默认为true

page

分页配置,有三种配置方式:

url

ajax请求的url

ajaxOption

直接作为tangram 中baidu.ajax.request(url,[options])的第二个参数,onsuccess定义无效。 data参数只作为ajax请求的默认参数,可以被request方法参数替换

orderBy

初始的排序字段序号,格式形如"1":第二列 。"2-1":第三列的第二个子列(第三列必须是组头)

order

初始的排序类型 desc / asc

loadMask

ajax请求时遮罩控件区域,默认为false

loadMessage

ajax请求时遮罩提示,默认为"正在加载..."

onRowClick

行点击时触发,事件参数为:

					{
						rowIndex:rowIndex,//行序号
						row:rowdata,//行数据
						ref:{
							cell:cell,//触发事件的单元格(td标签)
							row:row,//触发事件的行(tr标签)
							table:table,//触发事件的table标签DOM
							src:src//触发事件的源对象
						}
					};
				

onRowDblClick

行双击时触发,事件参数为:

					{
						rowIndex:rowIndex,//行序号
						row:rowdata,//行数据
						ref:{
							cell:cell,//触发事件的单元格(td标签)
							row:row,//触发事件的行(tr标签)
							table:table,//触发事件的table标签DOM
							src:src//触发事件的源对象
						}
					};
				

onCellClick

单元格点击时触发,事件参数为:

					{
						columnIndex:columnIndex,//在table中是第几列 从0开始
						refIndex:refIndex,//refIndex 在grid.optoins.columns中的下标,分组子列格式形如"1-0"
						rowIndex:rowIndex,//行序号
						column:column,//列配置信息
						ref:{
							cell:cell,//触发事件的单元格(td标签)
							row:row,/触发行(tr标签)
							table:table,//事件的table标签DOM
							src:src//触发事件的源对象
						}
					}
				

onSelect

行选中时触发,点击行将会选中/取消选中行,也可以调用selectRow方法选中行:事件参数与rowclick事件参数一致。
如果时调用selectRow方法选中行,事件有关的参数为空

onUnSelect

取消行选中时触发,点击行将会选中/取消选中行,也可以调用unSelectRow方法取消选中行:事件参数与rowclick事件参数一致。
如果时调用unSelectRow方法选中行,事件有关的参数为空

onBeforeRequest

ajax请求前调用方法,事件参数为ajaxOption

onBeforeLoad

ajax请求回调时触发,或者调用loadData时触发,事件参数为表格参数

onAfterLoad

数据加载完毕后触发,或者调用loadData后触发,事件参数为表格参数

onBeforeSort

排序前触发方法:事件参数为

						{
							orderBy:col.field,//排序字段
							order:order//排序类型 desc asc
						}
					

方法

resize

重新调整表格大小,通常在表格容器大小发生变化时调用。
参数({width:w,height:h}),width可以是数字,也可以是"auto",height必须是数字。
如果设置autoHeight=true,height只是设置最小高度

request

ajax请求加载表格数据,参数为(data),data为ajaxOption中的data属性。data将会覆盖默认属性。
Grid默认的请求参数为:

					{
						orderBy:"排序字段",
						order:"asc/desc",
						curPage:"当前页数",
						perPage:"每页记录条数"
					}
				

loadData

手动加载表格数据,参数为(data)
表格数据格式为:

					{
						"data":{
							"page":{
								"total":"52"//total属性如果缺省,自动取上次请求时的值,没有上次请求值,total是list.length
							},
							"list":[
								{"id":"42","name":"z0614_ui_sample_all"},
								{"id":"41","name":"z0614_bws_sample"},
								//...
							]
						}
					}
				

如果表格数据不是上述约定格式,可以通过onBeforeLoad方法或者beforeload事件解析成该格式。

getData

获取表格数据,格式形如表格数据格式

selectRow

选择行,参数为(rowIndex)

unSelectRow

选择行,参数为(rowIndex)

toggleSelectRow

选择行/取消选择行,参数为(rowIndex)

getSelected

获取选中行的第一行数据,如果没有选择行,返回null,可以指定参数列,返回指定列值,如getSelected("id"),只返回选中行id值,如getSelected(["id","name"]),只返回选中行{id:id,name:name}

getSelections

获取选中行数据,返回数组,可以指定参数列,返回指定列值,getSelections("id"),只返回选中行id值的数组,,getSelections(["id","name"]),返回选中行{id:id,name:name}的数组

reOrder

按字段排序,参数为(colIndex,order) colIndex格式形如"1","1-1"。order:asc/desc

hideColumn

隐藏列,参数为(colIndex)colIndex格式形如"1","1-1"。

showColumn

显示列,参数为(colIndex)colIndex格式形如"1","1-1"。

addRow

添加数据行,参数为(row[,rowIndex])row是新行数据,rowIndex:在第rowIndex行前新增,rowIndex如果不指定,行数据追加到表格最后。rowIndex从0开始,rowIndex如果为0,则在最上方添加行。addRow与addDOMRow区别

updateRow

添加数据行,参数为(row,rowIndex)row是新行数据,rowIndex:行序号,从0开始

deleteRow

删除数据行,参数为(rowIndex)rowIndex:行序号,从0开始。会删除表格数据

addDOMRow

添加DOM行,参数为(row[,rowIndex])row是新行数据,rowIndex:在第rowIndex行钱新增,rowIndex如果不指定,行数据追加到表格最后。rowIndex从0开始,rowIndex如果为0,则在最上方添加行。函数返回新行的rowIndex

addRow与addDOMRow区别,addRow是在表格数据上添加一行,然后重新加载一次数据,数据加载完后会触发afterload事件,addDOMRow则是在表格上找到rowIndex行,利用DOM操作直接添加行,不会触发afterload事件

updateDOMRow

更新DOM行,参数为(row,rowIndex)row是行数据,rowIndex:行序号,从0开始

deleteDOMRow

删除DOM行,参数为(rowIndex),删除DOM row。不删除表格数据。

cellIterator

单元格遍历,参数为遍历函数,函数参数为:

					{
						column:colopts,//列选项
						cell:cell,//单元格td
						row:row,//单元格所在tr
						colIndex:refcol,//列序号
						rowIndex:rowIndex,//行序号
						rowdata:rowdata//行数据
					}
					

showMask

显示遮罩层

hideMask

隐藏遮罩层

事件

resize

调用resize方法是触发,事件参数为{}

beforerequest

ajax请求前触发该方法,事件参数为ajaxOption

datafilter

ajax请求成功触发该方法,可以利用该事件将服务端返回数据解析成表格所需的数据,事件参数为ajax返回的json对象。

beforeload

数据加载前触发事件,在loadData方法中触发,参数为表格数据格式

afterload

数据加载后触发事件,参数为表格数据格式

unselect

取消行选择触发事件,参数为行点击参数格式

select

行选择触发事件,参数为行点击参数格式

beforesort

排序前触发事件,参数为{orderBy:orderfiled,order:"asc/desc"}

hidecolumn

隐藏列触发事件,参数为{colIndex:colIndex}

showcolumn

显示列触发事件,参数为{colIndex:colIndex}

addrow

添加数据行触发事件,参数为{row:row,rowIndex:rowIndex}

updaterow

更新数据行触发事件,参数为{row:row,rowIndex:rowIndex}

deleterow

删除数据行触发事件,参数为deleterow

adddomrow

添加DOM row触发,调用addDOMRow方法时触发参数{rowIndex:rowIndex,newRowIndex:newRowIndex,rowdata:rowdata}

updatedomrow

更新DOM row触发,调用updateDOMRow方法时触发,参数{rowIndex:rowIndex,rowdata:rowdata}

deletedomrow

删除DOM row触发,调用deleteDOMRow方法时触发,参数{rowIndex:rowIndex}

cellclick

单元格触发事件,参数为单元格点击事件参数

rowclick

表格行点击触发事件,参数为表格行点击事件参数

rowdblclick

表格行双击触发事件,参数为表格行点击事件参数

headercellclick

列头单元格点击触发事件,参数为{ref:{table:table,row:row,cell:cell,src:src}}

columnresize

列宽发生变化时,参数为{column:columnopts}

initialized

初始化完毕触发事件,参数为{}

beginrowjoin

拼接表格html字符串,在每行循环开始时,可以利用该事件添加数据行前面的html代码(比如在分组时需要在每组的第一行前面添加分组行)
参数为:

						{
							realColumnsLength:realColumnsLength,//实际table中row的列数(td个数)
							rowdata:row,//该行的数据
							rowIndex:i,//行号,从0开始
							joinedArray:arr//已经拼接的字符串数组,如果需要添加html,可以使用joinedArray.push("the html before <tr>");
						}
					

endrowjoin

拼接表格html字符串,在每行循环结束时,可以利用该事件添加每数据行后面的html代码
参数为:

						{
							realColumnsLength:realColumnsLength,//实际table中row的列数(td个数)
							rowdata:row,//该行的数据
							rowIndex:i,//行号,从0开始
							joinedArray:arr//已经拼接的字符串数组,如果需要添加html,可以使用joinedArray.push("the html after </tr>");
						}
					

endrowsjoin

在最后一行数据行循环完执行,可以在表格最下方添加tr。如合计。
参数为:

						{
							joinedArray:arr//已经拼接的字符串数组,如果需要添加html,可以使用joinedArray.push("the html after </tr>");
						}
					

插件功能文档

行扩展,数据展开/收缩

需引入tangram.grid.rowexpand.js

行可以拖动改变顺序

需引入tangram.grid.rowsortable.js

列冻结

需引入tangram.grid.columnfreeze.js

可编辑表格

需引入tangram.grid.editable.js

分组统计功能

需引入tangram.grid.groupsummary.js

分组统计功能用数据分组显示,以及简单的统计,统计数据可以来源于ajax请求,也可以来源于javascript简单统计。
Grid本身支持简单的统计类型,比如,count:计个数,sum:求和,avg:平均值,max:最大字符串值,min:最小字符串值,minnumber:最小数字,maxnumber:最大数字。并支持扩展
自定义统计类型myaverage如:

						baidu.ui.Grid.ext.summarytype.myaverage = function(previousValue,currentvalue,seqIndex,sequenceLength){
							//previousvalue 同一个统计序列中上一次调用mysummary该方法的返回值
							//currentvalue 当前值
							//seqIndex:当前序号,统计数据组中的序号,从0开始
							//sequenceLength:统计数据组的长度
							if(seqIndex==0){
								return parseFloat(currentvalue);
							}else{
								var v = previousValue;
								v+=parseFloat(currentvalue);
								if(seqIndex=sequenceLength-1){//最后一条求平均值
									return v/sequenceLength;
								}else{
									return v;//不是最后一条,求和
								}
							}
						}
					

分组统计功能使用示例:

					var griddemo = new baidu.ui.Grid({
						element:"gridwidthgroupsummary",
						groupBy:"country",//分组字段
						groupHeader:function(param){//分组行显示内容
							//{groupValue:groupValue,groupData:{}}
							return param.groupValue+" 共"+(param.groupData[param.groupValue].rows.length)+"公司";
						},
						groupSummary:true,//显示分组合计
						summary:true,//显示总合计
						columns:[{
								field:'rank',
								header:"2011排名",
								width:80,
								sortable:false,
								summaryFormat:"合计:",//合计行单元格显示内容
								groupSummaryFormat:"小计:"//小计行单元格显示内容
							},{
								field:'name',
								header:"公司名称(中英文)",
								width:400,
								sortable:false,
								groupSummary:"count",//分组合计类型,使用javascript统计
								groupSummaryFormat:"共#{groupSummaryValue}家",
								summay:"count",//总合计类型
								summaryFormat:"共#{summaryValue}家"
							},{
								field:'income',
								header:"营业收入(百万美元)",
								width:140,
								align:"right",
								sortable:false,
								groupSummary:"maxnumber",
								groupSummaryFormat:"最高:#{groupSummaryValue}",
								summay:"maxnumber",
								summaryFormat:"最高:#{summaryValue}"
							},{
								field:'profit',
								header:"利润(百万美元)",
								width:140,
								align:"right",
								sortable:false,
								groupSummary:"avg",
								groupSummaryFormat:function(data){//groupSummaryFormat也可以是一个方法
									//可以直接通过this.getData()获取ajax表格数据,this指向表格实例
									return "平均:"+data.groupSummaryValue.toFixed(2);
								},
								summay:"avg",
								summaryFormat:function(data){
									return  "平均:"+data.summaryValue.toFixed(2);
								}
							},{
								field:'country',
								header:"国家",
								width:120,
								sortable:false
							}
						],//other grid options
				

添加的配置:

列定义添加的配置:

TreeGrid

需引入tangram.grid.treegrid.js

使用TreeGrid可以将某一列显示为树形,该列能够展开/收缩节点。TreeGrid对表格请求数据没有特别格式要求,只需要指定id字段和parentid字段即可。

						var griddemo = new baidu.ui.Grid({
							element:"treegrid",
							columns:[
								{field:'name',header:"名称",width:400,
									renderer:'tree',//树形列
									idfield:'id',//主键字段名称,节点行的唯一标识
									parentfield:'parentid',//父节点字段名称
									expandBy:function(data){//可以展开特定的节点
										return data.cellvalue=="EditPlus 3";//初始展开特定节点
										//return true;//展开所有节点
									}
								},
								{field:'createtime',header:"创建时间",width:100},
								{field:'readonly',header:"只读",width:100,renderer:function(data){return data.cellvalue=="false"?"否":"是"}},
								{header:"类型",width:100,renderer:function(data){
									var id = data.rowdata.id;
									if(data.rowdata.name.indexOf(".")!=-1){
										return (data.rowdata.name.substr(data.rowdata.name.lastIndexOf(".")+1)+"文件");
									}
									if(this.treedata[id].children.length>0){//treedata是解析出来的属性数据
										return "文件夹";
									}
									return "文件";
								}}
							],//...
					
						//加载树形数据
						//需要提供idfield,parentfield字段值
						griddemo.loadData({
							data:{
								list:[
									{id:"1",parentid:"",name:"C:\\",readonly:"false",createtime:"2011-07-30"},
									{id:"18",parentid:"15",name:"htpasswd",readonly:"false",createtime:"2011-07-30"},
									{id:"19",parentid:"15",name:"server.pid",readonly:"false",createtime:"2011-07-30"},
									{id:"14",parentid:"",name:"D:\\",readonly:"false",createtime:"2011-07-30"},//...
					

TreeGrid在呈现数据前会将Grid请求数据解析,解析将会改变data.list的数据, (可以通过getOriginList()方法获取原始的表格请求数据), 同时会生成treedata,treedata的格式为:

						{
							[idvalue]:{//key 为id字段值,如果为跟节点,idvalue为"root"
								rowIndex:rowIndex,//该行数据在表格原始请求数据中的rowIndex,从0开始
								parent:parentfieldvalue,//节点的父节点id值
								children:[0,1..]该节点的子节点的rowIndex数据,rowIndex是原始数据的rowIndex
							}
						}
					

通过treedata的originList就可以方便的实现Tree的遍历

TreeGrid中的同级节点的排序是以原始list顺序为准的,比如,A与B是同级节点,在原始list中A在B的后面,显示在Grid中的顺序也是A在B的后面。这样原有的表格排序将会变成同级节点的排序。

Tree列的定义:

TreeGrid相关方法:

如果需要修改指定节点行的字段值,可以使用updateDOMRow方法

键盘事件

需引入tangram.grid.keyboard.js

增加配置属性keyboard当keyboard:true才可以激活键盘事件,配置属性keysrc为监听事件的DOM对象,默认是document.body

增加方法focus/blur用于表格控件聚焦/失去焦点。只有表格在聚焦状态下才能监听键盘事件。默认点击表格控件将会聚焦

可支持的键盘事件:

页内排序

需引入tangram.grid.pagesort.js

对于没有分页而且没有url属性的表格,可以对指定field属性而且指定sortable为true(默认为true)的列进行页内排序。

列可以通过拖放改变顺序

需引入tangram.grid.columndragsort.js

配置属性columndraggable设置为true可是打开该功能。列拖动后顺序会发生改变,可以通过 getOriginColumns()方法获取原始列定义数组

扩展

列类型扩展

参考列定义

自定义分页控件

参考分页定义

自定义统计类型

参考自定义统计类型

已知的Bug

WebKit浏览器下出现列对不齐的情况

webkit的table-layout:fixed bug引起,参见这里

对Grid有兴趣?

Tangarm Grid代码目前托管在github 上:https://github.com/hafeyang/tangramgrid

git地址:git://github.com/hafeyang/tangramgrid.git

也可以用svn地址:http://svn.github.com/hafeyang/tangramgrid


Tangram Grid is the Grid you need!