VAL表达式语法规范 V1.0
VAL表达式用于解析PLC寄存器地址。
VAL表达式必须指定PLC连接编号，绑定对应PLC设备的寄存器；可用于数据库字段值描述、MQTT收发内容描述等场景。
语法由ExprParser解析器实现，支持TYPE、DEC、STRLEN、MAP映射、ARRLEN数组。
1、总览语法格式
完整表达式：VAL(PLC=编号,ADDR=地址,TYPE=类型,DEC=小数,STRLEN=长度,ARRLEN=数组长度,MAP=映射规则)
- 外层：
VAL(...)，括号内部为参数列表，逗号分隔键值对 KEY=VALUE
2、ADDR寄存器地址说明
| PLC品牌 |
示例ADDR值 |
说明 |
| 三菱 |
D100、M0.0 |
D寄存器、M位地址 |
| 西门子 |
DB1.0、DB1.0.0 |
DB块字节、DB块位地址 |
| 欧姆龙 |
D1000 |
D区寄存器 |
3、支持TYPE数据类型
当前支持类型集合：BIT/UINT16/INT16/UINT32/INT32/F32/F64/STRING/DATETIME
| TYPE写法 |
说明 |
附加参数 |
| BIT |
布尔位 |
‑ |
| INT16 |
有符号16位整数 |
‑ |
| UINT16 |
无符号16位整数 |
‑ |
| INT32 |
有符号32位整数 |
‑ |
| UINT32 |
无符号32位整数 |
‑ |
| F32 |
单精度浮点 |
DEC=N 设置保留小数位数 |
| F64 |
双精度浮点 |
DEC=N 设置保留小数位数 |
| STRING |
字符串 |
STRLEN=50；简写 TYPE=STRING(80) |
| DATETIME |
时间日期 |
TYPE=DATETIME(yyyy-MM-dd HH:mm:ss) 自定义格式；不带括号使用默认格式 yyyy-MM-dd HH:mm:ss |
4、全部参数说明表
| 参数名 |
是否必填 |
示例 |
说明 |
| PLC |
✅必填 |
PLC=0 |
PLC设备索引编号 |
| ADDR |
✅必填 |
ADDR=D100 |
PLC寄存器地址 |
| TYPE |
✅必填 |
TYPE=F32 |
数据类型，参考上表 |
| DEC |
❌可选 |
DEC=2 |
F32/F64有效，保留小数位数，默认0 |
| STRLEN |
❌可选 |
STRLEN=100 |
STRING字符串长度；TYPE=STRING(N)简写也可设置，STRLEN优先级更高 |
| ARRLEN |
❌可选 |
ARRLEN=10 |
数组元素数量；0代表普通单变量；大于0开启数组模式；数组模式下MAP映射失效 |
| MAP |
❌可选 |
MAP=0:停止|1:运行\|报警|2:故障 |
数值映射；|分隔多条；\|转义竖线；数组ARRLEN>0时MAP直接被忽略清空 |
5、合法示例集合
// 示例1：PLC编号0，D100，F32浮点，保留2位小数
VAL(PLC=0,ADDR=D100,TYPE=F32,DEC=2)
// 示例2：PLC编号1，D1050，UINT32整数，带MAP映射
VAL(PLC=1,ADDR=D1050,TYPE=UINT32,MAP=0:待机|1:运行|2:故障)
// 示例3：PLC编号0，DB块字符串，STRING长度80
VAL(PLC=0,ADDR=DB1.100,TYPE=STRING,STRLEN=80)
// 示例4：STRING简写括号形式
VAL(PLC=0,ADDR=DB1.200,TYPE=STRING(120))
// 示例5：BIT位读取（M0.0）
VAL(PLC=0,ADDR=M0.0,TYPE=BIT)
// 示例6：数组，D700开始连续5个INT16
VAL(PLC=0,ADDR=D700,TYPE=INT16,ARRLEN=5)
// 示例7：DATETIME类型，使用默认时间格式
VAL(PLC=0,ADDR=D200,TYPE=DATETIME)
// 示例8：DATETIME自定义时间格式
VAL(PLC=0,ADDR=D210,TYPE=DATETIME(yyyy/MM/dd HH:mm))
6、关键语法规则
- 参数不区分大小写，内部全部KEY转大写；值部分原样保留。
- 逗号
,作为参数分隔符；等号=分割key‑value；参数前后空格自动Trim忽略。
TYPE=STRING(N)简写语法：括号内数字设置字符串最大长度；STRLEN参数优先级高于简写括号内数字。TYPE=DATETIME(format)简写语法：括号内自定义时间格式化字符串；不带括号则使用默认格式 yyyy-MM-dd HH:mm:ss。- ARRLEN>0进入数组模式：MAP映射规则直接清空无效，数组不支持MAP。
- MAP映射规则：竖线
|多条分隔；\|转义文本内部原生竖线；仅整数数值才执行映射；无匹配返回原始数值。
- 静态文本逃逸：外层整体用英文单引号包裹
'VAL(PLC=0,ADDR=D100,TYPE=F32)'，不做解析，原样输出文本。
7、PlcBindInfo 模型字段说明
对应C#代码内 PlcBindInfo 实体类。
| 字段 |
说明 |
| PlcIndex |
PLC设备索引【必填】 |
| Address |
PLC寄存器地址 |
| DataType |
数据类型 BIT/UINT16/INT16/UINT32/INT32/F32/F64/STRING/DATETIME |
| DecimalDigits |
小数位数，浮点类型生效，默认0 |
| StringLength |
字符串最大长度，STRING类型生效，默认50 |
| DateTimeFormat |
DATETIME类型格式化字符串，默认 yyyy-MM-dd HH:mm:ss |
| ArrayLen |
数组长度，0=普通单变量，>0数组模式 |
| MapRule |
映射原始字符串；ARRLEN>0强制置空 |
| CompiledMap |
预编译后的映射字典，模板加载阶段生成，渲染直接使用 |
| ExtraParams |
原始全部解析键值对，用于未来扩展参数 |
8、上层调用业务注意事项
- VAL表达式必须填写PLC索引，用来确定访问哪一个PLC连接。
- ARRLEN数组模式：返回数组对象；上层渲染、替换接口需要处理数组输出（例如逗号拼接）。
- MAP映射仅对整数生效；浮点、字符串、DATETIME直接返回原值，不执行映射。
9、错误场景说明
- 缺少PLC / ADDR / TYPE → Parse返回null，代表表达式非法，原文本保留不替换。
- ARRLEN传入负数 → 重置ArrayLen=0，退化为普通单变量。
- MAP语法错乱（缺少冒号）：该条映射项直接跳过，其它正常项继续生效。
- 数组模式ARRLEN>0，即使写MAP参数，内部直接清空MapRule，不做映射。
- TYPE填写不在支持列表内的类型，表达式判定非法返回null。