jQuery DataTables options 记录

参考文档:DataTables reference page

简介

columns 是一个数组,用于指定DataTables包含的列的定义,每项包含的属性包括:

columns.data: 用于指定字段名,可能的值包括:

  • undefined: 当指定为undefined时,将会使用columns.defaultContent代替; 如果没有指定columns.defaultContent, dataTables 会报错;
  • null: 当指定为null时,如果columns.render有被定义,传递给rendering function的数据将是原始数据源的当前行的所有数据;如果没有renderer, columns.defaultContent 将会起作用;如果没有指定defaultContent,显示数据将会是空字符串。null 可用于所有其他的数据类型。
  • function: 如果指定为一个函数时,函数会被执行,返回值将作为显示内容。在DataTables 1.10.1中,这个函数会在和当前行的数据对象相同的作用域内执行。

data属性是一个可以设置和读取的选项。如果你只是需要格式化数据输出,columns.render 选项会更好,因为它是只读的,并且使用起来更加简单。

DataTables 1.10.3 以后,data 选项可以和一个DOM 数据源一起使用,指示DataTables为DOM数据源对象中的每列的数据应该存到哪里。默认情况下,DataTables 将把这些数据存在一个数组里。但是使用这一选项,你可以提供对象属性名来描述使用的对象的结构。

data属性可以使用的类型

integer:

指定数据源中的数组索引。这是DataTables默认使用的值(每列递增)。

string:

读和写的对象时数据源的一个对象属性。有3种特殊的选项值可用来改变DataTables从数据源对象中读取数据的方式:

. – Dotted Javascript notation. 就像你在Javascript中使用 . 读取嵌套对象一样,这也可以在data属性中使用。例如:browser.version 或是 browser.name。如果对象参数名中包含 .,使用\\ 转义,如first\\.name。

[] – Array notation. DataTables 能够自动合并数组数据源的数据,使用提供的字符合并在中括号之间的数据。比如:name[, ] 将生成一个来自原数组的,以逗号分隔的序列。如果中括号之间没有指定字符, 将会返回原始数组的数据。

() – Function notation. 在参数结尾添加() 将会执行给定名称的函数。如:browser() 是在数据源上执行的一个简单函数;browser.version() 是一个嵌套属性上的函数,甚至 browser().version 是从函数返回值中获取一个对象属性。推荐在render 中使用function notation而不是在data中,因为它作为renderer使用起来更简单。

null:

直接使用当前行的原始数据源, 而不是中原始数据源中摘取。这一动作会对其他两个初始化选项有影响:

columns.defaultContent : 当data选项值为null 并且当前列的defaultContent有指定时,当前单元格将使用defaultContent中定义的值。

columns.render: 当data选项值为null 并且render 选项有指定时,当前行的整个数据源将被renderer使用。

object:

对DataTables请求的不同数据类型使用不同的数据(filter, display, type, sort)。 对象的属性名是属性执行的数据类型,并且属性值可以使用integer, string 或是函数来定义,columns.data的规则同样适用。注意 必须指定 _ 选项。这是默认值,如果你没有指定DataTables 请求的数据类型。如:

"data":{
    "_": "phone",
    "filter": "phone_filter",
    "display": "phone_display"
}

function data(row, type, set, meta)

当DataTables 需要读取或是这种单元格的值的时候,给定的函数将被执行。

该函数可能会被调用多次,因为DataTables 会为它需要的不同的数据类型调用该函数 – sorting, filtering 和 display.

参数定义:

 NameTypeOptionalDescription
1rowarray,objectNoThe data for the whole row2typestringNoThe data type requested for the cell3setAnyNoValue to set if the type parameter is set. Otherwise, undefined.4metaobjectNoSince 1.10.1: An object that contains additional information about the cell being requested. This object contains the following properties:row – The row index for the requested cell.col – The column index for the requested cell.settings – The DataTables.Settings object for the table in question. This can be used to obtain an API instance if required.

当调用类型是set的时候,函数返回值不是必须的,但是其他情况下返回值被用于请求的数据。

Default

自动使用列的索引值。

示例

从对象中读取表数据:

// JSON structure for each row in this example:
//   {
//      "engine": {value},
//      "browser": {value},
//      "platform": {value},
//      "version": {value},
//      "grade": {value}
//   }
$('#example').dataTable( {
  "ajaxSource": "sources/objects.txt",
  "columns": [
    { "data": "engine" },
    { "data": "browser" },
    { "data": "platform" },
    { "data": "version" },
    { "data": "grade" }
  ]
} );

从深度嵌套对象中读取信息:

// JSON structure for each row:
//   {
//      "engine": {value},
//      "browser": {value},
//      "platform": {
//         "inner": {value}
//      },
//      "details": [
//         {value}, {value}
//      ]
//   }
$('#example').dataTable( {
  "ajaxSource": "sources/deep.txt",
  "columns": [
    { "data": "engine" },
    { "data": "browser" },
    { "data": "platform.inner" },
    { "data": "platform.details.0" },
    { "data": "platform.details.1" }
  ]
} );

把DOM 数据表读取到数据对象中:

$(document).ready(function() {
    $('#example').DataTable({
        "columns": [
            { "data": "name" },
            { "data": "position" },
            { "data": "office" },
            { "data": "age" },
            { "data": "start_date" },
            { "data": "salary" }
        ]
    });
} );

使用函数data 对sorting, filtering 和displaying 提供不同的信息:

$('#example').dataTable( {
  "columnDefs": [ {
    "targets": 0,
    "data": function ( row, type, val, meta ) {
      if (type === 'set') {
        row.price = val;
        // Store the computed display and filter values for efficiency
        row.price_display = val=="" ? "" : "$"+numberFormat(val);
        row.price_filter  = val=="" ? "" : "$"+numberFormat(val)+" "+val;
        return;
      }
      else if (type === 'display') {
        return row.price_display;
      }
      else if (type === 'filter') {
        return row.price_filter;
      }
      // 'sort', 'type' and undefined all just use the integer
      return row.price;
    }
  } ]
} );

使用默认内容:

$('#example').dataTable( {
  "columnDefs": [ {
    "targets": [ 0 ],
    "data": null,
    "defaultContent": "Click to edit"
  } ]
} );

使用array notation – 从数组中输出一个序列:

$('#example').dataTable( {
  "columnDefs": [ {
    "targets": [ 0 ],
    "data": "name[, ]"
  } ]
} );

 jsbin示例: http://jsbin.com/yeqevu/edit?html,js,output

该文翻译DataTables 官方文档,仅作记录复习只用。

相关推荐