AtTable 复杂用法

夏源庆

最后更新于 2026-10-30 11:40:07

完整页面见 CRUD 列表 和 左右布局。MCP get_component 将方法和暴露状态分别返回；data、loading、pagination 等是状态，不是方法。

请求协议与参数合并

listApi 返回 { data: apiData, err }。分页路径相对于 apiData：默认 list 为 data，total 为 meta.total，请求页码键为 page、页大小为 size。样板模拟响应采用 { data: { list, total }, err }，所以显式配置 pagerKeys，避免受全局 AtConfigProvider 配置影响。

useTableListApi(api) 提供 tableRef、getList、passDefaultList、tableFilter。passDefaultList(defaults) 内部按 { ...defaults, ...tableParams } 合并，表格参数覆盖默认参数；defaults 对象不是响应式请求订阅。父级条件变化需要显式 tableFilter，或用 listApi 包装函数在每次调用时读取最新上下文。

filter(filters, withOldParams = true)：传入对象会把页码重置为 1；默认合并缓存参数，false 替换缓存参数。移除筛选条件时不要只传空对象并期望旧条件被删除。tableFilter 是不等待请求的包装，需等列表加载结束时使用实例的 await filter(...) 或 data-loaded 事件。

分页、排序与刷新

refresh(keepPage = true) 保留当前筛选和页码；refresh(false) 回到第一页。删除末页最后一条后按产品规则回退或回到首页，组件不会自动选择业务期望的页。

远程排序默认将字段和方向写入 orderByColumn、isAsc；通过 sorterKeys 映射接口协议。当前排序变化不会自动回第一页。页大小改变会回第一页。

autoFetch: false 用于父条件准备后或弹窗打开后才加载；但当前实现存在默认排序列时，挂载仍会触发初始化排序请求。需要严格延迟加载的场景不要同时设置 defaultSortOrder；先 await open，再调用 filter/refresh。本次只记录此边界，不修改组件行为。

选择、回显与树表联动

始终提供稳定 row-key，不能依赖页内下标。getSelectedData<Row>() 的泛型是单行类型，返回 count、checkedKeys、checkedRows。键可以包含非当前页数据；checkedRows 是已获取行的缓存，不能仅根据任意 key 推导出完整业务对象。

用 setCheckedKeys 回显选择；数据加载后需要复原业务选择时监听 data-loaded。该事件携带 data、originData、pagination、source；source 区分 init/page/page-size/sort/filter/refresh。更换父树节点或切换业务上下文时，显式 clearSelection，避免带入旧上下文。

左右布局样板等待 tableRef 和选中节点都可用，再 clearSelection + tableFilter(..., false)。弹窗双表预览应使用稳定标识，将主表已选行转为预览接口返回，再刷新预览表。

响应性与透传边界

默认 data 使用 shallowRef，直接修改内部行字段不保证触发视图更新。行内编辑需要 deepReactive，或整体替换数据。部分 attrs 在 setup 时转换，useData 也在初始化时取 props；不要假设动态替换全部表格配置都能被重新初始化。使用稳定配置与显式 filter/refresh；必须重建实例时使用业务身份 key。

继承 Naive UI 的 DataTableProps 是类型声明；AtTable 自己管理 data、loading、分页、checkedRowKeys 等并向下绑定，不能把它们当作未封装的原生 DataTable 随意控制。精确透传以源码和 MCP 返回的模板绑定证据为准。

场景来源与核验

• dt-lion-platform-pc/src/views/DataBackup2/TaskDetail/components/SubscribeModal/index.vue:85：打开后初始化；107–126 行是双表选择与预览、auto-fetch false。
• dt-g-mpas-pc/src/views/PrivateData/index.vue:125：data-loaded 后同步业务选中状态。
• 当前实现：components/src/table/src/hooks/use-data.ts、use-list-api.ts、components/src/table/src/AtTable.vue。上述请求路径、参数优先级、排序和默认排序例外均从当前实现核验。