smart-naive-table

smart-naive-table

写好 columns，一个完整的后台列表页就出来了；宽屏是表格，手机上自动变卡片。 搜索、过滤、排序、分页、字典标签、列设置、可编辑，全部从列配置里长出来。

简体中文 | English

亮点

• 列驱动，一份配置长出整页：搜索表单、条件构造器、表头过滤、字典标签、格式化、列设置、可编辑控件，全部从 columns 派生，不用再写一套并行配置。
• 移动端自适应：开 card-on-narrow，容器宽度 < 600 时表格自动换成卡片列表，业务按钮折叠成「操作 ▾」，搜索收成「输入框 + 筛选」底部抽屉，排序走底部抽屉，控件放大到触控尺寸（40px）；可编辑表格在窄档点卡片开底部抽屉表单。同一份 columns，不写第二套移动端代码。分档按容器宽度而不是视口宽度，嵌在侧栏 / 弹窗里也对。
• 条件搜索 + 表头过滤：一行式「字段 + 比较符 + 值」条件构造器，列头漏斗面板支持勾选或多条件（≤ 5 条、且 / 或），15 个操作符，已生效条件 chips；远程模式产出统一的 filters 参数，静态数据模式前端直接求值。
• 官方优先，不另起炉灶：它是 Naive UI 的上层封装，n-data-table 的属性原样透传；明暗主题和语言跟随 <n-config-provider>；运行时依赖只有 sortablejs（开启行拖拽才加载）。
• 大数据与嵌入：fill-height 铺满定高父容器、虚拟滚动、分页条贴底；每页条数可到 10000；页面内放大、批量栏、「更多」菜单。
• Excel 式可编辑表格：按数据类型推断控件，批量保存 + 脏标记 + 放弃，Excel 粘贴、撤销、行级只读、异步校验；外部 / 主数据用 select-table 下拉表格。
• 下拉表格选择 SmartSelectTable：触发器像下拉框，点开是「搜索框 + 带分页的表格」，单选 / 多选、本地或远程。
• 开箱即用的工程细节：完整 TypeScript 类型、中文文案包 zhCNLabels、labels 渲染期求值（切语言即时生效）、全局默认值、storage-key 持久化列设置。

功能清单

下表按「组件预览」的 15 个模块组织（侧栏 查询 / 列 / 行 / 数据 / 布局 五组）。预览列写的是模块号：npm run dev 后打开 http://localhost:5173/prototype.html?m=<模块号>（&theme=dark 切暗色），就能看到对应功能的真实表现；窄档在浏览器里把窗口缩到 400 宽左右即可。预览列写「—」的是预览没有单独模块、但库里有实现的能力。带 ★ 的是最值得一试的几项。

另外：完整 TypeScript 类型；useSmartTable（脱离 UI 的数据核心）、过滤内核函数等工具可单独使用（见 其它导出）。

截图

下面所有截图都是从「组件预览」（/prototype.html，真实 SmartTable 渲染）实际截取的，不是设计稿截图。拍摄脚本是 tools/parity/readme-shots.mjs。

同一份配置，宽档 / 窄档，明 / 暗（预览模块 2「条件搜索」）：

窄档的底部抽屉：左 = 点「排序」（预览模块 4，暗色）；右 = 可编辑表格里点卡片，整行表单（预览模块 14，亮色）。

表头过滤（预览模块 3）：点列头漏斗，勾选式面板 + 「高级条件」，已生效条件在表格下方以 chips 显示。

列设置（预览模块 7）：显隐、拖拽排序、固定到左 / 右、恢复默认。

可编辑表格（预览模块 14）：改过的格左上角有小三角，工具栏出现「放弃修改」和「保存修改(N)」，合计行实时更新。

下拉表格 select-table（预览模块 14，暗色）：点开「工序名称」，浮层里是「搜索框 + 带分页的表」，选一行自动带出其它列。

移动端自适应

开 card-on-narrow，同一份 columns 就同时适配宽屏和手机，不需要第二套移动端代码：

<SmartTable :columns="columns" :fetcher="fetcher" card-on-narrow />

• 分档按容器宽度（不是视口宽度）：库根节点宽度 < 600 为窄档，< 1280 为中档，其余为宽档；用 ResizeObserver 量根节点，嵌在侧栏 / 弹窗 / 放大层里也按它自己的宽度判定。中档与宽档的条件搜索栏所在工具栏是同一套排布：头部、条件栏、操作区排成一行，放得下就并排，放不下条件栏折到下一行；条件栏里的值输入框封顶 320px，可用 CSS 变量 --smart-table-cond-value-max-width 调。
• 默认关闭：不开 card-on-narrow 时，窄容器与宽容器是同一套表格与工具栏（窄容器下分页也不画每页条数选择器）。
• 卡片列表：第一个数据列作卡片标题，其余列是两列「标签：值」，操作列（card: 'action'，缺省取最后一个 fixed: 'right' 的列）放在卡片底部；列上写 card: 'title' | 'meta' | 'action' | 'handle' | false 可覆盖；列设置里隐藏的列卡片里同样隐藏。点卡片 = @row-click，勾选框在卡片右上角，宿主绑的 checked-row-keys / expanded-row-keys 照常生效。
• 触控尺寸：工具栏按钮、输入框、分页项统一放大到 40px（官方 large）；窄档不画每页条数选择器，分页用官方 simple。
• 工具栏折叠：业务按钮（#toolbar-right + 「更多」）收成「操作 ▾」，点开在原位多出一行。宿主传了 #toolbar 时，头部（标题 + #toolbar）独占第一行、放不下就换行，「操作 ▾」靠左、内置图标靠右落到第二行（不传 #toolbar 时是单行）。
• 搜索收成「输入框 + 筛选」：用条件构造器（search: { container: 'table' }）时，窄档只留一个输入框和「筛选」按钮，点「筛选」从底部抽屉展开同一份多条件面板。
• 排序抽屉：有可排序列时，工具栏最下面多一行「排序」按钮，点开底部抽屉，每列「无 / 升序 / 降序」（只能启停，不改优先级）。
• 底部面板：可编辑表格（editable）在窄档点卡片 = 底部抽屉表单（整行即时保存，其中的 select-table 字段点开贴底选择面板）；SmartSelectTable 在视口 < 600 或放不下浮层时也改用底部面板。
• 行拖拽：卡片保留拖拽，手柄列写 card: 'handle'，放在标题行最左；开了 row-draggable 的卡片在标题行末尾显示行号。
• 合计卡：宿主给了 naive 的 summary（合计行）时，窄档卡片列表末尾多一张「合计」卡。
• 树表：行里带 children（字段名取 children-key，默认 children）的树表在卡片里按先序拍平，标题按层级缩进（每层 indent，默认 16px），有子级的卡片标题前有展开 / 折叠箭头。读的都是 NDataTable 的官方属性（children-key、indent、expanded-row-keys、default-expanded-row-keys、default-expand-all、cascade），不需要库自己的额外属性；分页 / 排序只作用于根行（同官方），勾选按 cascade 级联、父卡片半选。没绑 expanded-row-keys 时展开态由库持有（表格 ↔ 卡片切档不互通，绑上就互通）。不支持：懒加载（on-load）、check-strategy、row-draggable / editable 与树同用。
• chips 与分页：已生效条件 chips 在窄档单独占一行、放在分页上方。
• 限制：列头漏斗的窄档抽屉（卡片模式没有表头，漏斗没有入口；需要筛选请用条件构造器）；卡片列表不做虚拟滚动（窄档不能改每页条数，默认每页 100）。列设置在窄档是气泡，不是抽屉。

预览里 15 个模块的主表都带 card-on-narrow（窗口缩到 400 宽左右，或用浏览器的设备模拟 390 × 844）：模块 2 / 3 / 4 看条件搜索、筛选抽屉与排序抽屉，模块 10 看卡片里的拖拽手柄，模块 14 看卡片点开的底部抽屉表单，模块 15 看树表卡片（展开 / 折叠、级联勾选）。

安装

npm i smart-naive-table

项目中需已安装 vue >= 3.3 和 naive-ui >= 2.44（peerDependencies 是 vue ^3.3.0、naive-ui ^2.44.0；验证过的版本是 naive-ui 2.45.3）。ESM 输出，自带 TypeScript 类型。

快速开始

<script setup lang="ts">
import { SmartTable, type SmartTableColumn, type SmartTableFetcher } from 'smart-naive-table'

interface User {
  id: number
  account: string
  name: string
  status: number
  createTime: string
}

// ① 定义列：search 生成搜索项；options + tag 把状态值翻译成彩色标签
const columns: SmartTableColumn<User>[] = [
  { type: 'index' },
  { key: 'account', title: '账号', search: true },
  { key: 'name', title: '姓名', search: true },
  {
    key: 'status',
    title: '状态',
    search: true,
    tag: true,
    options: [
      { label: '在职', value: 1, tagType: 'success' },
      { label: '离职', value: 2, tagType: 'error' },
    ],
  },
  { key: 'createTime', title: '创建时间', format: 'datetime' },
]

// ② 对接后端：把接口返回值转换成 { items, total }
const fetcher: SmartTableFetcher<User> = async ({ page, pageSize, ...query }) => {
  const res = await getUserPage({ current: page, size: pageSize, ...query }) // 换成你的接口
  return { items: res.records, total: res.total }
}
</script>

<template>
  <!-- ③ 渲染；storage-key 用来记住用户的列设置 -->
  <SmartTable :columns="columns" :fetcher="fetcher" storage-key="user-list" />
</template>

这样就得到一个完整的列表页：

• 搜索区：「账号」「姓名」输入框、「状态」下拉框（选项来自 options），以及查询 / 重置按钮
• 表格：序号、状态标签、格式化后的时间，底部带分页
• 工具栏：刷新（仅远程模式）、列设置

点击「查询」时，fetcher 收到的参数（空值已自动剔除）：

{ page: 1, pageSize: 100, account: 'user01', status: 1 }

提示：把 SmartTable 放在 <n-config-provider> 内，主题和语言都跟随它。组件自带文案默认是英文，中文项目请看 全局配置与中文文案。更完整的演示见 playground/DemoBasic.vue；上面「截图」里各个表格的源码在 playground/prototype/。

常用写法

搜索项

{ key: 'name', title: '姓名', search: true }                           // 输入框
{ key: 'status', title: '状态', options: statusOptions, search: true } // 有 options 时自动用下拉框
{ key: 'age', title: '年龄', search: { type: 'number' } }              // 指定控件类型
{ key: 'keyword', title: '关键字', hideInTable: true, search: true }   // 只做搜索项，不显示成列

// 日期范围，参数名指定为 createRange → fetcher 收到 createRange: ['2024-01-01', '2024-01-31']
{ key: 'createTime', title: '创建时间', search: { type: 'daterange', key: 'createRange' } }

控件类型：input（默认）、number、select、date、daterange、switch；需要完全自定义时用 search.render。全部字段见 SearchConfig。

搜索区布局：

<SmartTable :search="{ collapsible: true, collapsedRows: 1 }" /> <!-- 超过 1 行时折叠，带展开 / 收起 -->
<SmartTable :search="{ layout: 'inline' }" />                    <!-- 无卡片、单行排列，适合窄栏 -->
<SmartTable :search="{ container: 'table' }" />                  <!-- 模式 2：条件构造器（字段 + 比较符 + 值），并入表格卡片，产出走 filters -->
<SmartTable :search="false" />                                   <!-- 不显示搜索区 -->

模式 2「条件构造器」（search: { container: 'table' }）：搜索区并入表格卡片的一行「字段 + 比较符 + 值」，点「更多条件」（»）展开多条件面板；字段候选 = 声明了 search 的列（带 search.render、type: 'switch' 的列放不进一行，不进构造器），比较符取 search.actions，缺省取 filter.actions，再缺省取按类型的推荐集合（导出常量 RECOMMENDED_ACTIONS）。条件和列头漏斗共用同一份过滤态，请求里带的是 filters（经 filterSerializer），而不是扁平的搜索参数；默认开 filter-chips（可显式关掉）；容器宽 < 600 时收成「输入框 + 筛选」，点「筛选」从底部抽屉展开同一份条件面板。

字典、标签与格式化

import type { SmartTableOption } from 'smart-naive-table'

const statusOptions: SmartTableOption[] = [
  { label: '在职', value: 1, tagType: 'success' },
  { label: '休假', value: 2, tagType: 'warning' },
  { label: '离职', value: 3, tagType: 'error' },
]

{ key: 'status', title: '状态', options: statusOptions, tag: true }   // 显示为彩色标签
{ key: 'deptId', title: '部门', options: () => api.getDeptOptions() } // 异步字典：自动 loading、并发去重
{ key: 'salary', title: '薪资', format: 'money' }                     // 6,000.00
{ key: 'birthday', title: '生日', format: 'date' }                    // 2024-01-01
{ key: 'score', title: '得分', format: (v) => `${v} 分` }             // 自定义格式

options 支持静态数组、ref、异步函数三种写法；异步字典可调用实例方法 reloadOptions() 重新拉取。

操作列与自定义单元格

import { h } from 'vue'
import { NButton } from 'naive-ui'

{
  key: 'actions',
  title: '操作',
  width: 120,
  fixed: 'right',
  hideInSetting: true, // 不出现在列设置面板里
  render: (row) => h(NButton, { text: true, type: 'primary', onClick: () => edit(row) }, () => '编辑'),
}

不想写 render 函数，也可以用插槽：

<SmartTable :columns="columns" :fetcher="fetcher">
  <template #cell-name="{ row }">
    <a @click="open(row)">{{ row.name }}</a>
  </template>
</SmartTable>

单元格渲染优先级：render → #cell-{key} 插槽 → options 翻译 → format → 原始值。

列设置

点击工具栏最右侧的图标打开（效果见上面的截图），可以勾选显隐、拖拽排序、固定到左 / 右侧。

• 传了 storage-key 就会保存到 localStorage，刷新页面不丢失
• 列定义改动后自动合并：删掉的列被剔除，新增的列插到声明位置
• hide: true 初始隐藏（可在面板中勾回）；hideInSetting: true 不进面板

表头过滤

列上加 filter 就会在表头出现漏斗图标，面板有两种形态，按列自动选：

• 勾选式（列上有 options）：直接勾选字典项，多选时内部等价于「若干 等于 条件取或」（multiple: false 用官方单选按钮）；底部「高级条件」可切到多条件编辑，勾选表达不了的条件（如 不等于）会自动展开在这里，不会丢
• 条件式（列上没有 options）：多行「动作 + 值」（最多 5 条，≥ 2 条时可选「且 / 或」）；动作按值类型给默认集合（文本给 包含 / 不包含 / 等于 / 不等于，数字和日期给 等于 / 大于 / 小于 等）
• 面板里改的是草稿，点「确定」才生效；Esc 关闭并丢弃草稿，Tab 在面板内循环

const columns: SmartTableColumn<Row>[] = [
  // 有字典 → 勾选式；multiple: false 变单选
  { key: 'status', title: '状态', options: statusOptions, tag: true, filter: true },
  // 没字典 → 条件式，文本列默认「包含 / 不包含 / 等于 / 不等于」
  { key: 'name', title: '姓名', filter: true },
  // 数字列：给一个初始过滤值（也是面板里「重置」的恢复目标）
  {
    key: 'salary',
    title: '薪资',
    format: 'money',
    filter: { defaultValue: { logic: 'and', conditions: [{ action: 'gte', value: 10000 }] } },
  },
  // 日期列：值是纯日期串时按「整天」比较，「等于 2024-03-05」能命中当天任意时刻
  { key: 'createTime', title: '创建时间', format: 'datetime', filter: true },
]

远程模式（传了 fetcher）过滤在后端做：条件变化后回到第 1 页重查，参数默认长这样，后端照着翻成 SQL / ORM 条件即可：

{
  "page": 1,
  "pageSize": 100,
  "filters": [
    { "field": "name", "logic": "and", "conditions": [{ "action": "contains", "value": "张" }] },
    { "field": "status", "logic": "or", "conditions": [{ "action": "equal", "value": 1 }, { "action": "equal", "value": 2 }] }
  ]
}

后端形状不一样就传自己的序列化器（也可以用 createSmartTableDefaults({ filterSerializer }) 全局设一次）：

<SmartTable :columns="columns" :fetcher="fetchList" :filter-serializer="toMyBackendShape" />

静态模式（传了 data）过滤在前端做，不用写任何适配代码。需要自定义匹配就写 filter.filter：

{ key: 'tags', title: '标签', filter: { filter: (value, row) => row.tags.some((t) => matchFilterValue(value, t)) } }

面板也可以整个自己画，ctx 含 value、setValue、close：

{ key: 'deptId', title: '部门', filter: { render: ({ value, setValue, close }) => h(MyPanel, { value, setValue, close }) } }

过滤态可以编程式读写：tableRef.filters、tableRef.setFilter(key, value)、tableRef.clearFilters()，变化时触发 @filter-change。

想让用户一眼看到当前生效的条件，加 filter-chips：表格下方、与分页同一行（左 chips、右分页；没有分页时在表格下方自成一行）多出已生效条件 chips，点 chip 重开该列面板、× 删掉这一条，放不下时折成「+N」；有列声明了 defaultValue 时，偏离默认才出现「恢复默认」，否则 ≥ 2 个 chip 时出现「清除全部」：

<SmartTable :columns="columns" :fetcher="fetchList" filter-chips />

整表一键关掉（和 :search="false" 同一套写法，列上的 filter 声明一并失效）：

<SmartTable :columns="columns" :fetcher="fetchList" :filter="false" />

也可以 createSmartTableDefaults({ filterable: false }) 全局关，再用实例上的 :filter="true" 单独打开某张表。

列宽拖拽

表格上加 resizable，所有数据列的表头右边缘就能拖动改宽：

<SmartTable :columns="columns" :fetcher="fetchList" storage-key="staff" resizable @column-resize="onResize" />

• 单独某列不想让拖：列上写 resizable: false（列上的值永远优先于表格上的开关）
• 传了 storage-key 就会连同列设置一起存进 localStorage，刷新页面保持
• 拖动过程中持续触发 @column-resize（key、width），写 localStorage 内部做了防抖
• 拖某一列只改这一列：首次拖动时会把所有列（含序号 / 勾选列）钉成当前实际宽度，同时把表格切到 table-layout: fixed、宽度写死成列宽之和。此后左侧的列纹丝不动，只有被拖的列跟着鼠标走
• 表格始终填满容器:列宽之和小于容器时,富余宽度由**最后一个可见、非固定、可拖的列(吸收列)**吸收(表头里没有占位列),其余列仍是拖出来的精确宽度;加宽到超过容器则照常横向滚动。吸收列没有拖拽把手(即使还没拖过列宽也没有):要调它的宽度,拖它左邻列的把手;给某列写 resizable: false 可让它不参与吸收(吸收列顺延到前一列)。想回到按容器自适应,点列设置里的「恢复默认」
• 拖不到 0 宽:可拖拽列自动补 minWidth:默认 60,带排序 / 过滤图标的列取 max(60, 图标下限)(仅排序 93、仅过滤 102、两者 123);列上写了 minWidth 以列上的为准
• 列设置里的「恢复默认」会把宽度一起还原

分页

默认是官方 simple 分页（页码输入框 / 总页数），每页 100 条；可选项没显式给 pageSizes 时按 fill-height 区分：不开是 [100, 500, 1000]，开了是 [100, 1000, 10000]（一页上万行只有虚拟滚动扛得住），显式给了就照你的、不分 fill-height：

• 每页条数选择器是嵌在分页 suffix 里的官方 NPagination，文案跟随 <n-config-provider> 的语言（「100 / 页」），不需要额外配置文案；pageSizes 里写 { label, value } 对象会原样显示，当前每页条数不在选项里时自动并入
• 窄档（表格根节点宽度 < 600px）不画每页条数选择器，免得分页条折行
• 默认每页条数的解析优先级：实例 default-page-size > 实例 pagination.pageSize / pagination.defaultPageSize > 全局 defaultPageSize > 宿主（实例或全局）显式给的 pageSizes 的第一项 > 100
• 想用页码序列：:pagination="{ simple: false }"（此时走官方 showSizePicker / pageSizes）；simple 下官方不渲染 showQuickJumper / pageSlot
• ⚠ 远程模式请求里的 pageSize 默认是 100：后端若限制了 pageSize 上限，请用 default-page-size 或 pageSizes 调小
• 改每页条数后回到第 1 页（远程、静态数据模式都一样）
• 远程请求失败（翻页 / 改每页条数 / 搜索）时，页码和每页条数还原到表里实际展示的那一页，分页条不会停在没拿到数据的页上；error 事件照常触发
• 不开 fill-height 时，翻页 / 改每页条数后若卡片顶部已滚出视口，页面会自动滚回卡片顶部；开了 fill-height 则表体在卡片内滚动、翻页后表体回顶

更多场景

调用表格方法

<script setup lang="ts">
import { ref } from 'vue'
import type { SmartTableInst } from 'smart-naive-table'

const tableRef = ref<SmartTableInst<User>>()

// 在需要的地方调用：
// tableRef.value?.refresh()  保持当前页刷新（如编辑之后）
// tableRef.value?.search()   回到第 1 页查询（如新增之后）
// tableRef.value?.reset()    清空搜索条件并查询
// tableRef.value?.sort('createTime', 'descend')  编程式排序；clearSorter() 清空
</script>

<template>
  <SmartTable ref="tableRef" :columns="columns" :fetcher="fetcher" />
</template>

可编辑表格

<SmartTable
  ref="tableRef"
  :columns="columns"
  :fetcher="fetcher"
  row-key="id"
  :editable="{ rowReadonly: (r: Row) => r.status === '停用', newRow: () => ({ status: '启用' }) }"
  @save="onSave"
/>

import type { EditSavePayload, SmartTableColumn } from 'smart-naive-table'

// Row = 表格行类型；Op = 工序库（主数据）的行类型
const columns: SmartTableColumn<Row>[] = [
  { type: 'selection', width: 40 },
  { key: 'rd', title: '', width: 48, card: 'handle', render: handleCell },   // 拖拽手柄(row-draggable + drag-handle)
  { type: 'index', title: '工序号', width: 80 },                           // 序号列:位置,不是数据、不可编辑、拖动后自己跟着变;声明在手柄后就排在手柄后
  { key: 'name', title: '工序名称', rules: { required: true },             // 表头自动带红 *
    // 外部 / 主数据 → select-table:点开是「搜索框 + 带分页的表」;fill 把选中行的其它字段一并填进本行(普通草稿编辑:各自脏标记、一步撤销)
    editorProps: { columns: opCols, data: opLibrary, valueKey: 'code', labelKey: 'name',
      fill: (op: Op) => ({ center: op.center, setup: op.setup }) } },
  { key: 'center', title: '工作中心', options: centers },                 // 下拉(> 8 项自动可搜索)
  { key: 'setup', title: '准备工时(分)', rules: { int: true, min: 0,
      // 跨行校验:第三个参数是表里当前所有行(含草稿)。validator 也可以返回 Promise(异步查重)
      validator: (v, row, rows) => true } },                               // 数据值 number → 数字框
  { key: 'report', title: '报工' },                                        // 数据值 boolean → 复选框
  { key: 'status', title: '状态', options: statuses, readonly: false },   // readonly: false = 不受 rowReadonly 影响(停用的行仍能改状态)
]

async function onSave({ changes, done, fail }: EditSavePayload<Row>) {
  try {
    // changes.rows:每项 { type: 'created' | 'updated' | 'deleted', row, changes? },updated 只含改过的字段
    await api.save(changes.rows)
    done() // 清草稿,远程模式自动刷新当前页;本地数据请先自己更新 data 再 done()
  } catch (e) {
    fail(e) // 保留草稿,不丢数据(同时触发 @error)
  }
}

• 推断：editor（显式）→ readonly / editor: false → 有 render / #cell-* → 不可编辑 → editorProps 里有 columns 且有 data 或 fetcher → select-table（外部 / 主数据：下拉里是一张带搜索 + 分页的表，见下面的 SmartSelectTable）→ options（下拉；值是数组 = 多选）→ format: 'date' | 'datetime' | 'money' → 数据值（前 20 行第一个非空值：boolean / number / 日期串 / 含换行或超过 30 字 → 多行 / 其余 → 输入框）→ 输入框。inferEditor(column, rows) 是公开的纯函数。
• 下拉的值类型：options 的 value 可以是数字或字符串。进入编辑后触发器显示选项文字（数字 id、枚举数值也一样：按 String() 双边比较对上选项，取该项自己的 value），提交写回的仍是选项自己的 value（数字不会变字符串）。单选的当前值对不上任何选项（空、0 而选项里没有 0、值已不在选项里）时触发器显示占位文字，不回显原始值；不选就离开按原有校验处理（必填的空、非空但不在选项里提示「请选择」并留在编辑态；非必填的空保持为空），Esc 放弃则格子保持原值。多选里对不上的项原样保留。select-table 的值按 labelKey 的文本比较，不受此影响。
• 键盘与剪贴板：↑ ↓ ← → / Tab / Shift+Tab 移动（只读列跳过；锁定的格可选中、可复制，只是不能编辑）；Enter / F2 进入编辑；直接打字替换原值；Space 切复选框；Delete 清空（必填列拒绝）；编辑中 Enter 提交下移、Shift+Enter 提交上移、Esc 放弃；Ctrl+C 复制选中格；Ctrl+V 粘贴 Excel 的单格或多格块（制表符分列、换行分行），从选中格起向右向下依次填充，按各列类型转换（数字去千分位、布尔认 TRUE / 是、选项按标签或值、日期补零）并校验，任何一格不合法则整块不应用；只读 / 锁定 / 待删的格跳过，超出当前列表的行忽略（不自动追加新行）；Ctrl+Z 撤销最近一次提交（栈 50，一次粘贴 = 一步，保存 / 放弃后清空，save: 'cell' 下不可用）。
• 保存：保存前统一校验（草稿格的同步规则 + 新增行全部格 + 异步校验的结果），不通过就不发 @save、选中第一个不合法的格并发 @invalid。异步 rules.validator：提交后单元格显示加载态、结果落定为不通过则标红（悬停看原因）、过期结果丢弃，「保存」会等它。
• 翻页 / 搜索 / 排序：不拦截；草稿叠在数据上，翻页 / 重新请求都保留（被筛选条件或翻页挡住的已改行看不见，但仍计入 N、仍会被保存，工具栏在「保存修改(N)」旁标出「含 M 条当前不可见」）。离开页面：有未保存修改时注册 beforeunload 提示（editable: { beforeunload: false } 可关）；宿主的路由守卫用实例的 isDirty / dirtyCount，再配合 save() / discard()。
• fillHeight / 虚拟滚动：可用。草稿在仓库里不在 DOM 里，编辑中的格滚出窗口再滚回来内容还在；方向键 / Tab 走到还没渲染的行会自动滚进视口。
• 下拉表格（select-table）：外部 / 主数据（几十行以上、或来自接口）用它，小的静态枚举用 options（> 8 项自动可搜索）。editorProps: { columns, data | fetcher, valueKey?, labelKey?, searchKeys?, fill? }，单元格的值 = 选中行的 labelKey 字段（缺省 = 本列 key）；fill(picked, row) 返回 { 其它列 key: 值 }，随选中一并写入（普通草稿编辑：各自脏标记、一次 Ctrl+Z 全部撤销、同样校验，任何一格不合法则整次不应用并标红）。粘贴的文本在有本地 data 时必须是已有的名称或 valueKey 编码（命中同样 fill），只给 fetcher 时照收文本。单元格内只支持单选（小枚举的多选用 multiselect）；窄档抽屉里它是一个触发框，点开贴底选择面板。
• 新增行：默认放第 1 行；editable: { add: { position: 'bottom' } } 追加到列表末尾（有顺序的数据，如工艺路线）。新增后自动进入编辑的是第一个「必填且为空」的格。add: false 隐藏工具栏按钮。
• 行级只读：rowReadonly 锁住的行里，列上写 readonly: false 的格不受影响（如「状态」，否则停用的行没法再启用）；窄档抽屉里被锁的字段置灰，标签列宽用 editable: { labelWidth }（缺省 72px）调。
• 可填格提示：缺省时能填的格与展示格同底色，锁定格 / 无编辑器的列只是字色偏灰，大表里不易分辨。editable: { fillHint: true } 给「有编辑器且未锁定」的格铺一层极淡的主色底（主色的 6%），悬停多一圈 1px 的内描边；锁定格、无编辑器的列、待删行的格仍是无底灰字。选中、校验错误、新增行的底色与描边优先（新增行内不再叠这层底），固定列的实底不受影响；窄档卡片没有逐格编辑，不加提示。缺省关闭。
• 锁定格灰底：与可填格提示相反的取向——可填格保持白色（行原有的底色），不能填的格灰一点。editable: { lockedFill: true } 给锁定的格（rowReadonly / 列 readonly 函数锁住的）与没有编辑器的数据列铺一层宿主主题的「禁用输入框」灰（Naive 主题变量 inputColorDisabled，明暗跟随主题，字色仍是次要文字色）；可填格不加底色，悬停多一圈 1px 的内描边，提示「点一下就能填」。灰多深由宿主主题决定：Naive 默认亮色主题的 inputColorDisabled 是不透明的 rgb(250, 250, 252)，只比白底深约 2%，很淡；要更明显，在宿主的 themeOverrides.common.inputColorDisabled 里设成半透明的灰，例如亮 rgba(100, 116, 150, .12)、暗 rgba(140, 170, 255, .05)。勾选 / 序号 / 展开列、card 为 'handle' / 'action' 或标题为空的列（拖拽手柄、操作列）、待删行的格不上灰；其它「只是控件、不是数据」的列在列上写 lockedFill: false 退出（写 true 强制上灰）。灰画成 inset box-shadow，与选中框、校验错误框、新增行色条合成，行悬停色、斑马纹、勾选行 / 当前行的高亮和固定列的实底都不受影响；窄档卡片没有逐格编辑，不加灰。可与 fillHint 同开但意义不大，推荐只开其一。缺省关闭。
• 序号列与拖拽：{ type: 'index' } 声明在某个数据列（如拖拽手柄列）之后时，就排在那一列后面；窄档 + row-draggable 的卡片会在标题行末尾显示行号（同「行拖拽排序」示例）。窄档卡片列表末尾，宿主给了 naive 的 summary（合计行）时多一张「合计」卡。
• 不做：填充柄、区域选择、合并单元格 / 公式、查找替换、右键菜单、跨结构变更的撤销、粘贴追加新行、复制行。

下拉表格选择 SmartSelectTable

独立组件（不依赖可编辑表格），用法像 NSelect：触发器点开是浮层（窄屏 = 底部抽屉），里面一个搜索框 + 嵌套的 SmartTable（分页、虚拟滚动、表头吸顶）；触发器右侧的箭头是放大镜（点开的是带搜索的选择面板，不是选项列表）。选物料、选工序、选客户这类「列表很长、要看多列才认得出」的场景都用它；可编辑表格的 select-table 编辑器就是它的一层薄封装。

<SmartSelectTable
  v-model:value="materialId"
  :columns="[{ key: 'code', title: '物料编号' }, { key: 'name', title: '物料名称' }, { key: 'spec', title: '规格' }]"
  :data="materials"
  label-key="name"
  clearable
/>
<!-- 远程 + 多选:fetcher({ page, pageSize, keyword }) → { items, total };v-model 是 valueKey 的数组 -->
<SmartSelectTable v-model:value="ids" multiple :columns="cols" :fetcher="fetchMaterials" @pick="(rows) => ..." />

• 属性：columns（SmartTable 的列）· data（本地）/ fetcher（远程，同 SmartTableFetcher，多一个原样的 keyword）· valueKey（默认 'id'，v-model:value 的值）· labelKey（触发器显示，默认第一列）· renderLabel(row) · multiple（值是数组；面板带勾选列与「已选 N 项 / 清空 / 确定」，跨页跨搜索保留）· maxTagCount（默认 2，其余 +N）· placeholder / clearable / disabled / size / title（窄屏面板标题）· panelWidth（默认 640，受视口限制）· pageSize（默认 100）/ pageSizes（不传 = 库内置 [100, 1000, 10000]）· searchKeys / searchPlaceholder · label（远程且有初始值时触发器显示的文字）· labels。事件：update:value、pick（单选 = 行，多选 = 点「确定」时的行数组）、close（面板关闭）。实例：open() / close() / focus()。
• 搜索：面板顶部只有一个搜索框（自动聚焦、带放大镜与清除 ×），占位符由搜索列的标题自动拼（如「物料编号/物料名称/规格」）。本地 data 实时模糊过滤（大于 2000 行防抖 120ms）：忽略大小写与全半角，空白切词、所有词都要命中，每个词可命中任一搜索字段（默认 = 有 key、不是序号 / 勾选、没有自定义 render 的列，searchKeys 可限定），不做拼音；远程 fetcher 回车或停手 300ms 后请求。改搜索词回第 1 页、表体回顶部。
• 键盘：Esc 先清空搜索再关闭；↓ ↑ 在行间移动高亮（滚进视口，虚拟列表里没渲染的行也行）；Enter 选中高亮行（搜索框里只剩一行时直接选它；多选 = 确定）；多选下 Space 勾选高亮行。单选再次打开时已选行高亮并滚进视口（本地数据会翻到它所在的页，远程数据不翻页）。
• 限制：可编辑表格的单元格里只支持单选；SearchForm（搜索表单）里没有下拉表格控件。

增删改弹窗

useTableCrud 管理弹窗的打开、提交、删除状态，弹窗和表单用你自己的 n-modal + n-form：

import { useTableCrud } from 'smart-naive-table'

const crud = useTableCrud({
  form: () => ({ name: '', email: '' }), // 新增时的空表单
  create: (form) => api.create(form),
  update: (form, row: User) => api.update(row.id, form),
  remove: (row: User) => api.remove(row.id),
  onSuccess: () => tableRef.value?.refresh(),
})

<!-- 打开：crud.openCreate() 新增、crud.openEdit(row) 编辑；删除：crud.removeRow(row) -->
<n-modal v-model:show="crud.visible.value" preset="card" :title="crud.mode.value === 'create' ? '新增' : '编辑'">
  <n-form :model="crud.model.value">
    <n-form-item label="姓名"><n-input v-model:value="crud.model.value.name" /></n-form-item>
  </n-form>
  <template #footer>
    <n-button type="primary" :loading="crud.submitting.value" @click="crud.submit()">保存</n-button>
  </template>
</n-modal>

crud.submit() 成功后自动关闭弹窗并触发 onSuccess。完整示例见 playground/DemoCrud.vue。

全局配置与中文文案

组件自带的按钮文案（查询、重置、列设置、过滤面板等）默认是英文。库内置了一份完整的中文文案 zhCNLabels，在入口文件 provide 一次，所有表格都会生效：

// main.ts
import { createApp } from 'vue'
import { SMART_TABLE_DEFAULTS, createSmartTableDefaults, zhCNLabels } from 'smart-naive-table'
import App from './App.vue'

const app = createApp(App)

app.provide(
  SMART_TABLE_DEFAULTS,
  createSmartTableDefaults({
    labels: zhCNLabels, // 想改个别词：{ ...zhCNLabels, search: '查找' }
    pageSizes: [50, 100, 500], // 显式给了就不按 fill-height 区分
  }),
)

app.mount('#app')

也可以只给某张表：<SmartTable :labels="zhCNLabels" />。labels 里的键全部可选，缺的键取英文默认。

输入框占位符（"请输入"）和日期面板来自 Naive UI 自己的语言包，给 <n-config-provider> 配上即可：

<script setup lang="ts">
import { NConfigProvider, zhCN, dateZhCN } from 'naive-ui'
</script>

<template>
  <n-config-provider :locale="zhCN" :date-locale="dateZhCN">
    <!-- 你的页面 -->
  </n-config-provider>
</template>

• 多语言切换：labels 传 computed，列 title、选项 label 写成函数 () => t('xxx')，切换语言立即生效
• 优先级：表格上的属性 / 列上的值 > 全局默认 > 内置默认
• 全部可配置字段见 全局默认字段

API 速查

列配置

数据列支持 Naive UI 列的全部属性（width、minWidth、fixed、align、ellipsis、sorter、resizable 等），另外增加：

filter 由本包接管（比 Naive 原生列过滤多了条件面板与远程联动），因此不透传 Naive 的 filter / filterOptions 等原生过滤属性。

• Option：{ label, value, tagType?, disabled?, children? }，tagType 可选 default / primary / info / success / warning / error
• 特殊列：{ type: 'index' } 序号（跨页连续）、{ type: 'selection' } 多选、{ type: 'expand', renderExpand } 展开行

SearchConfig

FilterConfig

• FilterAction（15 个）：'equal'（等于）、'notEqual'、'contains'（包含）、'notContains'、'gt'（大于）、'gte'、'lt'（小于）、'lte'，以及 'isNull' / 'isNotNull'（为空 / 不为空，不需要值）、'like'（SQL LIKE：% 任意长度、_ 单个字符，整串匹配、忽略大小写）、'startsWith' / 'endsWith'（忽略大小写）、'in' / 'notIn'（值是数组）。列头面板的默认可选操作符是前 8 个，其余需在列上 filter.actions 显式开启；未知操作符一律按不匹配处理
• FilterValue：{ logic: 'and' | 'or', conditions: { action, value }[] }；值为空（null / '' / []）的条件不参与求值（isNull / isNotNull 除外），全空即未过滤
• 各列之间恒为「与」，列内部由 logic 决定
• 内置面板一列最多编辑 5 条条件（≥ 2 条时可选「且 / 或」），勾选式产出若干 equal 取「或」；一条 in 经勾选面板回写会变成若干 equal 取「或」（语义相同、序列化形状不同）。编程式 setFilter / defaultValue 不限条数

Props

其它未列出的属性（如 striped、max-height、checked-row-keys、virtual-scroll）会原样传给 n-data-table。

SearchFormConfig（search 属性的对象形式）：

事件

插槽

实例方法

全局默认字段

通过 createSmartTableDefaults({...}) 设置，均为可选：

其它导出

src/index.ts 的全部导出：

• 组件：SmartTable、SmartSelectTable
• 组合式：useSmartTable(fetcher, options)（组件内部使用的数据核心：加载、分页、搜索、防竞态，不依赖 UI，可自己搭界面）、useTableCrud、useOptions（以及 findOption、optionLabel）、useFilters、useSmartTableDefaults
• 全局配置：SMART_TABLE_DEFAULTS、createSmartTableDefaults
• 文案与格式化：defaultLabels、zhCNLabels、mergeLabels、formatDate、formatDatetime、formatMoney、applyFormat
• 过滤内核（与 UI 无关，后端 mock 或自建界面可直接复用）：matchCondition、matchFilterValue、applyFilters、isFilterActive、activeConditions、defaultFilterSerializer、optionsToFilterValue、filterValueToOptions、isOptionsRepresentable、NO_VALUE_ACTIONS、isValuelessAction、actionValueKind、RECOMMENDED_ACTIONS、deriveFilterDefs、deriveInitFilters、filterOptionsKey
• 可编辑表格内核：inferEditor、inferEditorInfo、validateEdit、validateEditAsync、createEditStore
• 其它工具：cleanParams、matchKeyword（SmartSelectTable 的本地搜索匹配）、loadState / saveState / clearState / mergeCols（列设置的 localStorage 读写）
• 类型：SmartTableColumn、SmartTableDataColumn、SmartTableFetcher、SmartTableInst、SmartTableProps、SmartTableOption、SmartTableLabels、SearchConfig、FilterConfig、FilterValue、EditableConfig、SmartSelectTableProps 等

labels 文案键

labels 的键全部可选，缺的键取英文默认（defaultLabels），中文用 zhCNLabels。按用途分组：

行为说明

• 请求前自动清洗搜索参数：字符串去掉首尾空格；空串、null、undefined、空数组不传；0 和 false 保留
• 快速翻页时，先发出、后返回的旧响应会被丢弃，不会覆盖新数据
• 重置时搜索项恢复为 defaultValue，没有则为 null
• 固定列未写 width 时自动补上宽度（minWidth 或 120），避免 Naive 固定列错位
• scroll-x 默认等于可见列的宽度之和（含拖拽后的宽度），手动传入则以你的为准
• 过滤条件变化后回到第 1 页：远程模式重新请求，静态模式在前端过滤
• 过滤值为空（null / '' / []）的条件会被忽略，不会传给后端（isNull / isNotNull 不需要值，照常传）；0 和 false 保留
• 过滤值是纯日期串（YYYY-MM-DD）时按「整天」比较，等于 2024-03-05 能命中当天任意时刻
• 列宽写入 localStorage 做了防抖;存储结构版本为 v2;存储里的密度只在开了密度按钮(toolbar: { density: true })时生效,否则以 default-density 为准
• 列设置至少保留一列：只剩一列可见时，它的勾选框禁用

浏览器与版本支持

已知限制

文档索引

本地开发

npm install
npm run dev        # 启动开发服务器：/prototype.html 是与设计方案对齐的组件预览（本页截图来自它），/playground.html 是功能演示
npm test           # 单元测试
npm run typecheck  # 类型检查
npm run build      # 构建到 dist/

分支与发布：日常开发在 dev 分支，通过 PR 合并到 main。发布新版本时，先在 dev 上执行 npm version patch --no-git-tag-version（或 minor / major）并更新 CHANGELOG，合并到 main 后会自动发布到 npm 并创建 GitHub Release。

License

Apache-2.0