模块

DataTable

可选模块附带的交互式数据网格。排序、多类型筛选、分页、行选择、列管理和完全可主题化的框架无关渲染器 — 通过纯列定义配置。

安装

DataTable 是一个独立模块 — 它不依赖任何图表库，可以单独使用。导入类，指向一个容器元素和一个数据数组即可。

import { DataTable } from 'katucharts.js/datatable';

const table = new DataTable('#grid', { data: rows });

该模块自动带有作用域样式表；你无需手动导入任何 CSS。

快速开始

将行作为数据传递，并描述每一列。未提供列时，网格会从第一行推断列信息。

const rows = [
  { id: 'm5gr84i9', amount: 316, status: 'success',    email: '[email protected]' },
  { id: '3u1reuv4', amount: 242, status: 'success',    email: '[email protected]' },
  { id: 'derv1ws0', amount: 837, status: 'processing', email: '[email protected]' },
];

new DataTable('#grid', {
  data: rows,
  columns: [
    { accessorKey: 'status', header: 'Status' },
    { accessorKey: 'email',  header: 'Email' },
    { accessorKey: 'amount', header: 'Amount', type: 'number' },
  ],
  pagination: { pageSize: 10 },
  filtering: { enabled: true },
});

列

每列是一个对象。使用 accessorKey、header、cell、enableSorting 及相关属性 — 或 KatuCharts 自有的 field、title 和 formatter 名称，这些等效接受。

属性	类型	默认值	描述
`accessorKey`	string	—	用于访问此列值的行对象键。field 的别名。
`accessorFn`	(row) => any	—	从整个行而不是单一键派生值，例如 row => row.first + ' ' + row.last。
`id`	string	accessorKey	显式列 ID。对于没有 accessorKey 的列（操作列或复选框列）是必需的；否则默认为 accessorKey。
`header`	string \| (ctx) => Node	—	头部内容。可以是纯文本标签字符串，也可以是接收 column 和 table 参数并返回标记或 DOM 节点的函数。
`cell`	(ctx) => string \| Node	—	自定义单元格渲染器，接收 row、column、getValue 和 table 参数。返回 HTML 字符串或 DOM 节点。formatter 的别名。
`type`	string	'string'	值类型 — string、number、date、boolean 或 html。驱动默认对齐、格式化和推断的筛选类型。
`enableSorting`	boolean	true	列是否可排序。sortable 的别名。在操作/复选框列上设置为 false。
`enableHiding`	boolean	true	列是否出现在列可见性菜单中并可被切换关闭。
`enableColumnFilter`	boolean	true	列是否显示筛选控件。filterable 的别名。
`filterType`	string	—	列的筛选 UI — 参见筛选部分。省略时从 type 推断。
`filterFn`	(row, id, val) => boolean	—	自定义谓词 (row, columnId, filterValue) => boolean，覆盖内置筛选逻辑。
`size / minSize / maxSize`	number	—	列宽，单位像素（别名 width）。minSize / maxSize 限制调整大小范围。
`pinned`	'left' \| 'right'	—	将列固定到 'left' 或 'right' 边缘，使其在滚动时保持可见。
`align`	string	—	文本对齐 — left、center 或 right。根据列类型默认应用。
`meta`	object	—	任意数据，你可以在 header / cell 回调中读回。

accessorKey 和 field 可互换，header（字符串）和 title 也可互换，cell 和 formatter 亦然。使用你喜欢的命名习惯；在不同列中混用它们都是可以的。

单元格和标头渲染

在单元格或表头中显示任何内容。column 的 cell 函数渲染其内容——返回文本、HTML 字符串或 DOM 节点——header 函数构建自定义表头标记，例如可排序的按钮。

const usd = (n) => new Intl.NumberFormat('en-US',
  { style: 'currency', currency: 'USD' }).format(n);

columns: [
  // function header with a sort button
  {
    accessorKey: 'email',
    header: ({ column }) => {
      const b = document.createElement('button');
      b.textContent = 'Email';
      b.onclick = () => column.toggleSorting();
      return b;
    },
  },
  // cell returning markup
  {
    accessorKey: 'amount',
    header: () => '<div style="text-align:right">Amount</div>',
    cell: ({ row }) =>
      `<div style="text-align:right">${usd(row.getValue('amount'))}</div>`,
  },
  // an action / checkbox column has no accessorKey — give it an id
  { id: 'actions', cell: ({ row }) => renderMenu(row.original) },
]

每个回调接收 row、column 和 table 的值，你可以用它们读取数据并驱动数据网格：

辅助方法	描述
`row.getValue('field')`	读取当前行中某个 column 的值。
`row.original`	完整的原始 row 对象。
`row.toggleSelected()`	选中或清除该行。
`column.toggleSorting()`	按此 column 对网格排序。
`column.setFilterValue(value)`	按值筛选此 column。
`table.nextPage()`	转到下一页（也可用 previousPage()）。
`table.toggleAllPageRowsSelected()`	选中当前页面上的所有行。

相同的帮助程序在回调外通过 table.getTableApi() 可用，用于构建自定义工具栏或控件。

排序

排序默认开启；点击标头循环升序 → 降序 → 未排序。在全局禁用它、启用多列排序或设置初始排序。

new DataTable('#grid', {
  data: rows,
  sorting: {
    enabled: true,
    multiSort: true,
    defaultSort: [{ column: 'amount', direction: 'desc' }],
  },
});

// or set an initial state
new DataTable('#grid', {
  data: rows,
  initialState: { sorting: [{ id: 'amount', desc: true }] },
});

启用 multiSort 后，Shift-点击标头按多列排序；小徽章显示每列的排序优先级。

筛选

网格提供全局搜索框加每列筛选行。两者都可独立开启或关闭，每列选择（或推断）多种筛选类型之一。

可通过设置 filtering.enabled = false 关闭整个筛选行，或通过 filterable: false（enableColumnFilter: false）隐藏单个列的筛选器。当有任何筛选器活跃时，“重置筛选器”按钮会自动显示。

名称	描述
`text`	子字符串匹配（默认不区分大小写）。
`number`	精确值或最小/最大范围。
`numberrange`	两个输入框界定数值范围。
`select`	列不同值的单选下拉菜单。
`multiselect`	多选下拉菜单 — 匹配任何选定值的行通过。
`faceted`	带计数徽章的 Faceted 多选弹出框。
`boolean`	True / False / All 下拉菜单。
`date`	单日期匹配。
`daterange`	开始/结束日期边界。

在工具栏启用全局搜索框；它匹配所有可见列（或选定的子集）。

new DataTable('#grid', {
  data: rows,
  search: { enabled: true, placeholder: 'Search…' },
  filtering: { enabled: true },          // per-column filter row
  columns: [
    { accessorKey: 'email', header: 'Email' },                        // text filter
    { accessorKey: 'status', header: 'Status', filterType: 'faceted' },
    { accessorKey: 'amount', header: 'Amount', type: 'number',
      filterType: 'numberrange' },
    { accessorKey: 'id', header: 'ID', filterable: false },           // no filter
  ],
});

Faceted 类型呈现多选弹出框，从数据自动构建其选项。

分页

分页默认开启。配置页面大小、提供的大小选项及渲染的控件。

属性	类型	默认值	描述
`enabled`	boolean	true	打开或关闭分页。关闭时，所有行渲染（超过阈值时使用虚拟滚动）。
`pageSize`	number	25	每页行数。
`pageSizes`	number[]	[10,25,50,100]	每页行数下拉菜单中提供的大小。
`position`	'top' \| 'bottom' \| 'both'	'bottom'	页脚渲染位置 — top、bottom 或 both。
`showPageSizeSelector`	boolean	true	显示每页行数下拉菜单。
`showPageInfo`	boolean	true	显示'显示第 1–10 行，共 42 行'摘要。
`showFirstLast`	boolean	true	显示跳转到第一页/最后一页按钮。

行选择

启用单行或多行选择，可选复选框和标头全选。

const table = new DataTable('#grid', {
  data: rows,
  selection: { mode: 'multi', checkbox: true },
});

table.on('selection:change', ({ selected }) => {
  // do something with the selected rows
});

属性	类型	默认值	描述
`mode`	'none' \| 'single' \| 'multi'	'none'	'none'、'single' 或 'multi'。
`checkbox`	boolean	false	渲染复选框列（多选模式下还有标头全选复选框）。
`selectAll`	boolean	true	允许标头复选框选择页面上的每一行。
`preserveOnFilter`	boolean	false	筛选器更改时保持当前选择，而不是清除它。

列管理

除了渲染，列可以隐藏、固定、调整大小和重新排序。调整大小默认开启；其他的可选。

“列”工具栏菜单可切换每个列的显示/隐藏（遵守 enableHiding）。通过设置 columnVisibility.enabled = false 隐藏按钮。
可通过列上的 pinned 属性或使用 columnPinning.enabled = true 结合 pinColumn() 方法将列固定到左侧或右侧。
拖动列头的右边缘可调整大小。通过 columnResizing.enabled = false 禁用此功能。
通过设置 columnReordering.enabled = true 启用拖拽排序。

主题化和 CSS

整个视觉层由单个类上的 --kdt-* CSS 自定义属性驱动，因此你可以通过设置一个变量重新主题化 — 不需要 !important。每个部分也有稳定的类名，你可以直接定位。

在 .katucharts-datatable（或其包装器）上设置以下任何内容来重新主题化。网格提供合理的浅色默认值和内置深色调色板。

变量	描述
`--kdt-bg`	表格背景。设置为 transparent 融入页面。
`--kdt-popover-bg`	下拉菜单 / faceted 菜单的背景 — 即使表格背景透明也保持不透明。
`--kdt-fg`	默认文本颜色。
`--kdt-muted`	微妙的表面（标头、分组行、徽章）。
`--kdt-muted-fg`	辅助 / 标头 / 占位符文本颜色。
`--kdt-border`	边框和分隔线颜色。
`--kdt-accent`	行、按钮和菜单项的悬停/活跃表面。
`--kdt-primary`	主要强调色 — 选定的复选框、活跃的分页按钮。
`--kdt-radius`	容器、输入、按钮和菜单的圆角半径。
`--kdt-row-height`	正文行高（也可通过 density 设置）。
`--kdt-font-family`	整个网格的字体族。

/* Re-theme by setting variables on a wrapper — no !important */
.my-grid .katucharts-datatable {
  --kdt-primary: #b43417;
  --kdt-radius: ;
  --kdt-accent: #fbeae5;
}

主题化和 CSS · classNames

更喜欢附加自己的类？传递 classNames 对象来挂接任何部分 — root、toolbar、table、header、row、cell、footer 和 pagination。

new DataTable('#grid', {
  data: rows,
  classNames: { root: 'my-grid', row: 'my-row', cell: 'my-cell' },
  style: { theme: 'dark', density: 'compact', radius: 12 },
});

density: 'compact' | 'normal' | 'comfortable' 调整行高和填充。工具栏'密度'项让用户实时切换。

通过设置 style.theme = 'dark'（或在根元素上设置 data-theme="dark"）将整个网格切换到深色模式。

style 对象也接受高级快捷方式（borderColor、accentColor、radius、fontFamily、alternateRowColor、hoverRowColor …），这些会为你翻译成匹配的 CSS 变量。

事件

通过 events 选项（或 .on(name, handler) 方法）订阅以响应用户交互。

事件	描述
`rowClick`	行被点击——payload: row, rowIndex, originalEvent。
`cellClick`	单元格被点击——payload: value, row, column, rowIndex, colIndex。
`selectionChange`	选择状态改变——payload: selected, added, removed。
`sortChange`	排序改变——payload: column, direction, multiSort。
`filterChange`	筛选器改变——payload: column, value, allFilters。
`pageChange`	分页改变——payload: page, pageSize, totalPages。
`cellEdit`	单元格被编辑——payload: row, column, oldValue, newValue。

本地化

内置的界面文本——搜索和筛选占位符、分页、导出和密度菜单、列控件——提供多种语言。你可以显式选择语言、让表格跟随浏览器，或覆盖个别文本。

默认情况下，表格会自动检测浏览器语言，无匹配时回退到英文。设置 locale 可固定语言；一旦设置便不会自行更改。

// Auto-detect from the browser language (default)
new DataTable('#grid', { data: rows });

// Pin a locale — stays fixed regardless of the browser
new DataTable('#grid', { data: rows, locale: 'pt-BR' });

开箱即用的语言：

语言	描述
`en`	英文（基础／回退）。
`pt-BR`	葡萄牙文（巴西）。
`es`	西班牙文。
`zh`	简体中文。

未知或部分匹配的语言（例如 pt-PT）会先按主语言回退，然后回退到英文。

覆盖个别文本

传入 lang 可覆盖当前语言的任意文本。按键覆盖始终优先于语言包，因此你可以固定语言并仍自定义个别标签。

new DataTable('#grid', {
  data: rows,
  locale: 'pt-BR',
  lang: { search: 'Procurar produtos…' },   // wins over the locale pack
});

使用 setLocale 在运行时切换语言——表格会重新渲染并保留 lang 覆盖。

const table = new DataTable('#grid', { data: rows });
table.setLocale('es');   // switch language and redraw

在创建表格前使用 registerLocale 添加你自己的语言；省略的文本会回退到英文。

import { DataTable, registerLocale } from 'katucharts.js/datatable';

registerLocale('fr', { search: 'Rechercher…', noData: 'Aucune donnée' });
new DataTable('#grid', { data: rows, locale: 'fr' });

分页箭头（« » ‹ ›）与语言无关，不会翻译；如需不同符号，可通过 lang 覆盖。

选项参考

传递给 new DataTable(container, options) 的顶级选项。功能块是对象，因此你可以在一个位置启用和配置每个功能。

选项	类型	描述
`data`	any[]	行数组。稍后可用 setData() 替换。
`columns`	ColumnDefinition[]	列定义。省略时从数据推断。
`rowKey`	string	用作稳定行标识的字段。
`sorting`	object	排序行为 — enabled、multiSort、defaultSort。
`filtering`	object	每列筛选 — enabled、position、showReset。
`search`	object	全局搜索框 — enabled、placeholder、columns、debounceMs。
`pagination`	object	分页 — 见上面的分页表。
`selection`	object	行选择 — 见上面的选择表。
`columnVisibility`	object	列可见性工具栏菜单 — enabled。
`columnPinning`	object	列固定 — enabled。
`columnResizing`	object	列调整大小 — enabled（默认 true）。
`columnReordering`	object	拖动重新排序列 — enabled。
`grouping`	object	按一列或多列分组行并带有聚合。
`virtualScroll`	object	大型数据集的虚拟化渲染 — enabled、rowHeight、threshold。
`exporting`	object	CSV / JSON / 剪贴板导出和导出工具栏菜单 — enabled、formats。
`serverSide`	object	通过 URL 的服务器端数据、排序、筛选和分页。
`toolbar`	object	工具栏 — enabled 及显示的项（search、columnToggle、export、density…）。
`style`	object	视觉风格 — density、theme、colors 和 CSS 变量快捷方式。
`classNames`	object	各部分类钩。
`initialState`	object	便利的起始状态 — pageSize、sorting、columnVisibility、columnFilters。
`events`	object	事件处理器。
`locale`	string	内置文本的语言代码（省略或 'auto' 会从浏览器自动检测，任意其他值则固定）。
`lang`	object	覆盖 UI 字符串（页面信息、无数据、按钮标签…）。

程序化 API

实例暴露方法来从你自己的代码驱动网格。

方法	描述
`setData`	setData(rows) — 替换所有数据；未设置列时重新推断。
`getData / getSelectedRows`	getData() / getFilteredData() / getSelectedRows() — 读取当前行。
`sort / clearSort`	sort(column, direction?) / clearSort() — 控制排序。
`setFilter / clearFilter`	setFilter(column, value) / clearFilter(column?) — 控制筛选器。
`search / clearSearch`	search(query) / clearSearch() — 驱动全局搜索。
`goToPage / setPageSize`	goToPage(n) / setPageSize(n) — 控制分页。
`showColumn / pinColumn`	showColumn(field) / hideColumn(field) / pinColumn(field, dir) — 管理列。
`selectRow / selectAll`	selectRow(i) / deselectRow(i) / selectAll() / deselectAll()。
`exportCSV / exportJSON`	exportCSV() / exportJSON() / copyToClipboard() — 导出数据。
`getTableApi`	getTableApi() — 表格帮助程序对象，用于自定义集成。
`update / redraw / destroy`	update(options) / redraw() / destroy() — 更新或拆除网格。

这些选项是分层的：用其块启用功能，逐个细化列，通过 CSS 变量主题化一切。浏览主页上的实时网格。