@qynpm/table

@qynpm/table 是后台页面唯一标准表格门面，承接已由标准管理页验证的 QyTable 行为。业务页面只使用 QyTable 和 QyTableColumn，不直接选择 Element Plus、@qynpm/table-schema、VXE 或 ProTable。

主题前置条件

本包消费 Qy CSS variables；消费项目应在应用入口导入 @qynpm/admin-theme。表格包不复制 tokens，Element Plus 的全局变量映射只由主题包提供。

渲染边界

业务页面
  -> QyTable
  -> ElementTableRenderer
  -> table-schema adapter
  -> ElTable

• QyTable 负责稳定 props、emits、slots、loading/error/rows/empty 状态优先级和 renderer 方法代理。
• ElementTableRenderer 是当前唯一 renderer，负责把 Element Plus 事件转换成公共 context、同步展开/当前行/selection 受控状态、承载 fixed、height/maxHeight 和 .el-table__* 样式。Element Plus 实例和列对象都不属于业务 API。
• table-schema adapter 是内部列适配层，不是页面 API；负责列映射、formatter、值展示、排序筛选、copy/image、cell/header slot 优先级和 type: 'actions' 行操作列。
• action 协议直接复用 @qynpm/admin-framework/actions，按钮底座复用 @qynpm/ui/qy-button。

Naive 或 React renderer 后续也必须消费同一套公共 props 和标准事件 context，不能把当前 Element Plus 参数顺序扩散到业务页面。

当前不提供 setup 列、列设置、可编辑列、VXE、虚拟滚动、树懒加载、自动请求、自动分页、合计行、合并单元格、row-dblclick 或内置 confirm。

公开 API

Props 保留 data、columns、loading、error、errorText、rowKey、childrenKey、emptyText、defaultExpandAll、defaultExpandedRowKeys、expandedRowKeys、highlightCurrentRow、currentRowKey、indentSize、height、maxHeight、selectedRowKeys 和 permissions。

列协议保留 key、label、prop、width、minWidth、fixed、align、headerAlign、showOverflowTooltip、visible、type、copy、image、actions、display、valueDisplay、hideWhenEmpty、sortable、sortMethod、sortBy、sortOrders、filters、filterMultiple、filterMethod、filteredValue、formatter 和 meta。列类型为 default、index、selection、expand、image、enum、tag、status、actions；未知类型降级为 default。

valueDisplay 只用于 enum/tag/status：options 支持静态数组或接收 { row, rowIndex, column, value } 的同步函数；严格相等优先，随后做字符串等值匹配；空值默认显示 -，可用 emptyText 覆盖；tone 只允许 neutral/primary/success/warning/danger，appearance 只允许 light/plain。color 由 renderer 转换，公共类型不接受 Element Plus tagProps。未知对象值使用安全文本回退，不显示 [object Object]。

actions 的 display: 'inline' 与值展示不是同一概念，不能和 valueDisplay 混用；排序筛选字段只用于普通数据列。当前保持兼容型 QyTableColumn，不为类型外观强制消费者迁移到破坏性的 discriminated union。

宽度规则固定为：QyTable 与 Element Plus table 始终占满父容器；状态、排序、图标、selection 和 actions 等窄列使用 width 保持稳定，名称、备注、路径等内容列优先使用 minWidth 并承接剩余空间。若所有可见普通数据列都只声明了 width，adapter 会把最后一个非 fixed 普通数据列的 width 作为 minWidth，确保不足一屏时铺满、fixed right 贴边；列最小宽度总和超过容器时，横向滚动仍只发生在 Element Plus 内部。

公开事件：

• selection-change(rows, keys)。
• update:expandedRowKeys(keys) 与 expand-change({ row, expanded, expandedRowKeys })。
• row-click({ row, rowIndex, columnKey, nativeEvent })。
• update:currentRowKey(key) 与 current-change({ row, previousRow, currentRowKey })。
• sort-change({ key, prop, order }) 与 filter-change({ key, values })。

保留 loading、error、empty、cell-${column.key}，并新增 header-${column.key}，表头 slot 只接收 { column, label } 公共字段；camelCase key 继续兼容小写 slot。type: 'expand' 的展开内容仍通过对应的 cell slot 提供。

Expose 保留 clearSelection、getSelectionRows、toggleRowSelection、toggleAllSelection、toggleRowExpansion、setCurrentRow、clearSort、clearFilter、doLayout，新增 sort(key, order)；sort 使用公共列 key，页面不需要知道 Element Plus columnKey。

Runtime

宿主通过 configureQyTableRuntime({ copy, message }) 注入浏览器剪贴板和反馈能力，并可通过 resetQyTableRuntime() 在测试后清理。公共包不依赖宿主的 feedback、store、router 或请求实现；runtime 内部仅转换为 @qynpm/table-schema 的 runtime。

宿主可在自身 runtime 层提供 table-schema adapter，页面不直接 import @qynpm/table-schema。

验证

pnpm --filter @qynpm/table test
pnpm --filter @qynpm/table typecheck
pnpm --filter @qynpm/table build