记录与表格

可运行示例在浏览器中运行本章示例↗

这里运行与本地夹具相同的 Vanilla JS 源码。模型请求由服务端网关转发，供应商密钥不会进入浏览器。

本地运行pnpm tutorial:dev j-06 --locale zh源码examples/tutorials/j-06-records-and-tables/

HTML 表格在视觉上把单元格分组，却没有告诉模型：排序后哪一行还是同一个业务对象、哪个单元格是稳定键、哪个按钮只修改这一行。记录补上这些含义，同时不替换表格。

示例保留语义化 <table>，并把每个 <tr> 声明为一条待办记录：

<table class="tasks">
  <thead>
    <tr><th scope="col">待办</th><th scope="col">状态</th><th scope="col">完成</th></tr>
  </thead>
  <tbody data-tasks></tbody>
</table>

表头向人解释列，下面的记录向助手解释行：

pling.record(row, {
  data: task,
  label: `待办：${task.text}`,
});

task 就是提供文字和状态单元格的同一个对象。用户切换待办后，下一份快照读取新的 done，而不是挂载时留下的副本。

使用稳定的业务键

任务 id 而不是行号，构成记录及其动作的锚点：

pling.tool(check, {
  id: `toggle@${task.id}`,
  desc: `切换“${task.text}”的完成状态。`,
});

排序、筛选或插入之后，t2 仍指向同一条任务，row-1 不会。表格的视觉顺序比业务身份变得频繁，这一点尤其重要。

区分显示单元格与记录字段

状态单元格显示“未完成”或“已完成”这样的人类标签；模型收到记录里的 done 布尔值，也就是业务逻辑真正使用的值。这样模型不需要从翻译后的文字猜测状态。

表格可以显示更多列，但不必全部进入记录。如果某列包含敏感数据，默认不要把它放进记录；应按敏感数据章节的写法显式标记。

行内动作属于行

完成按钮位于行内，并使用稳定的任务 id。说明指出具体任务，记录提供当前状态。二者结合后，模型可以先选行，再执行操作，不需要根据单元格位置猜测。

不要把“标记完成”编码成一个可写记录字段。记录只读。修改必须是一个动作，并拥有自己的可用性、策略和结果证据。

运行示例

pnpm tutorial:dev j-06

打开 http://127.0.0.1:5271/，或使用 --locale zh 和 http://127.0.0.1:5271/?lang=zh。

pnpm tutorial:check j-06

检查会确认表格渲染了三条稳定记录，行内动作只切换自己的记录，并且通过表单新增任务后会生成第四条带对应声明的行。

常见问题

把记录放在表格上，而不是行上。 模型会看到一个很大的对象，无法判断哪个动作属于哪个业务项。

用可见行号作为 id。 排序和删除会破坏它。应使用数据库键或业务键。

只暴露可见单元格文字。 模型可能需要底层状态值，而不是翻译标签。应保留明确、稳定的业务值。

行销毁时忘记注销记录。 刷新表格时也必须清理旧行声明，与任何动态列表一样。

下一步：表单、异步更新与弹窗。