前言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[]): Promisevoid { 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; } }三、字段类型对照ArkTS 类型ValuesBucket 值SQLite 类型string‘小明’TEXTnumber2450INTEGERnumber3.14REALbooleantrueINTEGER(0/1)Uint8ArraybufferBLOB四、最佳实践字段名与表列名一致注意大小写批量插入用事务beginTransaction commit提高性能验证必填字段NOT NULL的字段必须赋值日期用字符串ISO 格式YYYY-MM-DD总结ValuesBucket 是 RDB 写入操作的数据容器。核心要点{ 列名: 值 }键值对、insert单条写入、beginTransaction/commit批量写入。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源ValuesBucket API 参考第 135 篇RDB第 136 篇predicates第 138 篇orderBy