jquery plug-in DataTable API中文文档参考

前言：最近在做一个WEB后台，无意中发现这个插件，试用了一下觉得不错，但网上关于它的资料大多不全，所以利用一些时间将其API文档翻了一下，发在园子里供大家参考。（p.s:个人E文水平很差，对着灵格斯翻出来，肯定有很多不对的地方，欢迎指正，但请勿喷。）

构造函数：

默认带一个可选参数，该参数为一个对象，可配置项在DataTable.defaults命名空间中定义。

 

方法和参数说明：

一、静态属性

方法或属性名	参数说明	返回值类型	功能描述	应用示例
version	无	string	主要供插件开发者使用，用于检测兼容性。其输出格式为：a.b.c.d.e。其中abc均为整数，d为描述字符串（dev或beta），e也是一个整数，d和e为可选项。	$.fn.dataTable.version

二、实例方法

方法或属性名	参数说明	返回值类型	功能描述	应用示例
$(sSelector, oOpts)	1、sSelector(字符串或节点名或jquery选择字符串)，指定要选取的行 2、oOpts(js对象，可选），对选择器的范围进行再限制，即sSelector只在这个对象规定的范围中选取。有三个可选参数： （1）filter（应用过滤）：字符串，默认值为“none"，即不应用。只在被当前应用在table中的过滤器过滤以后的行中选择，如果当前table没有应用过滤器，即使设置了filter:"applied"也会在所有行中查找。 （2）order：字符串，默认值为”current"。这个参数默认影响返回数组中TR元素的排序。"current"表示按照表当前正在使用的索引列进行排序，"original"表示按照表最初读取数据时使用的索引列进行排序。 （3）page：限制选择是否仅限于当前显示的页面。"current"表示仅限于当前页，"all"表示所有页。如果此项被设置为"current"，则order会被假设为"current",filter为"applied"，也就是说即使手动给这两个参数设置了不同的值也会被忽略。	jquery对象	使用一个jquery选择器从表的TR(包含在tbody中的TR)元素中查找符合条件的行的集合（jquery对象）	oTable.$('tr:odd').css('backgroundColor', 'blue'); oTable.$('tr:odd', { order: "current",page:"current" }).css('backgroundColor', 'blue');
_(sSelector, oOpts)	同上	匹配元素中包含的数据，如果选择器匹配元素包含非TR、TD或者TH元素，则返回数组对应位置会是一个空条目。	使用方式基本同上面的$一样，但它返回的是所有匹配行的数据--也就是说，sSelector的匹配目标应该是TR行或者是TD/TH单元格而不是其它的元素，因为只有这些行/单元格才包含数据。如果找到匹配的行，返回的数据将是生成该行的原始数据（数组或对象），如果原始数据源来自于DOM，则返回一个通用数组。 这个方法通常和$方法一起配合使用，通过向两个方法给定同样的参数，可以保证返回数组中（行集合/数组）索引能够互相匹配。 注：按照说明的意思，这个方法应该可以获取单元格的数据，但实际通过测试只能获取首行的单元格数据，像"tr:eq(2) td:eq(1)"这样的选择器返回的是undefined
fnAddData(mData, bRedraw)	1、mData:数组或者对象，必选项。表示要添加到表中的数据，可以是以下四种类型之一： （1）一维数据数组，表示单行 （2）2维数据数组，表示多行 （3）单个对象，和初始化时定义的mData相对应的数据对象，表示单行 （4）对象数组，同上，表示多行 2、bRedraw：布尔值，可选，默认true，指示是否立即重绘表格。	一个整数数组，表示各条新增数据在内置的aoData数组中的索引位置。	向表中添加一行或多行数据，注意这个方法仅对处理客户端数据有效（数据来自于客户端脚本对象、数组或DOM，或者初始化时指定了sAjaxSource但没有指定"bServerSide": true），如果数据源指定的是“经过服务端处理”（初始化时指定了"bServerSide": true）的话，要向表中添加新数据，需要先调用一个Ajax方法将数据添加到数据源中，也就是服务端，再由服务端将数据返回给表。	oTable.fnAddData([[16, "张三", 55, "男", "1982/12/1"], [54, "李四", 55, "男", "1982/12/1"], [88, "王五", 55, "男", "1982/12/1"]]);
fnAdjustColumnSizing(bRedraw)	1、Bredraw:布尔值，可选，默认true，表示是否重绘表。	无	调用这个方法会使得DataTable根据所包含的数据长度和开发者给列指定的长度（样式表、DOM中直接指定、或者初始化时指定了sWidth参数）重新计算列宽，并调整表格的显示，这个方法在表的父容器大小发生变化时相当有用（比如浏览器窗口大小变化）。	oTable.fnAdjustColumnSizing();
fnClearTable(bRedraw)	1、bRedraw:布尔值，可选，默认为true，表示是否立即重绘表格。	无	快速、直接的清除表中所有数据行。如果bRedraw为false，屏幕显示不会发生变化，但像$、_方法已经取不到值了。	oTable.fnClearTable(false);
fnClose(nTr)	1、nTr，html node(也就是TR)，代表要被“close”的行。	成功返回0，失败返回1（未找到匹配的行）	只针对状态为“open"的行，功能是关闭当前状态为“open"的行。	$('#example tbody tr').click( function () {     if ( oTable.fnIsOpen(this) ) {       oTable.fnClose( this );     } else {       oTable.fnOpen( this, "Temporary row opened", "info_row" );     }   } );
fnDeleteRow(mTarget, fnCallBack, bRedraw)	1、mTarget:混合型，可以是被删除行在aoData中的索引，也可以是要删除的TR元素（用jqury选择器表示）。 2、fnCallBack：函数或者null，可选，回调函数。删除动作开始时调用，传递给此函数的参数有两个，第一个是一个包含当前表所有初始化信息的对象，第二个是将要被删除行的数据数组。 3、bRedraw:布尔值，可选，默认true。是否重绘表格。	被删除的行。	删除表中某行。	oTable.fnDeleteRow( 0 );
fnDestroy(bRemove)	1、bRemove:布尔值，可选，默认false。表示是否完全删除该表。如果为true，则连原始DOM也会被删除。	无	将表恢复为原始定义的html DOM结构，移除应用到table上的样式和事件监听。	oTable.fnDestroy();
fnDraw(bComplete)	1、bComplete:布尔值，可选，默认true。表示在重绘之前是否对表进行重新过滤和重新排序。	无	重绘表。	oTable.fnDraw();
fnFilter(sInput, iColumn, bRegex, bSmart, bShowGlobal, bCaseInsensitive)	1、sInput:字符串，必选，指定要过滤显示的某列数据的全部或一部分。 2、iColumn，整数或null，可选，指定sInput要匹配的列，从0开始。 3、bRegex,布尔值，可选，默认为false，是否将sInput视为正则表达式。 4、bSmart,布尔值，可选，默认为true，是否开启智能搜索。（这个API说明有点坑，也没有示例，通过研究跟踪源码才搞明白，如果为true，则如果sInput包含有空格字符，则会以空格为界将其拆分为数组，搜索同时包含数组中每个字符串的行，对应数据可以是一列的内容，也可以不在一列中，如果为false，则将空格视为欲搜索字符） 5、bShowGlobal:布尔值，可选，默认true，是否在表附带的搜索输入框中显示sInput的内容。 6、bCaseInsensitive:布尔值，可选，默认true，是否不区分大小写	无	对表中数据进行过滤。
fnGetData(mRow, iCol)	1、mRow:整数或tr/td/th节点。可选，如果指定一个tr节点则从数据源返回整行的数据，如果指定的是td/th则返回相应单元格中的数据。如果是一个整数，会把这个整数视内部数组aoData的索引，返回对应的数据。 2、iCol：整数，可选，指定列序号。	如果无参调用，则返回全表数据；指定了mRow，返回对应行的数据；指定了iCol，返回对应单元格的数据。	获取表的全部数据，如果指定了行和列则返回对应行或列的数据
fnGetNodes(iRow)	1、iRow：整数，可选，指定要获取行在表中的序号。这个序号不是显示出来的行序，而数据在aoData中的序号。	无参调用返回包含所有TR元素的数组，指定了iRow，只返回对应行的TR。	获取一个body中包含的TR节点元素数组。
fnGetPosition(nNode)	1、nNdoe：node，可以是body中的TR、TD、TH元素。	如果nNode是TR，则返回该行在表中的显示序号，即使顺序发生了变化，它返回的还是最初的序号；如果nNode是单元格，返回一个数组：[行序，可见列序，全部列序]。	返回特定单元格在表中的显示位置，以数字表示，从0开始，详见返回值说明。
fnIsOpen(nTr)	1、nNode：node，要检查的行（html dom)。	当前行状态为open，则返回true，否则返回false。	检查行的状态是否为open。
fnOpen(nTr, mHtml, sClass)	1、nTr：node，被打开（open）的行。 2、mHtml：string\node\jquery，打开行后添加的html内容。 3、sClass：string，设置新添加的单元格的样式（因为它实际生成的是一个新行，包含一个td来放置mHtml的内容）	打开后的添加的新行，如果未找到匹配行，返回undefined。	在当前页面指定行下面添加一个新行并显示指定的mHtml内容。
fnPageChange(mAction, bRedraw)	1、mAction：string/int。可取值为：“first","previous","next","last"，或者是要跳转到的页码，注意0代表第1页。 2、bRedraw：bool，可选，默认true，是否重绘表格。	无	翻页。
fnSetColumnVis(iCol, bShow, bRedraw)	1、iCol：int，被显示或隐藏的列序号，从0开始。 2、bShow：bool，true为显示，false为隐藏。 3、bRedraw：bool，可选，默认为true，是否重绘。	无	显示或隐藏指定列。
fnSettings()	无	指定表的配置对象	获取指定表的配置对象。
fnSort(iCol)	1、iCol：int，列索引。	无	按照指定列对表进行排序。
fnSortListener(nNode, iColumn, fnCallback)	1、nNode：node,要添加监听程序的元素 2、iColumn：int,指定的索引列 3、fnCallback：function，可选，回调函数	无	给某个元素添加对应特定列的监听处理程序。（这个方法暂时还没有理解）
fnUpdate(mData, mRow, iColumn, bRedraw, bAction)	1、mData：object/array/string，更新数据 2、mRow：node/int，被更新的TR元素或数组在aoData中索引。 3、iColumn：int，可选，要更新的列。和mRow一起即可确定单元格位置。 4、bRedraw：bool，可选，默认true，是否重绘表格。 5、bAction：bool，可选，默认true，是否执行预重绘动作。	成功返回0，错误返回1	更新表行或单元格数据，该方法既可以接受单一值，也可以接受数组或对象
fnVersionCheck(sVersion)	1、sVersion：string，版本号，可以是X.Y.Z格式，也可以接受X或X.Y格式。	大于等于指定版本号返回true，否则返回false。	对比当前DataTable的版本号。

 

三、静态方法

 

方法或属性名	参数说明	返回值类型	功能描述	应用示例
fnIsDataTable(nTable)	nTable，node，被检查的table元素。	是DataTable表返回true，否则返回false.	检查指定指定table元素是否为DataTable表。
fnTables(bVisible)	bVisible:bool，可选，默认false，是否包含被隐藏表。	table node数组（注意不是DataTable实例）	获取所有已经初始化的DataTable表。
fnVersionCheck(sVersion)			同实例方法。

 

四、事件

 

事件名称	传入参数	描述
destroy	1、e，event,jquery事件对象 2、o:object，DataTable设置对象	DataTable销毁事件，调用fnDestroy时触发。
draw	同上	页面中表重绘时触发。也可以给fnDrawCallback指定回调函数来绑定此事件。
filter	同上	应用到表的过滤条件发生改变时触发。
init	1、2同上 3、json,对象，从服务端获取的JSON对象。	DataTable初始化完成事件，当表完成渲染、装载数据后触发。
page	1、2同上	页面改变事件，当表的当前分页发生变化是触发
processing	1、2同上 3、bShow:boolean，DataTable是否正在执行动作标记	正在处理事件，（未测试成功，以下内容为个人理解），当DataTalbe执行一些比较耗时的动作时触发（如排序、过滤）。可以用来通知用户DataTable正在执行某个动作，或者某个操作已经完成。
sort	1、2同上	排序事件，表的排序条件发生变化时触发。
stateLoaded	1、2同上 3、json：object，保存在客户端的状态信息。	状态载入完成事件。当状态信息已经从本地存储中载入同时配置对象内容也按照载入数据修改完成时触发。
stateLoadParams	同上	状态载入时事件。当状态信息已经从本地存储中载入但配置对象内容还未按照载入数据修改时触发。
stateSaveParams	1、2同上 3、json：object，将要被保存的状态信息。	状态保存事件，当表的状态发生变化，需要重新保存状态信息时触发。
xhr	1、2同上 3、json：object，从服务端返回的JSON对象。	Ajax事件，当一个服务端Ajax请求完成时触发（注意，这个事件处理程序由fnServerData调用，如果改写了fnServerData，需要在你自己的success函数中手动触发这个事件）。