cJson 开发者文档手册

概述

cJson 是 VBMAN 框架提供的 JSON 处理类，基于 VBA-JSON v2.3.1 (Tim Hall) 改进封装。它提供了简单易用的 API 来解析和生成 JSON 数据，支持嵌套对象、数组、文件操作等功能。

主要特性

• 类型映射清晰：Dictionary（字典）↔ JSON 对象 {...}，Collection（集合）↔ JSON 数组 [...]
• 节点创建与成员设置分离：NewItem/NewItems 创建子节点，Item/Items 在节点上增改成员
• 默认成员：Root 是默认成员，可直接用 Json("key") 访问，支持链式嵌套
• 支持嵌套：无限层级的 JSON 对象和数组嵌套
• 文件操作：支持从文件加载和保存 JSON 数据
• 编码解码：支持 JSON 字符串与 VB 对象的相互转换
• 格式化输出：支持自定义缩进格式化 JSON 字符串
• 中文支持：支持中文原样显示（不进行 Unicode 转码）
• 数组下标：集合数组下标从 1 开始（符合 VB 习惯）

创建方式

方式一：使用全局实例（推荐）

'使用 VBMAN 内置的全局 Json 实例
With VBMAN.Json
    .Item("name") = "张三"
    MsgBox .Encode()
End With

方式二：创建新实例

'创建独立实例
Dim Json As New VBMANLIB.cJson
Json.Item("name") = "张三"
MsgBox Json.Encode()

'或者使用 With New
With New VBMANLIB.cJson
    .Item("name") = "张三"
    MsgBox .Encode()
End With

快速示例

示例 1：创建简单 JSON 对象

With New cJson
    .Item("code") = 200
    .Item("msg") = "操作成功"
    .Item("data") = "返回数据"
    MsgBox .Encode(, 2, True)
End With
'输出：
'{
'  "code": 200,
'  "msg": "操作成功",
'  "data": "返回数据"
'}

示例 2：创建包含数组的 JSON

With New cJson
    .Item("code") = 200
    .Item("msg") = "操作成功"
    With .NewItems("data")  '创建数组
        With .NewItem()      '数组第一个对象
            .Item("name") = "张三"
            .Item("age") = 25
        End With
        With .NewItem()      '数组第二个对象
            .Item("name") = "李四"
            .Item("age") = 30
        End With
    End With
    MsgBox .Encode(, 2, True)
End With

示例 3：解析 JSON 字符串（使用 Root 访问）

Dim JsonText As String
JsonText = "{""name"":""张三"",""age"":25}"

With New cJson
    .Decode JsonText
    '使用 Root（默认成员）访问 - 推荐方式
    MsgBox .Root("name")  '输出：张三
    MsgBox .Root("age")   '输出：25

    '或者直接使用默认成员特性
    MsgBox $("name")     '输出：张三
End With

文档导航

• 快速开始 - 5 分钟上手指南
• API 参考 - 完整的属性和方法说明
• 示例代码 - 详细的代码示例

注意事项

1. 类型对应：Dictionary（字典）对应 JSON 对象 {...}，Collection（集合）对应 JSON 数组 [...]
2. Root 是默认成员：可直接用 Json("key") 访问，等同于 Json.Root("key")，用于链式读写
3. NewItem/NewItems 创建节点：NewItem 创建子对象节点，NewItems 创建子数组节点
4. Item/Items 增改成员：Item 在对象节点上设置键值对，Items 在数组节点上添加元素
5. 数组下标从 1 开始：VB 的 Collection 对象下标从 1 开始，与 JavaScript 不同
6. 全局实例共享数据：VBMAN.Json 是全局实例，数据会在多次使用间保留，必要时调用 .Clear() 清理