n-table 表格
用于库存、订单和记录等结构化数据。通过 columns 定义列，children 定义分组表头；不需要额外的列组件。
平台兼容性
Web 与微信小程序的运行检查范围见研发验收记录。本次验收按用户要求排除 Android；App 保留编译记录，尚未进行设备运行验收。
基础用法
<n-table :data="rows" :columns="columns" stripe selection @selection-change="onSelectionChange" />import type { NTableColumn } from "@/uni_modules/new-ui/components/n-table/props";
const rows: UTSJSONObject[] = [
{ name: "收纳盒", count: 12 },
{ name: "保温杯", count: 0, is_selected: true }
];
const columns: NTableColumn[] = [
{ prop: "name", label: "名称", width: 150, fixed: "left" },
{ prop: "count", label: "数量", width: 100, align: "right", sortable: true, sortType: "number" }
];实现说明
| 机制 | 组件做法 | 融合说明 |
|---|---|---|
| 列与分组 | columns/children 递归计算叶子列和表头跨度 | 将声明列与配置列的内容能力收敛在一个组件，不增加列组件 |
| 固定行列 | Web/微信使用 sticky；App 根据滚动坐标更新单元格横向位移和表头纵向位移 | 原生端不支持 CSS sticky；使用同一份真实列几何，不复制浮层或插入隐藏占位节点 |
| 微信滚动方向 | 按限高与自动高度提供完整元素变体，竖向开关在原生元素创建时即为确定值 | 横向方向初始化时即可判断是否同时纵向滚动，避免留下仅横向滚动的尾部预留空间 |
| 宽度 | 测量实际宿主，定宽/最小宽度/等分余量 | 不依赖屏幕宽度，适合卡片和分栏 |
| 排序 | 排序源下标，保留原对象与同值顺序 | 显示下标与源下标分别回传；空或非法数值/日期最后排列 |
| 选择 | 独立选中与禁用数组，同一事务派发最终集合 | 不修改 data，不使用异步延迟汇总；全选包含半选反馈 |
| 内容 | 文字、图片、按钮列与 item/header 插槽 | 全表插槽按 column.prop 判断需要替换的列 |
| 外观 | 主题令牌与字符串样式 | 对象样式统一为本库的字符串通道；加载图标统一由 loading 插槽定制 |
数据数组替换会按 is_selected/is_disabled 重新初始化选择与禁用状态；原地增删或移动行按原对象保留交互状态，显式修改两项数据标记会同步更新。排序不改动 data；resetSort 恢复源数组顺序。列宽、配色等外观更新保留当前排序。toggleRowSelection 与 toggleRowDisabled 接收 data 中的原对象。禁用已选行不再出现在选择回执中，解除禁用后恢复该行的选中资格。加载期间不派发行、单元格、按钮、选择或排序操作事件。
width/minWidth 控制列宽；height 固定整行高度，minHeight 提供下限，多列约束统一取最大值。未设置 height 时长内容自然撑高整行；固定行高建议不小于 40px，内容过长可配合 ellipsis。分组表头高度由各层 headerHeight 最大值累计，叶子表头跨满剩余层级。fixed 对分组的所有子列生效，可在子列指定方向或用 false 取消继承。表内纵向滚动需设置正 height；scroll=false 仅关闭横向滚动。
cellStyle/headerCellStyle 应用于内部内容容器；列宽、固定偏移、整行最小高度由列属性控制。customStyle 作用于根，可用于外距和主题变量。背景支持实色与方向关键词渐变；固定列背景须不透明。
外边框由表格根节点绘制，行列分隔线由单元格绘制，空态、加载态及限高滚动均保持相应方向的外边框。vertical 不绘制上下边和数据行线，horizontal 不绘制左右边和列线；分组表头的层级分界线在任何启用边框的模式下保留，false/none 一并关闭；最后一列、最后一行不重复叠加外框。horizontal/vertical 的方向线使用直角，避免线端被容器圆角裁弯；完整外框保留主题圆角。
页面滚动与表内滚动
height 是可选属性。整页展示一张表格时，推荐不传，让表格随内容自然撑高，由页面纵向滚动：
<n-page>
<n-table :data="rows" :columns="columns" />
</n-page>这里的表格放在 n-page 主体中，横向列过多时仍可在表内横向滚动。页面触底分页由业务页的 onReachBottom 请求下一页，再追加到 rows；请求去重、失败重试与是否还有下一页由业务管理。不设置高度时，表格不派发纵向 scrolltolower，fixed 也不提供随页面滚动的表头吸顶。
需要固定区域或常驻预览时，才设置正数 height，由表格内部纵向滚动，监听 scrolltolower 加载下一页。这种限高预览可放在 n-page 的 footer 中。
| 使用方式 | height 写法 | 纵向滚动容器 | 触底入口 |
|---|---|---|---|
| 整页表格 | 不传 | 页面 | 页面 onReachBottom |
| 限高表格 | 传正值，例如 :height="280" |
表格内部 | 表格 scrolltolower |
不需要显式传 :height="0"。内部默认值 0 用来表示自动高度，保留显式 0 与不传等效的兼容行为；业务代码推荐直接省略属性。
触底分页
设置正 height 并监听 scrolltolower，在业务页请求下一页并向原数据数组追加记录。请求期间用独立状态防重复；追加加载不必开启表格的 loading 遮罩，因此已有行可继续操作。失败保留原数据并提供重试入口，页面销毁或切换数据时取消未完成请求。
示例的“更多行”首屏 24 条，每次触底再模拟请求 24 条，不设置总数上限；加载状态和重试使用 n-loadmore，监听其 loadmore 事件。预览放在 n-page 的 footer 插槽中，复制源码包含相同分页和取消逻辑。示例使用延时模拟响应，接入真实业务时替换为接口请求。
列对齐
全表 align 默认为 left，每列可通过 align 覆盖，支持 left、center、right，适用于文字、图片、操作按钮和插槽内容。headerAlign 独立控制表头；未设置时跟随本列 align。
例如仅让操作列的标题和按钮居中：
const actionColumn: NTableColumn = {
prop: "actions", label: "操作", width: 88,
align: "center", type: "buttons", buttons: [{ text: "详情" }]
};窄屏分组表格建议使用完整边框区分跨层表头，名称列预留足够宽度，并启用 ellipsis 保持行高整齐。示例采用 140px 商品列，分组标题左对齐，使初始视口内可读；需要整组居中时设置 headerAlign: "center"，标题按完整列组宽度居中，超出视口的部分随表格横向滚动查看。自定义 item 插槽需自行设置文字省略和对齐，示例及复制源码提供相应写法。
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| data | UTSJSONObject[] | [] | 行数据；is_selected 设置初始选中，is_disabled 禁止选择；组件不修改原对象 |
| columns | NTableColumn[] | [] | 列配置；children 定义分组表头，叶子列可设置文字、图片、操作按钮及固定方向 |
| tableLayout | "fixed" / "auto" | fixed | fixed 使用列宽或等分剩余空间；auto 为未指定宽度的列按最小宽度分配 |
| scroll | boolean | true | 允许表内横向滚动；关闭后宽表在容器内裁剪 |
| height | NTableLength | 0（可省略） | 可选高度，数字 px 或 px/rpx 字符串；不传随内容撑高，由页面纵向滚动；正值开启表内纵向滚动，显式 0 与不传等效 |
| full | boolean | false | 列总宽度不足容器时，将余量平均分到全部列 |
| fixed | boolean | false | 固定表头；设置正 height 时在表内吸顶 |
| showHeader | boolean | true | 显示表头 |
| stripe | boolean | false | 显示隔行底色 |
| border | NTableBorder | true | true/all 四边与行列线；horizontal 上下边及行线；vertical 左右边及列线；启用边框时保留分组表头层级线；false/none 无线 |
| borderColor | string | 空串 | 边框颜色；空串跟随主题 |
| background | string | 空串 | 行背景，支持实色及方向关键词渐变；空串跟随主题，行 background 可覆盖 |
| headerBgColor | string | 空串 | 表头背景，支持实色及方向关键词渐变；空串跟随主题 |
| stripeColor | string | 空串 | 隔行背景；空串跟随主题 |
| highlightCurrentRow | boolean | false | 点击后高亮当前行 |
| align | NTableAlign | left | 默认内容对齐方式，列 align 可覆盖 |
| size | number | 0 | 表头字号（px），0 跟随主题；列 size 可覆盖 |
| color | string | 空串 | 表头文字色；空串跟随主题，列 color 可覆盖 |
| fontWeight | string | 600 | 表头字重 |
| textSize | number | 0 | 内容字号（px），0 跟随主题；列 textSize 可覆盖 |
| textColor | string | 空串 | 内容文字色；空串跟随主题，列 textColor 可覆盖 |
| ellipsis | boolean | false | 内容单行省略；false 自动换行，未固定行高时整行随内容等高拉伸 |
| padding | number | -1 | 单元格上下留白（px），-1 取主题 |
| selection | boolean | false | 显示多选列，禁用行不参与全选和选择回执 |
| initEmitChange | boolean | false | 初始化及数据替换后派发 selectionChange |
| checkboxColor | string | 空串 | 选择框选中颜色；空串跟随品牌色 |
| checkboxBorderColor | string | 空串 | 选择框未选描边色；空串跟随主题 |
| checkmarkColor | string | 空串 | 选择框勾线色；空串跟随主题填充文字色 |
| loading | boolean | false | 加载中；阻止排序、选择、行及操作事件 |
| loadingMode | string | circle | 加载形态：circle/semicircle/flower/dots/bars，使用 loading 插槽可替换全部加载内容 |
| loadingSize | number | 22 | 加载指示器尺寸（px） |
| loadingText | string | 空串 | 加载提示；空串使用语言包默认值 |
| loadingColor | string | 空串 | 加载指示器颜色；空串跟随品牌色 |
| emptyText | string / null | null | 空态提示；null 使用语言包，空串隐藏文字 |
| emptySize | number | 0 | 空态字号（px），0 跟随主题 |
| emptyColor | string | 空串 | 空态文字色；空串跟随主题 |
| bounces | boolean | false | 滚动回弹 |
| showScrollbar | boolean | false | 显示原生滚动条 |
| cellStyle | string | 空串 | 单元格内容容器样式；列宽、行高、固定定位由布局属性控制 |
| headerCellStyle | string | 空串 | 表头内容容器样式，不覆盖列宽与固定定位 |
| customClass | string | 空串 | 根节点附加类名，类须定义在组件自己的样式表内 |
| customStyle | string | 空串 | 根节点样式，可设置外距与主题令牌；表内几何由列属性控制 |
列配置
| 字段 | 说明 |
|---|---|
| prop / label | 数据字段与表头文字；prop 支持点路径 |
| children | 子列数组，用于分组表头 |
| width / minWidth | 数字 px 或 px/rpx 字符串；未设宽度时最小 100px，显式 width 以该宽度为准，minWidth 可进一步限制 |
| height / minHeight | 固定整行高度与最小高度，多列约束取最大值；未固定时随内容撑高 |
| headerHeight | 本层表头高度，默认 44px |
| align / headerAlign | left/center/right；表头与内容分别设置 |
| fixed | true/left/right；默认不固定，组内继承父列 |
| sortable / sortType / sort | 是否排序、number/date/string 类型、初始 ascending/descending |
| sortColor / sortSize / sortRight | 排序指示器颜色、尺寸与右侧位置 |
| type | text/image/buttons；默认文字 |
| imgWidth / imgHeight | 图片尺寸，默认宽度 40px；未设高度按原比例，指定高度后按固定盒裁剪显示 |
| buttons | 操作按钮数组；每项 text/color/size/fontWeight |
| color / size / background | 本列表头文字色、字号及背景 |
| textColor / textSize | 本列内容文字色、字号 |
事件
| 事件 | 说明 |
|---|---|
| cell-click | 点击普通单元格时触发，参数为 |
| header-click | 点击表头时触发，参数为 |
| row-click | 点击普通单元格时同时触发，参数同 cell-click |
| click | 点击内置操作按钮时触发，参数为 |
| selectionChange | 选择集合改变时触发，参数为可选行的原数据对象数组 |
| select | 切换单行选择时触发，参数为 |
| selectAll | 全选或取消全选时触发，参数为 |
| sortChange | 排序改变或重置时触发，参数为 |
| scrolltolower | 纵向滚动到底时触发，参数为原生滚动详情 |
| error | 配置或方法参数无效时触发，参数为 |
插槽
| 插槽 | 参数 | 说明 |
|---|---|---|
| header | column, columnIndex | 表头内容，不覆盖排序行为 |
| item | row, column, rowIndex, sourceIndex, columnIndex, value | 单元格内容；rowIndex 为显示下标，sourceIndex 为源下标 |
| empty | 无 | 空数据且非加载时显示 |
| loading | 无 | 替换加载指示器与文字 |
实例方法
const tableRef = ref<NTableComponentPublicInstance | null>(null);
tableRef.value?.setSort("count", "ascending");
tableRef.value?.toggleRowSelection(rows[0], true);| 方法 | 参数 | 说明 |
|---|---|---|
| clearSelection | 无 | 清空可选行并派发选择变化 |
| toggleRowSelection | row, selected=null | 指定或切换原行对象的选择 |
| toggleRowDisabled | row, disabled=null | 指定或切换原行对象的禁用 |
| toggleAllSelection | 无 | 全选/取消全部可选行 |
| setSort | prop, order=ascending | 对可排序列设置顺序，空串清除 |
| resetSort | 无 | 恢复源顺序，选择保留 |
| columnColorMethod | fn, prop | 回调 (value, sourceIndex, columnIndex) 返回内容文字色，空串取主题 |
主题令牌
排序指示器还支持 --n-table-sort-size、--n-table-sort-arrow、--n-table-sort-gap。
支持 --n-table-radius、--n-table-row-height、--n-table-padding-x/y、--n-table-font-size、--n-table-text-color、--n-table-header-color、--n-table-border-color、--n-table-checkbox-size/radius/color/border-color、--n-table-checkmark-color、--n-table-current-background、--n-table-empty-height、--n-table-disabled-opacity、--n-table-pressed-opacity。
微信端内部开启 scroll-view 的 enhanced，使 bounces 和 showScrollbar 具备原生生效前提；其他端不绑定该微信专属属性。
已验证范围
- Web：375px 与 1024px，深浅主题；通过浏览器 MCP 验证排序、选择隔离、固定行列、分组表头、空态、加载态及图片加载。
- 微信小程序：HBuilderX 5.26、VDOM、样式隔离 2.0；开发者工具实际运行验证排序、选择、禁用行、恢复顺序和行几何；官方自动化 SDK 在组件作用域内验证表头/单元格/操作点击、原生滚轮变更事件到确认按钮、固定行列滚动、到底事件、加载守卫和原生滚动开关。
- Android：按要求排除本次验收，不以此前编译记录证明本次版本的设备运行。
验收脚本位于 scripts/test-table.mjs、scripts/test-table-web.mjs 和 scripts/test-table-weixin.mjs，浏览器与微信脚本由 MCP 工具调用适配器驱动。