RUST✅NXJSON✅详细使用说明书✅50+个函数，功能齐全实用

jcos

比一版更新多了30个函数，功能更齐全了！

# NX JSON 库 - 易语言使用文档
## 简介
NX JSON 是一个高性能的 JSON 解析和操作库，使用 Rust 编写，提供易语言封装接口。

## 初始化与销毁
### 自动管理
类对象创建时自动初始化，销毁时自动释放，无需手动调用。
.局部变量 json, 类_json_NX
' 创建对象时自动初始化
' 对象销毁时自动释放

## 解析操作
### 解析
解析 JSON 文本为对象。
**语法：** `解析(JSON文本, [为对象], [错误原因])`
**示例：**
结果 ＝ json.解析("{"name":"张三","age":25}", 真, )

### 清除
清空 JSON 对象的所有内容。
**语法：** `清除()`
**示例：**
json.清除()

## 输出操作
### 取数据文本
获取 JSON 对象的紧凑字符串表示。
**语法：** `取数据文本()`
调试输出(json.取数据文本())
' 输出: {"name":"张三","age":25}

### 取格式化文本
获取带缩进的格式化 JSON 字符串。
**语法：** `取格式化文本()`
**示例：**
调试输出(json.取格式化文本())
' 输出:
' {
'   "name": "张三",
'   "age": 25
' }

## 属性判断
### 属性是否存在
检查指定路径的属性是否存在。
**语法：** `属性是否存在(属性名)`
**示例：**
.如果 (json.属性是否存在("['name']"))
    调试输出("name 属性存在")
.否则
    调试输出("name 属性不存在")

### 是否为空
判断属性是否为空或不存在。
**语法：** `是否为空(属性名)`

### 是否为空值
判断属性值是否为 null。
**语法：** `是否为空值(属性名)`

### 是否为数组
判断属性是否为数组类型。
**语法：** `是否为数组(属性名)`

### 是否为对象
判断属性是否为对象类型。
**语法：** `是否为对象(属性名)`

### 是否为数值
判断属性是否为数值类型。
**语法：** `是否为数值(属性名)`

### 是否为文本
判断属性是否为字符串类型。
**语法：** `是否为文本(属性名)`

### 是否为逻辑
判断属性是否为布尔类型。
**语法：** `是否为逻辑(属性名)`

### 取类型
获取属性的类型值。
**语法：** `取类型(属性名)`
| 返回值 | 类型 |
| -1 | 未知
| 0 | 未定义/null
| 1 | 布尔值
| 2 | 数值
| 4 | 对象
| 5 | 数组
| 6 | 字符串

## 属性设置
### 置属性
设置属性值。
**语法：** `置属性(属性名, 值, [为对象])`
**示例：**
' 设置字符串
json.置属性("['name']", "张三", )
' 设置 JSON 对象
json.置属性("['data']", "{"id":1}", 真)
' 创建空对象
json.置属性("['info']", "{}", 真)
' 创建空数组
json.置属性("['list']", "[]", 真)

### 置属性对象
设置属性为 JSON 对象。
**语法：** `置属性对象(属性名, 值)`
**示例：**
json.置属性对象("['user']", "{"id":1,"name":"张三"}")

### 置属性数值
设置数值属性。
**语法：** `置属性数值(属性名, 值)`
**示例：**
json.置属性数值("['age']", 25)
json.置属性数值("['price']", 99.99)

## 属性获取
### 取通用属性
获取属性值。
**语法：** `取通用属性(属性名, [为对象])`
**示例：**
' 获取字符串值
json.取通用属性("['name']", )
' 获取对象文本
json.取通用属性("['user']", 真)

### 取属性
获取属性为新的 JSON 对象。
**语法：** `取属性(属性名)`
**示例：**
userJson ＝ json.取属性("['user']")
userJson.取文本("['name']")

### 取属性数值
获取数值属性。
**语法：** `取属性数值(属性名)`
**示例：**
json.取属性数值("['age']")

### 取属性对象
获取属性的 JSON 文本。
**语法：** `取属性对象(属性名)`
**示例：**
json.取属性对象("['user']")
输出: {"id":1,"name":"张三"}

### 取整数
获取整数属性值。
**语法：** `取整数(属性名)`
json.取整数("['id']")

### 取数字文本
获取数字的字符串表示（支持大整数，不会溢出）。
**语法：** `取数字文本(属性名)`
**示例：**
' 对于超大整数，取整数可能溢出返回0，此时请使用取数字文本
json.取数字文本("['big_number']")
' 输出: 9223372036854775807

### 取数值
获取数值属性值（含小数）。
**语法：** `取数值(属性名)`
**示例：**
json.取数值("['price']")

### 取逻辑
获取布尔属性值。
**语法：** `取逻辑(属性名)`
**示例：**
.如果 (json.取逻辑("['enabled']"))
    调试输出("已启用")
.否则
    调试输出("已禁用")
.如果结束

### 取文本
获取字符串属性值。
**语法：** `取文本(属性名)`
**示例：**
json.取文本("['name']")

## 属性删除
### 删属性
删除指定属性。
**语法：** `删属性(属性名)`
**示例：**
json.删属性("['temp']")

## 数组操作
### 成员数
获取数组成员数量。
**语法：** `成员数(属性名)`
**示例：**
json.成员数("['list']")

### 加成员
添加数组成员。
**语法：** `加成员(值, [属性名], [为对象], [开头添加])`
**示例：**
' 先创建空数组
json.置属性("['list']", "[]", 真)
' 追加到末尾
json.加成员("值1", "['list']", , )
json.加成员("值2", "['list']", , )
' 添加到开头
json.加成员("值0", "['list']", , 真)
' 添加 JSON 对象
json.加成员("{\"id\":1}", "['list']", 真, )

### 取成员
获取数组成员为新的 JSON 对象。
**语法：** `取成员(成员索引, [属性名])`
**示例：**
item ＝ json.取成员(0, "['list']")
item.取文本("['name']")

### 取成员文本
获取数组成员的文本值。
**语法：** `取成员文本(成员索引, [属性名], [为对象])`
**示例：**
' 获取字符串值
json.取成员文本(0, "['list']", )
' 获取对象文本
调试输出(json.取成员文本(0, "['list']", 真)

### 置成员
设置数组成员值（只能修改已存在的索引）。
**语法：** `置成员(成员索引, 属性名, 值, [为对象])`
**注意：** 此方法只能修改已存在的元素，不能添加新元素。添加元素请使用 `加成员`。
**示例：**
' 先创建有元素的数组
json.置属性("['list']", "[\"a\",\"b\",\"c\"]", 真)
' 修改第一个元素
json.置成员(0, "['list']", "新的值", )

### 删成员
删除数组成员。
**语法：** `删成员(成员索引, [属性名])`
**示例：**
json.删成员(0, "['list']")

## 批量操作
### 取所有属性名
获取指定路径下的所有属性名。
**语法：** `取所有属性名(属性名数组, [属性名])`
**示例：**
数量 ＝ json.取所有属性名(属性列表, )
.计次循环首 (数量, i)
    调试输出(属性列表 )
.计次循环尾 ()

### 取所有属性值
获取指定路径下的所有属性值。
**语法：** `取所有属性值(属性值数组, [属性名], [向下递归])`
**示例：**
' 非递归获取
json.取所有属性值(值列表, , 假)
' 递归获取所有嵌套值
json.取所有属性值(值列表, , 真)

## 高级操作
### 克隆
克隆当前JSON对象，创建一个完全独立的副本。
**语法：** `克隆()`
json2 ＝ json.克隆()
' 修改json2不会影响原json对象
json2.置属性("['name']", "李四", )
json.取文本("['name']")) ' 输出: 张三
json2.取文本("['name']")) ' 输出: 李四

### 查询
使用JSONPath语法查询JSON数据。
**语法：** `查询(查询表达式)`
JSONPath表达式，如`$.store.book[0].title`
**示例：**
json文本 ＝ "{"store":{"book":[{"title":"Book1","price":10},{"title":"Book2","price":20}],"bicycle":{"color":"red","price":100}},"name":"Test Store"}"
json.解析(json文本, 真, )
' 查询单个属性
json.查询("$.name")
' 输出: "Test Store"
' 查询嵌套属性
json.查询("$.store.bicycle.color")
' 输出: "red"
' 查询数组元素
json.查询("$.store.book[0].title")
' 输出: "Book1"
' 查询所有匹配项
json.查询("$.store.book.title")
' 输出: ["Book1","Book2"]

### 合并
将另一个JSON对象合并到当前对象。
**语法：** `合并(来源JSON, [是否覆盖])`
**示例：**
json1.解析("{"name":"张三","age":25}", 真, )
json2.解析("{"age":30,"city":"北京"}", 真, )
' 不覆盖已存在属性
json1.合并(json2, 假)
json1.取数据文本()
' 输出: {"name":"张三","age":25,"city":"北京"}
' 覆盖已存在属性
json1.合并(json2, 真)
json1.取数据文本()
' 输出: {"name":"张三","age":30,"city":"北京"}

### 对比
对比两个JSON对象的差异。
**语法：** `对比(对比JSON)`
**示例：**
json1.解析("{"name":"张三","age":25}", 真, )
json2.解析("{"name":"张三","age":30,"city":"北京"}", 真, )
调试输出(json1.对比(json2))
' 输出差异信息

### 验证
使用JSON Schema验证当前JSON数据。
**语法：** `验证(Schema对象)`
**示例：**
' 定义Schema
schema.解析("{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"integer"}},"required":["name","age"]}", 真, )
' 验证数据
.如果 (json.验证(schema) ＝ “”)
    调试输出("验证通过")
.否则
    调试输出("验证失败: " ＋ json.验证(schema))
.如果结束

### 批量获取
批量获取多个属性值。
**语法：** `批量获取(属性名数组)`
**示例：**
' 一次性获取多个属性值
调试输出(json.批量获取("["name","age","city"]"))
' 输出: ["张三",25,"北京"]

### 批量设置
批量设置多个属性值。
**语法：** `批量设置(设置项数组)`
**示例：**
' 一次性设置多个属性
json.批量设置("[["name","李四"],["age",30],["city","上海"]]")

### 批量删除
批量删除多个属性。
**语法：** `批量删除(属性名数组)`
**示例：**
' 一次性删除多个属性
json.批量删除("["temp","cache","log"]")

## 编码转换
### GBK到UTF8
将GBK编码文本转换为UTF-8编码。
**语法：** `GBK到UTF8(GBK文本)`
**示例：**
utf8结果 ＝ json.GBK到UTF8("中文测试")
' 注意：UTF-8结果在易语言中显示为乱码是正常的

### UTF8到GBK
将UTF-8编码文本转换为GBK编码。
**语法：** `UTF8到GBK(UTF8文本)`
**示例：**
原始文本 ＝ "中文测试"
utf8结果 ＝ json.GBK到UTF8(原始文本)
gbk结果 ＝ json.UTF8到GBK(utf8结果)
' gbk结果应该等于原始文本

### USC2到GBK
将USC2编码（`\uXXXX`格式）转换为GBK编码。
**语法：** `USC2到GBK(USC2文本)`
**示例：**
调试输出(json.USC2到GBK("\u4e2d\u6587\u6d4b\u8bd5"))
' 输出: 中文测试

### USC2到UTF8
将USC2编码（`\uXXXX`格式）转换为UTF-8编码。
**语法：** `USC2到UTF8(USC2文本)`
**示例：**
json.USC2到UTF8("\u4e2d\u6587")

## 流式解析（大文件处理）
流式解析功能用于处理超大JSON文件，无需一次性加载整个文件到内存。

### 流式查询
直接查询JSON Lines文件（每行一个JSON对象），无需完整解析。
**DLL命令：** `nx_json_stream_query`
**语法：** `流式查询(文件路径, 查询路径)`
**示例：**
' 查询大文件中的特定数据
结果 ＝ nx_json_stream_query ("目录\data.jsonl", "$.name")
结果 ＝ 流式查询("data.jsonl", "$.name")

### 流式分割
将大JSON文件分割成多个小文件，每个文件包含指定数量的对象。
**DLL命令：** `nx_json_stream_split`
**语法：** `流式分割(文件路径, 最大对象数)`
**示例：**
' 将大文件分割成每个包含1000个对象的小文件
分割文件列表 ＝ nx_json_stream_split ("large_data.json", 1000)
或用易语言的函数调用
分割文件列表 ＝ 流式分割("large_data.json", 1000)
调试输出(分割文件列表)
' 输出: ["large_data_part_0.json","large_data_part_1.json",...]

### 流式解析器管理
流式解析器管理功能用于创建和管理流式解析器句柄，监控大文件解析进度。
#### 流式创建
创建流式解析器，返回句柄。

#### 流式取文件大小
获取要解析的文件大小。
**语法：** `流式取文件大小(句柄)`

#### 流式取进度
获取当前解析进度。
**语法：** `流式取进度(句柄)`
**返回值：** 整数型，解析进度（0-100），-1表示错误

#### 流式销毁
销毁流式解析器，释放资源。
**语法：** `流式销毁(句柄)`
**返回值：** 整数型，1成功，0失败

#### 流式加载行
加载文件所有行到内存，返回总行数。
**语法：** `流式加载行(句柄)`
**返回值：** 整数型，文件总行数，-1表示错误

#### 流式取行
获取指定行或下一行内容。
**语法：** `流式取行(句柄, [行号])`
**返回值：** 文本型，行内容（空字符串表示无更多行或行号超出范围）

**完整示例：**
句柄 ＝ json.流式创建 ("large_file.json")
.如果 (句柄 ≠ -1)
    文件大小 ＝ json.流式取文件大小 (句柄)
    调试输出("文件大小: " ＋ 到文本 (文件大小) ＋ " 字节")
    ' 加载所有行
    行数 ＝ json.流式加载行 (句柄)
    调试输出("总行数: " ＋ 到文本 (行数))
    ' 逐行读取
    .计次循环首 (行数, i)
        行内容 ＝ json.流式取行 (句柄, 0)  ' 获取下一行
        调试输出("第" ＋ 到文本 (i) ＋ "行: " ＋ 行内容)
        进度 ＝ json.流式取进度 (句柄)
        调试输出("进度: " ＋ 到文本 (进度) ＋ "%")
    .计次循环尾 ()
    json.流式销毁 (句柄)
.如果结束

**获取指定行示例
' 直接获取第5行
行内容 ＝ json.流式取行 (句柄, 5)

**底层DLL命令（如需直接使用）
.DLL命令 nx_json_stream_create, 整数型, "nx_json.dll", "nx_json_stream_create"
    .参数 文件路径, 文本型
.DLL命令 nx_json_stream_get_file_size, 长整数型, "nx_json.dll", "nx_json_stream_get_file_size"
    .参数 句柄, 整数型
.DLL命令 nx_json_stream_get_progress, 整数型, "nx_json.dll", "nx_json_stream_get_progress"
    .参数 句柄, 整数型
.DLL命令 nx_json_stream_destroy, 整数型, "nx_json.dll", "nx_json_stream_destroy"
    .参数 句柄, 整数型

## 其他
### 取版本
获取库版本号。
**示例：**
json.取版本()
' 输出: 1.5.0

## 路径语法
### 支持的路径格式
| 格式 | 示例 | 说明
| 点号格式    | `user.name` | 访问嵌套属性
| 方括号格式 | `['user']['name']` | 支持中文和特殊字符
| 数组索引    | `list.0` 或 `['list']['0']` | 访问数组元素
| 混合格式    | `users.0.name` | 混合使用

### 路径示例
' 对象属性
json.取文本("name")
json.取文本("['name']")
json.取文本("['中文字段']")
' 嵌套对象
json.取文本("user.name")
json.取文本("['user']['name']")
' 数组元素
json.取成员文本(0, "list")
json.取文本("['list']['0']")
' 嵌套数组对象
json.取文本("users.0.name")
json.取文本("['users']['0']['name']")
```
## 完整示例
### 示例1：构建简单对象
json.置属性("['状态']", "success", )
json.置属性数值("['数量']", 100)
json.置属性("['消息']", "操作成功", )
调试输出(json.取数据文本())
' 输出: {"状态":"success","数量":100,"消息":"操作成功"}

### 示例2：构建嵌套对象
' 创建用户对象
json.置属性("['user']", "{}", 真)
json.置属性("['user']['id']", "1", )
json.置属性("['user']['name']", "张三", )
json.置属性数值("['user']['age']", 25)
调试输出(json.取格式化文本())

### 示例3：构建数组
' 创建数组
json.置属性("['list']", "[]", 真)
' 添加元素
.计次循环首 (3, i)
    json.加成员("项目" ＋ 到文本 (i), "['list']", , )
.计次循环尾 ()
调试输出(json.取数据文本())
' 输出: {"list":["项目1","项目2","项目3"]}

### 示例4：构建对象数组
json.置属性("['状态']", "success", )
json.置属性数值("['数量']", 3)
json.置属性("['data']", "[]", 真)
.计次循环首 (3, i)
    json.加成员("{}", "['data']", 真, )
    json.置属性("['data']['" ＋ 到文本 (i － 1) ＋ "']['id']", 到文本 (i), )
    json.置属性("['data']['" ＋ 到文本 (i － 1) ＋ "']['name']", "用户" ＋ 到文本 (i), )
.计次循环尾 ()
调试输出(json.取格式化文本())

### 示例5：解析并遍历
json.解析("{"name":"张三","age":25,"city":"北京"}", 真, )
数量 ＝ json.取所有属性名(属性列表, )
.计次循环首 (数量, i)
    调试输出(属性列表  ＋ " = " ＋ json.取通用属性(属性列表 , ))
.计次循环尾 ()

### 示例6：数据库查询结果转JSON
.如果 (记录数 ＞ 0)
    json.置属性("['状态']", "success", )
    json.置属性数值("['数量']", 记录数)
    .计次循环首 (记录数, i)
        json.置属性("['" ＋ 到文本 (i － 1) ＋ "']", "{}", 真)
        .计次循环首 (字段数, j)
            序号到字段名 (记录集, j － 1, 字段名)
            读字段值 (记录集, 字段名, 字段值)
            json.置属性("['" ＋ 到文本 (i － 1) ＋ "']['" ＋ 字段名 ＋ "']", 字段值, )
        .计次循环尾 ()
        到下一行 (记录集)
    .计次循环尾 ()
.否则
    json.置属性("['状态']", "error", )
    json.置属性数值("['数量']", 0)
    json.置属性("['消息']", "没有找到数据", )
.如果结束

## 注意事项
1. **空路径行为**：使用空字符串 `""` 作为路径会替换整个 JSON 对象，请谨慎使用。
2. **数组索引**：数组索引从 **0** 开始，易语言计次循环从 **1** 开始，注意转换。
3. **置成员 vs 加成员**：
   - `置成员`：只能修改已存在的元素
   - `加成员`：动态添加新元素
4. **中文属性名**：建议使用方括号格式 `['中文属性']` 访问中文属性名。
5. **内存管理**：类对象自动管理内存，无需手动释放。
6. **取所有属性名/值的分隔符**：`取所有属性名` 和 `取所有属性值` 内部使用换行符 `\n`（ASCII 10）分隔返回结果。如果在自定义封装时手动分割返回的文本，请使用 字符(10) 而非 #换行符。
   ' 正确做法
   属性名数组 ＝ 分割文本 (返回文本, 字符(10), )
   ' 错误做法（会导致分割失败）
   属性名数组 ＝ 分割文本 (返回文本, #换行符,


模块地址
https://bbs.ijingyi.com/thread-14873571-1-1.html
关注群，时不时更新..
(这个使用说明是最新版的)

airaz

鬼炙

膜拜大佬

hehz977

感谢分享

mytiger

感谢分享

suming99

1101469226

tvvvhg

拿几个币

huxian

拿几个币

welkin

感谢分享