jQuery DataTables options 记录

Posted 2020-09-17 learning dotnet

参考文档：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.

参数定义：

	Name	Type	Optional	Description
1	row	array,object	No	The data for the whole row
2	type	string	No	The data type requested for the cell
3	set	Any	No	Value to set if the type parameter is set. Otherwise, undefined.
4	meta	object	No	Since 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[, ]"
  } ]
} );

 

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