SuperAPI AI 工具集

tanstack-ember-table-getting-started

前端与建站

查看项目

更新于 10-16 09:23

技能介绍

用途

该技能用于指导在 Ember 应用中创建 TanStack Ember Table v9 表格,涵盖从环境要求、初始化设置到 Ember 特有渲染模式的完整流程。Ember Table 是无头(headless)实现,它提供响应式表格模型与渲染助手,而语义化标记、CSS、可访问性以及设计系统组件均由应用自己掌控。

环境与依赖

v9 插件要求 Ember 5.8 或更新版本,并使用 Embroider 或 ember-auto-import v2。推荐使用带 Glint 的 .gts/.gjs 模板标签组件。该技能建立在 @tanstack/table-core 的 core 与 table-features 模块之上。

主要能力与用法

设置部分给出了从 @tanstack/ember-table 导入 FlexRenderCell、FlexRenderHeader、createColumnHelper、tableFeatures、useTable 及类型 Cell、Row 的示例,并定义了 features、columnHelper、columns、初始数据、getRowId 和 getAllCells,最后在组件类中使用 @tracked data 与 this.table = useTable(() => ({...}))。

useTable 接收一个 options thunk。被该 thunk 读取的 tracked 属性会更新表格选项,而在 getter/模板中读取表格 API 会参与 Glimmer 追踪。features 与 columns 应保持在模块或组件生命周期级别的稳定作用域;仅在数据发生有意义变化时才替换 @tracked data。

Ember 特有模式

  • 在模板中保留方法接收者:v9 的 table、column、row、cell 和 header 方法位于原型上,需要其接收者。Ember 模板会提取函数引用,因此应在 getter 或小型模块级辅助函数中调用方法。示例中给出了 getCanSort 与 toggleSort 辅助函数,并说明应将 toggleSort header.column 传给 {{on}},而不要直接传入提取出的 Table 方法。
  • 通过匹配组件渲染定义:使用 FlexRenderCell、FlexRenderHeader 和 FlexRenderFooter 搭配其对应对象。定义可以返回原始值或 flexRenderComponent(Component, options)。被渲染的组件接收 @ctx 及可选 @options;Table 不会替你实例化任意组件库标记。

常见错误

  • 高优先级:传入 options 对象而非 thunk。错误写法 useTable({...}),正确写法 useTable(() => ({...}))。thunk 是将 tracked 选项读取连接到表格的方式。
  • 高优先级:将未绑定的原型方法传给模板修饰符。错误写法 {{on 'click' header.column.getToggleSortingHandler}},正确做法是将其包装在一个对 header.column 调用该方法的辅助函数中。提取出的 v9 原型方法会丢失 this,可能抛出异常或静默作用于错误的接收者。
  • 高优先级:在 options thunk 内重新创建模型输入。错误写法是在 useTable(() => ...) 内调用 columnHelper.columns(...) 或 this.data.slice()。正确做法是保持 columns 稳定并直接传递 tracked data 引用。thunk 可能会重新运行,不应在每次 tracked 更新时制造新的模型输入。
  • 中优先级:使用感知可见性的 API 却未引入对应 feature。在 tableFeatures({}) 状态下应渲染 row.getAllCells();在使用 row.getVisibleCells() 之前需先添加 columnVisibilityFeature。

API 发现

可检查 node_modules/@tanstack/ember-table/declarations/index.d.ts 了解导出,use-table.d.ts 了解选项/响应式行为,FlexRender.d.ts 与 flex-render.d.ts 了解渲染器契约,以及 node_modules/@tanstack/table-core/dist/features/<feature>/ 了解受 feature 门控的 API。不要替换为 React hooks、订阅或组件签名。

限制

资料未提供收费、价格、平台或实际运行效果等信息。