窗口 XML 参考

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

Y++ 窗体布局保存在 XML 中。写针对具体控件的 YSS 前，请先读取对应 XML（或整理出控件名称与 typeId 清单）。

硬约束

YSS / 代码标识控件用属性 名称，不要用 标题。
typeId（如 button）对应 YSS 类型选择器；中文标签名可交叉验证。
路径固定为 窗口/{窗体名}/{窗体名}.xml；窗体名 = 根元素 名称 = 默认 {名称}.yss。
几何属性（左边/顶边/宽度/高度）是设计基准；运行时布局/停靠可能再算一遍。

文件位置

路径	说明
`窗口/{窗体名}/{窗体名}.xml`	主文件；设计器保存的布局
`窗口/主窗口/主窗口.xml`	新建工程时的默认窗体

窗体名与根元素属性 名称 一致，也与默认加载的 {窗体名}.yss 文件名一致。

文档结构

<?xml version="1.0" standalone="no"?>
<窗口 名称="主窗口" 宽度="1128" 高度="602"...>
  <标题>窗口标题栏文字</标题>
  <控件>
    <按钮 名称="按钮1" typeId="button" 左边="16" 顶边="96" 宽度="120" 高度="32" 标题="确定".../>
    <复选框 名称="复选框1" typeId="checkbox".../>
...
  </控件>
</窗口>

根元素 `<窗口>`

常用属性（写 YSS 时一般只需 名称）：

属性	含义
`名称`	窗体名，对应 YSS 文件名 `{名称}.yss`
`宽度` / `高度`	客户区尺寸
`背景色`	窗体背景（非 YSS，XML 属性）
`圆角`	窗外框圆角半径（DIP）；运行时用 D2D + alpha 裁剪（不用 GDI RGN）
`标题栏按钮样式`	`windows`（右侧线框）或 `macos`（左侧交通灯）
`背景材质`	`none` / `acrylic`（亚克力毛玻璃）/ `mica`（云母）/ `tabbed`
`标题栏高度`	自绘标题栏高度（DIP）

控件元素

<控件> 下每个自闭合子元素为一个控件。标签名为中文类型名，同时带 typeId 英文标识。

写 YSS 时必取字段：

XML 字段	用途
`名称`	YSS 按名选择：`button#按钮1` 或 `#按钮1`
`typeId`	YSS 类型选择器：`button`、`checkbox` 等
`标题`	显示文字（按钮/标签等）；不是 YSS 选择器
元素标签名	中文类型，与 `typeId` 交叉验证
`左边` / `顶边` / `宽度` / `高度`	设计基准几何（相对窗体客户区）
`停靠`	可选。`无`（默认）/`上`/`下`/`左`/`右`/`填充`。菜单/工具/状态栏仍用专用「位置」吸附

不要用 标题 当作 YSS 的 #名称；名称始终是 名称 属性。

布局（停靠 + 布局管理器）

窗体缩放时，运行时与设计器按约束重排：

菜单栏 / 工具栏 / 状态栏仍走各自的吸附布局。
设置了 停靠 的控件先占用客户区边缘；其余控件保持设计时的左边/顶边/宽高。
需要随窗拉伸时，请把控件放入 水平布局 / 垂直布局（可设弹簧、布局占比）。用法见窗口布局.md。
带 所属容器 的子控件相对容器客户区求解。

元素名 ↔ typeId ↔ YSS 选择器

XML 元素标签	typeId	YSS 选择器	说明
按钮	`button`	`button`
标签	`label`	`label`
文本框	`textbox`	`textbox`	含单行
文本框	`multilinetextbox`	`textbox`	多行；YSS 仍用 `textbox`
图片框	`picturebox`	`picturebox`
分组框	`groupbox`	`groupbox`
下拉框	`combobox`	`combobox`	元素名是「下拉框」
单选框	`radiobutton`	`radiobutton`
复选框	`checkbox`	`checkbox`
开关	`switch`	`switch`
进度条	`progressbar`	`progressbar`
滑块	`slider`	`slider`
列表框	`listbox`	`listbox`
选项卡	`tabwidget`	`tabwidget`
树形视图	`treeview`	`treeview`
菜单栏	`menubar`	`menubar`
分页	`pager`	`pager`	页码导航；专用属性见下

typeId 以 XML 为准；若与元素标签不一致，以 typeId 映射 YSS。

分页（`pager`）专用属性

XML 属性	说明
`当前页` / `总条数` / `每页条数` / `显示页码数`	数据与页码窗口
`功能样式`	扁平/描边/胶囊/极简/块状
`显示首页末页` / `显示跳转`	导航与跳转区
`GO位置`	`隐藏` / `输入框右` / `输入框左`
`跳转框宽度`	像素；`0`=自动
`省略页码`	真/假
`显示每页条数` / `每页条数选项`	下拉；选项换行分隔
`显示分隔线`	真/假
`信息文本位`	`paddingR` 低 3 位整数
`当前页发光` / `发光色` / `发光大小`	当前页按钮发光

分页设计器属性与代码 API 见 yss/pager.md。

从 XML 生成 YSS 选择器

规则：

{typeId}#{名称}     → 精确到单个控件，例如 checkbox#复选框1
{typeId}            → 该类型全部控件，例如 button
#{名称}             → 任意类型，按名称匹配，例如 #按钮1
{typeId}:{伪状态}   → 例如 checkbox:checked、button:hover

示例：XML 片段

<复选框 名称="复选框1" typeId="checkbox" 标题="同意协议".../>
<按钮 名称="按钮_确认" typeId="button" 标题="确定" 默认按钮="真".../>

对应 YSS：

checkbox#复选框1 {
    indicator-size: 18;
}

checkbox#复选框1:checked {
    checkmark-color: #00CC66;
}

button#按钮_确认 {
    border-radius: 6;
}

button:default {
    font-bold: true;
}

XML 中的样式 vs YSS

同一控件 XML 内已有大量视觉属性（背景色、边框颜色、悬停背景色 等）。YSS 会覆盖或补充这些属性，且更适合主题化、伪状态、子控件。中文属性名与英文 YSS 键的对应见 YSS.md「XML / 设计器中文属性 ↔ YSS 英文键」。

建议分工：

任务	优先改
全窗体主题、换肤、伪状态	`.yss` 文件
单个控件设计器微调	XML 属性（或 YSS 按名覆盖）
批量同类控件	YSS 类型选择器 `{typeId} {... }`
表格格子配色	代码 API（datagrid / tablewidget），不要硬套单元格 YSS

与 YSS 文档的配合

读本文件 → 得到 名称 + typeId
读 YSS.md → 语法、优先级、能力边界与通用属性
读 yss/{typeId}.md → 该组件可用属性（multiline 读 textbox.md）
抄片段 → 常见任务写法.md「给窗口换肤」

限制与注意

XML 不包含运行时动态创建的控件；仅设计器布局。
菜单项、列表项、树节点等内容在 XML 属性（如 菜单项列表、节点列表）中，不是独立 YSS 选择器；项级样式用组件文档中的 :item 等规则。
修改 XML 后需保存；修改 资源/{窗体名}.yss 后 F5 运行才会部署到 exe 旁。

完整片段示例

树视图等复杂控件的属性组合，可对照本仓库控件文档与设计器属性面板；XML 字段名以设计器写出为准。

该文件中可看到：按钮1、树形视图1、多行文本框1（typeId=textbox）、菜单栏1 等，可直接用于练习从 XML 生成 YSS 选择器。

硬约束