前言

ValuesBucket 是关系型数据库中用于插入/更新的数据结构，以键值对形式表示一行数据。在「猫猫大作战」中，每局游戏结束后的战绩数据通过 ValuesBucket 写入 GAME_RECORD 表。

一、ValuesBucket 基础

const valueBucket: relationalStore.ValuesBucket = {
  'player_name': '小明',
  'score': 2450,
  'duration': 180,
  'max_level': 5,
  'max_combo': 5,
  'game_date': '2026-07-28',
};

// 插入数据
const rowId = await store.insert('GAME_RECORD', valueBucket);
console.info(`插入成功，行 ID: ${rowId}`);

二、更新与批量插入

// 更新
const updateBucket: relationalStore.ValuesBucket = {
  'player_name': '小明V2',
  'score': 5000,
};
const changedRows = await store.update(updateBucket, predicates);

// 批量插入
async function batchInsert(records: GameRecord[]): Promise<void> {
  await store.beginTransaction();
  try {
    for (const r of records) {
      await store.insert('GAME_RECORD', {
        'player_name': r.playerName,
        'score': r.score,
        'duration': r.duration,
        'max_level': r.maxLevel,
        'max_combo': r.maxCombo,
        'game_date': r.gameDate,
      });
    }
    await store.commit();
  } catch (err) {
    await store.rollback();
    throw err;
  }
}

三、字段类型对照

四、最佳实践

1. 字段名与表列名一致：注意大小写
2. 批量插入用事务：beginTransaction + commit 提高性能
3. 验证必填字段：NOT NULL 的字段必须赋值
4. 日期用字符串：ISO 格式 YYYY-MM-DD

总结

ValuesBucket 是 RDB 写入操作的数据容器。核心要点：{ '列名': 值 } 键值对、 insert 单条写入、 beginTransaction/commit 批量写入。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• ValuesBucket API 参考
• 第 135 篇：RDB
• 第 136 篇：predicates
• 第 138 篇：orderBy