AndroidRemoteController/doc/JSON_PARSER.md

JSON Parser 使用文档

功能说明

通过 IPC 调用 json-parser.js 进行 JSON 文件的创建、读取、更新和存在性检查。

重要： 所有文件只能保存在 static 目录下，使用相对路径即可。如果传入 jason/testjson，实际文件路径为 static/jason/testjson.json。

操作类型

1. create - 创建 JSON 文件

创建新的 JSON 文件。

参数：

• operation: 'create'
• filePath: JSON 文件相对路径（相对于 static 目录），如 jason/testjson，会自动添加 .json 扩展名
• jsonString: JSON 数据（字符串格式）

示例：

const response = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'create', 'jason/testjson', JSON.stringify({devices: [], settings: {}}))).stdout)

返回：

{
  "success": true,
  "message": "JSON file created successfully"
}

2. read - 读取 JSON 文件

读取 JSON 文件内容。如果文件不存在，返回 { success: true, data: null }。

参数：

• operation: 'read'
• filePath: JSON 文件相对路径（相对于 static 目录），如 jason/testjson
• keyPathJson: （可选）键路径数组，如 JSON.stringify(['devices', 0, 'ip'])

示例：

// 读取整个文件
const readResult = await window.electronAPI.runNodejsScript('json-parser', 'read', 'device_list.json')
const readResponse = JSON.parse(readResult.stdout)
const data = readResponse.data

// 如果文件不存在（data 为 null），则创建
if (data === null) {
    const createResult = await window.electronAPI.runNodejsScript('json-parser', 'create', 'device_list.json', JSON.stringify({devices: []}))
}

// 读取特定路径
const ip = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'read', 'jason/testjson', JSON.stringify(['devices', 0, 'ip']))).stdout).data

返回：

// 文件存在时
{
  "success": true,
  "data": {...}
}

// 文件不存在时
{
  "success": true,
  "data": null
}

3. update - 更新 JSON 文件

更新 JSON 文件内容。

参数：

• operation: 'update'
• filePath: JSON 文件相对路径（相对于 static 目录），如 jason/testjson
• jsonString: 要更新的 JSON 数据（字符串格式）
• keyPathJson: （可选）键路径数组，用于更新特定路径

示例：

// 更新整个文件（合并）
const response = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'update', 'jason/testjson', JSON.stringify({newKey: 'value'}))).stdout)

// 更新特定路径
const response = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'update', 'jason/testjson', JSON.stringify(true), JSON.stringify(['settings', 'autoConnect']))).stdout)

返回：

{
  "success": true,
  "message": "JSON file updated successfully"
}

4. check - 检查文件是否存在

检查 JSON 文件是否存在。

参数：

• operation: 'check'
• filePath: JSON 文件相对路径（相对于 static 目录），如 jason/testjson

示例：

const exists = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'check', 'jason/testjson')).stdout).exists

返回：

{
  "success": true,
  "exists": true
}

封装函数使用（推荐）

在 device.js 中已提供封装函数，使用更简洁：

import { 
  createJsonFile, 
  readJsonFile, 
  updateJsonFile, 
  checkJsonFileExists 
} from './device.js'

// 创建 JSON 文件
const result = await createJsonFile('jason/testjson', {devices: []})

// 读取整个文件
const data = await readJsonFile('jason/testjson')

// 读取特定路径
const ip = await readJsonFile('jason/testjson', ['devices', 0, 'ip'])

// 更新整个文件
const result = await updateJsonFile('jason/testjson', {newKey: 'value'})

// 更新特定路径
const result = await updateJsonFile('jason/testjson', true, ['settings', 'autoConnect'])

// 检查文件是否存在
const exists = await checkJsonFileExists('jason/testjson')

键路径格式

键路径使用数组格式，然后通过 JSON.stringify() 序列化：

// 访问 devices[0].ip
JSON.stringify(['devices', 0, 'ip'])

// 访问 settings.theme
JSON.stringify(['settings', 'theme'])

// 访问 users[1].profile.name
JSON.stringify(['users', 1, 'profile', 'name'])

注意事项

1. 文件路径：使用相对路径（相对于 static 目录），如 jason/testjson 会保存为 static/jason/testjson.json
2. 自动添加扩展名：如果路径没有 .json 扩展名，会自动添加
3. 路径安全：禁止使用 .. 或绝对路径，所有文件只能在 static 目录下
4. JSON 序列化：所有 JSON 数据必须使用 JSON.stringify() 序列化
5. 返回值解析：脚本返回的 stdout 是 JSON 字符串，需要 JSON.parse() 解析
6. 错误处理：检查返回的 success 字段判断操作是否成功
7. 自动创建目录：如果文件所在目录不存在，会自动创建
8. read 操作特性：文件不存在时返回 { success: true, data: null }，可通过 data === null 判断文件是否存在

实际应用示例

读取或创建文件

const readResult = await window.electronAPI.runNodejsScript('json-parser', 'read', 'device_list.json')
const readResponse = JSON.parse(readResult.stdout)
let jsonData = readResponse.data

if (jsonData === null) {
    const createResult = await window.electronAPI.runNodejsScript('json-parser', 'create', 'device_list.json', JSON.stringify({devices: []}))
    const createResponse = JSON.parse(createResult.stdout)
    if (createResponse.success) {
        jsonData = {devices: []}
    }
}

错误示例

{
  "success": false,
  "error": "Missing jsonString parameter for create operation"
}

{
  "success": false,
  "error": "Invalid file path"
}