写入与删除

所有写入方法都是异步操作。准备好数据集 ID 后再调用，并在界面中处理请求等待与失败。

insert(datasetId, data)

const created = await platform.data.insert(todos.id, {
  title: "取快递",
  done: false,
});
console.log(created.id, created.data.title);

返回 Promise<RecordRow>，结构为 { id, table_id, data, created_at, updated_at }。这里业务字段保留在 data 中，不像 query 和 getRecord 那样展开到顶层。

写入只提供业务字段，系统字段由平台生成。金额应提供数字，状态应提供 boolean；服务端会检查已声明字段的类型与必填约束，不会自动转换业务类型。可选字段可以写入 null，非文本字段不能使用空字符串表示空值；JSON 字段可以保存任意有效 JSON 值。

insertMany(datasetId, records)

const created = await platform.data.insertMany(todos.id, [
  { title: "买菜", done: false },
  { title: "取快递", done: false },
]);

一次接受 1 至 50 个数据对象，返回 Promise<RecordRow[]>，每条记录也使用嵌套 data。空数组或超过 50 条会报错。

当前批量方法按顺序插入，不保证事务原子性。中途失败时，之前成功写入的记录可能已经存在，不要不加检查就重试整批数据。

update(datasetId, recordId, patch)

const updated = await platform.data.update(todos.id, row.id, { done: true });

只传需要修改的字段，服务端将它们与现有业务数据进行浅合并；嵌套对象会整体替换，不进行递归合并。返回更新后的 RecordRow。记录不存在时会报错。

patch 是 update 的别名。服务端会检测读取和写入之间的记录或表结构变化。数据库页面还会携带编辑开始时的版本，拒绝覆盖过期内容。应用 JSB 目前未提供显式版本参数，多端协作仍需要应用根据业务设计处理。

remove(datasetId, recordId)

await platform.data.remove(todos.id, row.id);

成功返回 { ok: true }，记录不存在时会报错。delete 是 remove 的别名。删除记录是持久操作，可以先使用 ui.dialog 请求用户确认。

避免重复提交

const button = ui.button("保存", async () => {
  button.disabled = true;
  try {
    await platform.data.insert(todos.id, { title: input.value.trim(), done: false });
    ui.toast("已经保存");
  } catch (error) {
    ui.toast(error instanceof Error ? error.message : "保存失败");
  } finally {
    button.disabled = false;
  }
});

接口没有通用的幂等键参数。网络中断后结果不明确时，应先检查实际数据，再决定是否重新写入。