Y++ 语言基础

Y++ / YStudio 开发文档 · 一点滴

本文是 Y++ 语言的规范速览。以本文与各支持库/控件文档的签名表为准，禁止虚构 API。 想直接对照着写出可运行窗口，见最小窗口程序。

产品品牌：Y++ / y++
IDE 名称：YStudio
示例命名前缀：Ypp…（如管道名 YppDesk）
不要使用第三方旧产品名或仓库目录名当作品牌

更细主题见文末链接；官网速览页：https://www.yddphp.cn/lang.html

0. 硬约束（写代码时必守）

类型名写完整中文类名：HTTP类、JSON类、绘制类、管道类……不要写成 HttpClient / JSON / Painter。
方法与命令调用必须带括号：http.提交(...)、继续()、跳出()、p.绑窗口()。属性赋值不用括号：按钮1.标题 = "确定"。
控件名来自窗口 XML 的「名称」字段，代码里直接写标识符：按钮1.单击，不要臆造控件名。
事件函数签名与设计器 / 控件文档一致：函数主窗口.创建完毕 ()、函数按钮1.单击 (整数 X, 整数 Y)。
逻辑常量用 真 / 假，不要写 true / false。
关键字用中文：函数 如果 否则 当 循环 返回 选择 分支 尝试 捕获。
禁止套用其它语言习惯：无 /* */ 块注释；无 var/let/async/await；循环不用 for/while 关键字。
数组声明：整数 arr[] / 文本 list[]（[] 在变量名后）。面板「整数数组」「文本数组」指元素类型，不是两个变量；禁止 整数[] arr。
不要发明不存在的方法；不确定时查对应 docs/*.md 签名表（如 http.md、painter.md、yss/button.md）。
阻塞 IO（HTTP、管道等待、大文件）若放工作线程，回写 UI 必须回到界面线程（见 thread-support.md）。
命名管道短名用 ASCII（如 YppDesk）。
多窗口：载入(窗口名) / 关闭(窗口名)，不要加引号。
循环参数详解见 basic-flow.md（循环 三种写法、当、遍历）。

易错对照

错误写法	正确写法
`HTTP http` / `HttpClient`	`HTTP类 http`
`http.提交`（无括号）	`http.提交("GET", url)`
`true` / `false`	`真` / `假`
`if (x) { }`	`如果 (x) { }`
`for (i=0; i<10; i++)`	`循环 (10, i) { }`
`计次循环` / `判断循环`	`循环` / `当`
`continue` / `break`	`继续()` / `跳出()`
`整数[] arr` / 把「整数数组」拆成两个变量	`整数 arr[] = []`
`文本[] list`	`文本 list[] = []`
`循环 (整数 i = 0, 10)`	先 `整数 i = 0`，再 `循环 (10, i)`
`按钮1.标题("确定")`	`按钮1.标题 = "确定"`
`p.绑组件("按钮1")`	`p.绑组件(按钮1)`（组件名无引号）
`返回 x`	`返回 (x)`
`/* 注释 */`	`// 注释`
`载入("窗口1")`	`载入(窗口1)`（窗口名无引号）
`关闭("窗口1")`	`关闭(窗口1)`

1. 源文件与工程

扩展名	用途
`.yc`	窗体/主逻辑（中文源）
`.yt`	自定义类型（结构体式）
`.ypp`	自定义类
`.yp`	DLL / 系统 API 声明
`.yss`	样式表（类似 CSS）
`.xml`	窗口与控件布局（设计器生成）

工程根目录有 .ysproj。窗口默认路径：窗口/主窗口/主窗口.xml。控件用 XML 里的名称在代码中写属性，例如 按钮1.标题 = "确定"。

一个典型窗口程序至少包含：

窗口/主窗口/主窗口.xml（界面）
源代码/main.yc（逻辑与事件）
工程文件 *.ysproj

2. 注释

// 行注释（推荐）
' 也可用单引号行注释（兼容）

没有块注释 /* */。

3. 类型一览

3.1 基本类型

类型关键字	含义	示例
`整数`	32 位有符号整数	`整数 n = 0`
`长整数`	64 位整数	`长整数 x = 0`
`短整数`	16 位整数	`短整数 s = 0`
`字节`	0～255	`字节 b = 0`
`小数` / `单浮点`	单精度浮点	`小数 r = 1.5`
`双浮点`	双精度浮点	`双浮点 d = 1.0`
`文本`	字符串（源里写 UTF-8/中文即可）	`文本 s = "Y++"`
`逻辑`	布尔	`逻辑 ok = 真`
`字节集`	二进制缓冲	`字节集 buf`
`通用`	可装多种值的装箱类型	`通用 v`

逻辑常量：真 / 假（不要写 true / false）。

3.2 支持库对象类型

声明即构造（值类型/句柄类），常见如：HTTP类、JSON类、管道类、定时器类、进程类、TCP类、UDP类、SQLite类、Excel类、Word类、打印类、绘制类、画笔类、画刷类、字体类 等。

抓外部命令标准输出、简易终端壳：用 进程类（可启动 cmd / PowerShell / 任意 exe），不要与扁平「进程操作」混淆。

管道类 p
HTTP类 http
Word类 doc
打印类 打
绘制类 g

完整清单与每参签名见文档中心「支持库」栏（如 painter.md、http.md、word.md、excel.md、print.md）。

设计器里把多个控件拼成可复用块（.yuc，可跨工程拷贝）：见 用户组件（需授权开通 component.usercompose）。

3.3 自定义类型 / 类

见 usertype.md、userclass.md。

4. 变量定义

格式： 类型名字 [= 初值]

变量名可用中文或英文。
局部变量写在函数体内；需要跨函数时用模块级变量（写在函数外）。
赋值用 =；比较用 == / !=。

整数 数量 = 0
文本 名字 = "值班台"
逻辑 已连接 = 假

数量 = 数量 + 1
名字 = 名字 + "-客户端"
已连接 = 真

4.1 数组

「整数数组」「文本数组」不是两个变量。 IDE 支持库面板里的条目名表示元素类型为整数/文本的数组声明模板：写成 元素类型变量名[]，只声明一个变量。

说法	含义	正确写法
整数数组	整数类型的数组	`整数 arr[] = []` → 变量名 `arr`，元素为整数
文本数组	文本类型的数组	`文本 list[] = []` → 变量名 `list`，元素为文本
小数/逻辑数组	同理	`小数 xs[]` · `逻辑 flags[]`
二维 / 三维	`[]` 的层数就是维数	`整数矩阵[][]` · `文本表[][]` · `整数体[][][]`

整数 arr[] = []              // 空的整数数组，变量名 arr
整数 列表[] = [1, 2, 3]      // 带初值
整数 缓冲[100]               // 预分配 100 个元素（初值多为 0）
文本 list[] = ["甲", "乙"]   // 文本数组，变量名 list
文本 names[] = 枚举管道()    // 命令返回文本数组时可直接赋给文本 名[]
整数 矩阵[][] = 数组_创建二维(2, 3, 0)
文本 子键[] = 取注册子键列表("当前用户", "Software")

声明必须写出元素类型。返回文本数组就写 文本名[]，返回整数数组就写 整数名[]，维数与 [] 的层数一致。不要只写「数组」当类型。

下标从 0 开始：列表[0] 是第一个元素。
[] 写在变量名后面；禁止 整数[] arr、文本[] list（C/Java 习惯）。
不要写成 整数数组（那是名为「数组」的单个整数变量），也不要把面板名拆成「整数」+「数组」两个声明。
取长度用数组操作命令（见 basic-array.md，如 数组长度）。
方法签名里的返回类型写 整数数组 / 文本数组 时，接收方应声明为 整数名[] / 文本名[]。
函数形参 / 返回值也必须带元素类型（见 §5.1）；不要只写「数组」（默认按整数数组理解）。

4.2 文本字面量

双引号："hello"、"你好"
拼接："a" + "b"，或数字先 到文本(n) 再拼
路径里的反斜杠在字符串中写 \\，例如 "data\\a.bin"（相对工程根）

4.3 属性 vs 方法

种类	写法	示例
属性读写	`对象.属性` / `对象.属性 = 值`	`标签1.标题 = "就绪"`
方法/命令	`对象.方法(参数…)`	`按钮1.刷新()`
全局命令	`命令(参数…)`	`输出("ok")`、`信息框(s)`

5. 程序结构与函数

5.1 函数

函数 名字 (类型 参数1, 类型 参数2) {
    返回 (表达式)   // 有返回值时
}

// 无参 / 无返回
函数 初始化 () {
    输出("ok")
}

返回 ()：无值返回（结束函数）
返回 (x)：返回表达式
空参数列表也要写括号：函数初始化 () {... }

扩展类作形参 / 返回值

扩展类（HTTP类、JSON类、TCP类、字体类 等）可以作函数参数和返回值，写法与变量声明相同：

函数 取正文(HTTP类 client, 文本 url) 文本 {
    返回(client.提交("GET", url))
}

HTTP类 http
输出(取正文(http, "https://example.com/"))

扩展类是句柄：按值传递仍指向同一会话对象。若要在函数里换绑调用方变量，写 引用 HTTP类 client。

数组作形参 / 返回值

数组参数默认按引用传递（调用方不必写 &）。元素类型必须写清，与变量声明一致：

写法	含义
`函数 f(整数 a[])` / `函数 f(整数数组 a)`	整数数组形参
`函数 f(文本 list[])`	文本数组形参
`函数 f() 文本[]` / `函数 f() 文本数组`	返回文本数组
`函数 f() 整数[]`	返回整数数组
仅写 `数组` / `数组 a`	按整数数组理解（易与文本数组混淆，不推荐）

函数 合并(文本 a[], 文本 b[]) 文本[] {
    文本 out[] = a
    整数 i = 0
    循环 (i < 数组长度(b)) {
        数组添加(out, b[i])
        i = i + 1
    }
    返回 (out)
}

文本 x[] = ["甲"]
文本 y[] = ["乙"]
文本 z[] = 合并(x, y)    // 左侧必须是 文本 名[]

类型必须左右一致：不能把「整数数组」赋给「文本数组」（会报「不能将…赋给…」）。接收支持库返回值时同理，见 basic-array.md。

5.2 窗体 / 控件事件

约定：窗体名.事件() / 控件名.事件()。函数名必须与设计器生成的事件名一致。

函数 主窗口.创建完毕 () {
    标签1.标题 = "就绪"
}

函数 按钮1.单击 (整数 X, 整数 Y) {
    信息框(文本框1.文本)
}

常见窗体事件：创建完毕、即将关闭、尺寸改变。常见控件事件：单击、内容改变 等（以设计器「事件」菜单与各控件文档为准；被单击 在部分场景可作 单击 的别名）。

事件回调若由支持库注册（如 TCP 数据到达），形参见该库文档，不要改形参顺序或类型。

6. 分支

如果 (条件) {
...
} 否则 {
...
}

// 多分支
如果 (n == 1) {
} 否则 如果 (n == 2) {
} 否则 {
}

选择语句：

选择 (n) {
    分支 1 {
    }
    分支 2, 3 {
    }
    默认 {
    }
}

条件必须写在括号里：如果 (x > 0) {... }。

7. 循环

部分旧环境把计数循环叫「计次循环」、条件循环叫「判断循环」。Y++ 没有这些关键字：计次 → 循环；条件 → 当；跳过本轮 → 继续()。

完整面板说明见 basic-flow.md（与 IDE「基础支持库 → 流程控制」一致）。

7.1 `循环`（计数 / 区间）

计数变量须先在外部声明；括号里只写变量名，不能写 整数 i。

写法	签名	行为
一	`循环(次数, 计数变量){ }`	计数从 0 到 `次数-1`，共 `次数` 次
二	`循环(起始, 终止, 计数变量){ }`	含端点，步长 1：`循环(1, 10, i)` → 1…10
三	`循环(起始, 终止, 步长, 计数变量){ }`	自定义步长：`循环(1, 10, 2, k)` → 1,3,5,7,9

整数 i = 0
循环 (10, i) {
    输出(到文本(i))   // 0…9
}

整数 n = 0
循环 (1, 5, n) {
    输出(n)           // 1…5
}

整数 k = 0
循环 (1, 10, 2, k) {
    输出(k)           // 1,3,5,7,9
}

7.2 `当`（条件循环，≈ while）

当(条件){ }：条件为真则重复；体内须改动与条件相关的变量，否则会死循环。

整数 n = 0
当 (n < 10) {
    n = n + 1
    输出(n)
}

7.3 `遍历`（数组 / 字典）

`遍历`

签名：无遍历(元素变量, 数组变量){ 语句 }
说明：亦可 遍历(项, 字典[, 保序|正序|倒序]) 或 遍历(键, 值, 字典[, 保序|正序|倒序])。元素变量、数组/字典变量均须外部已声明；括号里只写名字。

写法	签名	说明
数组	`遍历(元素变量, 数组变量){ }`	依次取出每个元素
字典值	`遍历(项, 字典[, 保序\\|正序\\|倒序]){ }`	只取各值；默认保序
字典键值	`遍历(键, 值, 字典[, 保序\\|正序\\|倒序]){ }`	同时取键与值；默认保序

字典排序：保序（写入顺序，默认）、正序（键升序）、倒序（键降序）。详见 basic-flow.md。

整数 列表[] = [1, 2, 3]
整数 项 = 0
遍历 (项, 列表) {
    输出(项)
}

文本 list[] = ["a", "b"]
文本 行 = ""
遍历 (行, list) {
    输出(行)
}

通用 配置 = 字典_批量置(["端口", "8080", "名称", "服务"])
通用 值 = 0
遍历 (值, 配置) { }           // 默认保序
遍历 (值, 配置, 正序) { }     // 按键升序

7.4 循环控制（必须带括号）

写法	含义
`继续()`	跳过本轮剩余语句，进入下一轮（不要写「到循环尾」）
`跳出()`	退出当前这一层 `循环`/`当`/`遍历`（嵌套时只退最内层）

8. 运算符与常用命令

类别	写法
算术	`+ - * / %`
比较	`== != > >= < <=`
逻辑	`且` `或` `非`（部分场景兼容 `&&` `\\|\\|`，以检查器为准）
文本拼接	`"a" + "b"`、`到文本(n)`

常用内置命令（签名摘要）

`输出`

签名：无输出(文本内容)
说明：调试输出

`信息框`

签名：（以检查器为准）
说明：弹窗提示

`到文本` / `到整数`

签名：文本到文本(…) / 整数到整数(…)
说明：类型转换

`取文本长度`

签名：整数取文本长度(文本内容)

`数组长度`

签名：整数数组长度(数组)
说明：返回元素个数；下标从 0。

`继续` / `跳出`

签名：无继续() / 无跳出()
说明：必须带括号

`返回`

签名：返回 () / 返回 (表达式)

完整文件/编码/线程等见各支持库文档。子程序指针回调：&函数名，形参必须与库文档一致。

9. 控件属性与多窗口

属性用点号读写，名称与窗口 XML 中 名称 一致：

按钮1.启用 = 假
标签状态.标题 = "已连接"
文本框1.内容 = "hello"

多窗口命令签名

`载入`

签名：逻辑载入(组件名窗口名, [逻辑模态=假])
说明：窗口名无引号

`关闭`

签名：无关闭(组件名窗口名)
说明：关已载入次级窗；关主窗走关闭流程

`本窗关闭`

签名：无主窗口.关闭([逻辑执行=真])
说明：关闭(假) 可取消「即将关闭」

载入(工作台)
工作台.标签1.标题 = "已打开"
关闭(登录窗)

错误	正确
`载入("工作台")`	`载入(工作台)`
`关闭("登录窗")`	`关闭(登录窗)`

详见多窗口设计.md、window-xml.md、工程结构.md。

即时绘制叠层见 painter.md；画布场景编辑见 canvas.md。

10. 支持库调用模式

HTTP类 http
文本 正文 = http.提交("GET", "https://example.com")
如果 (正文 == "") {
    信息框(http.取错误())
    返回 ()
}

JSON类 j
如果 (j.解析(正文) == 假) {
    信息框(j.取错误())
    返回 ()
}

每个 *类 变量一般是独立会话（头、超时、上次响应互不影响）。
失败语义以各库为准：HTTP 失败常返回空文本 + 取错误()；JSON/SQLite 等多返回 逻辑假 + 取错误()。
管道：pipe.md
线程：thread-support.md — 勿在界面线程里长时间阻塞

11. 异常

尝试 {
    抛出("出错了")
} 捕获 (文本 错) {
    输出(错)
}

能进入 捕获 的是 抛出(文本)，以及运行库抛出的异常。
到整数 失败返回 0（不抛异常）。整数除零 / 取余除数为零会抛异常并进入 捕获。

12. DLL / 指针 / 资源 / 样式

API 声明：dllapi.md、dll-pointers.md
第三方 DLL：third-party-dll.md
嵌入资源：:/ 路径，见 resource-embed.md
样式：YSS，见 YSS.md

13. 编写约束清单（汇总）

品牌与示例名只用 Y++ / y++ / YStudio / Ypp…。
关键字用中文：函数 如果 否则 当 循环 返回 真 假。
循环里用 继续() / 跳出()，不要伪造「到循环尾」「跳出循环」。
支持库类型名与文档一致（管道类 不是 Pipe；HTTP类 不是 HttpClient；绘制类 不是 Painter）。
控件事件签名与设计器生成一致；改属性先确认窗口 XML 里的 名称。
阻塞 IO 放在线程池任务里时，回写 UI 必须回到界面线程。
命名管道短名用 ASCII（如 YppDesk）。
不要发明不存在的关键字或方法；以各篇签名表（参数类型、默认值、取值/常量、返回值）为准。