# Y++ 支持库命令语法说明
本文说明 Y++ 中支持库命令、支持库类、回调、返回值、可选参数和组合调用的写法。具体命令是否存在、参数类型及所属支持库，以 IDE 输入补全和光标处 F1 帮助为准。
## 1. 普通命令调用
基本格式：
```yc
命令名(参数1, 参数2)
```
无参数命令也要写括号：
```yc
文本 运行目录 = 系统_取运行目录()
整数 鼠标X = 取鼠标X()
整数 鼠标Y = 取鼠标Y()
```
有返回值时可直接赋给同类型变量，也可放进表达式：
```yc
整数 数量 = 数组长度(文件列表)
文本 配置路径 = 系统_取运行目录() + "\\config\\app.json"
如果 (文件是否存在(配置路径)) {
输出("配置文件存在")
}
```
不关心返回值时可以直接调用：
```yc
输出("程序开始")
移动鼠标(100, 200)
延时(300)
```
## 2. 参数写法
### 2.1 字面量、变量和表达式
```yc
输出("固定文本")
文本 用户名 = "张三"
输出(用户名)
整数 宽 = 800
整数 高 = 600
输出("面积=" + 到文本(宽 * 高))
```
字符串使用双引号。Windows 路径中的反斜杠写成 `\\`：
```yc
文本 文件 = "D:\\data\\users.json"
```
也可以使用 `/`：
```yc
文本 文件 = "D:/data/users.json"
```
### 2.2 可选参数
帮助中使用方括号标出的参数可以省略。例如帮助若显示：
```text
某命令(文本 内容, [整数 超时=3000], [逻辑 显示详情=假])
```
可按顺序调用：
```yc
某命令("测试")
某命令("测试", 5000)
某命令("测试", 5000, 真)
```
不能跳过中间参数只填写最后一个参数，除非该命令帮助明确支持其它写法。
### 2.3 类型转换
参数类型不一致时先显式转换：
```yc
文本 数量文字 = "128"
整数 数量 = 到整数(数量文字)
输出("数量=" + 到文本(数量))
```
不要依赖文本、整数、逻辑之间的隐式转换。
## 3. 支持库类和对象方法
支持库中带“类”的功能通常先声明对象，再用点号调用方法：
```yc
JSON类 文档
HTTP类 请求器
SQLite类 数据库
```
方法格式：
```yc
对象.方法(参数)
```
属性格式：
```yc
对象.属性
对象.属性 = 值
```
示例一：JSON 类组合调用：
```yc
函数 生成用户JSON() 文本 {
JSON类 根
根.置文本("姓名", "张三")
根.置整数("年龄", 28)
根.置逻辑("启用", 真)
返回(根.到文本())
}
```
示例二：对象之间传递结果：
```yc
函数 保存配置() {
JSON类 配置
配置.置文本("服务器", "127.0.0.1")
配置.置整数("端口", 8080)
文本 内容 = 配置.到文本()
写文件(系统_取运行目录() + "\\config.json", 内容)
}
```
示例三：读取对象属性和事件属性：
```yc
MQTT类 客户端
函数 收到消息() {
输出("主题：" + 客户端.事件主题)
输出("正文：" + 客户端.事件文本)
}
函数 主窗口.创建完毕() {
客户端.消息到达(&收到消息)
客户端.连接("127.0.0.1", 1883, "YPPClient")
客户端.启动事件循环(20)
}
```
## 4. 回调函数和函数地址
支持库要求回调时，一般传 `&函数名`：
```yc
函数 下载完成() {
输出("下载完成")
}
函数 开始下载() {
下载器.完成(&下载完成)
}
```
回调形参必须与命令帮助一致。帮助要求零参数回调时不要自行增加参数；事件数据通常从对象的 `事件文本`、`事件字节集`、`错误信息` 等属性读取。
```yc
串口类 串口
函数 串口收到数据() {
字节集 数据 = 串口.事件字节集
输出("收到字节数=" + 到文本(字节集长度(数据)))
}
```
一个回调可登记到对象，多个对象应分别读取各自的事件属性：
```yc
MQTT类 生产连接
MQTT类 测试连接
函数 生产消息() {
输出("生产：" + 生产连接.事件文本)
}
函数 测试消息() {
输出("测试：" + 测试连接.事件文本)
}
```
## 5. 数组作为参数和返回值
```yc
数组 文件列表[] = 取文件列表("D:/data", "*.*", 假, 真)
整数 i = 0
循环 (数组长度(文件列表), i) {
输出(文件列表[i])
}
```
向动态数组添加数据：
```yc
文本 名称[] = []
数组添加(名称, "张三")
数组添加(名称, "李四")
输出(名称[0])
```
二维、三维数组或自定义类型数组是否适用于某个命令，要按该命令的参数类型使用，不能看到“数组”就传任意元素类型。
## 6. 命令嵌套与拆分
简单返回值可以嵌套：
```yc
输出(到文本(数组长度(文件列表)))
```
涉及网络、文件、数据库或多步状态时建议拆开，便于检查失败位置：
```yc
文本 路径 = 系统_取运行目录() + "\\data.json"
逻辑 存在 = 文件是否存在(路径)
如果 (!存在) {
输出("文件不存在：" + 路径)
返回()
}
文本 内容 = 读文件(路径)
如果 (内容 == "") {
输出("文件为空或读取失败")
返回()
}
输出(内容)
```
## 7. 条件、循环和错误处理中的命令
```yc
函数 查找名称(文本 名称列表[], 文本 目标) 整数 {
整数 i = 0
循环 (数组长度(名称列表), i) {
如果 (名称列表[i] == 目标) {
返回(i)
}
}
返回(-1)
}
```
```yc
函数 安全读取(文本 路径) 文本 {
尝试 {
返回(读文件(路径))
} 捕获 {
输出("读取失败：" + 路径)
返回("")
}
}
```
## 8. 多线程中调用支持库
耗时的文件、网络和计算可放到线程或线程池；窗口组件属性不要在后台线程直接修改，应回到界面事件或使用支持库提供的界面调度方式。
```yc
函数 后台任务() {
文本 内容 = 读文件("D:/data/big.json")
输出("后台读取完成，字符数=" + 到文本(文本长度(内容)))
}
函数 开始按钮.单击(整数 X, 整数 Y) {
整数 线程句柄 = 启动线程(&后台任务)
如果 (线程句柄 == 0) {
输出("线程启动失败")
}
}
```
## 9. 常量与支持库命令
支持库内置常量通常以 `#` 开头：
```yc
如果 (按键 == #回车键) {
输出("按下回车")
}
模拟鼠标点击(#鼠标左键, 100, 200)
```
常量不是函数，不要在后面加括号。
## 10. 错误写法与正确写法
### 错误：无参数命令漏括号
```yc
// 错误
文本 路径 = 系统_取运行目录
// 正确
文本 路径 = 系统_取运行目录()
```
### 错误：把普通命令当对象方法
```yc
// 错误：输出不是“系统”对象的方法
系统.输出("你好")
// 正确
输出("你好")
```
### 错误：把类方法当普通命令
```yc
JSON类 数据
// 错误
置文本("姓名", "张三")
// 正确
数据.置文本("姓名", "张三")
```
### 错误：回调漏写 `&`
```yc
// 错误：这会立即调用函数，或产生参数类型错误
客户端.消息到达(收到消息())
// 正确：传函数地址
客户端.消息到达(&收到消息)
```
### 错误：自行改变回调参数
```yc
// 帮助要求零参数时，以下写法错误
函数 收到消息(文本 主题, 文本 内容) { }
// 正确
函数 收到消息() {
输出(客户端.事件主题)
输出(客户端.事件文本)
}
```
### 错误：返回类型不匹配
```yc
// 错误
整数 数量 = "10"
// 正确
整数 数量 = 到整数("10")
```
### 错误：将支持库常量写成函数
```yc
// 错误
整数 键 = #回车键()
// 正确
整数 键 = #回车键
```
### 错误：使用不存在的重载
```yc
// 错误：根据其它语言经验随意添加参数
移动鼠标(100, 200, 500, "平滑")
// 正确：只按 IDE 参数提示调用
移动鼠标(100, 200)
```
## 11. 排查顺序
1. 输入命令名后查看补全，确认支持库已经加载。
2. 将光标放在命令或方法上按 F1，确认参数数量、类型、返回值和示例。
3. 类方法必须由正确类型的对象通过点号调用。
4. 回调必须核对函数参数，并使用 `&函数名`。
5. 同名命令冲突时删除重复 `.ypi` 声明，或给 API 使用不同中文别名。
评论