任务栏英雄存档数据

本文解释 getLatestStructuredData('3678970') 成功返回的 data。它是一个账号存档对象，以 snake_case 命名为主，包含英雄、关卡、背包、仓库和物品实例，没有额外的 slots 包装。

字段说明基于已保存业务数据的定义，不是真实账号响应。调用权限、返回状态及错误处理见游戏存档指南。下表中的整数通常为数字，超出 JavaScript 安全整数范围时返回字符串；数组也可能为 null，使用前需要校验。

顶层字段

字段	类型	含义
`update_time`	整数	记录更新时间；与原存档时间 `last_saved_time` 区分
`game_version`、`account_version`	字符串	游戏版本、账号数据版本
`play_time`	数字	存档保存的游玩时长值
`last_saved_time`	字符串	原存档保存时间
`common`	对象	关卡、波次和当前出战配置
`summary`	对象	英雄、符文、物品和槽位的汇总统计
`heroes`	数组或 `null`	全部英雄存档数据
`rune_save_data`	数组或 `null`	符文记录，元素包含 `rune_key`、`level`
`pets`	数组或 `null`	宠物记录，元素包含 `pet_key`、`is_unlock`
`attributes`	数组或 `null`	属性记录，元素包含 `key`、`level`
`inventory_slots`、`stash_slots`	数组或 `null`	背包与仓库槽位
`item_instances`	数组或 `null`	具体物品实例及附魔信息
`values`	对象	已保存的价值信息：`market_value`、`price_state`、`currency`

时间字段没有统一格式。本文不对 update_time、play_time 约定额外的单位，也不保证 last_saved_time 可直接传给 Date。values 是已保存结果，不是实时市场报价。

关卡与汇总

路径	含义
`common.max_completed_stage`	最高完成关卡
`common.current_stage_key`	当前关卡 Key
`common.current_stage_wave`	当前关卡波次
`common.arranged_hero_keys[]`	出战英雄 Key，可关联 `heroes[].hero_key`
`common.arranged_pet_key`	出战宠物 Key，可关联 `pets[].pet_key`
`summary.max_hero_level`	最高英雄等级
`summary.learned_rune_count`	已学符文数
`summary.unlocked_hero`、`summary.total_hero`	已解锁英雄数、英雄总数
`summary.item_count`	物品数
`summary.inventory_slots`、`summary.stash_slots`	背包和仓库槽位数

英雄

以下是 heroes[] 每个元素的已知字段。

字段	类型	含义
`hero_key`	整数	英雄 Key
`hero_level`	整数	英雄等级
`is_unlock`	布尔值	是否解锁
`hero_exp`	数字	英雄经验
`ability_point`	整数	能力点
`allocated_hero_ability_point`	整数	已分配能力点
`equipped_item_ids`	字符串数组或 `null`	已装备物品的实例 ID，关联 `item_instances[].unique_id`
`equipped_skill_keys`	整数数组或 `null`	已装备技能 Key
`unlocked_attribute_group_keys`	整数数组或 `null`	已解锁属性组 Key

槽位与物品实例

inventory_slots[] 和 stash_slots[] 使用相同结构：

字段	类型	含义
`index`	整数	槽位索引
`item_unique_id`	字符串	此槽位中的物品实例 ID
`is_unlock`	布尔值	槽位是否解锁
`is_unlocked_by_rune`	布尔值	是否由符文解锁

物品的具体数据在 item_instances[] 中：

字段	类型	含义
`item_key`	整数	物品种类 Key
`unique_id`	字符串	物品实例 ID；同类物品的不同实例用它区分
`is_chaotic`	布尔值	存档中的混沌标记
`is_blocked`	布尔值	存档中的锁定标记
`is_server_pending_item`	布尔值	存档中的服务端待处理物品标记
`enchant_count`	整数数组或 `null`	附魔次数记录，保留原数组顺序
`enchant_data`	数组或 `null`	附魔属性明细
`item_get_source_type`	整数	获得来源类型的原始枚举值
`decoration_applied_total_count`	整数	装饰应用累计次数
`engraving_applied_total_count`	整数	雕刻应用累计次数
`inscription_applied_total_count`	整数	铭文应用累计次数

enchant_data[] 包含 stat_mod_key（属性修饰 Key）、tier（档位）、value（数值）、recipe_type（配方类型）、mod_type（修饰类型）、material_key（材料 Key）和 stat_type（属性类型）。类型字段保留游戏原枚举值，不要在没有映射资料时自行推断名称。

关联背包与物品

下面演示用实例 ID 关联数据，而不是把 item_key 当作唯一物品。示例只列出关联所需字段，不限定返回对象的其他字段。

import hbSDK from '@heybox/hb-sdk'

const result = await hbSDK.gameSaves.getLatestStructuredData('3678970')
if (result.status === 'ready') {
  const items = Array.isArray(result.data.item_instances)
    ? result.data.item_instances
    : []
  const slots = Array.isArray(result.data.inventory_slots)
    ? result.data.inventory_slots
    : []
  const itemsById = new Map<string, Record<string, unknown>>()
  for (const item of items) {
    if (item && typeof item === 'object' && typeof item.unique_id === 'string') {
      itemsById.set(item.unique_id, item)
    }
  }
  for (const slot of slots) {
    if (slot && typeof slot === 'object' && typeof slot.item_unique_id === 'string') {
      console.log('背包槽位与物品', slot.index, itemsById.get(slot.item_unique_id))
    }
  }
}

heroes[].equipped_item_ids 也按同样方式关联。关联不到实例时应保留缺失状态，不把它解释成完整物品数据。完整接入还需处理其他返回状态及调用异常。

使用边界

数据提供 Key、ID 和数值，不自动补充英雄名称、物品图片、技能说明或实时市场价格。
heybox_id 和 steam_id 不在公开返回对象中。
未初始化的集合可能为 null；展示可用 value ?? []，外部数据仍应先检查类型。
读取只返回已有解析结果，不触发同步或解析，也不保证与文件列表中的某个 ZIP 一一对应。

任务栏英雄存档数据 ​

顶层字段 ​

关卡与汇总 ​

英雄 ​

槽位与物品实例 ​

关联背包与物品 ​

使用边界 ​

相关文档 ​