【DataTable.js】02.DataTable参考

一、Option

1.1 Features

属性	类型	默认值	描述
autoWidth	boolean	true	是否自动调节单元格宽度，若传入了columns.width，可禁用该选项
ordering	boolean	true	是否支持排序
paging	boolean	true	是否支持分页
scrollX	boolean	false	是否支持横向滚动条
scrollY	string		启用垂直滚动。垂直滚动将限制DataTable到给定的高度，并允许滚动任何溢出当前视口的数据。这可以用作分页的替代方案，以便在一个小区域中显示大量数据。值可以是任意的CSS单位，也可以是一个数字，默认以像素(px)为单位。
searching	boolean	true	是否支持搜索

1.2 Data

1.2.1 ajax

使用此初始化参数，数据表可以从多个源(包括Ajax数据源)获取要在表主体中显示的数据。与其他动态数据源一样，可以将数组或对象用于每行(含列)的数据源。用于从特定对象属性中读取的数据。

ajax属性有3种表达方式

• string：设置请求的URL
• object：继承jQuery.ajax的所有属性
• function：自定义函数，用于获取数据

注意，从DataTables 1.10.6开始，当一个函数用于ajax时(即使没有ajax请求)，xhr事件将被触发。在1.10.6之前，不会触发任何事件。

1.2.2 ajax.dataSrc

ajax选项基本上继承了jQuery提供的所有选项。但是我们提供了额外的dataSrc选项，以提供更改datattables将从服务器返回的JSON中读取的数据的能力，或者将数据从一种形式操作到另一种形式(无论是JSON到另一种形式的JSON, XML, YAML等)。这样做是因为ajax的成功选项不应该被改变------DataTables在内部使用它来在数据加载完成时执行绘制表。

ajax.dataSrc可以有两种形式：

• string：作为一个字符串，dataSrc定义了数据源对象(即Ajax请求返回的)要读取的属性。注意，如果Ajax源只是返回要显示的数据数组，而不是对象，请将此参数设置为空字符串。此外，您可以使用Javascript点对象表示法来获取多个层次对象/数组嵌套的数据源。
• function：作为一个函数，dataSrc提供了将从服务器返回的数据从一种表单操作到另一种表单的能力。例如，如果您的数据分散在多个数组中，您可以将其组合成单个数组，以返回数据表进行处理和显示。在这种形式下，dataSrc可以用来转换任何数据源，如非json数据(XML、YAML等)到DataTables期望的Javascript数组。

作为一个字符串时，若返回的对象中包含data属性，则会直接获取data的信息。

示例：

$('#example').DataTable({
    ajax: {
        url: 'data.txt',
        dataSrc(json) {
            for(let i = 0, len = json.data.length; i < len; i++) {
                json.data[i][0] = '<a href="/message/'+json.data[i][0]+'">View message</a>'
            }
            return json.data
        }
    }
})

在这个案例中，我们可以通过dataSrc属性，对获取到的数据进行处理，该方法包含一个参数，ajax请求后的数据。

1.3 Callbacks

在表格的绘制过程中，DataTable提供一些回调函数，用于增强数据和样式的处理。

1.3.1 createdRow

当创建TR元素(并插入所有TD子元素)或使用DOM源注册TR元素时，执行此回调，从而允许对TR元素进行操作。

这在使用延迟呈现(deferRender)或服务器端处理(serverSide)时特别有用，因此您可以在创建行时添加事件、类名信息或以其他方式格式化行。

例如：

$('#example').DataTable({
    ajax: {
        url: 'data.txt',
    },
    createdRow(row, data, dataIndex, cells) {
        console.log('row:', row)
        console.log('data:', data)
        console.log('dataIndex:', dataIndex)
        console.log('cells:', cells)
        
        // 当行数为奇数时，为当前行增加important样式
        if(dataIndex % 2 == 0) {
            $(row).addClass('important')
        }
    }
})

通过控制台打印createdRow方法的参数，row可以获取当前行的element，data可以获取当前行的数据，dataIndex可以获取当前行的序号（从0开始），cells可以获取当前的单元格的element。根据这些参数我们就可以对行元素或者单元格进行增强。

1.3.2 drawCallback

对表的每个绘制事件采取操作可能很有用，例如，您可能希望使用新显示的数据更新外部控件，或者启用服务器端处理后，您可能希望将事件分配给新创建的元素。这个回调正是为这个目的而设计的，它将在每次提取时执行。

该方法提供一个参数settings，该参数是数据表将每个表的配置和数据存储在一个设置对象中。

就DataTables API而言，该对象的结构被认为是私有的，不支持对该对象中的值进行读写。

通过settings可以创建一个API对象，从而获取相关的数据。例如：

$('#example').DataTable({
    ajax: {
        url: 'data.txt',
    },
    drawCallback(settings) {
        let api = new $.fn.dataTable.Api(settings)
        // 获取当前页的行数据
        console.log(settings)
        console.log(api.row({ page: 'current' }).data())
    }
})

1.3.3 initComplete

了解表何时完全初始化、数据何时加载和绘制通常是有用的，特别是在使用ajax数据源时。在这种情况下，表将在加载数据之前完成初始运行(毕竟Ajax是异步的!)，因此提供这个回调是为了让您知道数据何时完全加载。

示例：

$('#example').DataTable({
    ajax: {
        url: 'data.txt',
    },
    initComplete(settings, json) {
        console.log(settings, json)
		// 当表格被渲染前，弹窗        
        alert( 'DataTables has finished its initialisation.' )
    }
})

1.3.4 preDrawCallback

作为drawCallback回调函数的伙伴，该函数在每次绘制表的开始时调用。因此，它可以用于在每次渲染之前更新或清理显示(例如删除事件)，并且还可以通过返回false来取消渲染。任何其他返回(包括未定义)将导致完全绘制。

$('#example').DataTable({
    ajax: {
        url: 'data.txt',
    },
    preDrawCallback(settings) {
        $('#example tbody').on('click', 'td', () => {
            alert('preDrawCallback')
        });
    }
})

若该函数的返回值为false，则表格不再渲染，例如：

$('#example').DataTable({
    ajax: {
        url: 'data.txt',
    },
    preDrawCallback(settings) {
        if($('#test').val() == 1) {
            return false
        }
    }
})

1.4 Options

1.4.1 destroy

像往常一样初始化一个新的数据表，但是如果有一个与选择器匹配的现有数据表，它将被销毁并替换为新表。如果您想要更改不能通过API更改的表的属性，这将非常有用。

注意，如果您不更改表的配置，而只是更改表显示的数据，那么使用ajax.reload()方法(或rows.add()等)要有效得多。

示例：

$('#example').dataTable( {
  "scrollY": "200px"
} );
 
// Some time later, recreate without (no scrolling)
$('#example').dataTable( {
  "destroy": true
} );

1.4.2 lengthMenu

该参数允许您轻松地指定长度下拉选择列表中的条目，当启用分页时，datatable会显示该列表。可以是:

• 1维数组：该数组将用于显示选项和用于显示长度或的值；
• 2维数组：它将使用第一个内部数组作为页长度值，第二个内部数组作为显示的选项。这对于语言字符串(如'All')很有用。

页长度值必须始终是整数值> 0，唯一的例外是-1。当使用-1作为值时，它告诉datattables禁用分页(即显示所有行)。

示例：

$('#example').dataTable( {
    // 设置页面显示的数据量
    "lengthMenu": [ 10, 25, 50, 75, 100 ]
} );

$('#example').dataTable( {
    // 当值为-1时，显示全部
    "lengthMenu": [ [10, 25, 50, -1], [10, 25, 50, "All"] ]
} );

1.4.3 order

如果排序被启用(排序)，那么datatable将在初始化期间执行第一次传递排序。使用这个参数，您可以定义在哪个列上执行排序，以及排序方向。顺序必须是数组的数组，每个内部数组由两个元素组成:

• 排序的索引
• 排序方式，asc为顺序，desc为倒序

如果需要，这个二维数组结构允许将多列顺序定义为初始状态。

$('#example').dataTable( {
    // 不排序
    "order": []
} );

$('#example').dataTable( {
    // 按第一列和第二列排序
    "order": [[ 0, 'asc' ], [ 1, 'asc' ]]
} );

1.4.4 orderFixed

该选项与order选项协同工作，order选项为表提供初始排序状态，然后用户可以通过单击列标题修改该状态，而该选项指定的排序将始终应用于表，而不管用户交互如何。

这种固定排序可以在用户自己的排序标准之前(pre)或之后(post)应用，使用下面描述的该选项的两种不同形式(数组或对象)。用于描述表的排序条件的值以两个元素数组的形式给出:

• 排序的索引
• 排序方式，asc为顺序，desc为倒序

也可以给出一组嵌套数组(即数组中的数组)来允许分配多列排序。如果列(可见或隐藏)必须始终按优先顺序排序(例如优先级顺序或索引列)，或者将相似的行分组在一起，则此选项可能很有用。

示例：

$('#example').dataTable( {
    // 固定第1列，以顺序排列，不受交互影响
    "orderFixed": [ 0, 'asc' ]
} );

$('#example').dataTable( {
    "orderFixed": {
        // 固定第2列的排序，优先排序第2列
        "pre": [ 1, 'asc' ]
    }
} );

$('#example').dataTable( {
    "orderFixed": {
        // 再排序后，再对第1列和第2列进行排序
        "post": [[ 0, 'asc' ], [ 1, 'asc' ]]
    }
} );

1.4.5 pageLength

使用分页时要在单个页面上显示的行数。

默认显示每页10行

1.4.6 pagingType

DataTables的分页选项将在表下面显示分页控件(默认情况下，可以使用dom和CSS更改其位置)，最终用户可以使用这些按钮来导航表的页面。分页控件中显示的按钮由这里给出的选项定义。

• numbers-只显示页码
• simple-只显示上一页和下一页按钮
• simple_numbers-显示上一页和下一页按钮和页码
• full-显示首页，上一页，下一页和末页按钮
• full_numbers-显示首页，上一页，下一页和末页按钮和页码
• first_last_numbers-显示首页，末页和页码

示例：

$('#example').dataTable( {
	pagingType: 'full_numbers',
} );

1.4.7 search

搜索选项允许在初始化期间设置datattables执行过滤的方式，并设置初始的全局过滤器。

search提供了以下几种过滤方式：

• search.caseInsensitive-是否不区分大小写。
• search.regex-是否支持正则表达式。
• search.smart-是否使用DataTables的智能过滤。
• search.search-设置一个全局筛选

1.5 Columns

1.5.1 columns

初始化参数中的columns选项允许您定义有关各个列行为方式的详细信息。有关可以设置的列选项的完整列表，请参阅下面的相关参数。

属性	类型	默认值	描述
columns.className	string		为单元格指定一个样式
columns.data	integer/string/null/object/function	自动获取列的索引值	设置来自行数据对象/数组的列的数据源
columns.orderable	boolean	true	是否支持按该列排序
columns.orderData	integer/array	自动获取列的索引值	关联排序与orderFixed相似
columns.render	integer/string/object/function		渲染(处理)表中使用的数据
columns.type	string	原始数据	设置列的类型，用于筛选和排序
columns.visible	boolean	true	是否显示该列的数据
columns.width	string	自动检测	设置列的宽度

1.5.1.1 columns.data

该属性提供了5种表达式用于不同的情况

• integer-列的索引，一般用于数据集为数组的情况，可以用数组的索引标识在列中显示的位置；
• string-对象表达式，一般用于数据集是json对象的情况，使用对象的属性名称标识在列中显示的位置；
• null-当结果集的数据与列数一直时，可以使data为null，会按结果集中的顺序依次显示；
• object-对于数据表请求的不同数据类型，使用不同的数据。在表格进行展示、排序、筛选时，调用预设的数据；
• function-当datattables需要设置或获取列中单元格的数据时，将执行给定的函数。

示例：

let table = $('#example').DataTable({
    ajax: {
        url: 'data1.json',
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { 
            data: {
                // 表格显示的数据，若为对象形式则必须拥有该属性
                _: 'start_date.display',
                // 设置排序时的值，当该列进行排序时调用这个值
                sort: 'start_date.timestamp'
            }
        },
        { 
            data(row, type, set, meta) {
                console.log(type)
                if(type === 'display') return row.salary.display
                if(type === 'sort') return row.salary.sort
                // 进行筛选时，调用该值
                if(type === 'filter') return row.salary.filter

                return row.salary.display
            } 
        },
    ],
})

data方法可以存在4个参数

• row-当前行的数据
• type-操作类型，包含display,sort,filter,type
• set-如果type的类型是set则获取新赋予的值
• meta-包含有关被请求单元格的附加信息的对象

通过返回值，显示最后呈现的数据（若type类型为set，则可以不需要返回值）

1.5.1.2 columns.render

与columns.data用法类似，可以通过方法来加工数据，得到想要获取的值。

示例：

let table = $('#example').DataTable({
    ajax: {
        url: 'data1.json',
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { 
            data: 'office',
            render(data, type, row, meta) {
                // data-当前展示的数据，type-操作类型，row-当前行所有的数据，meta-DataTable设置
                console.log(data, type, row)
                return data
            }
        },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' },
    ],
})

二、API

2.1 Core

2.1.1 ajax.json

获取Ajax请求后,服务器返回的结果。

获取该数据时需要配合添加事件xhr，在请求结束前获取，否则无法获取到结果。

示例：

var table = $('#example').DataTable( {
    ajax: "data.json"
} );
 
table.on('xhr', () => {
    // 获取data.json中的数据，返回值是一个json对象
    console.log(table.ajax.json());
});

2.1.2 ajax.params

获取Ajax发送给服务器的数据。

示例：

var table = $('#example').DataTable({
    ajax: "data.json",
    data: {
        a: "1",
        b: "2"
    }
});
 
table.on('xhr', () => {
    // 获取data的数据，返回值是一个json对象
    console.log(table.ajax.params());
});

2.1.3 ajax.reload

再次发起ajax请求，并重新渲染表格。该方法可以传递两个参数，用于增强该功能：

名称	类型	是否为空	默认值	描述
callback	function	N	null	函数，该函数在重新加载数据并完全重新绘制表时执行。该函数被赋予一个参数---服务器返回的JSON数据，并且不期望返回。
resetPaging	boolean	N	true	重置(默认操作或true)或保持当前分页位置(false)。当为false时，重新加载表格时会保持当前页码和排序方式。

示例：

let table = $('#example').DataTable({
    ajax: {
        url: 'data.json',
    }
})

setInterval(() => {
    table.ajax.reload((data) => {
        console.log('数据重新请求', data)
    }, false)
}, 10000)

2.1.4 ajax.url

获取或设置新的url。该方法可以获取当前表格请求的url地址，也可以通过传入参数来重新设置ajax请求的地址。

名称	类型	是否为空	默认值	描述
url	string	N	null	设置新的ajax请求地址

若要设置新的请求地址，可以使用ajax.url().load()方法，重新渲染表格。

2.1.5 clear

清理表格中的数据。该函数可以直接清空当前表格中的所有数据，在调用draw()方法重新绘制表格。

clear()方法不能在serverSide为true时使用，当支持了服务器处理后，应当从数据源中进行删除操作并重新绘制表格（例如向服务端发送Ajax请求）。

示例

var table = $('#example').DataTable()

table
    .clear()
    .draw();

2.1.6 data

获取表格中的数据。此方法提供对API上下文中表中每行使用的原始数据的访问。他的返回值是一个DataTable的API实例。

示例：

var table = $('#example').DataTable();
 
alert('There are'+table.data().length+' row(s) of data in this table');

与clear()方法类似，不能使用在服务端。

2.1.7 destroy

销毁表格。可以对当前表格进行销毁。

若需要重新渲染表格，销毁当前表格是必要的，为了避免内存泄漏。

名称	类型	是否为空	默认值	描述
remove	boolean	N	false	是否完全删除当前DOM节点，当为false时会将其保留在DOM中，保持原始的未增强的HTML状态

示例：

let table = $('#example').DataTable({
    ajax: {
        url: 'data.json',
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' },
    ],
})

// 点击按钮时，移除整个DOM节点
$('#btn').on('click', function() {
    table.destroy(true)
})

2.1.8 draw

绘制表格。该方法有三个参数，除了第一个参数，其他参数都会重置排序和搜索。

名称	类型	是否为空	默认值	描述
paging	boolean	N	false	是否完全删除当前DOM节点，当为false时会将其保留在DOM中，保持原始的未增强的HTML状态

参数paging用于确定将执行哪种绘制数据表，有三种选择：

• full-reset或是true，排序和搜索将被重新计算，并在其新位置重新绘制行。分页将被重置回第一页，默认为true
• full-hold或是false，排序和搜索将被重新计算，并在其新位置重新绘制行。分页不会被重置，即当前页面仍将显示
• page，排序和搜索将不会更新，分页位置将保持在原来的位置。这对于分页(即page())很有用，当数据在两次绘制之间没有改变时。

示例：

let table = $('#example').DataTable({
    ajax: {
        url: 'data.json',
    },
    columns: [
        {  data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' },
    ],
})
// 点击按钮时，前往下一页
$('#btn').on('click', () => { table.page('next').draw('page') })
// 点击按钮时，按照第二列进行倒序排列，且保持当前码
$('#btn').on('click', () => { table.order([[1, 'desc']]).draw(false) })

2.1.9 on,off,one

on()方法用于绑定监听事件，off()方法用于移除监听事件，而one()方法用于使监听事件只执行一次。

名称	类型	是否为空	默认值	描述
event	string	N		监听事件
callback	function	N		回调函数

2.1.10 order

获取或设置表格的排序方式。排序信息由DataTables以二维数组格式存储。为方便起见，该方法允许通过传入多个一维排序数组或二维排序数组来执行多列排序。当从表中检索排序信息时，总是返回一个二维排序数组。

示例：

var table = $('#example').DataTable();
var order = table.order();
 
alert( 'Column '+order[0][0]+' is the ordering column' );

var table = $('#example').DataTable();
 
// Sort by columns 1 and 2 and redraw
table
    .order( [[ 1, 'asc' ], [ 2, 'asc' ]] )
    .draw();

2.1.11 page

获取或设置当前页。

• page()：获取当前页信息
• page(set)：设置显示的页

名称	类型	是否为空	默认值	描述
set	string,integer	N		若为integer类型时，可以使表格跳转至指定页面；若为string类型可通过以下设置：first-跳转至首页；next-跳转至下一页；previous-跳转至上一页；last-跳转至末页

若操作了页码，要使用draw方法对表格重新绘制。

同时还可以通过page.info()方法获取当前页的分页信息，该方法提供关于表的分页状态的信息，以及关于表中记录数量的信息(包括总数和搜索结果集中的记录数量)。

示例：

$('#btn').on('click', () => { console.log(table.page.info()) })

• page-当前页码，从0开始
• pages-总页数
• start-当前页第一条记录的索引值
• end-当前页最后一条记录的索引值
• length-每页的记录数
• recordsTotal-总记录数
• recordsDisplay-应用当前搜索后的数据集长度
• serverSide-一个布尔值，指示表是否在服务器端处理模式下运行(serverSide)。

还可以通过page.len()方法设置页面显示的记录数，示例：

$('#btn').on('click', () => { table.page.len(20).draw() })

该方法的参数是每页显示的记录数，若为-1，则显示所有记录

2.1.12 search

用于进行搜索或获取搜索结果。Datatables有一个内置的搜索算法，称为"智能"搜索，其设计目的是使搜索表数据对最终用户来说易于使用。DataTables中的智能搜索提供以下功能:

• 按顺序匹配单词。例如，当搜索Allan Fife时，他会同时搜索Allan和Fife，无论这两个单词出现在表格的任意位置。
• 部分单词匹配。由于datatables提供即时过滤并向用户提供即时反馈，因此可以在结果集中匹配单词的部分，例如All将匹配Allan。
• 保留文本。DataTables 1.10增加了通过将搜索文本括在双引号中来搜索精确短语的功能。例如，"Allan Fife"将只匹配包含短语Allan Fife的文本。

示例：

// 当点击按钮时，搜索Thor，并重新绘制表格
$('#btn').on('click', () => { table.search('Thor').draw() })

2.2 rows

2.2.1 row

获取表格中的行

注意，row()方法选择单行。如果在此方法中提供的选择器解析多行，则结果将被截断为单行------即找到的第一行。如果需要处理多行，可以使用相同的选择选项使用row()方法。

名称	类型	是否为空	默认值	描述
rowSelector	row-selector	N		行选择器
modifier	selector-modifier	Y		选项，用于指定单元格的排序方式，以及是否应考虑表中的分页或筛选。

行选择器可以以多种不同的形式给出，以便于应用于您的数据和用例:

• 可以选择为空，为空时会选择所有的行；
• integer-通过行的索引值选择行；
• string-通过jQuery的id选择器选择行；
• string-通过jQuery的class选择器选择行；
• node-通过HTML结点，可以是tr或是td；
• array-通过数组获取行信息；

示例：

let table = $('#example').DataTable({
    ajax: {
        url: 'data.json',
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' },
    ],
})

$('#btn').on('click', function() {
    // 获取第51行的数据，data()方法可以获取当前数据的值，以一个对象形式保存
    console.log(table.rows(50).data())
})

let table = $('#example').DataTable({
    ajax: {
        url: 'data.json',
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' },
    ],
})

$('#example tbody').on('click', 'tr', function() {
    if ($(this).hasClass('selected')) {
        $(this).removeClass('selected');
    } else {
        table.$('tr.selected').removeClass('selected');
        $(this).addClass('selected');
    }
})

$('#btn').on('click', function() {
    // 获取class为selected的行的数据
    console.log(table.rows('.selected').data())
})

let table = $('#example').DataTable({
    ajax: {
        url: 'data.json',
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' },
    ],
})

$('#example tbody').on('click', 'tr', function() {
    // 获取点击行的数据，传入node结点用于获取当前行
    console.log(this, table.row(this).data())
})

selector-modifier为cells、columns、rows以及其单数形式服务，用于设置获取的行数据，该参数的本质是一个对象。该属性拥有以下几个属性：

• order-顺序修饰符提供了控制处理行的顺序的能力。当其值为current(applied)时，获取出来的数据会按表内的顺序排序，若为index(original)时，获取出来的数据按其索引值排序。
• page-页修饰符允许您控制选择器是应该考虑表中的所有数据而不考虑分页，还是应该只使用当前显示的页中的行。当其值为all时，不受分页影响直接获取所有的数据；若为current，则只显示当前页的数据。
• search-搜索修饰符提供了使用应用于表的搜索选项控制选择器使用哪些行的功能。当其值为none时，不受搜索内容影响，获取所有的待选择的数据；若为applied，仅使用与应用于表的当前搜索相匹配的行；若为removed，仅使用已被应用的搜索从表中删除的行。

示例：

let table = $('#example').DataTable({
    ajax: {
        url: 'data.json',
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' },
    ],
    createdRow(row, data, dataIndex, cells) {
        if(data.extn > 9000) {
            // 当extn的值大于9000时，为当前行添加selected样式
            $(row).addClass('selected')
        }
    }
})

$('#btn').on('click', function() {
    // 获取的数据按索引顺序排序，只获取当前页的结果，获取结果不受查询条件影响
    console.log(table.rows('.selected', { order: 'index', page: 'current', search: 'none' }).data())
})

2.2.2 row.child

child方法可用于获取或添加子行

父行可以同时附加一个或多个子行。但是，子行被API视为一个实体，也就是说，它们要么全部显示，要么全部隐藏。
此外，子行可以在隐藏之后继续存在，从而允许在将来需要时快速轻松地再次显示它们。隐藏行是使用row().child.hide()执行的。如果不再需要子行，也可以使用row().child.remove()或以false为唯一参数的此方法销毁子行(隐藏并释放其分配的内存)。
请注意，在创建子行时，此方法不会自动使添加的子行可见。根据需要使用row().child().show()链接方法(或row().child.show())。

示例：

function format(d) {
    // `d` is the original data object for the row
    return (
        '<table cellpadding="5" cellspacing="0" border="0" style="padding-left:50px;">' +
        '<tr>' +
        '<td>Full name:</td>' +
        '<td>' +
        d.name +
        '</td>' +
        '</tr>' +
        '<tr>' +
        '<td>Extension number:</td>' +
        '<td>' +
        d.extn +
        '</td>' +
        '</tr>' +
        '<tr>' +
        '<td>Extra info:</td>' +
        '<td>And any further details here (images etc)...</td>' +
        '</tr>' +
        '</table>'
    );
}

let table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: {
        url: 'data.json'
    },
    columns: [
        {
            className: 'dt-control',
            orderable: false,
            data: null,
            defaultContent: '',
        },
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    createdRow(row, data, index, cell) {
        // 获取api对象
        const api = new $.fn.dataTable.Api(this)
        // 为每一行增加子行
        api.row(index).child(format(data)).show()
    }
})

child()方法可以有以下几种用法：

• row().child()-获取当前行的子行，若没有子行则返回undefined。
• row().child(showRemove)-是否展示或移除（销毁）当前行的子行。当值为true时，相当于使用row().child.show()；当值为false时，不同于row().child.hide()方法隐藏该子行，会从内存中销毁该子行，与row().child.remove()方法。
• row().child(data[,className])-设置要在子行中显示的数据。请注意，调用此方法将替换已经附加到父行上的任何子行。

名称	类型	是否为空	默认值	描述
data	string,node,jQuery,array	N		子行中显示的数据可以以多种不同的方式给出
className	string	Y		当datatables生成子行时，添加到子行的td单元格节点的类名

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        {
            className: 'dt-control',
            orderable: false,
            data: null,
            defaultContent: '',
        },
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});

// Add event listener for opening and closing details
$('#example tbody').on('click', 'td.dt-control', function () {
    console.log(this)
    var tr = $(this).closest('tr');
    var row = table.row(tr);

    // 判断当前行的子行是否显示
    if (row.child.isShown()) {
        // 关闭子行
        row.child.hide();
        tr.removeClass('shown');
    } else {
        // 添加子行，并展示
        row.child(format(row.data())).show();
        tr.addClass('shown');
    }
});

该案例中调用了以下child()方法的子方法：

名称	描述
row().child().hide()	在创建新的子行后隐藏子行
row().child().remove()	销毁选中的子行
row().child().show()	使新定义的子行可见
row().child.isShown()	判断子行是否可见

2.2.3 row.data

获取或设置行数据。

请注意，当用作setter时，此方法将设置应用于表的数据，但在调用draw()方法之前不会更新表的内部数据缓存。这可以简单地作为row().data()方法返回对象(例如table)的链接方法来实现。table.row(0).data(newData).draw()这样做是为了便于对表进行优化，在重新绘制表之前可以应用连续的更新。

示例：

$('#example tbody').on('click', 'tr', function () {
    table.row(this).data({
        "id": "100",
        "name": "Tom",
        "position": "Beijing",
        "salary": "$300",
        "start_date": "2011/04/25",
        "office": "Edinburgh",
        "extn": "5421"
    })
})

该方法的复数形式，rows().data()，此方法用于从DataTables中获取与选择器匹配的行中的单元格所使用的数据。

此方法不能用于修改表中的数据，只能用于检索数据。请使用row().data()方法，它可以用作setter。

2.2.4 row.index

row().index()方法可以获取当前行的索引值。数据表将行和列的数据存储在内部索引中，以便快速排序、搜索等。有时知道这些索引是什么是很有用的，因为它们可以用于row()、column()和其他使用选择器的API方法中的高效选择器。

他的复数形式rows().indexes()方法，此方法用于检索所选行的索引，然后将其用作选择器的一部分来更新数据。示例：

$('#btn').on('click', function () {
    // 获取拥有selected样式的行的索引，返回值是一个DataTable Api
    var row = table.rows('.selected').indexes()

    // 通过DataTable Api获取行的信息
    console.log(table.rows(row).data())
})

2.2.5 row.node

row().node()方法可以获取当前的node结点。其复数形式rows().nodes()可以获取多个选中的结点。

2.2.6 row.remove

row().remove()方法可以移除当前行的数据。此方法(以及rows().remove())将从DataTable中完全删除选中的行，从而从浏览器中删除为数据和节点分配的内存。请注意，此方法从表内部删除数据，但该操作不会在视觉上显示，直到调用draw()方法来更新显示。这可以简单地作为row().remove()方法返回对象的链接方法调用，例如table.row().remove().draw();。如果为了优化而删除多行，则使用此方法减少所需的绘制次数。

其复数形式rows().remove()可以移除多行记录。

2.2.7 row.add

row().add()方法可以新增行。

var table = $('#example').DataTable();
 
table.row.add( {
    "name":       "Tiger Nixon",
    "position":   "System Architect",
    "salary":     "$3,120",
    "start_date": "2011/04/25",
    "office":     "Edinburgh",
    "extn":       "5421"
} ).draw();

其复数形式rows().add()方法可以添加多行记录。

2.2.8 rows.every

rows().every()方法与each()和iterator()方法类似，可以循环遍历rows()方法获取的行。该方法的参数为一个函数，该函数有三个参数：

• rowIdx-遍历的行的索引值
• tableLoop-表循环计数器
• rowLoop-行循环计数器

示例：

let table = $('#example').DataTable({
    ajax: {
        url: 'data.json',
    },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'extn' },
        { data: 'start_date' },
        { data: 'salary' },
    ],
})

$('#example tbody').on('click', 'tr', function() {
    if ($(this).hasClass('selected')) {
        $(this).removeClass('selected');
    } else {
        $(this).addClass('selected');
    }
})

$('#btn').on('click', function () {
    table.rows('.selected').every(function(rowIdx, tableLoop, rowLoop) {
        console.log(table.row(rowIdx).data())
        console.log(rowIdx, tableLoop, rowLoop)
    })
})

2.3 columns

2.3.1 column

从DataTable中选择要处理的单个列，其链式方法提供处理该列的能力，采取诸如切换其可见性或从该列获取数据之类的操作。

请注意，该方法选择单个列。如果提供的选择器解析到多个列，结果将被截断为只有一个列------即找到的第一个列。如果需要处理多个列，可以使用columns()方法提供相同的选择选项。

该方法有2个参数：

名称	类型	是否为空	默认值	描述
columnSelector	column-selector	N		列选择器
modifier	selector-modifier	Y		选项，用于指定单元格的排序方式，以及是否应考虑表中的分页或筛选。

列选择器可以以多种不同的形式给出，以便于应用于您的数据和用例:

• 可以选择为空，为空时会选择所有的列；
• integer-通过列的索引值选择列；
• {integer}:visIdx-列可见索引选择器;
• {integer}:visible-列可见索引选择器;
• {string}:name-列名选择器;
• string-通过jQuery的class选择器选择行；
• node-通过HTML结点，可以是tr或是td；
• array-通过数组获取列信息，数组的内容可以是列数或者是列的类名；

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});
// 获取第二列的列名，返回值为string
console.log(table.column(1).dataSrc())

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position', visible: false },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});
// 当第二列隐藏时，若不加visible则返回postion，通过visible获取显示的第二列
console.log(table.column('1:visible').dataSrc())

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position', visible: false },
        { name: 'office', data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});
// 通过列的名字获取列信息
console.log(table.column('office:name').dataSrc())

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position', },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});

$('#example tbody').on('click', 'td', function() {
    // 点击单元格所在的列，获取该列的信息
    console.log(table.column(this).dataSrc())
})

2.3.2 column.data

获取所选列中单元格的数据。示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position', visible: false },
        { name: 'office', data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});

$('#example tbody').on('click', 'td', function() {
    console.log(table.column(this).data())
})

该方法会返回一个DataTable Api实例，其中包含一个数组，用于存储获取列的所有数据。

他的复数形式columns().data()方法可以获取所选中的列的数据，每一列形成一个数组，存储在DataTable Api实例中。

2.3.3 column.dataSrc

column().dataSrc()方法可以获取列的数据源属性，该方法只会在回去columns.data属性的值，并不会受columns.render属性的影响。示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { name: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});

$('#example tbody').on('click', 'td', function() {
    console.log(table.column(this).dataSrc())
})

该方法有3种返回值：

• integer-返回该列所在的索引值；
• string-返回该列的columns.data的值；
• function-返回一个函数。

2.3.4 column.nodes

column().nodes()获取所选列的单元格节点。此方法用于在选择器匹配的列中获取表主体单元格的节点(th/td元素)。示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position', visible: false },
        { name: 'office', data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});

$('#example tbody').on('click', 'td', function() {
    // 获取当前列的结点
    console.log(table.column(this).nodes())
})

该方法的复数形式columns().nodes()方法，可以获取多列的结点信息，会以数组的形式存储在DataTable Api实例中。

2.3.5 column.order

column.order方法可以设置当前列的排序方式，其参数可以为asc或desc。此方法为order()方法提供了一种有用的替代方法，允许您使用灵活的column()选择器选择要排序的列，并按照指定的方向排序。使用该方法时，需要调用draw()方法重新绘制表格。示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
});

$('#btn').on('click', function() {
    // 点击后按第3列倒序排序，并重新绘制表格
    table.column(2).order('desc').draw()
})

其复数形式columns().order()方法，可以对多列进行排序。

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
});

$('#btn').on('click', function() {
    // 点击后按第2列和第3列倒序排列，并重新绘制表格
    table.columns([1, 2]).order('desc').draw()
})

columns().order()方法相较于order()方法不够灵活，无法控制每一列的排序方式和顺序。

2.3.6 column.search

column().search()方法可以搜索当前列的内容，与search()方法类似，只是将搜索范围指定在某一列中。示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
});

$('#btn').on('click', function() {
    // 获取input框中的内容
    let val = $('#search').val()
    // 搜索第2列中符合该内容的数据
    table.column(1).search(val).draw()
})

该方法的参数有以下几种可选项：

名称	类型	是否为空	默认值	描述
input	string	N		需要检索的字符串
regex	boolean	Y	false	是否支持正则表达式
smart	boolean	Y	true	是否执行智能搜索
caseInsen	boolean	Y	true	是否区分大小写，true为不区分

其复数形式columns().search()方法可以检索多个列的结果，示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name', className: 'select-filter' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'salary' },
    ],
    initComplete() {
        // 获取类名为select-filter的列
        this.api().columns('.select-filter').every(function() {
            // 获取当前列的实例
            const column = this

            // 当选择器发生改变时，将选择器的值进行搜索
            let select = $('<select />').appendTo(this.footer()).on('change', function() {
                column.search($(this).val()).draw()
            })

            // 为选择器增加选项
            this.cache('search').sort().unique().each(function(d) {
                select.append( $('<option value="'+d+'">'+d+'</option>') )
            })
        })
    }
});

2.3.7 column.visible

column().visible()方法可获取该列的显示状态，返回值为boolean值，若传递一个布尔值的参数，可控制该列的显示状态。示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name', className: 'select-filter' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'salary' },
    ],
});

$('#btn').on('click', function() {
    // 获取第2列
    const column = table.column(1)
    // 设置第2列的显示状态，若显示则取消显示
    column.visible(!column.visible())
})

其复数形式columns().visible()方法在DataTable中显示和隐藏列可能非常方便，特别是在显示具有大量信息密度的表时。此方法允许动态更改列的可见性，或者读取列的可见性状态。

2.3.8 column.index

column().index()在处理DOM时，您通常会使用列的可见索引，因为这是DOM中可用的信息(当一个列被datatable隐藏时，它将完全从DOM中删除，如果需要，将来可以通过column().visible()重新插入或再次显示。但是，在处理表的原始数据时，通常需要使用列数据索引。该方法用于在两种格式之间进行转换。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position', visible: false },
        { data: 'office' },
        { data: 'salary' },
    ],
});

$('#example tbody').on('click', 'td', function() {
    // 获取列在页面中显示的索引值
    let visIdx = $(this).index()
    // 获取列在数据中的索引值
    let dataIdx = table.column(this).index('formVisible', visIdx)
    console.log('Column data index: '+dataIdx+', and visible index: '+visIdx)
})

该方法的参数如下：

名称	类型	是否为空	默认值	描述
type	string	N		应该发生的转换类型
index	integer	N		要转换的索引

type类型有两个值：

• formVisible或toData将可见索引转换为列的数据索引
• formData或toVisible将数据索引转换为列的可见索引

返回值是其显示的索引值

其复数形式columns().indexes()可以获取多个列的索引值，返回值为DataTable Api实例。

2.3.9 columns.every

columns().every()方法类似rows().every()可以遍历选择的列。

2.4 cells

2.4.1 cell

从表中选择单个单元格。从DataTable中选择要使用的单个单元格，其链式方法提供获取/设置单元格中的数据、直接使用该节点以及其他操作的能力。

注意，此方法选择单个单元格。如果在此方法中提供的选择器解析多个单元格，则结果将被截断为单个单元格------即找到的第一个单元格。如果需要处理多个单元格，可以使用相同的选择选项使用cells()方法。

cell()方法有以下几种写法：

1. cell( [ modifier ] )-选择与该修饰符匹配的单元格

名称	类型	是否为空	默认值	描述
modifier	selector-modifier	Y		选项，用于指定单元格的排序方式，以及是否应考虑表中的分页或筛选。

---

2. cell( cellSelector, [ modifier ] )-选择单元格选择器找到的单元格

名称	类型	是否为空	默认值	描述
cellSelector	cell-selector	N		单元格选择器
modifier	selector-modifier	Y		选项，用于指定单元格的排序方式，以及是否应考虑表中的分页或筛选。

单元格选择器可以以多种不同的形式给出，以便于应用于您的数据和用例:

• string-jQuery选择器;
• node-元素结点;
• array-包含上述选项的任意组合的数组

---

3. cell( rowSelector, columnSelector, [ modifier ] )-选择从行和列选择器中找到的单元格

名称	类型	非空	默认值	描述
rowSelector	row-selector	Y		行选择器
columnSelector	column-selector	Y		列选择器
modifier	selector-modifier	N		选项，用于指定单元格的排序方式，以及是否应考虑表中的分页或筛选。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
})

$('#example tbody').on('click', 'td', function () {
    // 通过当前结点获取单元格
    console.log(table.cell(this).data())
})

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'id', orderable: false },
        { data: 'name' },
        { data: 'position', className: 'select-filter' },
        { data: 'office' },
        { data: 'salary' },
    ],
    initComplete(settings, json) {
        const api = this.api()
        // 通过行和列的索引值获取单元格
        console.log('索引为1的第1列数据：', api.cell(1, 1).data())
    }
})

它的复数形式cells()方法可以获取多个单元格的数据。示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'id', orderable: false },
        { data: 'name' },
        { data: 'position', className: 'select-filter' },
        { data: 'office' },
        { data: 'salary' },
    ],
});

// 当表格重新排列或搜索时，为第1列增加序号，并重新绘制
table.on('order.dt search.dt', function () {
    let i = 1
    table.cells(null, 0).every(function () {
        this.data(i++)
    })
}).draw()

2.4.2 cell.data

cell().data()方法可以获取或设置单元格的值。此方法用于处理cell()调用中使用的选择器检索到的单元格中的数据。它可用于获取现有数据或设置新值。

请注意，当用作setter时，此方法将数据设置为应用于表，将其存储在数据源数组或行对象中，但在调用draw()方法之前不会更新表的数据内部缓存(即搜索和顺序缓存)。绘制可以作为cell().data()方法返回的对象(例如table)的链接方法触发。例如：table.cell( 0, 0 ).data( 'Updated' ).draw()

其复数形式cells().data()方法可以获取多个单元格的数据，并以数组的形式保存在DataTable Api实例中。示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'id', orderable: false },
        { data: 'name' },
        { data: 'position', className: 'select-filter' },
        { data: 'office' },
        { data: 'salary' },
    ],
});

// 将第1列改为序号，在重新排序或搜索时也能重新排序
table.on('order.dt search.dt', function () {
    let i = 1
    table.cells(null, 0).every(function () {
        this.data(i++)
    })
}).draw()

$('#btn').on('click', function() {
    // 点击按钮时，获取样式为select-filter的单元格
    console.log(table.cells(null, '.select-filter').data())
})

2.4.3 cell.index

cell().index()方法可以获取当前单元格所在的位置，它的返回值为一个json对象，其结构如下：

{
    "row":           integer, // 所在行的索引值
    "column":        integer, // 所在数据列的索引值
    "columnVisible": integer  // 所在显示列的索引值
}

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'id', orderable: false },
        { data: 'name', visible: false },
        { data: 'position', className: 'select-filter' },
        { data: 'office' },
        { data: 'salary' },
    ],
});

// 将第1列改为序号，在重新排序或搜索时也能重新排序
table.on('order.dt search.dt', function () {
    let i = 1
    table.cells(null, 0).every(function () {
        this.data(i++)
    })
}).draw()

$('#example').on('click', 'td', function() {
    // 获取点击单元格的索引值
    console.log(table.cell(this).index())
})

其复数形式cells().indexes()方法可以获取多个单元格的索引，以数组的形式存储在DataTable Api实例中。

2.4.4 cell.node

cell().node()方法可以获取单元格的结点。其复数形式可以获取多个单元格的结点，并以数组的形式存储在DataTable Api实例中。

2.4.5 cell.render

datattables能够使用正交数据，即根据正在执行的操作，同一个单元格有不同的数据。一个典型的例子是日期/时间数据以数字格式(即时间戳)进行排序，但以复杂的格式进行显示。cell().data()方法提供对底层原始数据的访问，而此方法提供对每种类型的呈现数据的访问。提供它是为了允许插件作者访问表中可用的正交数据。

请注意，调用此方法将计算单元的呈现器，而不是从缓存中读取信息(参见cell().cache()从缓存中读取信息，参见cell().invalidate()清除缓存)。

该方法可以存入一个参数type该属性可通过指定类型获取单元格渲染后的值，示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data1.json',
    columns: [
        { data: 'id', orderable: false },
        { data: 'name' },
        { data: 'position', className: 'select-filter' },
        { data: 'office' },
        { data: {
            _: 'start_date.display',
            sort: 'start_date.timestamp'
        } },
    ],
});

// 将第1列改为序号，在重新排序或搜索时也能重新排序
table.on('order.dt search.dt', function () {
    let i = 1
    table.cells(null, 0).every(function () {
        this.data(i++)
    })
}).draw()

$('#btn').on('click', function() {
    // 获取最后一列渲染结果
    console.log(table.cells(null, 4).render('sort'))
})

type有以下几种类型：

• display-显示的内容
• filter-筛选值
• sort-排序值
• type-类型值

2.4.6 cells.every

与rows().every()和columns().every()方法类似，用于循环获取选择的单元格。该方法拥有一个方法参数，该方法有4个参数，如下：

• 单元格的行索引
• 单元格的列索引
• 表循环计数器
• 单元格循环计数器

注意方法内部的this为单元格的Datatable Api实例。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data1.json',
    columns: [
        { data: 'id', orderable: false },
        { data: 'name' },
        { data: 'position', className: 'select-filter' },
        { data: 'office' },
        { data: {
            _: 'start_date.display',
            sort: 'start_date.timestamp'
        } },
    ],
    initComplete(settings, json) {
        const api = this.api()
        console.log('索引为1的第1列数据：', api.cell(1, 1).data())
    }
});

// 将第1列改为序号，在重新排序或搜索时也能重新排序
table.on('order.dt search.dt', function () {
    let i = 1
    table.cells(null, 0).every(function (rowIdx, columnIdx, tableLoop, cellLoop) {
        console.log('this:', this)
        console.log(rowIdx, columnIdx, tableLoop, cellLoop)
        this.data(i++)
    })
}).draw()

2.5 Utility

2.5.1 any()

判断当前元素是否存在，返回值为一个布尔值，示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 判断是否有类名为selected的行数据
    if(table.rows('.selected').any()) {
        // 弹窗提示选中的个数
        alert('select ' + table.rows('.selected').count() + ' records.')
    }
})

2.5.2 count()

获取API实例中包含的元素数量。

重要的是要注意，长度属性本身不能简单可靠地用于确定API结果集是否包含任何元素，因为DataTables API支持多表，结果集由嵌套数组组成。因此，我们必须在能够使用length属性之前将数组平面化。

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        {
            className: 'dt-control',
            orderable: false,
            data: null,
            defaultContent: '',
        },
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
});

$('#btn').on('click', function() {
    // 点击按钮获取当前页的数据量
    console.log(table.rows({ page: 'current' }).count())
})

2.5.3 concat()

组合多个API实例以创建单个新实例。示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        {
            className: 'dt-control',
            orderable: false,
            data: null,
            defaultContent: '',
        },
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#btn').on('click', function() {
    console.log(table.column(1).data().concat(table.column(2).data()))
})

其结果为一个DataTable Api实例，数组中的每个值也都是一个DataTable Api实例。

2.5.4 each()

遍历API结果集的内容。

请注意，当使用复数方法(如rows()和columns()时，您可能希望使用rows().every()，columns().every()和cells().every()方法来遍历每一行，列或单元格，并将上下文设置为该表元素。这听起来可能有点复杂，但它可以显著简化您的代码!请参考每一种方法的详细信息。

该方法包含一个函数参数，该函数可以有一下参数：

• value-元素的值
• index-当前元素在结果集中的索引值
• api-正在遍历的API实例

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 循环选中的行
    table.rows('.selected').data().each(function(value, index, api) {
        console.log(value, index, api)
    })
})

2.5.5 eq()

将Api实例简化为单个上下文和结果集。DataTables API被设计为在单个API实例中处理多个表(上下文)，这通常是有用的，但有时您只想处理单个表，并从减少复杂性中获益(标量而不是矢量)。

其包含一个参数：

名称	类型	是否为空	默认值	描述
index	intege	Y		检索的索引值

该参数可以用在多表渲染时，挑选要选择的表

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    console.log(table.rows('.selected').eq(0))
    console.log(table.rows('.selected'))
})

// 通过类名筛选多表进行渲染
var table = $('table.display').DataTable();

$('#btn').on('click', function() {
	// 获取第2个表的行数
    console.log(table.rows().eq(1).count())
    // 获取两个表所有的行数
    console.log(table.rows().count())
})

2.5.6 filter()

使用通过给定测试的结果集中的所有元素创建一个新的API实例。

该方法可以传入一个回调函数，该函数可以有3个参数，如下：

• value-元素的值
• index-当前元素在结果集中的索引值
• api-正在遍历的API实例

var table = $('#example').DataTable();
 
var filteredData = table
    .column( 0 )
    .data()
    .filter( function ( value, index ) {
        return value > 20 ? true : false;
    } );

2.5.7 flatten()

将二维数组结构的API实例扁平化为一维数组结构。

此方法将二维数组结构简化为简单的一维结构，这在使用复数方法(如rows()和columns())时特别有用，这些方法可以返回二维结构数据(例如在columns数据中，每列都有自己的信息数组)。

一般用于columns()方法，columns()方法会将结果以二维数组的形式存在Datatable Api实例中，而rows()方法获取的只是一个一维数组。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 将二维数组简化为一维数组
    console.log(table.columns([0, 1]).data().flatten())
    console.log(table.columns([0, 1]).data())
})

2.5.8 indexOf()

在API实例的结果集中查找值的第一个实例。

知道一个值是否在结果集中，以及如果它存在，它在结果集中的位置通常是非常有用的。这个方法提供了这种能力，从索引0开始搜索给定的值(参见lastIndexOf()，从数组末尾开始)，并给出它在结果集中的位置。

示例：

var table = $('#example').DataTable();
 
var index = table
    .column( 0 )
    .data()
    .indexOf( 21 );
 
if ( index < 0 ) {
    alert( '21 was not found in the result set' );
}
else {
    alert( '21 was found at index: '+index );
}

该函数的返回值为一个integer类型，用于记录该数据出现的第一个索引值，若不存在该数据，则返回-1。

2.5.9 join()

将结果集中的元素连接成一个字符串。

该方法的操作方式与Javascript数组连接方法完全相同，将数组的内容(在本例中是API实例)组合成单个字符串。

名称	类型	是否为空	默认值	描述
separator	string	Y		分隔符

该方法的返回值为一个由结果集拼接而成的字符串。

获取的行数据是一个对象值，所以无法调用join方法对数据进行拼接

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 将第一列的数据有','拼接
    console.log(table.column(0).data().join(','))
})

2.5.10 length

API实例结果集中的元素数量。

2.5.11 pluck()

pluck()方法在处理对象时，可能经常发现需要一个只包含源对象的一个属性的数组。这通常涉及编写一个简单的循环来创建该数组，尽管在这里，该循环是在此方法中执行的，从而减少了为获取所需数据而进行的简单函数调用所需的代码量。

名称	类型	是否为空	默认值	描述
property	string,integer	Y		对象属性名称，从原始结果集中的元素中为新结果集使用。这通常是一个带有目标属性名称的字符串，但如果使用数组，也可以是数组索引。

该方法会将结果以数组形式保存在一个新的Datatable Api对象。

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 获取列为name的值
    console.log(table.rows('.selected').data().pluck('name'))
})

2.5.12 pop()

就像Javascript数组一样，由于DataTables API对象是"类似数组的"，可以使用此方法从结果集中删除项。弹出结果，弹出结束。API实例的结果集的长度减少1，并且从函数调用中返回被删除的项。shift()可用于执行相同的操作，但如果需要，则在数组的开头执行。

其返回值为删除项的内容。示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#btn').on('click', function() {
    // 从数据结果中删除最后一项
    let data = table.column(0).data()
    console.log('删除最后一行的第一列数据后：', data.pop())
    console.log('删除后：', data)
})

2.5.13 shift()

与Javascript数组一样，由于DataTables API对象是"类似于数组的"，因此可以使用此方法从结果集中删除项。移动结果，将项目移出结果集的开头。API实例的结果集的长度减少1，并且从函数调用中返回被删除的项。pop()可用于执行相同的操作，但如果需要，则在数组的末尾执行。

其返回值为删除项的内容。示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 从数据结果中删除第一项
    let data = table.rows('.selected').data()
    console.log('删除第1行的数据：', data.shift())
    console.log('删除后：', data)
})

2.5.14 push()

就像Javascript数组一样，由于DataTables API对象是"类似数组的"，可以使用此方法将项添加到结果集中。将项推入API实例将其添加到结果集的末尾。如果需要，可以使用unshift()在结果集的开头添加项。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 在最后一行增加一个数据
    let data = table.column(0).data()
    console.log(data.push('Tom'))
})

其返回值为增加数据后的实例的长度。

2.5.15 unshift()

就像Javascript数组一样，由于DataTables API对象是"类似数组的"，可以使用此方法将项添加到结果集中。不将项移动到API实例上将其添加到结果集的开头。如果需要，可以使用push()在结果集的末尾添加项。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 在选中的行数据中添加一行数据
    let rows = table.rows('.selected').data()
    console.log(rows.push({"id":"58","name":"Tom","position":"BeiJing","salary":"$170,750","start_date":"2011/07/25","office":"SanLitun","extn":"8422"}))
})

其返回值是增加数据后的实例长度。

2.5.16 reduce()

此方法可用于将结果集中的数据累积到单个值中。一个很好的例子是对一列数据中的值求和。注意，在这个方法中，结果集中元素的遍历是从左到右的(即从0开始)。reduceRight()可用于相反方向的横向。示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 对第4列的数据进行求和
    let sum = table.column(3).data().reduce(function(val, currentValue, index, api) {
        console.log(val, currentValue, index, api)

        return parseInt(val) + parseInt(currentValue)
    })

    console.log(sum)
})

reduce(fn)方法的参数为一个回调函数，该函数有4个参数：

• 累加器累加的值
• 当前元素的值
• 当前元素的索引
• 正在遍历的API实例

2.5.17 reduceRight()

与reduce()方法相对应，会从最后一位数据开始循环。

2.5.18 slice()

DataTables API对象是"类似于数组"的，并且继承了许多与Javascript数组相同的特征。slice()方法就是其中之一。它提供了创建实例的独立副本的能力，这样就可以在不影响原始副本的情况下对其进行操作。

2.5.19 sort()

提供了一种对API实例结果集中的数据进行排序的方法，如果您希望使用该数据向最终用户显示，例如作为搜索输入的选择列表，那么该方法将特别有用。此方法不应与order()混淆，order()用于对DataTable中的记录进行排序。

该方法使用一个回调函数，这是一个标准的Javascript排序比较函数。它接受两个参数:

• 对第一个值进行比较
• 对第二个值进行比较

并期望返回一个指示两个值的排序位置的值。小于0表示第一个值在第二个值之前，大于0表示第一个值在第二个值之后，返回0表示它们相同。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#btn').on('click', function() {
    // 按第4行进行排序
    let data = table.column(3).data()
    console.log(data.sort())
})

若没有使用comparefn，那么会直接将待排序的值转为字符串，并按照 UTF-16 码元顺序比较字符串进行排序。

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 根据选中的行按extn属性进行倒序排序
    let data = table.rows('.selected').data()
    data.sort(function(a, b) {
        return b.extn - a.extn
    })
    console.log(data)
})

2.5.20 splice()

pop()、shift()等方法可以用于修改Api实例的结果集，但它们仅限于在结果集的末尾开始操作。此方法可用于在任何点修改结果集。

该方法存在3个参数，用法如下：

名称	类型	是否为空	默认值	描述
index	integer	Y		开始修改Api实例结果集的索引。
howMany	integer	Y		要从结果集中删除的元素数目。如果只希望添加新项，则可以将其设置为0。
value_1	any	N		项要添加到第一个参数指定的索引处的结果集中。通过将多个项作为附加参数添加到单个调用中，可以添加多个项。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#btn').on('click', function() {
    // 将Fiona Green替换为Tom
    let data = table.column(0).data()
    let idx = data.indexOf('Fiona Green')
    data.splice(idx, 1, 'Tom')
    console.log(data[idx])
})

2.5.21 to$()

这个方法将根据API实例的结果集的内容创建一个jQuery对象。这主要用于处理API的nodes()函数，如rows().nodes()， column().nodes()和cells().nodes()，在这些函数中，使用jQuery提供的链接方法将API实例轻松转换为jQuery对象是很有用的。

请注意to$()和toJQuery()在功能上是相同的。提供这两种方法都是为了满足使用jQuery的两种常见形式。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#example').on('click', 'tr', function() {
    if($(this).hasClass('selected')) {
        $(this).removeClass('selected')
    } else {
        $(this).addClass('selected')
    }
})

$('#btn').on('click', function() {
    // 移除选中行的selected样式
    console.log(table.rows('.selected').nodes().to$().removeClass('selected'))
})

2.5.22 unique()

了解结果集中哪些数据是可用的，删除重复项(例如创建一个选择列表用作搜索输入)通常是有用的。虽然使用循环可以很容易地找到唯一的道具，但是这个实用函数用一个简单的方法为您提供了这种功能。

示例：

var table = $('#example').DataTable({
    order: [[1, 'asc']],
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office', className: 'select-filter' },
        { data: 'extn' },
    ],
})

$('#btn').on('click', function() {
    // 去除第3列的重复值，获取所有的唯一值
    console.log(table.column(2).data().unique())
})

三、Event

datatable及其扩展将在执行特定操作时发出自定义DOM事件，提供侦听这些事件并在事件发生时对其采取行动的能力，例如，在重绘表时更新有关表的显示信息。

可以使用on()方法或使用dt名称空间的jQuery.on()方法侦听DataTables发出的所有事件(所有事件都使用dt名称空间触发，以确保它们不会与来自其他库的自定义事件冲突!)

3.1 childRow

每当从表中插入或删除子行时，都会触发chilRow事件。

该方法有3个参数

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
show	boolean	Y		是否展示子行，true为展示，false为隐藏
row	DataTable Api	Y		为其显示子行的父行实例

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        {
            className: 'dt-control',
            orderable: false,
            data: null,
            defaultContent: '',
        },
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#example tbody').on('click', 'td.dt-control', function () {
    // console.log(this)
    var tr = $(this).closest('tr');
    var row = table.row(tr);

    // 判断当前行的子行是否显示
    if (row.child.isShown()) {
        // 关闭子行
        row.child.hide();
        tr.removeClass('shown');
    } else {
        // 添加子行，并展示
        row.child(format(row.data())).show();
        tr.addClass('shown');
    }
})

$('#example').on('childRow.dt', function(e, show, row) {
    console.log((show ? "Showing " : "Hiding ") + "row " + row.index());
})

3.2 destroy

当一个DataTable被删除，用一个增强的HTML表替换(或者干脆从DOM中完全删除)时，就会触发destroy事件。这可用于删除绑定事件、添加的DOM节点等，对插件作者尤其有用。

当通过调用destroy API方法或在初始化对象中传递destroy参数来销毁DataTable时，将触发此事件。

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#btn').on('click', function() {
    table.destroy(true)
})

$('#example').on('destroy.dt', function(e, settings) {
    console.log('表格已被移除')
})

3.3 draw

对表的每个绘制事件采取操作可能很有用。例如，您可能希望使用新显示的数据更新外部控件，或者当启用服务器端处理时，您可能希望将事件分配给新创建的元素。此事件可准确给出。

每当在页面上重新绘制表格时，就会触发绘制事件，与drawCallback相同(技术上讲，回调在事件之前触发，但它们是顺序发生的，因此两者都可以用于实现相同的效果)。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项

3.4 error

在任何复杂的应用程序中，错误控制都是一个重要的考虑因素，DataTables提供了这个事件，允许您将应用程序自己的错误处理挂钩到DataTables中。例如，您可以触发一个Ajax调用，该调用将记录一个错误以供调查，或者使用错误事件向最终用户显示自定义错误消息。

此事件与$.fn.datatable.ext密切相关。errMode选项，控制DataTables如何处理错误。该静态选项可以取以下四个值之一:

• alert 弹窗提示（默认）
• throw 抛出异常
• none 不做出响应

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项
techNode	integer	Y		错误码
message	string	Y		错误信息

示例：

$.fn.dataTable.ext.errMode = 'throw'
var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        {
            className: 'dt-control',
            orderable: false,
            data: null,
            defaultContent: '',
        },
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        // { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#example').on('error.dt', function(e, settings, techNode, message) {
    console.log('表格绘制有问题：', techNode, message)
})

3.5 init

init事件是initComplete初始化选项的事件补充。与回调函数一样，init事件在表完全初始化、数据加载和绘制完成后调用，这在使用ajax数据源时特别有用。在这种情况下，表将在加载数据之前完成初始运行(毕竟Ajax是异步的!)，因此提供这个回调是为了让您知道数据何时完全加载。

init事件与initComplete在同一点触发(从技术上讲，回调在事件之前触发，但它们是顺序发生的，因此两者都可以用来达到相同的效果)。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项
json	object	Y		ajax请求的返回值

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        {
            className: 'dt-control',
            orderable: false,
            data: null,
            defaultContent: '',
        },
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
    initComplete(settings, json) {
        console.log('initComplete-ajax异步请求完毕：', json)
    }
})

$('#example').on('init.dt', function(e, settings, json) {
    console.log('init-ajax异步请求完毕：', json)
})

3.6 length

每当更改表的页长度时，就会触发length事件。这可以通过用户与内置的页面长度控件进行交互，也可以通过API。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项
len	integer	Y		新标签页的长度

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#example').on('length.dt', function(e, settings, len) {
    console.log('new page length is ' + len)
})

当切换页面长度时会触发该事件

3.7 order

只要对表中的数据进行了排序，就会触发order事件。这通常由最终用户对列进行排序触发，但也可以通过order()方法启动，并在发生完全重绘(通过调用draw())时启动。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项
orderArr	array	Y		描述当前应用顺序的对象数组

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#example').on('order.dt', function(e, settings, orderArr) {
    console.log('order by ', orderArr)
})

参数orderArr为一个对象数组，若存在多个排序方式将以数组的形式存储。

3.8 page

当表的分页状态改变时触发page事件。这可以是最终用户从内置控件中选择要查看的页面或页面长度，也可以是当页面状态被API(page())更改时。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#example').on('page.dt', function(e, settings) {
    let page = table.page.info()
    console.log('当前页码为' + page.page)
})

3.9 preDraw

这个事件在DataTables开始它的绘制动作(执行draw()方法)时被触发，并且可以用来通知你这个状态。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项

示例：

var table = $('#example').DataTable({
    ajax: 'data2.json',
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#example').on('draw.dt', function(e, settings) {
    console.log('表格已绘制完毕！')
})

$('#example').on('preDraw.dt', function(e, settings) {
    console.log('开始绘制表格！')
})

3.10 preInit

当表被初始化并准备请求数据时，由DataTables发出此事件。在启动时，表将初始化其列和特性，但没有加载数据(通过Ajax或从DOM读取)。

它的主要目的是允许数据表扩展的作者向文档添加侦听器，以便在加载数据之前采取一些操作(例如修改要加载的数据量)。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项

示例：

$(document).on( 'preInit.dt', function (e, settings) {
    var api = new $.fn.dataTable.Api( settings );
 
    api.page.len( 20 );
} );
 
$('#example').DataTable();

3.11 preXhr

此事件在DataTables向服务器发出Ajax请求获取数据之前触发，因此与Ajax请求从服务器成功返回数据后触发的xhr事件对应。preXhr事件是为插件作者设计的，他们可以在扩展中侦听该事件并发送可能需要的任何其他数据。它与ajax非常相似。具有此功能的数据，该选项通常由为其表编写初始化代码的人使用，而不是插件作者。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项
data	object	Y		请求的参数

该事件一定要在表格初始化前进行绑定

示例：

$('#example').on('preXhr.dt', function(e, settings, data) {
    console.log(data)
})

var table = $('#example').DataTable({
    ajax: { url: 'data2.json', data: { a: 1, b: 2 } },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

通过该事件就可以在发起请求前对请求参数进行处理。

3.12 xhr

在处理Ajax数据时，知道DataTables何时完成了数据加载通常是很有用的，这样您就可以根据DataTables的配置(columns.data)将数据操作成DataTables期望的格式，也可以将服务器的JSON响应中包含的数据用于页面的其他部分。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项
json	object	Y		请求后得到的原始数据
xhr	object	Y		jQuery XHR对象

示例：

var table = $('#example').DataTable({
    ajax: { url: 'data2.json', data: { a: 1, b: 2 } },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#example').on('xhr.dt', function(e, settings, json, xhr) {
    console.log(json, xhr)
})

order: [[1, 'asc']],

})

$('#example').on('draw.dt', function(e, settings) {

console.log('表格已绘制完毕！')

})

$('#example').on('preDraw.dt', function(e, settings) {

console.log('开始绘制表格！')

})

## 3.10 preInit

当表被初始化并准备请求数据时，由DataTables发出此事件。在启动时，表将初始化其列和特性，但没有加载数据(通过Ajax或从DOM读取)。

它的主要目的是允许数据表扩展的作者向文档添加侦听器，以便在加载数据之前采取一些操作(例如修改要加载的数据量)。

事件触发方法参数如下：

| 名称       | 类型                 | 非空 | 默认值 | 描述           |
| ---------- | -------------------- | ---- | ------ | -------------- |
| `e`        | `object`             | Y    |        | jQuery事件对象 |
| `settings` | `Datatable.settings` | Y    |        | 表格的设置项   |

示例：

```js
$(document).on( 'preInit.dt', function (e, settings) {
    var api = new $.fn.dataTable.Api( settings );
 
    api.page.len( 20 );
} );
 
$('#example').DataTable();

3.11 preXhr

此事件在DataTables向服务器发出Ajax请求获取数据之前触发，因此与Ajax请求从服务器成功返回数据后触发的xhr事件对应。preXhr事件是为插件作者设计的，他们可以在扩展中侦听该事件并发送可能需要的任何其他数据。它与ajax非常相似。具有此功能的数据，该选项通常由为其表编写初始化代码的人使用，而不是插件作者。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项
data	object	Y		请求的参数

该事件一定要在表格初始化前进行绑定

示例：

$('#example').on('preXhr.dt', function(e, settings, data) {
    console.log(data)
})

var table = $('#example').DataTable({
    ajax: { url: 'data2.json', data: { a: 1, b: 2 } },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

外链图片转存中...(img-ePxKlydT-1708678487823)

通过该事件就可以在发起请求前对请求参数进行处理。

3.12 xhr

在处理Ajax数据时，知道DataTables何时完成了数据加载通常是很有用的，这样您就可以根据DataTables的配置(columns.data)将数据操作成DataTables期望的格式，也可以将服务器的JSON响应中包含的数据用于页面的其他部分。

事件触发方法参数如下：

名称	类型	非空	默认值	描述
e	object	Y		jQuery事件对象
settings	Datatable.settings	Y		表格的设置项
json	object	Y		请求后得到的原始数据
xhr	object	Y		jQuery XHR对象

示例：

var table = $('#example').DataTable({
    ajax: { url: 'data2.json', data: { a: 1, b: 2 } },
    columns: [
        { data: 'name' },
        { data: 'position' },
        { data: 'office' },
        { data: 'salary' },
    ],
    order: [[1, 'asc']],
})

$('#example').on('xhr.dt', function(e, settings, json, xhr) {
    console.log(json, xhr)
})