【技术文档】LuaGlobalVar — 全局变量操作

[VG3 Lua API 技术文档](http://218.76.30.1:30067/doc/691/)

## 概述

`LuaGlobalVar` 模块用于在 VG3 系统的全局变量块中存储和读取数据。全局变量跨脚本、跨流程保持有效，是数据共享与持久化的核心机制。支持的数据类型包括：布尔、整数、浮点、字符串、坐标、姿态、直线、范围、矩形、旋转矩形、圆以及它们的数组版本。

---

## 目录

| 编号 | 功能分类 | 说明 |
|------|----------|------|
| 1 | 全局控制 | 全局数据保存管理 |
| 2 | 变量检查 | 判断变量是否存在或有效 |
| 3 | 基础读写（通用） | 任意类型的读写与初始化 |
| 4 | 读取（按名称） | 20 种类型的按名称读取 |
| 5 | 读取（按索引） | 20 种类型的按索引读取 |
| 6 | 写入（按名称） | 常规写入 + 初始化写入 |
| 7 | 写入（按索引） | 按索引常规/初始化写入 |
| 8 | 使用示例 | 完整场景演示 |

---

## 1. 全局控制

控制全局变量的数据持久化行为。

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `SetSaveGlobalData(isSave)` | 设置是否自动保存全局数据到文件 | `isSave`: `bool` | 无 |
| `GetSaveGlobalData()` | 查询当前是否开启了自动保存 | 无 | `bool` |
| `SaveGlobalData()` | 手动将当前所有全局数据写入文件 | 无 | 无 |

**提示**：若不调用 `SetSaveGlobalData(true)` 或定时调用 `SaveGlobalData()`，全局变量的修改只在内存中有效，程序重启后不会恢复。

---

## 2. 变量检查

在读写操作前判断变量状态，避免访问不存在的变量。

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `IsExistGlobal(block, var)` | 判断指定变量是否已被创建 | `block`: 区块名，`var`: 变量名 | `bool` |
| `IsValidGlobal(block, var)` | 判断变量是否存在且值为有效类型 | 同上 | `bool` |

**使用场景**：当不确定某个变量是否已被写入过时，先调用 `IsExistGlobal` 做防护。

---

## 3. 基础读写（通用）

适用于任意数据类型的通用读写方法，通过 `CMvVariant` 对象传递值。

### 3.1 按名称读写

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `ReadGlobal(block, var, output)` | 读取变量到 CMvVariant 对象 | `block`: 区块名, `var`: 变量名, `output`: 输出的 CMvVariant 对象 | `bool` — `true`=成功，`false`=失败 |
| `WriteGlobal(block, var, value)` | 写入任意类型值 | 同上 + `value`: 值 | `bool` |
| `WriteGlobalString(block, var, str)` | 写入字符串 | 同上 + `str`: 值 | `bool` |
| `WriteInitGlobal(block, var, value)` | 写入初始化默认值（仅启动时写入一次） | 同上 + `value`: 值 | `bool` |
| `WriteInitGlobalString(block, var, str)` | 写入初始化字符串 | 同上 + `str`: 值 | `bool` |

### 3.2 按索引读写

使用区块索引和变量索引代替名称，适合已知索引位置时的快速操作。

| 方法 | 说明 | 参数 | 返回值 |
|------|------|------|--------|
| `ReadGlobalByIndex(blockIdx, varIdx, output)` | 按索引读取到 CMvVariant | `blockIdx`: 区块索引, `varIdx`: 变量索引, `output`: CMvVariant | `bool` |
| `WriteGlobalByIndex(blockIdx, varIdx, value)` | 按索引写入 | 同左（无 output） | `bool` |
| `WriteGlobalStringByIndex(blockIdx, varIdx, str)` | 按索引写入字符串 | 同上 | `bool` |
| `WriteInitGlobalByIndex(blockIdx, varIdx, value)` | 按索引写入初始化值 | 同上 | `bool` |
| `WriteInitGlobalStringByIndex(blockIdx, varIdx, str)` | 按索引写入初始化字符串 | 同上 | `bool` |

> **注意**：`ReadGlobal` / `ReadGlobalByIndex` 的第三个参数是一个已创建的 `CMvVariant()` 对象，**不是错误码返回值**。读写成功与否由 `bool` 返回值决定。变量不存在时 `ReadGlobal` 返回 `false`，类型化读取函数返回 `nil`。

---

## 4. 读取（按名称）

以下函数是类型化版本，内部自动处理类型转换，变量不存在时返回 `nil`。**推荐日常使用**。

### 4.1 基础类型

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `ReadGlobalBool(block, var)` | 读取布尔值 | `bool` / `nil` |
| `ReadGlobalLong(block, var)` | 读取整数 | `number` / `nil` |
| `ReadGlobalReal(block, var)` | 读取浮点数 | `number` / `nil` |
| `ReadGlobalString(block, var)` | 读取字符串 | `string` / `nil` |

### 4.2 几何类型

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `ReadGlobalRealPoint(block, var)` | 读取点坐标 `(x, y)` | `table` / `nil` |
| `ReadGlobalPosture(block, var)` | 读取姿态 `(x, y, angle)` | `table` / `nil` |
| `ReadGlobalLine(block, var)` | 读取直线 | `table` / `nil` |
| `ReadGlobalRange(block, var)` | 读取范围 | `table` / `nil` |
| `ReadGlobalRect(block, var)` | 读取矩形 `(x, y, w, h)` | `table` / `nil` |
| `ReadGlobalRotatedRect(block, var)` | 读取旋转矩形 | `table` / `nil` |
| `ReadGlobalCircle(block, var)` | 读取圆 `(cx, cy, r)` | `table` / `nil` |

### 4.3 数组类型

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `ReadGlobalBoolArray(block, var)` | 读取布尔数组 | `table` / `nil` |
| `ReadGlobalLongArray(block, var)` | 读取整数数组 | `table` / `nil` |
| `ReadGlobalRealArray(block, var)` | 读取浮点数组 | `table` / `nil` |
| `ReadGlobalRealPointArray(block, var)` | 读取点坐标数组 | `table` / `nil` |
| `ReadGlobalPostureArray(block, var)` | 读取姿态数组 | `table` / `nil` |
| `ReadGlobalLineArray(block, var)` | 读取直线数组 | `table` / `nil` |
| `ReadGlobalRectArray(block, var)` | 读取矩形数组 | `table` / `nil` |
| `ReadGlobalRotatedRectArray(block, var)` | 读取旋转矩形数组 | `table` / `nil` |
| `ReadGlobalCircleArray(block, var)` | 读取圆数组 | `table` / `nil` |

---

## 5. 读取（按索引）

与第 4 节功能对应，使用 `blockIdx` 和 `varIdx` 整型索引代替名称。返回值规则同上（`nil` 表示变量不存在）。

### 5.1 基础类型（按索引）

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `ReadGlobalBoolByIndex(blockIdx, varIdx)` | 按索引读布尔 | `bool` / `nil` |
| `ReadGlobalLongByIndex(blockIdx, varIdx)` | 按索引读整数 | `number` / `nil` |
| `ReadGlobalRealByIndex(blockIdx, varIdx)` | 按索引读浮点 | `number` / `nil` |
| `ReadGlobalStringByIndex(blockIdx, varIdx)` | 按索引读字符串 | `string` / `nil` |

### 5.2 几何类型（按索引）

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `ReadGlobalRealPointByIndex(blockIdx, varIdx)` | 按索引读点坐标 | `table` / `nil` |
| `ReadGlobalPostureByIndex(blockIdx, varIdx)` | 按索引读姿态 | `table` / `nil` |
| `ReadGlobalLineByIndex(blockIdx, varIdx)` | 按索引读直线 | `table` / `nil` |
| `ReadGlobalRangeByIndex(blockIdx, varIdx)` | 按索引读范围 | `table` / `nil` |
| `ReadGlobalRectByIndex(blockIdx, varIdx)` | 按索引读矩形 | `table` / `nil` |
| `ReadGlobalRotatedRectByIndex(blockIdx, varIdx)` | 按索引读旋转矩形 | `table` / `nil` |
| `ReadGlobalCircleByIndex(blockIdx, varIdx)` | 按索引读圆 | `table` / `nil` |

### 5.3 数组类型（按索引）

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `ReadGlobalBoolArrayByIndex(blockIdx, varIdx)` | 按索引读布尔数组 | `table` / `nil` |
| `ReadGlobalLongArrayByIndex(blockIdx, varIdx)` | 按索引读整数数组 | `table` / `nil` |
| `ReadGlobalRealArrayByIndex(blockIdx, varIdx)` | 按索引读浮点数组 | `table` / `nil` |
| `ReadGlobalRealPointArrayByIndex(blockIdx, varIdx)` | 按索引读点坐标数组 | `table` / `nil` |
| `ReadGlobalPostureArrayByIndex(blockIdx, varIdx)` | 按索引读姿态数组 | `table` / `nil` |
| `ReadGlobalLineArrayByIndex(blockIdx, varIdx)` | 按索引读直线数组 | `table` / `nil` |
| `ReadGlobalRectArrayByIndex(blockIdx, varIdx)` | 按索引读矩形数组 | `table` / `nil` |
| `ReadGlobalRotatedRectArrayByIndex(blockIdx, varIdx)` | 按索引读旋转矩形数组 | `table` / `nil` |
| `ReadGlobalCircleArrayByIndex(blockIdx, varIdx)` | 按索引读圆数组 | `table` / `nil` |

---

## 6. 写入（按名称）

### 6.1 常规写入

| 方法 | 说明 |
|------|------|
| `WriteGlobalBool(block, var, val)` | 写入布尔值 |
| `WriteGlobalLong(block, var, val)` | 写入整数 |
| `WriteGlobalReal(block, var, val)` | 写入浮点数 |
| `WriteGlobalRealPoint(block, var, pt)` | 写入点坐标 |
| `WriteGlobalPosture(block, var, pose)` | 写入姿态 |
| `WriteGlobalLine(block, var, line)` | 写入直线 |
| `WriteGlobalRange(block, var, range)` | 写入范围 |
| `WriteGlobalRect(block, var, rect)` | 写入矩形 |
| `WriteGlobalRotatedRect(block, var, rrect)` | 写入旋转矩形 |
| `WriteGlobalCircle(block, var, circle)` | 写入圆 |
| `WriteGlobalBoolArray(block, var, arr)` | 写入布尔数组 |
| `WriteGlobalLongArray(block, var, arr)` | 写入整数数组 |
| `WriteGlobalRealArray(block, var, arr)` | 写入浮点数组 |
| `WriteGlobalRealPointArray(block, var, arr)` | 写入点坐标数组 |
| `WriteGlobalPostureArray(block, var, arr)` | 写入姿态数组 |
| `WriteGlobalLineArray(block, var, arr)` | 写入直线数组 |
| `WriteGlobalRectArray(block, var, arr)` | 写入矩形数组 |
| `WriteGlobalRotatedRectArray(block, var, arr)` | 写入旋转矩形数组 |
| `WriteGlobalCircleArray(block, var, arr)` | 写入圆数组 |

### 6.2 初始化写入

这些函数在**程序启动时**写入默认值，已有值时不会覆盖，适合做配置初始化。

| 方法 | 说明 |
|------|------|
| `WriteInitGlobalBool(block, var, val)` | 初始化布尔 |
| `WriteInitGlobalLong(block, var, val)` | 初始化整数 |
| `WriteInitGlobalReal(block, var, val)` | 初始化浮点 |
| `WriteInitGlobalRealPoint(block, var, pt)` | 初始化点坐标 |
| `WriteInitGlobalPosture(block, var, pose)` | 初始化姿态 |
| `WriteInitGlobalLine(block, var, line)` | 初始化直线 |
| `WriteInitGlobalRange(block, var, range)` | 初始化范围 |
| `WriteInitGlobalRect(block, var, rect)` | 初始化矩形 |
| `WriteInitGlobalRotatedRect(block, var, rrect)` | 初始化旋转矩形 |
| `WriteInitGlobalCircle(block, var, circle)` | 初始化圆 |
| `WriteInitGlobalBoolArray(block, var, arr)` | 初始化布尔数组 |
| `WriteInitGlobalLongArray(block, var, arr)` | 初始化整数数组 |
| `WriteInitGlobalRealArray(block, var, arr)` | 初始化浮点数组 |
| `WriteInitGlobalRealPointArray(block, var, arr)` | 初始化点坐标数组 |
| `WriteInitGlobalPostureArray(block, var, arr)` | 初始化姿态数组 |
| `WriteInitGlobalLineArray(block, var, arr)` | 初始化直线数组 |
| `WriteInitGlobalRectArray(block, var, arr)` | 初始化矩形数组 |
| `WriteInitGlobalRotatedRectArray(block, var, arr)` | 初始化旋转矩形数组 |

---

## 7. 写入（按索引）

### 7.1 常规写入（按索引）

| 方法 | 说明 |
|------|------|
| `WriteGlobalBoolByIndex(blockIdx, varIdx, val)` | 按索引写布尔 |
| `WriteGlobalLongByIndex(blockIdx, varIdx, val)` | 按索引写整数 |
| `WriteGlobalRealByIndex(blockIdx, varIdx, val)` | 按索引写浮点 |
| `WriteGlobalRealPointByIndex(blockIdx, varIdx, pt)` | 按索引写点坐标 |
| `WriteGlobalPostureByIndex(blockIdx, varIdx, pose)` | 按索引写姿态 |
| `WriteGlobalLineByIndex(blockIdx, varIdx, line)` | 按索引写直线 |
| `WriteGlobalRangeByIndex(blockIdx, varIdx, range)` | 按索引写范围 |
| `WriteGlobalRectByIndex(blockIdx, varIdx, rect)` | 按索引写矩形 |
| `WriteGlobalRotatedRectByIndex(blockIdx, varIdx, rrect)` | 按索引写旋转矩形 |
| `WriteGlobalCircleByIndex(blockIdx, varIdx, circle)` | 按索引写圆 |
| `WriteGlobalBoolArrayByIndex(blockIdx, varIdx, arr)` | 按索引写布尔数组 |
| `WriteGlobalLongArrayByIndex(blockIdx, varIdx, arr)` | 按索引写整数数组 |
| `WriteGlobalRealArrayByIndex(blockIdx, varIdx, arr)` | 按索引写浮点数组 |
| `WriteGlobalRealPointArrayByIndex(blockIdx, varIdx, arr)` | 按索引写点坐标数组 |
| `WriteGlobalPostureArrayByIndex(blockIdx, varIdx, arr)` | 按索引写姿态数组 |
| `WriteGlobalLineArrayByIndex(blockIdx, varIdx, arr)` | 按索引写直线数组 |
| `WriteGlobalRectArrayByIndex(blockIdx, varIdx, arr)` | 按索引写矩形数组 |
| `WriteGlobalRotatedRectArrayByIndex(blockIdx, varIdx, arr)` | 按索引写旋转矩形数组 |
| `WriteGlobalCircleArrayByIndex(blockIdx, varIdx, arr)` | 按索引写圆数组 |

### 7.2 初始化写入（按索引）

| 方法 | 说明 |
|------|------|
| `WriteInitGlobalBoolByIndex(blockIdx, varIdx, val)` | 按索引初始化布尔 |
| `WriteInitGlobalLongByIndex(blockIdx, varIdx, val)` | 按索引初始化整数 |
| `WriteInitGlobalRealByIndex(blockIdx, varIdx, val)` | 按索引初始化浮点 |
| `WriteInitGlobalRealPointByIndex(blockIdx, varIdx, pt)` | 按索引初始化点坐标 |
| `WriteInitGlobalPostureByIndex(blockIdx, varIdx, pose)` | 按索引初始化姿态 |
| `WriteInitGlobalLineByIndex(blockIdx, varIdx, line)` | 按索引初始化直线 |
| `WriteInitGlobalRangeByIndex(blockIdx, varIdx, range)` | 按索引初始化范围 |
| `WriteInitGlobalRectByIndex(blockIdx, varIdx, rect)` | 按索引初始化矩形 |
| `WriteInitGlobalRotatedRectByIndex(blockIdx, varIdx, rrect)` | 按索引初始化旋转矩形 |
| `WriteInitGlobalCircleByIndex(blockIdx, varIdx, circle)` | 按索引初始化圆 |
| `WriteInitGlobalBoolArrayByIndex(blockIdx, varIdx, arr)` | 按索引初始化布尔数组 |
| `WriteInitGlobalLongArrayByIndex(blockIdx, varIdx, arr)` | 按索引初始化整数数组 |
| `WriteInitGlobalRealArrayByIndex(blockIdx, varIdx, arr)` | 按索引初始化浮点数组 |
| `WriteInitGlobalRealPointArrayByIndex(blockIdx, varIdx, arr)` | 按索引初始化点坐标数组 |
| `WriteInitGlobalPostureArrayByIndex(blockIdx, varIdx, arr)` | 按索引初始化姿态数组 |
| `WriteInitGlobalLineArrayByIndex(blockIdx, varIdx, arr)` | 按索引初始化直线数组 |
| `WriteInitGlobalRectArrayByIndex(blockIdx, varIdx, arr)` | 按索引初始化矩形数组 |
| `WriteInitGlobalRotatedRectArrayByIndex(blockIdx, varIdx, arr)` | 按索引初始化旋转矩形数组 |

---

## 8. 使用示例

### 8.1 通用读写的标准模式

```lua
-- ReadGlobal 需要先创建 CMvVariant 对象
local var = CMvVariant()
local ok = LuaGlobalVar:ReadGlobal("块1", "变量1", var)
if ok then
    local value = var:get()
    LuaLog:Debug("读取成功: " .. value)
else
    LuaLog:Debug("变量不存在，使用默认值 -10")
end
```

### 8.2 类型化函数（日常推荐）

```lua
-- 读前先检查
if LuaGlobalVar:IsExistGlobal("Config", "Speed") then
    local speed = LuaGlobalVar:ReadGlobalReal("Config", "Speed")
    LuaLog:Debug(string.format("Speed: %s", speed))
end

-- 带默认值的简洁写法
local count = LuaGlobalVar:ReadGlobalLong("Config", "Count")
if count == nil then count = 0 end

-- 写入基础类型
LuaGlobalVar:WriteGlobalLong("Config", "Count", 100)
LuaGlobalVar:WriteGlobalReal("Config", "Speed", 50.5)
LuaGlobalVar:WriteGlobalBool("Config", "Enabled", true)
LuaGlobalVar:WriteGlobalString("Info", "DeviceName", "视觉系统V1.0")
```

### 8.3 几何类型读写

```lua
-- 点坐标
local pt = {x = 1500.5, y = 2000.3}
LuaGlobalVar:WriteGlobalRealPoint("Positions", "PickPos", pt)
local pickPos = LuaGlobalVar:ReadGlobalRealPoint("Positions", "PickPos")

-- 姿态 (x, y, angle)
local pose = {x = 100.0, y = 200.0, angle = 45.0}
LuaGlobalVar:WriteGlobalPosture("Vision", "ObjectPose", pose)

-- 圆 (cx, cy, r)
local circle = {cx = 500.0, cy = 600.0, r = 50.0}
LuaGlobalVar:WriteGlobalCircle("Vision", "DetectedCircle", circle)

-- 矩形 (x, y, width, height)
local rect = {x = 100, y = 200, width = 150, height = 100}
LuaGlobalVar:WriteGlobalRect("Vision", "BBox", rect)
```

### 8.4 数组读写

```lua
-- 写入数组
local speeds = {10.0, 20.0, 30.0}
LuaGlobalVar:WriteGlobalRealArray("Config", "SpeedCurve", speeds)

-- 读取数组
local readSpeeds = LuaGlobalVar:ReadGlobalRealArray("Config", "SpeedCurve")
if readSpeeds then
    for i, v in ipairs(readSpeeds) do
        LuaLog:Debug(string.format("Speed[%d]: %s", i, v))
    end
end
```

### 8.5 按索引操作

```lua
-- 写入
LuaGlobalVar:WriteGlobalLongByIndex(0, 0, 999)
LuaGlobalVar:WriteGlobalRealByIndex(0, 1, 123.456)

-- 读取（通用方式）
local var = CMvVariant()
if LuaGlobalVar:ReadGlobalByIndex(0, 1, var) then
    LuaLog:Debug("值: " .. var:get())
end

-- 读取（类型化）
local val = LuaGlobalVar:ReadGlobalLongByIndex(0, 0)
```

### 8.6 初始化变量与数据持久化

```lua
-- 程序启动时设默认值
LuaGlobalVar:WriteInitGlobalReal("SystemConfig", "DefaultExposure", 100.0)
LuaGlobalVar:WriteInitGlobalLong("SystemConfig", "MaxCount", 5000)

-- 开启自动保存
LuaGlobalVar:SetSaveGlobalData(true)

-- 手动保存
LuaGlobalVar:SaveGlobalData()
```

### 8.7 场景示例

```lua
-- 区块："系统参数"，变量："当前个数"
local count = LuaGlobalVar:ReadGlobalLong("系统参数", "当前个数")
if count == nil then count = -10 end
LuaLog:Debug("当前个数: " .. count)

-- 区块："生产信息"，变量："总数"
local total = LuaGlobalVar:ReadGlobalLong("生产信息", "总数")
LuaLog:Debug("生产总数: " .. (total or 0))

-- 区块："机械手参数"，变量："Z拍照高度"
local zHeight = LuaGlobalVar:ReadGlobalReal("机械手参数", "Z拍照高度")
LuaLog:Debug("Z拍照高度: " .. (zHeight or 0))
```

---

## 注意事项

### 数据持久化
- 全局变量默认存储在项目中，程序重启后仍可访问
- 使用 `SaveGlobalData()` 或设置 `SetSaveGlobalData(true)` 确保数据写入文件
- `WriteInitGlobal*` 用于启动时设默认值，已有同名变量时不覆盖

### 命名规范
- 区块名和变量名建议使用有意义的名称
- 避免特殊字符和空格
- 保持命名一致，便于后续维护

### 类型安全
- 确保读写的类型匹配，否则可能引发运行时错误
- 读前用 `IsExistGlobal()` 或 `IsValidGlobal()` 检查变量状态
- 类型化读取函数在变量不存在时返回 `nil`，可据此做默认值处理
- `ReadGlobal` / `ReadGlobalByIndex` 的第三个参数是 `CMvVariant` 输出容器，**不是错误码**，成败由 `bool` 返回值体现

### 性能建议
- 频繁读写掉电保持的全局变量会影响性能，避免频繁读写开启保持的变量
- 实时性要求高的场景优先使用不要勾选掉电保存。

---