Table 表格
用于以行列表格形式展示结构化数据，支持排序、行选中、多选与加载态，可与分页组件联动。
columns / data 支持 attribute 声明式通道：直接写 JSON 字符串即可渲染表头与数据行（非法 JSON 回退空态），同时保留 property 通道（赋值数组对象，property 优先），可被 SSR 快照序列化。
数据通道契约（与 oas-chart 对齐阅读）：attribute 传 JSON 字符串，property 传对象/数组（免序列化，setter 内解析，优先级高于 attribute）。
oas-table的columns/datasetter 会把值反射回 attribute——property 赋值后getAttribute('columns')/getAttribute('data')可读回对应 JSON 字符串（attribute 与 property 保持单一数据源同步）；这与oas-chart（data 只写内部状态不反射、读取走el.data）不同。例外：columns含函数字段（render等）时 setter 走纯内存路径不反射，此类列读取请走el.columnsproperty。
基础用法（含排序）
可排序列
点击可排列表头在升序 / 降序 / 取消之间循环。
子元素声明式通道
用 <oas-table-column> 声明列
嵌套子列表达多级表头
单元格模板 cellTemplate（插值 row.字段）
columns 除了 attribute / property 数组，还支持子元素声明式通道：<oas-table-column data-key title sortable width align fixed ...>，属性对齐 TableColumn 字段（布尔字段为 true/false，serial-number / filters 等 kebab-case；列标识字段叫 key，但 key 是 Vue 模板保留字会被剥离不到 DOM——声明式请写 data-key（原生 HTML 下 key 直写亦可，组件双通道读取））；title 缺省时取默认插槽文本；嵌套 <oas-table-column> 表达多级表头（children）。子元素变化由 MutationObserver 感知自动重渲染。columns attribute / property 显式设置时优先于子元素通道。单元格模板 cellTemplate（配合 row.字段 占位插值）表达自定义单元格，克隆+水合成每格内容：原生 HTML 可在列内嵌 <template> 声明；Vue 宿主/文档站建议经 columns property 通道注入（JS 构造 HTMLTemplateElement，写法见上例——md/Vue 编译管线对 <template> 子内容处理不一致，dev 下会吃空）；render 函数仍优先于模板。
⚠️ 函数型字段（“一个细节”）：
render/filterMatch/ 编辑器回调（editOptions的函数）等函数类型无法经子元素 attribute、也无法经 JSON 序列化——子元素通道与columnsattribute 都不能表达。含函数字段的列，请用columnsproperty 赋值（JS 构造数组），或用声明式的cellTemplate（<template>+row.字段占位插值，函数替代品，写法见上例）表达自定义单元格。
密度档位
size：small / medium（默认）/ large
档位只改单元格 padding 与字号的默认值，全部走 CSS 变量：宿主可直接用 --oas-table-cell-padding-block / --oas-table-cell-padding-inline / --oas-table-font-size 覆盖（优先级高于档位）。非法值回落 medium 并告警。row-height 与档位正交：虚拟滚动等定高场景的行高由 row-height 决定，不受档位影响。
列对齐与宽度
对齐与宽度
受控排序与行选中
初始排序与选中
sort-key / sort-order 控制排序，selected 高亮选中行（点击行可切换选中）。
多选
行多选（checkable）
表头复选框一键全选/取消，行复选框单独勾选；选中变化派发 oas-check。
行单选（checkable="radio"）
行单选（radio 互斥）
当前选中：无
checkable="radio" 进入单选档（裸 checkable 多选行为不变）：勾选列渲染 radio、表头不再渲染全选框（保留空白列头维持列对齐），点选互斥——selected 为单值语义（至多一个行 key），再点已选行取消选中；oas-check detail 同为 { keys: string[] }（单选档至多一个元素）。
行级状态样式（row-class）
row-class：按行数据返回 class
停用行灰化、超标行警色：由 row-class 返回的 class 驱动。
row-class 为 property 函数通道：(row, index) => string（多值空格分隔），返回的 class 挂到数据行 tr，并同步暴露为该行 tr 与各单元格的 ::part() token——页面 CSS 用 ::part() 即可穿透 Shadow DOM 命中（上例的停用/超标行样式即此机制）。函数不可序列化：不参与 attribute / SSR 快照（契约同 columns.render），SSR 场景请在客户端水合后赋值。
与分页联动
表格 + 分页
表格数据按每页 5 条切片，翻页时通过 oas-change 事件更新 data 属性重新渲染。
固定列
左侧固定列
左右固定列 + 表头吸顶
列配置中 fixed: 'left' | 'right' 将该列表头与单元格设为 position: sticky（left / right 偏移按列宽自动累加），其余列可横向滚动；表头始终吸顶。
行内编辑
双击单元格编辑（含操作列）
最近编辑：—
设置 editable 开启行内编辑，列配置 editable: true 标记可编辑列（editor: 'input' 文本输入 / editor: 'select' 下拉选择 + editOptions），actions: true 渲染操作列（编辑/保存/取消按钮）。双击单元格或聚焦后按 Enter / F2 进入编辑：Enter 或失焦提交、Esc 取消；提交派发 oas-edit（detail: { rowIndex, key, column, value }），取消派发 oas-edit-cancel。空值提交默认还原旧值（非破坏）。
行内编辑能力（主路径已默认内含）：主路径
@oas-ui/ui/data/table已内置编辑能力（import 即注册），无需显式引用（下方 demo 走全量入口同样已内含）。若想保留不带编辑 machinery 的纯核瘦身，可改从纯核入口@oas-ui/ui/data/table/core引入——它不含该能力，此时<oas-table editable>静默失效并 dev 告警，需显式import '@oas-ui/ui/data/table/edit'（import 即注册）或换回主路径。（编辑器是 table 链最重的一块，改纯核约省三分之一；具体体积随版本变化，见仓库docs/perf-baseline.md。）
可编辑单元格自带可感知线索：hover 或键盘聚焦（focus-visible）时显示淡底色与右上角铅笔图标（图标不拦截交互），悬停有 title 提示「双击编辑」；三种方式进入编辑——双击、聚焦后按 Enter、聚焦后按 F2。
行内「交互宿主」上的点击/双击不连带行级手势：落在原生控件（button/a/input/select/textarea）、带 role 的 ARIA 元素或库内交互组件（如 oas-button、oas-link、oas-select）内部的点击只触发该控件自身行为——不切换行选中、也不会被双击判定误带入编辑；行点击与双击进编辑共用同一份排除清单，并随组件库新增交互型组件同步维护。业务侧行内自定义交互内容（图表、迷你挂件等）无需等库发版：在容器上标注 data-oas-row-click-ignore 即可让整块内容豁免行点击与行编辑。交互宿主不派发行级手势，但不阻止编辑态本身。
组件编辑器（editComponent）
editComponent：任意组件作为单元格编辑器
editComponent（columns JSON 字段）指定组件编辑器（优先于 editor）：双击后挂载对应组件并注入当前值。组件契约（最小集）：值可读（getFormValue() → value property → value attribute 三级兜底——getFormValue 为库内组件的 form-associated 内部通道，宿主自定义组件实现 value property 或 value attribute 其一即可）、提交事件（oas-change 或原生 change 其一）、Esc 取消；多行编辑器（textarea 内核）Enter 让路换行，提交走失焦。库内 form 组件（oas-input / oas-textarea / oas-switch 等）天然满足，宿主自定义 WC 同样可用。注意：横向滚动触发列窗口变化时整表重渲染，进行中的编辑会被静默取消（不派 oas-edit-cancel）——浮层编辑器同样适用该语义。
浮层组件编辑器（oas-select / oas-date-picker）
浮层编辑器：下拉选择 + 日期选择
浮层类组件（editComponent: 'oas-select' / 'oas-date-picker'）自动走浮层编辑器通道，与非浮层组件通道的差异：
- 进入编辑自动展开浮层（触发器驱动组件非受控开合，不写
open受控属性）；组件未注册（笔误 tag / 漏 import）时挂载即白板、不展开不告警，与非浮层通道行为一致。 - 浮层面板内交互不误提交：面板挂在组件 shadow 内，指针落在编辑器子树内的失焦（点选项/翻日历/搜索）被抑制——单值组件选定（
oas-change）即提交；多选组件勾选是中间态，失焦时一次性提交。 - Esc 双层级：浮层开着 Esc 只关浮层（编辑保留），浮层已关再按 Esc 取消编辑。
- 外点提交：点击编辑器与浮层以外区域提交当前值；点击表格内其他单元格沿用既有语义（触发行重建静默取消）。
oas-select 的编辑选项同步列配置：editOptions 优先，回落 options（与展示侧同一份选项语义）。type: 'multi-select' 列的默认编辑器即本通道的 oas-select multiple（见下方「字段类型」）。
受控编辑
受控编辑（edit-controlled）
该表格为受控模式：组件提交时不自动回写 data，由宿主监听 oas-edit 后自行更新。
edit-controlled 为受控编辑：提交时不自动回写 data，仅派发 oas-edit；宿主监听后自行更新 data（示例见下方脚本）。
吸顶行
表头 + 前 N 行吸顶
sticky-rows="N" 指定前 N 行吸顶于表头下方（配合滚动容器：设置 height 后表体可滚动）；与固定列（fixed: 'left' | 'right'）共存互不冲突。
大数据量（虚拟滚动）
万级数据虚拟滚动
设置 height 开启虚拟滚动（搭配 row-height 定高），表格只渲染可见窗口内的行，配合固定列与排序/多选使用；滚动派发 oas-scroll。
column-virtual：宽表横向虚拟滚动
column-virtual 开启横向虚拟滚动（列窗口化）：非固定列只渲染可视窗口列，窗口外列以占位格 colSpan 归并（宽度由 colgroup 求和，table-layout: fixed 强制启用）——60 列宽表 DOM 里只有十几列。可与 height 行虚拟双开；固定列须两端布局且恒渲染。约束（告警降级）：多级表头 / span-method / 合计行不兼容；建议全列显式 width（未设宽按预估 100px）。注意：横向滚动触发列窗口变化时整表重渲染，进行中的编辑会被静默取消。
斑马纹与边框
斑马纹（stripe）
完整边框（bordered）
设置 stripe 交替奇数/偶数行底色，设置 bordered 为单元格绘制完整网格边框。
合计行
合计行（summary）
summary 属性为 JSON 数组 [{ key, type: 'sum' | 'avg' | 'count', label? }]，表尾渲染合计行：label 显示在首个未聚合列，各聚合值显示在对应列；也支持在列配置上直接写 summary: 'sum' | 'avg' | 'count'。
合计范围
summary-scope 控制合计行统计范围：all（默认）对分页切片前的完整筛选结果全量合计（翻页不变），page 只对当前页小计。开启分页时两者差异可见。
合计范围：all（默认）与 page 对比
上面第一张表 summary-scope 缺省（all），第 1 页合计为全部 6 行的年龄和 177；第二张表 summary-scope="page"，第 1 页小计为当前页 3 行（30+25+35=90），翻页后小计随页变化。
可展开行
可展开行（expand 字段）
行数据存在非空 expand 字段时，表尾出现展开列，点击行尾按钮展开一整行展示自定义内容；展开状态保存在 expanded 属性（逗号分隔的 key 集合），切换时派发 oas-expand。
受控展开（expanded 属性）
expanded 为受控属性（逗号分隔的 key 集合）：预置展开行在首次渲染即展开，宿主可随时增删 key 驱动展开状态（树形父行与可展开行共用）。
树形数据
树形数据（children）
行数据存在 children 数组时按树形渲染：父行首列出现展开按钮，子行按层级缩进；展开状态同样保存在 expanded 属性，切换时派发 oas-expand。
加载态
加载态
设置 loading 属性后表头保留、数据区显示加载占位行；移除属性即恢复数据。
空态
空数据
自定义空态文案
空态富内容插槽（slot="empty"）
空态文案优先级：slot="empty" 插槽（<template slot="empty"> 或普通元素均可，普通元素克隆自身、模板克隆其内容）> empty-text 属性 > 内置 i18n 文案；插槽内容增删会自动重渲染。
列设置：显隐 / 拖拽重排 / 列宽
列拖拽重排 + 列宽拖拽
拖拽表头可重排列顺序，拖表头右缘热区可调列宽。· 列顺序：原序 · 列宽：—
列显隐（受控 column-keys / hidden）
说明：列拖拽重排 / 调宽分别派发 oas-column-order / oas-column-resize（宿主持久化可用）。列显隐两种方式：受控 column-keys（JSON 数组，可同时控制顺序）或在列配置写 hidden: true 默认隐藏。
触屏适配：HTML5 拖拽（dragstart）在触屏上不可用，触控（coarse pointer）下每个列头自动提供上移 / 下移按钮（桌面隐藏）与相邻列交换顺序；表头过滤钮、展开钮、列宽拖拽手柄的命中区在触屏下扩到 44px；过滤面板定位自动避让视口边缘（空间不足时翻转，窄屏不溢出）。
多列排序
Shift 点击多列排序（multi-sort）
初始 `multi-sort='[{"key":"age","order":"asc"},{"key":"name","order":"asc"}]'` 以 JSON 声明多列排序（表头序号 1、2 表示优先级）；按住 Shift 点击多个可排序列累积/切换/移除排序并写回 `multi-sort`，普通点击重置为单列。
序号列与省略号
序号列 + 省略号
serialNumber: true 的列渲染行序号（从 1 递增，不取数据字段值）；ellipsis: true 的列内容超出列宽时单行截断显示省略号（悬停 title 查看全文）。
多级表头
多级表头（children）
列配置 children 定义组表头：组列横跨其子列（colspan），叶子列按树深落位（rowspan 对齐数据行）；数据 / 排序 / 显隐 / 拖拽均作用于叶子列。
内置分页
表格内置分页（pagination）
设置 `pagination` 开启内置分页：顶层行先全局排序再切片，翻页/改页大小派发 `oas-page-change`。当前页：1
外部数据分页（total）
服务端分页（total + 受控 current，宿主换页数据）
设置 `total` 声明总行数：`data` 只放当前页切片（组件不再内部分页），翻页/改页大小派发 `oas-page-change` 由宿主拉取对应页数据（本 demo 用本地数据模拟服务端切片）。当前页：1 · 已加载页数据行数：—
列过滤
表头列过滤（filterable + filter-values 受控）
合并单元格
合并单元格（merge）
列配置 merge: true 将该列连续相同显示值的行合并为一个 rowspan 单元格（虚拟滚动模式下忽略合并）。
受控合并（span-method）
span-method：逐格显式声明 rowspan/colspan
季度列由 spanMethod 显式声明（Q1 / Q2 各跨 2 行）；销量列走列级 merge 自动同值合并——两机制按列独立并存。
span-method 为 property 函数通道：(row, column, rowIndex, columnIndex) => [rowspan, colspan] | {rowspan, colspan}，逐格显式声明合并；返回 0 表示本格被覆盖不渲染（覆盖关系由函数声明）。与列级 merge 自动合并按列独立并存（被显式 span 覆盖而缺格的行会断开该列 merge 的连续分组）；虚拟滚动模式下忽略（与 merge 同级的定高限制）。rowIndex 按数据行序（0 起，不含 expand 内容行），columnIndex 按有效列顺序；函数不可序列化，不参与 attribute / SSR 快照（契约同 columns.render）。
远程数据与排序 loading
排序触发重新请求（模拟远程）
监听 oas-sort-change 后置 loading 再请求远程分页/排序数据；本 demo 用模拟延时演示「排序 → loading → 重新渲染」的衔接，服务端实际排序由宿主在收到事件后发起请求（表格只负责派发事件与 loading 态）。
事件
排序与点击事件
排序：无 · 点击行：—
表头显隐
show-header 控制表头显隐（默认 true 保持现状）；设为 "false" 后表头不渲染，列配置仍作用于数据行对齐，适用于纯数据陈列、上方已有自绘标题行的场景。
show-header=false（可切换）
表格布局（table-layout）
table-layout="fixed" 把 table-layout 透传给内部 table：列宽严格按 width 声明分配（超长内容换行/截断不再撑宽列），适合列宽已定的报表场景；默认不透传（浏览器 auto 基线，列宽随内容自适应）。
table-layout=fixed（列宽严格生效）
行 hover 开关（hover）
hover="false" 关闭行 hover 底色（默认开启保持现状）；适合行内容自身带交互态（内嵌按钮高亮等）、不希望整行底色变化的场景。仅影响 hover 底色视觉，行点击/选中行为不受影响。
默认 hover 与 hover=false 对比
默认（hover 开）
hover="false"（关闭）
树形缩进（indent-size）
树形数据的每级缩进量由 indent-size 控制（px，默认 24）；配合更紧凑的层级展示或更深的层级结构使用。
indent-size=32（每级缩进加大）
展开行谓词（row-expandable）
rowExpandable（property 函数通道）按行判定是否渲染行尾展开钮：返回 false 的行不渲染（占位格保留、列对齐不破坏）。适合部分行没有可展开内容的场景。
仅「完整资料」的行可展开
王五的资料不完整（rowExpandable 返回 false），没有展开钮。
限高滚动（max-height）
max-height 限制表体滚动容器高度（数字按 px，也可传 CSS 值如 50vh）：内容超高时容器内滚动，表头吸顶（sticky）钉在容器顶部。轻量限高用它；需要虚拟滚动（万级行）用 height。
max-height=200（表头吸顶）
自定义过滤图标（filter-icon 插槽）
可过滤列的表头触发图标可用 slot="filter-icon" 自定义（<template> 或普通元素均可），缺省为内置过滤图形。
template 自定义过滤图标
单元格与双击事件（oas-cell-click / oas-row-dblclick）
点击数据单元格派发 oas-cell-click（detail 含 row / column / value / rowIndex / columnIndex）；双击数据行派发 oas-row-dblclick（detail 含 row / rowIndex）。落在行内按钮、链接、表单控件等交互宿主上的点击/双击不派发（与行选中同一份排除清单）。
单元格点击 / 行双击反馈
单击单元格：— · 双击行：—
导出 CSV / Excel（exportable）
exportable 在表格顶部显示导出工具栏（默认 CSV；export-format="excel" 切 Excel，"csv,excel" 两个按钮都出）。导出范围 = 表头 + 当前可见数据行（过滤 / 排序 / 分页切片后的当前页；虚拟滚动取完整展示集合）：actions 列不导出（勾选列/行展开列/拖拽手柄列也不在导出矩阵内——它们不是数据列）、serialNumber 列导出序号、select 编辑器导出选项 label。CSV 按 RFC 4180 转义并带 UTF-8 BOM；Excel 走 SpreadsheetML（.xls）。export-file-name 配文件名（默认 export）。也可编程式调用 table.exportData('csv' | 'excel')——按钮与方法都派发 oas-export（detail { format, fileName, rowCount }）。
导出 CSV / Excel（点击真实下载）
最近导出：—
网格导航（grid-navigation）
grid-navigation 给表格 role="grid" 语义（表头 columnheader、行 row、单元格 gridcell），数据区为单停靠点 Tab 序：Tab 聚焦滚动容器，随后方向键在单元格间漫游——左右跨行换行、上下保持同列、Home/End 到行首末、Ctrl+Home/End 到网格首末格、PageUp/PageDown 按可视区（分页时为 page-size）翻屏。Enter/Space 激活聚焦格内的控件（行展开钮、行勾选框），可编辑单元格在编辑态把键盘让给输入框。表头控件（全选、列筛选）保留各自 Tab 停靠。
方向键漫游（点击表格后按方向键）
点击单元格后用方向键漫游 · 单元格点击：
行拖拽排序（row-draggable）
row-draggable 增加拖拽手柄列；把某行手柄拖到另一行上派发 oas-row-reorder，detail { from, to, row }（from/to 为当前可见数据行序中的索引；to 为移除被拖行后的插入位，宿主可 const [moved] = rows.splice(from, 1); rows.splice(to, 0, moved) 直接复现）。组件自身不改 data（受控/事件驱动，与 sortable tabs、tree 拖拽同契约）。虚拟滚动（height）下禁用并 dev 告警一次。
拖手柄换位（宿主复现 oas-row-reorder）
最近重排：—
字段类型（column type）
columns 列配置的 type 字段声明字段类型，作用于默认展示渲染与默认编辑器（render / cellTemplate 自定义渲染在场时优先于 type）。全部类型：text（缺省纯文本）/ number / currency / select / multi-select / date / checkbox / link / progress / rate。配套列字段：currency（货币符号，缺省 ¥）、options（select / multi-select 选项 [{ value, label, color? }]，color 缺省走 token 默认色，找不到选项时显示原值文本）。数值类列（number / currency / progress / rate）与 sortable 并存时按原始数值排序，date 列按时间序；徽章 / 进度条 / 星级颜色全部走 CSS 变量 token（暗色自动可读）。
一个表内的多种字段类型列
示例同时覆盖空态：第 3 行库存为非数字（原样文本）、上架日期 ISO 串（取日期部分）；第 6 行库存为 null（空）、日期非法（原样文本）、进度条出界（夹取 0%）、评分出界（夹取 5 星）。
字段类型的行内编辑：number / currency / link 走原生 input（数值列提交回写 number）；progress / rate 原生 input 提交时夹取 0-100 / 0-5；multi-select 走浮层组件编辑器通道挂 oas-select multiple（勾选多个选项，options 自动同步为编辑选项，提交回写字符串数组，清空全部勾选后失焦提交 [] 也是合法值；第一期逗号分隔 input 编辑已退役，历史逗号分隔字符串数据在进入编辑时自动解析为选中集）；date 内置 YYYY-MM-DD 形态校验（非法形态保持编辑态）；checkbox 经组件编辑器通道挂 oas-switch（提交回写布尔）；select 走既有 select 编辑器通道（options 自动同步为编辑选项）。开启 editable 后双击任意类型列即可体验。
分组视图（group-by）
group-by="字段key" 按该字段值分节渲染：分节头行 = 折叠箭头 + 字段值 + 组内计数，点击箭头折叠 / 展开该组（默认全展开，aria-expanded 同步）。组间顺序按字段值首次出现序、排序作用于组内行；分组字段值缺失 / 为空的行归入「（空）」组（文案走 i18n）。分节头作为扁平行的一种参与行虚拟滚动，整行 colSpan 全宽（与 column-virtual / 固定列正交）；折叠状态在数据 / 属性变化时保留。与 merge 列 / span-method / row-draggable 同用时不兼容（告警一次并降级为普通渲染）。与 pagination 同用时为页内分组口径（组内计数 = 当前页计数，跨页组在每页各自成组）。
按部门分组（组内可排序，点击箭头折叠/展开）
单元格溢出提示（cell-tooltip）
cell-tooltip 默认开启（设 cell-tooltip="false" 关闭）：纯文本单元格溢出（内容宽超出列宽）时，悬停显示全文浮层——表格级单例浮层（不为每格创建实例），反色 token 配色暗色可读，滚动 / 重渲染时自动隐藏。已有原生 title 提示的 ellipsis 列与富内容格（自定义渲染 / 徽章 / 进度条等）不触发，避免双重提示。
悬停溢出格查看全文
访问地址列的完整 URL 远超列宽（长串不可断行）：悬停任一溢出格即可在浮层中查看全文，移开即隐藏。
API
oas-table
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
bordered | 完整边框：单元格网格描边（外框由组件自带） | — | — |
cell-tooltip | 单元格溢出提示（默认开启，"false" 关闭）：纯文本单元格溢出（scrollWidth > clientWidth）时 hover 显示全文浮层——表格级单例浮层（token 反色，暗色可读），滚动/重渲染自动隐藏；富内容格与已有原生 title 的 ellipsis 列豁免（避免双重提示） | string | true |
checkable | 行选择开关：存在即多选（复选框 + 全选头）；="radio" 单选（点选互斥、再点取消、无全选头），oas-check detail.keys ≤1 | string | — |
column-keys | 受控列显隐与顺序（key 数组或逗号串）：在场时按有效叶序重组表头与数据列（多级表头同祖先链叶子并组） | string[] | string | [] |
column-virtual | 横向虚拟滚动（列窗口化）：非固定列只渲染可视窗口列，窗口外列以占位格 colSpan 归并（宽度由 colgroup 求和）。约束：建议全列显式 width；多级表头 / span-method / 合计行不兼容（告警降级）；固定列须两端布局 | boolean | — |
columns | 列配置 [{ key, title, sortable?, width?, align?, fixed?, render?, summary?, editable?, editor?, editOptions?, editComponent?, actions?, type?, currency?, options? }]，JSON 字符串（attribute 声明式通道；property 赋值优先）；type 声明字段类型（number/currency/select/multi-select/date/checkbox/link/progress/rate）作用于默认展示渲染与默认编辑器，currency 为 currency 列货币符号（缺省 ¥），options 为 select/multi-select 选项 [{ value, label, color? }] | TableColumn[] | string | [] |
current | 当前页码（内置分页，受控） | string | 1 |
data | 行数据 [{ [key]: value, children?, expand? }]，JSON 字符串（attribute 声明式通道；property 赋值优先） | Array<Record<string, unknown>> | string | [] |
edit-controlled | 受控编辑：提交时不自动回写 data，仅派发 oas-edit，由宿主监听后自行更新 data | boolean | — |
editable | 行内编辑开关（需配合列配置 editable: true；操作列 actions: true 同理） | boolean | — |
empty-text | 空态文案 | — | — |
expanded | 已展开行 key 集合（逗号分隔；树形父行/可展开行共用） | string | — |
export-file-name | 导出文件名（不含扩展名；路径分隔符与保留字符自动净化） | string | export |
export-format | 导出格式：csv（默认）/ excel，或逗号组合 csv,excel（两个按钮）；非法回落 csv | string | csv |
exportable | 导出开关：表格顶部渲染导出工具栏（默认 CSV，可配 CSV/Excel），并开放 exportData 方法 | boolean | — |
filter-values | 受控列过滤值（JSON 对象：列 key → 选中值标量） | string | — |
grid-navigation | 键盘网格导航：role=grid，数据区单停靠点 + 方向键在单元格间漫游（Home/End/PageUp-Down，Enter/Space 激活格内控件） | boolean | — |
group-by | 分组视图：按字段值分节渲染（分节头 = 字段值 + 组内计数 + 折叠箭头，点击折叠/展开该组，默认全展开）；组间按字段值首次出现序、组内排序生效；空值行归入「（空）」组；与 merge 列 / span-method / row-draggable 同用时告警一次并降级为普通渲染；可与 column-virtual / 虚拟滚动并用（分节头整行 colSpan 全宽） | string | — |
height | 虚拟滚动视口高度（px）；设置后仅渲染可见窗口行 + 首尾占位行 | string | 320 |
hover | 行 hover 底色开关（仅视觉，不影响选中行为），"false" 关闭 | — | — |
indent-size | 树形数据每级缩进量（px） | string | 24 |
loading | 加载态：数据区显示加载占位行（表头保留） | boolean | — |
max-height | 表体限高滚动 + 表头吸顶（虚拟 height 同设时优先） | string | — |
multi-sort | 多列排序（JSON 数组：[{ key, order }]，按数组序依次排序） | string | — |
page-size | 每页条数（内置分页，默认 10） | string | 10 |
pagination | 内置分页开关（页脚分页条；宿主自管分页时不设） | boolean | — |
row-draggable | 行拖拽排序：渲染拖拽手柄列，拖放派发 oas-row-reorder；虚拟滚动（height）下禁用并告警一次 | boolean | — |
row-height | 虚拟滚动每行固定高度（px） | string | 40 |
row-key | 行唯一键字段 | string | key |
selected | 选中行 key 集合（逗号分隔） | string | — |
show-header | 表头显隐（默认 true）；false 时不渲染表头行，列配置仍作用于数据行对齐 | string | true |
size | 密度档位：small / medium（默认）/ large——只改单元格 padding 与字号默认值（全走 CSS 变量，可用 --oas-table-cell-padding-block / --oas-table-cell-padding-inline / --oas-table-font-size 覆盖，优先级高于档位）；非法值回落 medium 并告警；与 row-height 正交 | string | medium |
sort-key | 受控排序；sort-order 取 asc / desc / 空 | string | — |
sort-order | 受控排序；sort-order 取 asc / desc / 空 | SortOrder | — |
sticky-rows | 吸顶行数（数字 N）：前 N 行吸顶于表头下方（配合滚动容器与固定列共存） | string | — |
stripe | 斑马纹：奇数/偶数行交替浅底色 | boolean | — |
summary | 合计配置 [{ key, type: 'sum'|'avg'|'count', label? }]，JSON 字符串 | string | — |
summary-scope | 合计行聚合范围：all（默认，全量数据）/ page（当前页） | string | all |
table-layout | 透传表格布局算法（fixed 时列宽严格按 width 声明） | string | — |
total | 外部数据分页总行数（服务端分页）：与 pagination/current/page-size 配合，data 只放当前页切片（组件不再内部分页），总数直通分页器；翻页派发 oas-page-change 由宿主换数据；属性缺席或非法值回落内部分页 | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-cell-click | 点击数据单元格派发，detail: { row, column, value, rowIndex, columnIndex }（交互控件内不派发） |
oas-check | 复选框选中变化，detail: { keys: string[] } |
oas-column-order | 列拖拽重排后派发，detail: { keys }（新列序） |
oas-column-resize | 列宽拖拽调整后派发，detail: { key, width } |
oas-edit | 行内编辑提交（Enter/失焦/操作列保存），detail: { rowIndex, key, column, value }；受控模式组件不回写 data |
oas-edit-cancel | 行内编辑取消（Esc/操作列取消/空值提交还原），detail: { rowIndex, key, column, value }（value 为原值） |
oas-expand | 行展开/收起（树形子行或可展开内容行），detail: { key, expanded } |
oas-export | 导出触发（按钮或 exportData），detail: { format, fileName, rowCount } |
oas-filter-change | 列过滤值变化时派发，detail: { filters }（filters 为列 key → 选中值标量的对象） |
oas-page-change | 内置分页翻页时派发，detail: { page, pageSize } |
oas-row-click | 点击行（非 checkable 时同时切换选中），detail: { row, key } |
oas-row-dblclick | 双击数据行派发，detail: { row, rowIndex } |
oas-row-reorder | 行拖拽/Alt+↑↓ 重排，detail: { from, to, row }（to 为移除被拖行后的插入位；组件不改 data） |
oas-scroll | 虚拟滚动滚动事件（rAF 节流），detail: { scrollTop, start, end } |
oas-sort-change | 排序变化，detail: { key, order: 'asc' | 'desc' | '' } |
插槽
| 名称 | 说明 |
|---|---|
template[slot="empty"] | 空态富内容（优先于 empty-text 与默认空态文案） |
template[slot="filter-icon"] | 自定义可过滤列表头的触发图标 |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-table-cell-padding-block | var(--oas-space-3) |
--oas-table-cell-padding-inline | var(--oas-space-4) |
--oas-table-font-size | var(--oas-font-size-md) |
--oas-tooltip-bg | var(--oas-color-text-primary) |
--oas-tooltip-color | var(--oas-color-bg) |
oas-table-column
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
actions | 列操作（如行内编辑的保存/取消钮列） | — | — |
align | 列内容对齐（left/center/right） | — | — |
currency | currency 类型列的货币符号（缺省 ¥） | — | — |
data-key | 列标识（Vue 模板保留字 key 的规避通道；原生 HTML 下 key 直写亦可，组件双通道读取） | — | — |
editable | 列可编辑（双击单元格进编辑态） | — | — |
editor | 编辑器类型/配置（select/input 等） | — | — |
ellipsis | 列内容超宽单行截断省略号（悬停 title 看全文） | — | — |
filterable | 列可过滤（表头渲染筛选触发器） | — | — |
filters | 列筛选项配置 | — | — |
fixed | 列固定（left/right 吸附） | — | — |
hidden | 列隐藏（初始不参与渲染，列显隐面板可开） | — | — |
key | 列标识字段名（原生 HTML 直写；Vue 模板请用 data-key） | — | — |
merge | 列自动合并相邻同值单元格 | — | — |
options | select/multi-select 类型列的展示选项 JSON [{ value, label, color? }]（color 缺省走 token 默认色；type=select 时自动同步为编辑选项） | — | — |
serial-number | 行序号列（从 1 递增，不取数据字段） | — | — |
sortable | 列可排序（表头点击切换升/降/取消） | — | — |
summary | 列参与合计行（sum/avg/count） | — | — |
title | 列表头标题（缺省取默认插槽文本） | — | — |
type | 列字段类型（number/currency/select/multi-select/date/checkbox/link/progress/rate；text 为缺省纯文本）：驱动默认展示渲染与默认编辑器；render/cellTemplate 自定义渲染优先 | — | — |
width | 列宽（px 或 CSS 值；fixed 列建议显式声明） | — | — |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 自定义单元格内容（template 内用 row.字段 占位插值，双花括号语法） |
说明：
columns.render为函数类型，仅支持在 JS 侧构造后通过属性整体赋值，无法用 JSON 字符串表达；fixed列建议显式声明width（未声明时按 100px 兜底计算 sticky 偏移）。合计也可在列上直接写summary: 'sum' | 'avg' | 'count'；children（树形子行）与expand（可展开行内容）均为行数据字段。
加载占位行部件为 ::part(loading-row)，合计行 ::part(summary-row)、展开内容行 ::part(expand-row)，均可单独定制样式。