写针对具体控件的 YSS 前，请先读窗体 XML 获取控件 名称 与 typeId，见 README.md 与 window-xml.md。
YSS 用于描述窗体控件的视觉样式，属性名全部为英文，在代码中通过 加载YSS() / 应用YSS() 应用，或在程序启动时自动加载。
分组件文档（一组件一篇）： 按钮 · 标签 · 文本框 · 图片框 · 分组框 · 组合框 · 单选框 · 复选框 · 开关 · 进度条 · 滑块 · 列表框 · 选项卡 · 树形视图 · 菜单栏 · 工具栏 · 浏览器 · 日期选择器 · 完整示例见 样式演示_单选复选开关进度条.yss
快速开始
- 在工程 「资源」 目录放置
{窗体名}.yss（推荐），例如资源/主窗口.yss - 图片放在 「资源」 子目录，例如
资源/img/check-square.png - F5 编译运行：资源会复制到 exe 同目录（
img/、主窗口.yss等） - 程序启动后自动加载 exe 旁的
{窗体名}.yss，一般无需手写加载YSS()
/* 资源/主窗口.yss */
button {
border-radius: 4;
}
checkbox#复选框1 {
indicator-size: 18;
indicator-background-color: #2D2D30;
indicator-border-color: #707070;
}
checkbox#复选框1:checked {
checkmark-color: #00CC66;
indicator-checked-image: :/img/check-square.png;
}
// 可选：子目录 YSS 或运行时换肤
函数 主窗口.创建 {
加载YSS(":/yss/主题.yss")
}
文件位置
| 位置 | 说明 |
|---|---|
资源/{窗体名}.yss |
推荐；F5 整棵复制到 exe 旁 |
窗口/{窗体名}/{窗体名}.yss |
与窗口 XML 同目录；构建时也会参与生成 |
exe 旁 {窗体名}.yss |
运行时默认自动加载的文件 |
exe 旁 yss/xxx.yss |
子目录样式，需 加载YSS("yss/xxx.yss") |
语法
选择器 {
属性名: 值;
}
- 颜色：
#RRGGBB或#AARRGGBB - 布尔：
true/false - 注释：
// 行注释或/* 块注释 */ - 数值：整数（单位一般为 DIP 像素）
选择器
| 写法 | 含义 |
|---|---|
button |
该类型全部控件 |
button#按钮_确认 |
指定名称的按钮 |
#按钮_确认 |
指定名称（任意类型） |
button:hover |
悬停态规则块 |
checkbox:checked |
复选框选中态 |
checkbox:indeterminate |
复选框不确定态（三态） |
伪状态： :hover :pressed :focus :disabled :checked :indeterminate :on :off :default（selected 等同 pressed）
子控件： :item :tab :pane :chunk :handle :groove :drop-down :indicator（各组件支持的子控件见对应分文档）
:hover / :pressed 块中的 background-color、color 会映射为悬停/按下专用色，运行时随交互生效。
选择器索引（设计器组件 ↔ YSS 选择器）
| 设计器组件 | YSS 选择器 | 文档 |
|---|---|---|
| 按钮 | button |
button.md |
| 标签 | label |
label.md |
| 文本框 / 多行文本框 | textbox |
textbox.md |
| 图片框 | picturebox |
picturebox.md |
| 分组框 | groupbox |
groupbox.md |
| 组合框 | combobox |
combobox.md |
| 单选框 | radiobutton |
radiobutton.md |
| 复选框 | checkbox |
checkbox.md |
| 开关 | switch |
switch.md |
| 进度条 | progressbar |
progressbar.md |
| 滑块 | slider |
slider.md |
| 列表框 | listbox |
listbox.md |
| 选项卡 | tabwidget |
tabwidget.md |
| 树形视图 | treeview |
treeview.md |
| 菜单栏 | menubar |
menubar.md |
| 工具栏 | toolbar |
toolbar.md |
| 浏览器 | webbrowser |
webbrowser.md |
| 日期选择器 | datepicker |
datepicker.md |
按名称匹配时写 选择器#控件名称 或 #控件名称（名称与设计器/XML 中一致，如 按钮_确认）。
资源路径 :/
:/ 表示 exe 所在目录下的相对路径，与 YSS 文件本身在 exe 根目录还是子目录无关。
| 写法 | 解析为（exe 在 D:\app\） |
|---|---|
:/img/xx.png |
D:\app\img\xx.png |
:/yss/demo.yss |
D:\app\yss\demo.yss |
yss/demo.yss（相对路径） |
D:\app\yss\demo.yss |
主窗口.yss |
D:\app\主窗口.yss |
示例： YSS 在 exe/yss/demo.yss，图片在 exe/img/xx.png，YSS 内仍写：
indicator-checked-image: :/img/xx.png;
部署（F5 / 发布）：
- 工程「资源」目录整棵复制到 exe 旁（
资源/img/a.png→exe旁/img/a.png） - 发布目录
发布/{架构}/{Debug|Release}/同样包含img/、*.yss、form_yss_ext.bin等 - 若
exe/img/...不存在，会再尝试兼容旧路径exe/resources/img/...
设计器预览： :/ 解析为工程「资源」目录；打开窗口设计视图时会自动尝试加载 资源/{窗体名}.yss。
窗体（form）选择器
form / window / 主窗口 可写窗体外壳样式（运行时生效）：
form {
background-color: #1C1C1E;
border-radius: 16;
title-bar-height: 36;
caption-button-style: macos; /* 或 windows */
show-title-bar: true;
always-on-top: false;
backdrop: acrylic; /* none / acrylic / mica / tabbed */
}
| 属性 | 说明 |
|---|---|
background-color / background |
客户区背景 |
border-radius / corner-radius |
窗外框圆角（会裁剪 HWND） |
title-bar-height |
自绘标题栏高度 |
show-title-bar / title-bar |
是否显示自绘标题栏 |
caption-button-style / title-button-style |
windows 右侧线框；macos 左侧交通灯 |
backdrop / backdrop-style / background-material |
none / acrylic(毛玻璃) / mica(云母) / tabbed |
acrylic |
true 等价于 backdrop: acrylic |
always-on-top / topmost |
窗口置顶 |
title / window-title |
窗口标题 |
visible |
显示/隐藏 |
left / top / width / height |
窗口位置与外框尺寸 |
设计器里更多 Chrome（边框色、最大化按钮等）仍以窗口 XML 为准；上表为运行时 YSS 可直接改写的窗体项。
通用属性速查
以下属性适用于 button / label / textbox（picturebox 仅支持其中部分，见文末）。
| 属性 | 说明 | 典型值 |
|---|---|---|
color |
文字颜色 | #F5F5F5 |
text-align |
文字对齐 left/center/right | center |
background |
background-color 简写 |
#3E3E42 |
background-color |
背景色 | #3E3E42 |
border-color |
边框色 | #5A5A5A |
border-width |
边框宽度 | 1 |
border-radius |
圆角 | 6 |
show-border |
显示边框 | true |
transparent-background |
透明背景 | true |
font-size |
字号 | 14 |
font-family |
字体 | "Microsoft YaHei UI" |
font-bold |
粗体 | true |
font-italic |
斜体 | false |
opacity |
不透明度 0–100 | 90 |
background-gradient-color |
渐变第二色 | #2A2A2A |
background-gradient-direction |
vertical / horizontal |
vertical |
text-gradient-color |
文字渐变第二色 | #00BFFF |
text-gradient-direction |
文字渐变方向 | horizontal |
text-glow |
启用文字发光 | true |
text-glow-color |
发光颜色 | #00BFFF |
text-glow-size |
发光大小 | 4 |
outer-glow |
外发光 | true |
outer-glow-color |
外发光颜色 | #007ACC |
outer-glow-size |
外发光大小 | 5 |
shadow |
阴影 | true |
shadow-color |
阴影颜色 | #000000 |
shadow-blur |
阴影模糊 | 12 |
shadow-offset-x |
阴影 X 偏移 | 0 |
shadow-offset-y |
阴影 Y 偏移 | 4 |
text-3d |
立体字 | true |
text-3d-dark-color |
立体暗色 | #202020 |
text-3d-depth |
立体深度 | 4 |
padding-left / top / right / bottom |
内边距 | 6 |
hover-color |
悬停文字色（:hover） |
#FFFFFF |
hover-text-color |
同 hover-color（复选框等） |
#FFFFFF |
hover-background-color |
悬停背景色 | #008CDC |
pressed-color |
按下文字色 | #FFFFFF |
pressed-background-color |
按下背景色 | #005A9E |
focus-border-color |
焦点边框色 | #007ACC |
focus-background-color |
焦点背景色 | #1E1E1E |
focus-glow-color |
焦点光晕色 | #007ACC |
disabled-color |
禁用文字色 | #888888 |
disabled-background-color |
禁用背景色 | #3A3A3A |
border-style |
边框线型 | solid / dashed / dotted / dash-dot |
outline-color / outline-width |
焦点描边 | #007ACC / 2 |
box-shadow |
启用阴影（配合 shadow-*） |
true |
边距与内边距
| 属性 | 说明 |
|---|---|
padding |
简写：8 / 8 12 / 8 12 8 12（上 右 下 左） |
padding-left / top / right / bottom |
内容区内边距 |
margin |
简写，语法同 padding |
margin-left / top / right / bottom |
绘制区域外边距（在控件矩形内缩进背景） |
复选框 / 单选框专用（indicator）
| 属性 | 说明 | 范围 / 备注 |
|---|---|---|
indicator-size |
指示器宽高 | 8–48 |
indicator-spacing |
指示器与文字间距 | 0–64 |
indicator-radius |
指示器圆角（复选框） | 0–24 |
indicator-style |
单选框：pill 胶囊选中 / none 隐藏圆点 |
default |
indicator-checked-background-color |
选中时指示器填充色（复选框） | #9B6FD0 |
indicator-background-color |
指示器背景 | #2D2D30 |
indicator-border-color |
指示器边框 | #707070 |
checkmark-color |
选中勾颜色（复选框） | #00CC66 |
mark-color |
选中圆点颜色（单选框） | #007ACC |
indeterminate-color |
不确定态横条色 | #FFB020 |
indicator-checked-image |
选中态图片 | :/img/on.png |
indicator-unchecked-image |
未选中态图片 | :/img/off.png |
indicator-indeterminate-image |
不确定态图片 | :/img/dash.png |
checked-image |
indicator-checked-image 简写 |
|
unchecked-image |
indicator-unchecked-image 简写 |
|
indeterminate-image |
indicator-indeterminate-image 简写 |
|
hover-indicator-border-color |
悬停时指示器边框色 | #0096FF |
运行时加载
| 方式 | 说明 |
|---|---|
| 自动 | 窗体启动后加载 exe 旁 {窗体名}.yss（如 主窗口.yss） |
加载YSS() |
同上，省略路径时使用默认 {窗体名}.yss |
加载YSS(":/主窗口.yss") |
资源 URL，解析为 exe 旁文件 |
加载YSS("yss/demo.yss") |
相对 exe 目录的子路径 |
应用YSS(R"(...)") |
直接应用 YSS 文本，适合内联样式 |
两层样式机制：
form_yss_ext.bin（F5 自动生成）：复选框/单选框指示器扩展（尺寸、颜色、图片等），启动时自动加载- 完整
.yss文件：按钮/标签/文本框等全部样式；exe 旁{窗体名}.yss启动时自动加载，也可用加载YSS()换肤
应用YSS() 与 R"(...)" 原始字符串可配合使用，详见基础支持库「语法」中的 原始字符串 条目。
设计器
- 打开窗口 XML 进入设计视图时，自动尝试加载
资源/{窗体名}.yss或窗口/{窗体名}/{窗体名}.yss - 编辑
.yss文件并保存后，若当前在设计视图且与窗口同名，会即时刷新预览 - 设计器中
:/路径解析为工程「资源」目录
常见问题
Q：F5 后双击发布目录的 exe 没有样式？
A：确认 exe 旁存在 主窗口.yss、img/ 等文件；仅复制 exe 而不带资源无效。Debug 模式也可直接运行编译缓存目录中的 exe（该目录在 F5 时同样会部署资源）。
Q：:/img/xx.png 和 YSS 子目录的关系？
A：:/ 始终相对 exe 根目录。YSS 在 yss/demo.yss 时，图片仍写 :/img/xx.png，不要写相对于 YSS 文件的路径。
Q：还需要写 加载YSS() 吗？
A：默认窗体名对应的 主窗口.yss 在 exe 旁时会自动加载。子目录主题、运行时换肤、多套皮肤切换时再调用 加载YSS()。
Q：复选框图片不显示？
A：检查 资源/img/... 是否在 F5 后出现在 exe 旁 img/；YSS 中路径是否为 :/img/文件名.png。