JSON 专题
说明
如果你已经开始遇到对象、数组、路径取值、批量导入导出或复杂配置缓存这类需求，就可以从这里开始。
JSON 适合处理什么
JSON 更适合处理下面这类数据：
- 一组字段组成的结构化数据
- 同一功能下的多层配置
- 需要按路径读取的对象或数组
- 需要导入、导出、排序或批量处理的数据
如果当前需求只是保存一个整数或一个字符串，通常不需要一开始就上 JSON。
JSON 命令一览
本页中的 Json-InitJson、Json-InitFrom、Json-SaveToJsonFile 等名称用于速查；实际脚本里通常写成 JSON <标识> InitJson/InitFrom/SaveToJsonFile ... 这类格式。
如果你只是来查某个命令的单页参数，可以直接看 JSON 命令分组。
JSON 标识与有效期
JSON 命令通过“标识”管理一个 JSON 对象。
使用 JSON 标识时，先记住两点：
- 默认标识有效期为
180秒 标识|-1表示该 JSON 标识不过期
初始化 JSON 的关键不是先记命令名，而是先看你手里的数据从哪里来。
初始化 JSON
这组命令负责准备一份可继续读取、判断和修改的 JSON 数据。
| 命令 | 最小格式 | 一句话用途 |
|---|---|---|
Json-InitJson | <标识> InitJson <JSON字符串> | 从一段 JSON 字符串初始化目标标识 |
Json-InitJsonFromFile | <标识> InitJsonFromFile <文件路径> | 从 JSON 文件加载内容 |
Json-InitFrom | <标识> InitFrom <源标识>[.路径] | 从其他 JSON 标识复制全部或部分内容 |
Json-InitArrayFromCsv | <标识> InitArrayFromCsv <字符串> | 从 CSV 字符串初始化数组 |
Json-InitArrayFromCsvFile | <标识> InitArrayFromCsvFile <文件路径> | 从 CSV 文件初始化数组 |
什么时候用不同的初始化方式
| 情况 | 优先命令 | 原因 |
|---|---|---|
| 数据本来就在脚本里，而且内容不大 | Json-InitJson | 直接从一段 JSON 字符串创建对象或数组 |
| 数据已经保存在 JSON 文件里 | Json-InitJsonFromFile | 直接从文件加载，避免把大段 JSON 写进脚本 |
| 已有一份 JSON，只想复制整份或某一路径 | Json-InitFrom | 适合复用已有结果，或拆出子对象继续处理 |
| 原始数据是 CSV 字符串或 CSV 文件 | Json-InitArrayFromCsv / Json-InitArrayFromCsvFile | 适合先转成数组，再继续排序、导出或循环读取 |
JSON 活动数据|-1 InitJson {"name":"活动A","open":true}
JSON 临时结果 InitJson {"count":3}
从字符串创建
JSON <标识> InitJson <JSON字符串>
适合在脚本里直接创建对象或数组。
例如：
JSON 活动数据|-1 InitJson {"name":"跨服活动","openLevel":50}
从其他 JSON 提取
JSON <标识> InitFrom <源标识>[.路径]
这类写法适合从已有 JSON 的某个路径继续拆出子对象，或者把整份 JSON 先复制一份再继续处理。
其中 InitFrom 的“.路径”可以省略。省略时，更接近“把源标识对应的 JSON 整体复制一份”再继续使用；写了路径时，则只取该路径下的对象或数组。
从 CSV 导入数组
JSON <标识> InitArrayFromCsv <字符串>
JSON <标识> InitArrayFromCsvFile <文件路径>
这类写法适合把 CSV 数据转成数组结构，再继续排序、导出或逐项处理。
写入与维护
这组命令负责写值、改值、删节点、清空内容和合并对象。
| 命令 | 最小格式 | 一句话用途 |
|---|---|---|
Json-AddValue | <标识> AddValue <名称> <值> | 在当前层追加一个名称和值 |
Json-AddOrUpdateValue | <标识> AddOrUpdateValue <名称> <值> | 按名称添加或更新一个值 |
Json-SetValueByPath | <标识> SetValueByPath <路径> <值> | 按路径设置目标值 |
Json-AddOrUpdateObject | <标识> AddOrUpdateObject <源标识> <类型> | 把源 JSON 的对象项合并到目标 JSON |
Json-Clear | <标识> Clear | 清空当前 JSON 全部内容 |
Json-DeleteByName | <标识> DeleteByName <名称> | 按名称删除当前层节点 |
Json-DeleteByPath | <标识> DeleteByPath <路径> | 按路径删除 JSON 中的目标节点 |
JSON <标识> AddValue <名称> <值>
JSON <标识> AddOrUpdateValue <名称> <值>
JSON <标识> SetValueByPath <路径> <值>
JSON <标识> AddOrUpdateObject <源标识> <类型>
当前文档和引擎资料能对上的常见值类型包括：
| 类型 | 示例 |
|---|---|
| 整数 | 12345678 |
| 字符串 | 普通字符串 |
| 布尔值 | True / False |
| 浮点数 | 1.367 |
| 日期时间 | "2018-11-12 06:12:11" |
| 数组 | ["string",100,null,true,false,123.4] |
| 对象 | {"name":"ObjectName","value":"ObjectValue"} |
如果值里本身带空格，更稳妥的写法是用双引号把它包起来，避免被拆成多个参数。
AddOrUpdateObject 当前片段可确认的类型有两种：
| 类型 | 说明 |
|---|---|
0 | 只添加目标标识中不存在的项 |
1 | 目标标识中已存在时，更新该项 |
DeleteByPath 的路径可直接按点号继续向下写。例如：
JSON myjson DeleteByPath array.3
JSON myjson DeleteByPath myobj.subobj.int2
统计节点数量
JSON <标识> GetCountByPath <变量> [路径]
| 参数 | 必填 | 说明 |
|---|---|---|
| 标识 | 是 | 要统计节点数量的 JSON 标识 |
| 变量 | 是 | 用于接收节点数量的变量 |
| 路径 | 否 | 为空时统计第一层节点数量；填写时统计该路径下对象或数组的节点数量 |
当路径为空时，获取当前 JSON 第一层节点数量；写路径时，获取该路径下对象或数组的节点数量。
例如：
JSON 活动数据 GetCountByPath M10
JSON 活动数据 GetCountByPath M11 rewards
判断 JSON 内容
CheckJson 适合在 #IF 里先判断某个 JSON 路径、名称、值或整体内容是否满足条件。
| 方法 | 用来判断什么 | 适合什么时候用 |
|---|---|---|
X | 是否包含指定路径的子节点 | 想先判断某个路径是否存在 |
N | 当前层是否有指定名称 | 想判断对象里有没有某个字段 |
V | 当前层是否有指定数值 | 想判断当前层里是否已经存在某个值 |
E | 两个 JSON 内容是否相同 | 想判断两个 JSON 标识是否一致 |
常见写法
#IF
CheckJson 活动数据 X rewards.0
#ACT
SENDMSG 7 已检测到奖励配置
#IF
CheckJson 活动数据 N status
#ACT
SENDMSG 7 已检测到状态字段
#IF
CheckJson 当前奖励 V 1001
#ACT
SENDMSG 7 奖励池里包含 1001
使用说明
X最适合拿来判断路径是否存在，通常是进入下一步取值前的第一道判断。N更像“这一层里有没有这个字段名”，适合对象结构检查。V更适合数组值或当前层数据检查，不要把它当成路径读取命令来用。E用于比较两份 JSON 是否一致；如果你只是想取某个字段再比较，优先先用<$JSON(...)>读出来。
读取 JSON 数据
<$JSON(...)> 用来从已有的 JSON 标识里把值取出来。
| 写法 | 含义 | 说明 |
|---|---|---|
<$JSON(标识.路径)J> | 单行 JSON 字符串 | 读取当前对象或路径对应的单行 JSON 结果。 |
<$JSON(标识.路径)H> | 格式化 JSON 字符串 | 读取可读性更高的多行 JSON 结果。 |
<$JSON(标识.路径)C> | 节点数量 | 读取当前对象或数组的节点数量。 |
<$JSON(标识.路径)T> | 类型值 | 0 未定义，1 对象，2 数组。 |
<$JSON(标识.路径)N.索引> | 节点名称 | 按索引读取对象当前层的节点名称。 |
<$JSON(标识.路径)V> | 当前路径的值 | 直接读取当前路径对应的值。 |
<$JSON(标识.路径)V.名称或索引> | 子节点值 | 按名称或索引继续向下读取值。 |
常见写法
#ACT
Mov D98 <$JSON(myjson.数组)C>
Mov S99 <$JSON(myjson.对象)N.<$STR(D99)>>
#SAY
Json：<$JSON(myjson)H>
第 2 个值：<$JSON(myjson.数组)V.1>
使用说明
<$JSON(...)>适合“已存在 JSON 标识，现在只想把值取出来”的场景。V最常用，用来直接取当前路径的值；C适合循环前先取数量；N适合先拿对象键名再继续读值。- 当你需要读完整 JSON 文本时，用
J或H；当你只关心某个字段时，优先用V。 - 路径通常按点号继续向下写，例如
myjson.object.subobj.int2、myjson.array.3。
导出与排序
这组命令适合把运行中的 JSON 保存到文件、转换成 CSV，或在导出前先做排序处理。
| 命令 | 最小格式 | 一句话用途 |
|---|---|---|
Json-SaveToJsonFile | <标识> SaveToJsonFile <文件路径> | 把当前 JSON 保存到文件 |
Json-ToCsv | <标识> ToCsv <变量> | 把 JSON 转换为 CSV 字符串 |
Json-SaveToCsvFile | <标识> SaveToCsvFile <文件路径> | 把 JSON 保存为 CSV 文件 |
Json-SortByName | <标识> SortByName <0/1> | 按名称排序当前层节点 |
Json-SortByValue | <标识> SortByValue [0/1] | 按值排序当前层节点 |
排序参数
| 参数值 | 说明 |
|---|---|
0 | 升序 |
1 | 降序 |
需要注意的是，ToCsv 和 SaveToCsvFile 更适合用于数组对象；并不是所有 JSON 结构都适合直接导出成 CSV。