dotNetFlexGrid 控件Api说明文档

dotNetFlexGrid 控件Api说明文档

文档类别	技术文档
文档编号	T03-00001-YYMMDD
来源部门	技术部研发部门
应用范围	技术部
保密级别	★★★
修订历史记录
日期	版本	说明	作者
2010-8-2	1.0	Create	华磊

目 录
1、 目的

2、 版本历史

3、 简介

4、 服务端方法、属性

5、 客户端方法、事件

6、 快速开始

7、 常用操作和问题说明

8、 已知BUG

1、 目的

1.1 ；

2、 版本历史

2010-8-26 v1.23beta(重要更新)

n 修复insertNewRow()、updateRowData()方法不能正确处理对齐和宽度的bug。

n 修复insertNewRow()产生的行不能选中和触发事件的bug。

n 新增Js方法getGridJsonData()用于提取当前grid的所有数据，产生一个Json格式的字符串，可以保存在表单域中。

n 新增服务端方法ParseGetGridJsonData()用于解析getGridJsonData()生成的数据，将返回一个二维字典，配合CheckedRows可获取到用作表单提交的Grid的所有数据。

n 修复applyQueryReload()方法在参数已存在时只能处理一个参数的BUG.

2010-8-21 v1.22 beta

n 修复字段拖动位置后nBtn按钮的位置不正确的bug.

n 修复使用模板后可能导致的模板无效的bug.

n 修复字段sortable配置可能无效的bug。

2010-8-21 v1.21 beta

n 增加对控件配置目录的正确性检验，当配置错误的时候将会抛出一个易于理解的异常信息。

n 增加控件参数BasePath该参数用于配置控件的存放目录，请提供相对于网站更目录的绝对路径。

n 修复由于字段配置错误所导致的排列错位问题，现在将显示一个noset来标志错误的字段。

2010-8-19 v1.2 beta

n 修复快速查询时的键盘回车事件与控件外围事件的冲突的问题。

n 修复快速查询时设置正则表达式时可能导致的语法错误的问题。

n 数据提供方法DataHandler将不再强制要求与列的绑定顺序一致，现在通过返回的DataTable中的ColumnName自动绑定到合适的列，所以，请保证您的DataTable和控件中的列名一致（区分大小写）。

n 增加展现模板的功能，现InitConfig初始化时针对列配置增加了一个itemTemplate属性，该属性提供了当前列的展现模板设定。

n 演示项目中FirstGrid.aspx增加了客户端刷新、服务端刷新和快速查询功能的演示。

n 演示项目中TestTemplate.aspx提供了使用展现模板的演示。

2010-8-17 v1.1 稳定版

n 增加全客户端编辑模式，可在不加载任何数据的模式下进行表格数据的添加、删除、修改；通过该功能并结合服务端属性，即可完成将一或者多个动态表格包含在表单中整体提交；典型应用场景：进销存出入库单据、订单等。

n 调整客户端如下方法

u getCellDatas，现在可以正确获取到客户端调整列顺序后的数据了，返回的数据总是以初始化时的列顺序为准，保证了前后逻辑的一致性。
u updateRowData 新增方法，用于动态修改表格中的数据，提供的数据以初始化时的列顺序为准。
u insertNewRow，调整提供的数据以初始化时的列顺序为准。

n 优化表格列手动调整顺序，可以让客户自己对表格的列顺序进行调整。

n 优化客户端呈现效率-调整多数行、列数据处理方式为字典模式，摒弃大部分原采用的根据dom结构操作数据的方法，提升了客户端的响应速度。

n 修复客户端新增行无法选中的BUG。

n 截止当前版本，与原生FlexiGrid和假正经哥哥的改进版本变化非常之大，基本核心代码进行过重构和改进，与上述控件已不存在兼容的可能。

2010-8-13 v1.0正式版

n 增加通用分页存储过程解决方案。

n 新增表格数据的字典模式处理，摒弃原rowbinddata的方式，提升了处理效率和DOM的简洁性，修改若干返回数据的方法应用字典模式。

n 原有的getSelectRows方法更名为getSelectedRowsIds，返回当前选择行的id数组；

n 新增方法getSelectedRows，返回当前选择行的数组，数组元素是列的字典；

2010-8-2 v1.0beta

n 将样式表的加载改为JS动态加载。

n 采用类似于AJAX的反射模式调用数据提供函数，使得不必单独开发数据提供的页面或逻辑处理。

n 放弃原控件的Toolbar功能，我认为功能性操作应该与数据展示在表现形式和逻辑封装上分离开，比如操作权限控制应该有独立的逻辑处理。

n 新增若干客户端事件（单击行、双击行、选择行、加载等）。

n 新增服务端属性CheckedRows，整个控件可以作为表单的一部分提交，可在服务端直接获取当前选择的行的主键（ID）。

n 优化表格首行复选框的展示和处理，修复onrowchecked事件的若干BUG。

n 新增列参数checkField，第一个设为checkField的列通过绑定布尔值可以在加载数据时选择到需要被选择的行，该操作不会触发事件。

n 针对原有Javascript进行重新封装，提供单独的对象进行控件的处理。

n 修改数据提供模式固定为Json，本控件将只支持Json方式的异步数据提供。

n 修复多个控件存在时产生的若干BUG。

n 修复若干BUG，增加正则错误验证，各类数据null的验证。

3、 简介

致谢

最初版本以Jquery Flexigrid(http://www.flexigrid.info/)为展现模型，并大量采用了国人假正经哥哥的改进版本）中的样式和大量代码。

功能特点

1、 原生dotNet WebForm用户控件（采用用户控件的主要原因是方便修改和二次开发，待版本稳定后将推出服务端控件版本）。

2、 采用类似于AjaxPro的异步模式，表格数据的绑定、刷新、排序、查询及表格操作（新增、修改、删除）均采用异步局部刷新模式，即数据的更改不会使得当前页面重新刷新。

3、 支持表格的列拖动调整展现顺序。

4、 支持表格的列排序功能。

5、 支持表格的标题功能。

6、 集成数据分页器，通过配置可让用户自行选择分页条数。

7、 支持列的显示隐藏，用户可自行选择显示和隐藏具体的列。

8、 支持首列复选框的展示。

9、 支持斑马色。

10、 集成快速查询的功能，可针对查询的输入进行正则验证。

11、 支持全客户端模式，结合表单提交和列的隐藏，实际可以将控件作为高级的listbox或listview，用作复杂二维数据的存储和提交（典型应用场景：进销存出入库单据、订单等）。

12、 支持若干客户端事件（行点击、双击、加载等）。

13、 支持异步的重新加载，通过此功能可实现与其他控件的客户端联动或者多个Grid的联动。

14、 其他Grid的若干标准功能，不再累述。

4、 服务端方法、属性

1 辅助类型

1.1 dotNetFlexGrid.ExtParamConfig

扩展的Post传递参数配置，用于InitConfig

1.2 dotNetFlexGrid.SerchParamConfigOperater

快速查询配置的查询操作定义，用于InitConfig

1.3 dotNetFlexGrid.SerchParamConfig

快速查询参数配置，用于InitConfig

1.4 dotNetFlexGrid.FieldConfigAlign

Grid字段配置的字段对齐配置，用于InitConfig

1.5 dotNetFlexGrid.FieldConfig

Grid字段配置，用于InitConfig

1.6 dotNetFlexGrid.DataHandlerResult

数据生成函数的返回结果

1.7 dotNetFlexGrid.DataHandlerParams

异步请求的参数信息

1.8 dotNetFlexGrid.delegate DataHandlerDelegate

数据处理函数的委托定义

2 InitConfig初始化Grid配置方法

该方法为控件的核心方法(必须调用)，用于初始化Grid配置，函数定义：

---------------------------------------------------------------------------------------------------------------------

public void InitConfig(
string[] gridparam,//表格主控参数，选填时将采用默认值
FieldConfig[] fieldparam, //表格字段参数，不可选填
SerchParamConfig[] serchParam, //快速查询参数，用于配置快速查询的项目和操作模式，选填时不显示快速查询
ExtParamConfig[] postExtParam//附加的Post参数，用于额外的参数传递（用于DataHandler对应的方法）
)

---------------------------------------------------------------------------------------------------------------------

Gridparam赋值（初始化时请将:更换为=），如

this.DotNetFlexiGrid1.InitConfig(
new string[]{
"title=标题",//标题
"singleselected=false",//是否单选

}

)

---------------------------------------------------------------------------------------------------------------------

height: '240, //flexigrid插件的高度，单位为px，可设为auto
width: 'auto' //宽度值，单位为px，auto表示根据每列的宽度自动计算
striped: false //是否显示斑纹效果，默认是奇偶交互的形式
resizable: true //是否可调整表格打下
usepager: false //是否分页
nowrap: true //是否不换行
page: 1 //默认当前页
total: 1 //默认总页面数
useRp: true //是否可以动态设置每页显示的结果数
rp: 20 //每页默认的结果数
rpOptions: [10, 20, 30, 40, 50] //可选择设定的每页结果数
title: false //是否包含标题
query: '' //默认快速搜索查询的条件
qtype: '' //默认快速搜索查询的类别
qop: "Eq"//默认快速搜索的操作符
showcheckbox: false, //是否显示checkbox
singleselected: true //是否单选
selectedonclick: true //点击行是否选中
sortname: "" //默认排序字段
sortorder: "asc" //默认排序方式

showtc: true //是否显示表头

---------------------------------------------------------------------------------------------------------------------

3 DataHandler 异步处理的数据处理函数

核心属性，指定用作异步处理的数据处理函数，注意，此函数定义必须是public，并不能为static且必须在页面类中声明该函数，如果不提供该函数，则控件进入纯客户端模式，通过客户端事件和方法操作表格数据，可以用作储存列表数据的容器使用。

函数定义

---------------------------------------------------------------------------------------------------------------------

public delegate DataHandlerResult DataHandlerDelegate(DataHandlerParams p);

---------------------------------------------------------------------------------------------------------------------

DataHandlerResult 类定义

---------------------------------------------------------------------------------------------------------------------

public class DataHandlerResult
{
/// <summary>
/// 返回的数据页号
/// </summary>
public int page;
/// <summary>
/// 返回的总记录行数
/// </summary>
public int total;
/// <summary>
/// 包含数据的DataTable
/// </summary>
public DataTable table;
}

---------------------------------------------------------------------------------------------------------------------

DataHandlerParams类定义

---------------------------------------------------------------------------------------------------------------------

public class DataHandlerParams
{
/// <summary>
/// 初始化时的默认查询条件
/// </summary>
public Dictionary<string,string> defaultSearch;
/// <summary>
/// 请求页，即为分页中需要到达的页
/// </summary>
public int page;//请求页
/// <summary>
/// 需要返回的行数
/// </summary>
public int rp;//行数
/// <summary>
/// 快速查询的操作符
/// </summary>
public SerchParamConfigOperater qop;//查询操作符
/// <summary>
/// 快速查询的字段名
/// </summary>
public string qtype;
/// <summary>
/// 快速查询的字段值
/// </summary>
public string query;//搜索查询的条件
/// <summary>
/// 排序字段
/// </summary>
public string sortname;
/// <summary>
/// 排序方式,asc or desc
/// </summary>
public string sortorder;
/// <summary>
/// 附加的扩展参数，可以用作表单数据的传递
/// </summary>
public Dictionary<string, string> extParam;//扩展参数
}

---------------------------------------------------------------------------------------------------------------------

调用范例

---------------------------------------------------------------------------------------------------------------------

Grid1.DataHandler = new dotNetFlexGrid.DataHandlerDelegate(DotNetFlexGrid1DataHandler);

public dotNetFlexGrid.DataHandlerResult DotNetFlexGrid1DataHandler(
dotNetFlexGrid.DataHandlerParams p
)
{

//p为传递的参数信息，你需要通过他组织你的查询和筛选逻辑

//return 为绑定在Grid中的数据

}

---------------------------------------------------------------------------------------------------------------------

4 ServerShow调用控件展示方法

该方法为控件的核心方法(必须调用)，用于服务器配置完毕，调用控件展示。

方法定义

---------------------------------------------------------------------------------------------------------------------

public void ServerShow()
{}

---------------------------------------------------------------------------------------------------------------------

5 EventOnClickFunc行单击事件的处理函数关联属性

该属性提供客户端的行单击事件的处理函数关联，属性给定的函数名决定客户端的单击事件调用的对应函数。

Javascript函数定义范例

---------------------------------------------------------------------------------------------------------------------

DotNetFlexiGrid_onClick = function(rowId) {
//alert(e);
};

---------------------------------------------------------------------------------------------------------------------

6 EventOnDbClickFunc行双击事件的处理函数关联属性

该属性提供客户端的行双击事件的处理函数关联，属性给定的函数名决定客户端的双击事件调用的对应函数。

Javascript函数定义范例

---------------------------------------------------------------------------------------------------------------------

DotNetFlexiGrid_onDbClick = function(rowId) {
alert(e);
};

---------------------------------------------------------------------------------------------------------------------

7 EventOnCheckedFunc行的复选框选择事件的处理函数关联属性

该属性提供客户端的行的复选框选择事件的处理函数关联，属性给定的函数名决定客户端的复选框选择事件调用的对应函数。

Javascript函数定义范例

---------------------------------------------------------------------------------------------------------------------

DotNetFlexiGrid_onChecked = function(rowId) {
alert("onChecked" + e);
};

---------------------------------------------------------------------------------------------------------------------

8 EventOnUnCheckedFunc行复选框取消选择事件的处理函数关联属性

该属性提供客户端的行复选框取消选择事件的处理函数关联，属性给定的函数名决定客户端的行复选框取消选择事件调用的对应函数。

Javascript函数定义范例

---------------------------------------------------------------------------------------------------------------------

DotNetFlexiGrid_onUnChecked = function(e) {
alert("onUnChecked" + e);
};
---------------------------------------------------------------------------------------------------------------------

9 EventOnLoadFuncGrid加载成功事件的处理函数关联属性

该属性提供客户端的Grid加载成功事件的处理函数关联，属性给定的函数名决定客户端的Grid加载成功事件调用的对应函数。

Javascript函数定义范例

---------------------------------------------------------------------------------------------------------------------

DotNetFlexiGrid_onLoad = function() {
alert('onLoad');
};

---------------------------------------------------------------------------------------------------------------------

10 EventOnSelectedFunc属性

暂时不提供

11 DefaultSearch 定Grid的默认查询参数

可选参数，用作指定Grid的默认查询参数，DataHandler中可以接收到此参数用作默认（如主表单的筛选逻辑）的查询参数。

该属性为一个数组，可以增加任意名值对行的数据。

使用范例

---------------------------------------------------------------------------------------------------------------------

页面初始化时调用
this.dotNetFlexGrid1.DefaultSearch.Add("默认查询条件","中文的值");
DataHandler方法的处理
public dotNetFlexGrid.DataHandlerResult DotNetFlexGrid1DataHandler(
dotNetFlexGrid.DataHandlerParams p
)
{
…//获取数据的方法，产生了result.table中的数据
if (p.defaultSearch.ContainsKey("默认查询条件"))
{
//此处使用DataView的过滤功能进行模拟查询
DataView dv = result.table.DefaultView;
dv.RowFilter = "默认查询条件Like '%" + p.defaultSearch["默认查询条件"] + "%'";
result.table = dv.ToTable();
}

…//后续操作

};

---------------------------------------------------------------------------------------------------------------------

12 CheckedRows 表格选定值属性

该属性用于PostBack时的当前表格选定值的处理，该属性只读，并返回一个主键（主键根据DataHandler方法中table的主键决定）数组。

使用范例

---------------------------------------------------------------------------------------------------------------------

if (IsPostBack)
{
this.ListBox1.Items.Clear();
foreach (string s in dotNetFlexGrid1.CheckedRows)
this.ListBox1.Items.Add(s);
}

---------------------------------------------------------------------------------------------------------------------

13 ParseGetGridJsonData解析通过客户端方法getGridJsonData()生成的数据

该属性用于PostBack时解析getGridJsonData()生成的数据，从而返回一个完整的dotNetFlexGrid中的数据，客户端可以在表单提交的时候将当前的Grid数据存入一个隐藏域，在提交之后，服务端使用ParseGetGridJsonData获取到包含Grid所有数据的二维字典。也可配合CheckedRows使用，进一步获取到Grid中的选中状态。

使用范例

---------------------------------------------------------------------------------------------------------------------

DataTable result = new DataTable("StockFormIn");
result.Columns.Add("ProductId", System.Type.GetType("System.String"));
result.Columns.Add("ProductName", System.Type.GetType("System.String"));
result.Columns.Add("ProductNumber", System.Type.GetType("System.Int32"));
result.Columns.Add("ProductPrice", System.Type.GetType("System.Single"));
result.Columns.Add("ProductCode", System.Type.GetType("System.String"));
result.Columns.Add("OpType", System.Type.GetType("System.String"));

Dictionary<string, Dictionary<string, string>> listData = dotNetFlexGrid1.ParseGetGridJsonData(txtListData.Value);

foreach(string key in listData.Keys)
{
DataRow dr = result.NewRow();
dr["ProductId"] = listData[key]["ProductId"];
dr["ProductName"] = listData[key]["ProductName"];
dr["ProductNumber"] = int.Parse(listData[key]["ProductNumber"]);
dr["ProductPrice"] = Single.Parse(listData[key]["ProductPrice"]);
dr["ProductCode"] = listData[key]["ProductCode"];
dr["OpType"] = listData[key]["OpType"];

result.Rows.Add(dr);
}
this.Repeater1.DataSource = result;
this.Repeater1.DataBind(); ---------------------------------------------------------------------------------------------------------------------

5、 客户端方法、事件

控件提供封装好的的Grid操作对象，当前页的Dom 对象名为控件ID，即为如下示中的ID="dotNetFlexGrid1"，即为dotNetFlexGrid1。

<uc1:dotNetFlexGrid ID="dotNetFlexGrid1" runat="server" />

1 getSelectedRows()获取当前选中行的字典数组

使用范例

---------------------------------------------------------------------------------------------------------------------

获取第一行的代码

var dic=dotNetFlexGrid1.getSelectedRows();
if(dic&&dic.length>0)
alert("第一行数据InfoId="+dic[0].item("InfoId")+";");
遍历演示

function getRows()
{
var dic=dotNetFlexGrid1.getSelectedRows();
alert("选择了"+dic.length+"行");
$(dic).each(function(){
var row=this;
var text='';
text+="id:"+this.item("id")+"\r\n";
$(this.keys()).each(function(){
text+=this+"="+row.item(this)+"\r\n";
});
alert(text);

});
alert("第一行数据InfoId="+dic[0].item("InfoId")+";");
}
---------------------------------------------------------------------------------------------------------------------

2 getSelectedRowsIds()获取当前选中行的主键

使用范例

---------------------------------------------------------------------------------------------------------------------

var rows = DotNetFlexiGrid1.getSelectedRowsIds();
for (var i = 0; i < rows.length; i++) {
alert(rows[i]);
}

---------------------------------------------------------------------------------------------------------------------

3 reflashData()重新加载Grid

---------------------------------------------------------------------------------------------------------------------

DotNetFlexiGrid1.reflashData();

---------------------------------------------------------------------------------------------------------------------

4 deleteRows()删除指定主键的行

---------------------------------------------------------------------------------------------------------------------

DotNetFlexiGrid1.deleteRows(DotNetFlexiGrid1.getSelectedRowsIds());

---------------------------------------------------------------------------------------------------------------------

5 getCellDatas()获取指定行的表格数据(按表格当的排序，不依赖数据排序)

---------------------------------------------------------------------------------------------------------------------

//演示获取第一行的全部数据（包括被隐藏的列）

var id = DotNetFlexiGrid1.getSelectedRowsIds()[0];
if (id) {
var array = DotNetFlexiGrid1.getCellDatas(id);
if (array) {
for (var i = 0; i < array.length; i++) {
alert(array[i]);
}
}
}

---------------------------------------------------------------------------------------------------------------------

6 applyQueryReload()应用新的ExtParam重新加载Grid

---------------------------------------------------------------------------------------------------------------------

//演示模拟的双表格联动

function Grid1Onclick(id) {
//传递给Grid2一个查询选项数组并让其刷新
var p = [
{ name: "MasterTableId", value: dotNetFlexGrid1.getCellDatas(id)[5] },
{ name: "用于测试的", value: "测试的值" + id }
];
dotNetFlexGrid2.applyQueryReload(p);

}

---------------------------------------------------------------------------------------------------------------------

7 insertNewRow ()根据传递参数插入新行

---------------------------------------------------------------------------------------------------------------------

function InsertNewRows() {
DotNetFlexiGrid1.insertNewRow({
id: 'newid', //行的ID，后台绑定的是主键
cell: [
"列1",
"列2",
"列3",
"列4",
"列5",
'列6',
'列7'
]
});
}

---------------------------------------------------------------------------------------------------------------------

8 updateRowData()根据传递参数更改指定的行的数据

---------------------------------------------------------------------------------------------------------------------

function EditRows() {
var id = dotNetFlexGrid1.getSelectedRowsIds()[0];
if (id) {
dotNetFlexGrid1.updateRowData({
id: id,
cell: [
"edt_guid" + Math.round(Math.random() * 10000),

"e_f1",
"e_f2",
"e_f3",
"e_f4",
'e_f5',
'e_f6',
'e_f7'
]
});
}
}

---------------------------------------------------------------------------------------------------------------------

9 getGridJsonData ()提取当前grid的所有数据产生一个Json格式的字符串，可以保存在需要进行提交的表单域中，服务端配合ParseGetGridJsonData()使用。。

---------------------------------------------------------------------------------------------------------------------

function formSubmit() {
var lstData = $('#<%=txtListData.ClientID %>');
$(lstData).val(dotNetFlexGrid1.getGridJsonData());
return true;
}

---------------------------------------------------------------------------------------------------------------------

6、 快速开始

7、 常用操作和问题说明

1 什么是行的主键（ID）

dotNetFlexGrid实际在页面中展示标准的HTML TABLE,其中，Table Row将分配一个唯一的ID，该ID取值为DataHandler方法返回的表格中第一个为PrimaryKey的列对应的数据，如果表格中没有有效的PrimaryKey，则取第一个数据列的值作为Table Row ID。

Table Row ID用于dotNetFlexGrid大多数的行的操作，如客户端getSelectedRowsIds方法即返回Table Row ID的数组，服务端CheckedRows属性也是返回此类数组。

2 强调DataHandler函数

DataHandler采用的异步调用的方式，实际是针对当前页重新实例化了一个新的对象，故DataHandler指定的方法务必需要在当前页中声明，并且该方法必须是public的。

DataHandler中无论如何不要访问Page中的任何数据或控件值，这是没有意义的，如果需要传参，请使用DefaultSearch或初始化时的ExtParam进行参数传递。

再次强调，同Ajax一样，表格获取数据的请求是完全异步的，页面本身的处理逻辑和数据请求是2次不同的请求，他们之间没有上下文的关系。

3 绑定列的展现模板

InitConfig初始化时针对列配置增加了一个itemTemplate属性，该属性提供了当前列的展现模板设定，您可以在该属性中提供几乎任何Html内容（当然，请保证不会破坏表格结构），使用简单的模板语法“[@字段名]”来展现您所希望的格式，比如说：

“<input id=’ [@Guid]’ type=’text’ value=’[@String1]’ />”

上述语法将在指定的列展现一个以该行的Guid字段的值给出的Id的文本框，该文本框将展示String1字段的值。

8、 已知BUG