jqGrid中文文档.doc

1、jqGrid 3.6.2 中文文档安装jqGrid（1） 收藏 在你开始之前在你开始jqGrid之前，你需要具有基本的JavaScript和jQuery知识。有关jQuery的知识可访问jQuery网站。当你已有了这些基础知识后，我们从jqGrid的系统需求开始。系统需求基本需求： 浏览器（Mozilla FireFox、Safari、Google Chrome、Opera、Microsoft Internet Explorer） jQuery库v1.3及以上（） jQuery UI主题（/themeroller/#themeGallery） jqGrid插件（/blog/?page_id=6） 本地（静态）数据（如数组数据、XML数据文件或JSON数据文件）jqGrid主要是为了操作和呈现服务器上的动态数据，因此，你还需要一个web服务器（如IIS、Apache、Tomcat），一个数据库（如PostgreSQL、Oracle、MSSQL、MySQL）和服务器端脚本语言（如PHP、ASP）下载jqGrid你可以通过jqGrid网站的jqGrid下载生成器选择你需要的组件，生成适合你要求的jqGrid副本后下载。 选择你需要的组件下载生成器列出了所有组件：base，editing，subgrid，treegrid，import/export 和user contributed modules。你选择的组件将合并为一个javascript文件jquery.jqGrid.min.js。选择完成后，点击Download按钮，你将得到包含你所选内容的压缩文件。下载后下载后的压缩文件包括以下文件： /css/ui-jqgrid.css/js/i18n/grid.locale-bg.js所有语言文件.Changes.txtjquery-1.3.2.min.jsjquery.jqGrid.min.js/src/i18n/grid.locale-bg.js所有语言文件./css/jquery.searchFmon.jsgrid.custom.jsgrid.formedit.jsgrid.import.jsgrid.inlinedit.jsgrid.loader.jsgrid.postext.jsgrid.setcolumns.jsgrid.subgrid.jsgrid.tbltogrid.jsgrid.treegrid.jsjqDnR.jsjqModal.jsjquery.fmatter.jsjquery.searchFilter.jsjson2.jsJsonXml.js从文件结构上看，jqGrid需要的文件在 /css/ 和 /js/ 目录中，这些文件已被简化用于运行环境。此包中还包含了基本jQuery库，你不需要再去下载jQuery库。/src/目录中的文件为源代码，供开发人员修改和改进，为了不使用基本版本，需使用grid.loader.js ，参见“安装”下载UI主题从jqGrid 3.5版开始，jqGrid 完全兼容UI主题。为此，你需要下载所需的主题。主题可从jQuery UI站点/themeroller/中下载，你也可以创建你自己的主题，详细信息请访问。如果你只使用表格组件，只需使用基本的CSS文件ui.theme.css和ui.core.css（位于UI主题包的development-bundle/themes目录中）。有了所有需要的文件后，你就可以安装了。更新日志（略）这部分介绍了新版本修改的错误和增加的功能安装这节介绍安装步骤和技巧。假设你机器上已安装了一个web服务器。基本安装 解压jqGrid和UI主题压缩文件到一个临时文件夹中； 在web服务器上创建可访问的项目目录（如myproject）； 在myproject目录下创建js 和css两个目录； 将jqGrid包中css目录(非src/css)下的ui-jqgrid.css复制到myproject的css目录下； 将jqGrid包中js目录下的所有目录和文件复制到myproject的js目录下； 将UI主题包中css目录下的所有目录和文件复制到myproject的css目录下；以上操作后，你服务器中的目录结构应该是：/myproject/css/ui.jqgrid.css/ui-lightness/images/jquery-ui-1.7.2.custom.css/myproject/js/i18n/grid.locale-bg.js所有语言文件.Changes.txtjquery-1.3.2.min.jsjquery.jqGrid.min.js使用你喜欢的编辑器在myproject 目录下创建myfirstgrid.html 文件，输入以下代码：view plaincopy to clipboardprint?1. 3. 4. 5. 6. MyFirstGrid7. 9. 10. 11. 12. 13. 14. 15. 至此，你已构建了你的第一个jqGrid。开发安装目录结构与前面相同，将jqGrid包中的整个src 目录复制到js目录下。结构如下：/myproject/css/ui-jqgrid.css/ui-lightness/images/jquery-ui-1.7.2.custom.css/myproject/js/src/i18n/grid.locale-bg.js所有语言文件./css/ui-jqgrid.cssjquery.searchFmon.jsgrid.custom.jsgrid.formedit.jsgrid.import.jsgrid.inlinedit.jsgrid.loader.jsgrid.postext.jsgrid.setcolumns.jsgrid.subgrid.jsgrid.tbltogrid.jsgrid.treegrid.jsjqDnR.jsjqModal.jsjquery.fmatter.jsjquery.searchFilter.jsjson2.jsJsonXml.jsjquery-1.3.2.min.js打开grid.loader.js文件，修改pathtojsfiles为js/src/，代码如下：view plaincopy to clipboardprint?1. functionjqGridInclude()2. varpathtojsfiles=js/src/;/需要修改的地方3. /如果不需要某些模块，将include设为false4. varmodules=5. include:true,incfile:i18n/grid.locale-en.js,/jqGridtranslation6. include:true,incfile:grid.base.js,/jqGridbase7. include:true,incfile:mon.js,/jqGridcommonforediting8. include:true,incfile:grid.formedit.js,/jqGridFormediting9. include:true,incfile:grid.inlinedit.js,/jqGridinlineediting10. include:true,incfile:grid.celledit.js,/jqGridcellediting11. include:true,incfile:grid.subgrid.js,/jqGridsubgrid12. include:true,incfile:grid.treegrid.js,/jqGridtreegrid13. include:true,incfile:grid.custom.js,/jqGridcustom14. include:true,incfile:grid.postext.js,/jqGridpostext15. include:true,incfile:grid.tbltogrid.js,/jqGridtabletogrid16. include:true,incfile:grid.setcolumns.js,/jqGridsetcolumns17. include:true,incfile:grid.import.js,/jqGridimport18. include:true,incfile:jquery.fmatter.js,/jqGridformater19. include:true,incfile:JsonXml.js,/xmljsonutils20. include:true,incfile:jquery.searchFilter.js/searchPlugin21. ;22. varfilename;23. for(vari=0;imodules.length;i+)24. if(modulesi.include=true)25. filename=pathtojsfiles+modulesi.incfile;26. if(jQuery.browser.safari)27. jQuery.ajax(url:filename,dataType:script,28. async:false,cache:true);29. else30. IncludeJavaScript(filename);31. 32. 33. 34. functionIncludeJavaScript(jsFile)35. varoHead=document.getElementsByTagName(head)0;36. varoScript=document.createElement(script);37. oScript.type=text/javascript;38. oScript.charset=utf-8;39. oScript.src=jsFile;40. oHead.appendChild(oScript);41. ;42. ;43. jqGridInclude();你的HTML文件如下view plaincopy to clipboardprint?1. 3. 4. 5. 6. MyFirstGrid7. 9. 10. 12. html,bodymargin:0;padding:0;font-size:75%;15. 16. 17. 18. 19. 20. 至此，你已准备好调试和改进jqGrid。如何使用了解本节将帮助你更好地使用jqGrid和组件的全部功能。我们首先必须知道我们有两个部分： 服务器端操作和客户端呈现。换句话说：jqGrid是一个组件，使我们能用简单的方法在客户端使用服务器端技术呈现数据库信息并将对数据的操作返回给数据库。 什么是服务器端操作（SSM）?可能有很多定义，我试图从jqGrid角度来解释。基本的SSM的意思是服务器端的编辑处理而不是用户浏览器。SSM不是在页面上可见的。一切都是在服务器上用一些通用的编程语言做的。基本上它是服务器上的命令，告诉服务器一旦用户调用，把文件或文本放置到页面上。从jqGrid角度你应该关心的是：你必须有一段代码使用脚本语言和web服务器来处理存储在数据库中信息。使用这段代码你应能返回请求的信息给客户（web浏览器）。 jqGrid使用Ajax请求取得请求的信息并使用JavaScript处理给客户。 有了需要的信息，你可通过列模型（colModel）描述jqGrid要构造的表格数据。客户端要构造的表格数据有：Caption layer（标题区）Header layer（表头区）Body layer（表体区）Navigation layer（导航区）Caption layer包含表格的公共信息。Header layer包含列信息：标签，宽度等。Body layer 是从服务器取得的数据并按列模式定义显示。Navigation layer 包含得到的其他信息和请求片段信息的分页。navigation layer不仅可以放置在表格的底部，而且可放置在页面的任何地方。Navigation layer还是添加编辑、删除新增按钮或链接和搜索表格数据的地方。表格至少包括Header layer和Body layer. 为允许自由和灵活性，以及较好的样式， jqGrid依靠CSS管理它的外观。 2、jqGrid 3.6.2 中文文档安装jqGrid（2） 收藏 我的第一个表格作为本教程一个例子将提供整个文档，我们将创建一个有关发票信息的表格。首先我们需要定义在客户端显示数据： Invid发票号码Invdate发票日期amount发票金额tax税total金额总数（含税）note备注数据我们需要以下格式的表格（本例基于MySQL），可按以下方式创建： view plaincopy to clipboardprint?1. CREATETABLEinvheader(2. invidint(11)NOTNULLAUTO_INCREMENT,3. invdatedateNOTNULL,4. client_idint(11)NOTNULL,5. amountdecimal(10,2)NOTNULLDEFAULT0.00,6. taxdecimal(10,2)NOTNULLDEFAULT0.00,7. totaldecimal(10,2)NOTNULLDEFAULT0.00,8. notechar(100)DEFAULTNULL,9. PRIMARYKEY(invid);然后输入数据。HTML 文件使用我们安装时建立的文件myfirstgrid.htmlview plaincopy to clipboardprint?1. 3. 4. 5. 6. MyFirstGrid7. 9. 10. html,bodymargin:0;padding:0;font-size:75%;13. 14. 15. 16. 40. 41. 42. 43. 44. 45. 在标记间定义表格的位置。view plaincopy to clipboardprint?1. 2. 3. 4. 5. 6. 通过HTML的定义表格，在html文档中给这个表格一个独特的ID号。表格的Cellspacing, cellpadding和border属性由jqGrid给定，不需要在中给出。我们还需要分页操作，所以我们使用常用的标记定义了导航条，将navigator 的scroll指定为我们需要的jqGrid提供的CSS。导航条可以放在文档的任何地方，通常放在表格下方。In the current implementation the pager is placed above the grid in all situations instead that they can be somewhere in the html document. 我们可以在适当的位置使用jQuery document.ready 运行我们的脚本。更多信息见jQuery文档。构建表格的语法是：jQuery(#grid_selector).jqGrid( options )这里grid_selector为表格的ID号，jqGrid是插件名称，options是构造表格数组，如下：view plaincopy to clipboardprint?1. 2. url:example.php,3. datatype:xml,4. mtype:GET,5. colNames:InvNo,Date,Amount,Tax,Total,Notes,6. colModel:7. name:invid,index:invid,width:55,8. name:invdate,index:invdate,width:90,9. name:amount,index:amount,width:80,align:right,10. name:tax,index:tax,width:80,align:right,11. name:total,index:total,width:80,align:right,12. name:note,index:note,width:150,sortable:false,13. pager:jQuery(#pager),14. rowNum:10,15. rowList:10,20,30,16. sortname:invid,17. sortorder:desc,18. viewrecords:true,19. caption:Myfirstgrid20. 使用和设置上述参数的方法见下表，所有的设置项见API Methods和colModel API. 属性 描述url 这里告诉我们从哪里得到数据。通常这是个服务器端的文件，该文件链接数据库并返回适当的数据，用来填充表格。datatype 这里告诉从服务器返回用与构建表格的数据的类型。例子中告诉表格服务器返回的数据时XML数据。当然可以是其他数据，见API Methods mtype 这里告诉如何调用ajax：GET或POST。例子中我们使用GET从服务器端返回数据colNames 这是一个定义列名的数组。定义表头的文本，以逗号分隔。 colModel 这是列模型数组。这是表格最重要的部分。在此只解释例子中的项目，全部的信息见colModel API.Name为列名。此列名不必是数据库的列名，后面我们将看到如何对应数据；Index传递给服务器如何排序（可用列号代替）。通常是服务器端用于排序的数据表列名（列表）；Width列宽（pixels）；align列的对齐方式；sortable 决定此列是否允许排序，若为false，点击此列表头将不起作用。pager定义数据浏览导航分页条。这必须是一个有效的html元素；在例子中，我们定义的是id为pager的div元素。导航层可以放在任何地方。rowNum设置表格中显示多少条记录。此参数通过url出递给服务器用于返回数据。rowList用于构造select框选项的数组。此select框在分页条中，用于客户选择表格显示记录的条数。当改变后，此参数将替换url中的rowNum参数。sortname设置初始排序列。可以是列名或列号。此参数通过url供服务器使用。viewrecords定义是否在分页条上显示得到的记录总条数。caption设置挑个标题。如此参数不设置，标题条将不显示。至此，我们已完成了一半的工作，接下来我们要建立url定义的服务器端文件。服务器端文件jqGrid可构建多种格式数据的表格，缺省为以下结构的xml数据，让我们来看看如何使用其他结构的xml数据和其他形式的数据。缺省的XML数据结构：标记的解释如下：标记描述 rows表格的根标记page获得的页号total获得的总页数records获得的总记录数row表格的制定行cell实际数据。可以使用CDATA，这样我们可以加入图片、链接和选择框。每个row中的cell标记的数量必须等于colModel中定义的列数量。以上的例子中，我们定义了6列，所以每个row标记下cell的数量为6。 注意标记的id属性。如果每行需要唯一的id，最好不要省略此参数。如果省略了此参数，jqGrid有两种方法获得唯一的id：若colModel中某列的key设置为true，该列的值被作为行的id；否则，以行的顺序为行的id。if you are using a content-free primary key to identify your data rows, then do not include this value in the grid as a visible cell; instead, include it in the query and pass it as the row id attribute. It will always be available for jqGrid and even jQuery operations but not be visible on the page. 现在建立文件（以PHP 和MySQL为例）全部完成。将此文件以.php保存到myproject 目录下。二、BasicGrid一个实例jqGrid是一个带有属性，事件和方法JavaScript对象。属性可以是字符串，数字，数组，布尔值，甚至其他对象。JavaScript代码jQuery(#grid_id).jqGrid(options);HTML代码其中：grid_id是HTML中表格的id。options是“名称：值”对格式的设置数组。有些设置是值，有些是事件的响应函数，有些是jqGrid工作必须的选项。从XML文件中读取数据的例子：jQuery(document).ready(function() jQuery(#list).jqGrid( url:example.php, datatype: xml, mtype: GET, colNames:Inv No,Date, Amount,Tax,Total,Notes, colModel : name:invid, index:invid, width:55, name:invdate, index:invdate, width:90, name:amount, index:amount, width:80, align:right, name:tax, index:tax, width:80, align:right, name:total, index:total, width:80, align:right, name:note, index:note, width:150, sortable:false , pager: #pager, rowNum:10, rowList:10,20,30, sortname: invid, sortorder: desc, viewrecords: true, caption: My first grid ); ); 从json中读取数据的例子：jQuery(document).ready(function() jQuery(#grid).jqGrid( url:/jqGridModel?model=Wine, datatype: json, mtype: GET, colNames:id, Provider, Name, Year, Description, Type, Geographical Region, Creation Date, Edit Date, colModel: name:id,index:id, width:55, sortable:false, editable:false, editoptions:readonly:true,size:10, name:provider,index:provider, width:200,editable:false, name:name,index:name, width:200,editable:true, name:year,index:year, width:100,editable:true, name:description,index:description, width:300,editable:true, name:type,index:type, width:200, editable:true, edittype:select, editoptions:dataUrl: /jqGridOptionData?entity=WineType, name:geographical_region,index:geographical_region, width:200,editable:true, name:creationDate,index:creationDate, width:100, name:editDate,index:editDate, width:100, , jsonReader : repeatitems:false , rowNum:10, rowList:10,20,30, pager: jQuery(#gridpager), sortname: name, viewrecords: true, sortorder: asc, caption:Wines, editurl:/jqGridModel?model=Wine ).navGrid(#gridpager););HTML代码： 当创建网格，通常是几个属性相同的语句集（尽管这些属性可以在以后单独重写），见Options。事件由表格激发，用于执行附加的操作，具体表述见Events。表格还提供了用于获取或设置属性忽而或数据的属性，见Methods。网格的一个关键属性是列模式（colModel），它定义网格的内容：见colModel。Options（选项）属性类型描述缺省值运行时ajaxGridOptionsobject此项用于设置当表格设置获得数据时，ajax的全局属性，注意此项可能覆盖所有当前的ajax设置（包括error, complete和beforeSend 事件）。empty可写ajaxSelectOptionsobject此项用于设置在editoptions或searchoptions对象中通过dataUrl选择元素时， ajax的全局属性。empty 可写altclassstring交替行的类。 此项仅当altRows设置为true时有效。ui-priority-secondary可写altRowsboolean设置为交替行表格false可写autoencodeboolean当设置为true时，对来自服务器的数据和提交数据进行encodes编码。如 将被转换为<false可写autowidthboolean当设置为true时，表格宽度将自动匹配到父元素的宽度。这个匹配只在表格建立时进行，为了使表格在父元素宽度变化时也随之变化，必须运用客户代码来设置setGridWidth属性false只读captionstring表格的标题。显示在Header上。若为空号将不会显示。emptycellLayoutinteger该属性确定单元格的padding + border 宽度。通常不修改该属性，但若表格的CSS中改变了td元素，该属性需要修改。 缺省值5表示paddingLef(2) + paddingRight(2) + borderLeft(1)=55只读cellEditboolean是否允许单元格编辑。更多信息参见Cell Editingfalse可写cellsubmitstring确定单元格内容保存方式是remote还是clientArray 。更多信息参见Cell Editingremote可写cellurlstring单元格保存的url。更多信息参见Cell Editingnull可写