按钮（button）

选择器： button · 设计器组件： 按钮 · 按名称： button#名称 或 #名称
用途： 可点击的命令控件。

硬约束与叠画

1. 控件名来自窗口 XML「名称」；属性赋值无括号（如 标题 = "确定"），方法调用必须带括号（如 刷新()）。
2. 事件写 函数 控件名.事件名(参数…)，形参类型以本页事件表为准。
3. 任意控件客户区叠画用支持库 绘制类：绘制类 g → g.绑组件(本控件名)（组件名无引号）。画布场景编辑见 画布控件。
4. 字体对象见绘制文档中的字体类；置字体(字体类) 将字体应用到本控件。
5. 不要虚构未列出的方法；YSS 键见下文与 YSS.md。

属性

设计器属性面板与代码侧可读可写属性（来源：组件类库）。

属性	类型	读写	说明
提示	文本	读写	鼠标悬停时的提示文字
鼠标指针	文本	读写	空=默认；可用 arrow/hand/ibeam/cross/wait/no/sizeall 等预设，或.cur/.ani 路径（如 资源/press.cur）
左边	小数	读写	相对窗体左边的位置（像素）
顶边	小数	读写	相对窗体顶边的位置（像素）
宽度	小数	读写	控件宽度（像素）
高度	小数	读写	控件高度（像素）
停靠	整数	读写	0无 1上 2下 3左 4右 5填充；菜单/工具/状态栏仍用专用吸附
可见	逻辑	读写	真=显示，假=隐藏
启用	逻辑	读写	真=可用，假=禁用
句柄	长整数	只读	组件逻辑句柄（1 起，供动画类等绑定；非 HWND）；只读
标题	文本	读写	按钮上显示的文字
字体	文本	读写	字体名称，如 微软雅黑；读写：组件.字体 / 组件.字体 = “…”
字号	整数	读写	像素；读写：组件.字号 / 组件.字号 = 16
粗体	逻辑	读写	真=粗体；读写：组件.粗体 / 组件.粗体 = 真
斜体	逻辑	读写	真=斜体；读写：组件.斜体 / 组件.斜体 = 真
对齐	整数	读写	0=左对齐，1=居中，2=右对齐
文字色	文本	读写	如 #FFFFFF 或 #RRGGBB
背景色	文本	读写	如 #3E3E42 或 #RRGGBB
描边样式	整数	读写	0=实线，1=虚线，2=点线，3=点划线，4=双点划线
透明背景	逻辑	读写	真=透明，假=不透明
圆角	整数	读写	像素，0=直角
默认按钮	逻辑	读写	真=默认按钮（Enter 触发）
显示模式	整数	读写	0=图标+文字，1=仅图标，2=仅文字
文字省略	逻辑	读写	真=超出省略
热键下划线	逻辑	读写	真=显示热键下划线
图片	字节集	读写	图片字节；可用 到字节集(“图标.png”)
悬停图片	字节集	读写	图片字节；可用 到字节集(“图标.png”)
按下图片	字节集	读写	图片字节；可用 到字节集(“图标.png”)
禁用图片	字节集	读写	图片字节；可用 到字节集(“图标.png”)
长按毫秒	整数	读写	毫秒，0=禁用长按
动画过渡	逻辑	读写	真=启用动画
自定义绘制	逻辑	读写	真=自定义绘制
焦点边框色	文本	读写	如 #0096FF
焦点背景色	文本	读写	如 #RRGGBB
焦点发光色	文本	读写	如 #0096FF

方法

组件类库方法（调用必须带括号）。返回类型多为 无。共用：移动 / 置焦点 / 刷新 / 显示 / 隐藏 / 置字体 等。

叠画：可用 绘制类 绑组件(按钮1)；字体对象见同页 字体类。

方法	签名	返回	参数取值 / 说明
置悬停色	无 置悬停色([文本 文字色="#FFFFFF"], [文本 背景色="#008CDC"])	无	颜色 #RRGGBB/#AARRGGBB；可省略某一参
置按下色	无 置按下色([文本 文字色="#FFFFFF"], [文本 背景色="#005A9E"])	无
置焦点色	无 置焦点色([文本 边框色="#0096FF"], [文本 背景色=""], [文本 发光色="#0096FF"])	无
置禁用色	无 置禁用色([文本 文字色="#A0A0A0"], [文本 背景色="#3A3A3A"])	无
置背景渐变	无 置背景渐变([文本 渐变色="#2A2A2A"], [整数 方向=0])	无	方向：0 纵向 · 1 横向
置图片样式	无 置图片样式([整数 图标位置=0], [整数 图片大小=16], [整数 图片模式=0], [整数 间距=4], [整数 透明度=100])	无	位置 0左/1右/2上/3下；模式 0固定/1等比；透明度 0～100。图片内容用属性 图片/悬停图片 等
置九宫格	无 置九宫格(字节集 图片, [整数 左=8], [整数 上=8], [整数 右=8], [整数 下=8])	无	图片可用 到字节集("九宫.png")
置边框	无 置边框([逻辑 显示边框=真], [整数 边框大小=1], [文本 边框颜色], [整数 描边样式])	无	描边：0实 1虚 2点 3点划 4双点划
置阴影	无 置阴影([文本 阴影色="#000000"], [整数 模糊=4], [整数 X=0], [整数 Y=2])	无
置圆角	无 置圆角([整数 半径=4])	无	像素；0=直角
移动	无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度])	无	可选同时改宽高
置焦点	无 置焦点()	无
刷新	无 刷新()	无	立即重绘所在窗口
显示 / 隐藏	无 显示() / 无 隐藏()	无	等同 可见 = 真/假
置字体	逻辑 置字体(字体类 字体)	逻辑	见 绘制类文档·字体类

按钮1.置悬停色("#FFFFFF", "#008CDC")
按钮1.置背景渐变("#2A2A2A", 0)
按钮1.图片 = 到字节集("图标.png")
按钮1.置图片样式(0, 16, 0, 4, 100)
按钮1.刷新()

事件

在代码中写 函数 控件名.事件名(...) 处理。

事件	参数	说明
单击	整数 X, 整数 Y	鼠标左键单击控件。
双击	整数 X, 整数 Y	鼠标左键双击控件。
右键单击	整数 X, 整数 Y	鼠标右键单击控件。
鼠标按下	整数 X, 整数 Y, 逻辑 按下	鼠标键在控件上按下。按下=真表示当前仍按住。
鼠标抬起	整数 X, 整数 Y, 逻辑 按下	鼠标键在控件上放开。
鼠标移动	整数 X, 整数 Y, 逻辑 按下	鼠标在控件上移动。按下表示左键是否按住。
鼠标进入	整数 X, 整数 Y	鼠标指针进入控件区域。
鼠标离开	整数 X, 整数 Y	鼠标指针离开控件区域。
鼠标左键单击	整数 X, 整数 Y	鼠标左键单击（与「单击」同时触发）。
鼠标左键双击	整数 X, 整数 Y	鼠标左键双击（与「双击」同时触发）。
鼠标中间单击	整数 X, 整数 Y	鼠标中键单击控件。
鼠标齿轮滚动	整数 X, 整数 Y, 逻辑 向上	在控件上滚动鼠标滚轮。向上=真表示向上滚。
鼠标右键单击	整数 X, 整数 Y	鼠标右键单击（与「右键单击」同时触发）。
鼠标右键双击	整数 X, 整数 Y	鼠标右键双击控件。
获得焦点	无	控件获得键盘焦点。
失去焦点	无	控件失去键盘焦点。
按键按下	整数 键码, 整数 Shift, 逻辑 Ctrl, 整数 组合键	按键按下（含自动重复）。Shift=是否按住Shift；Ctrl=是否按住Ctrl；组合键=1/2/4 位标志。
按下某键	整数 键码, 整数 Shift, 逻辑 Ctrl, 整数 组合键	某键刚被按下的第一下（不含自动重复）。
按住某键	整数 键码, 整数 Shift, 逻辑 Ctrl, 整数 组合键	按住某键触发的自动重复。
抬起某键	整数 键码, 整数 Shift, 逻辑 Ctrl, 整数 组合键	某键被放开。
长按	整数 X, 整数 Y	按住左键达到「长按毫秒」后触发；触发后本次不再发单击。

函数 按钮1.单击 (整数 X, 整数 Y) {
    // …
}

YSS 样式

以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。

样式概览

YSS 控制外壳填充、描边、阴影/发光、图标与伪态配色。

伪状态与映射

伪状态： :hover（悬停）· :pressed（按下）· :focus（焦点）· :disabled（禁用）· :default（窗体默认按钮，回车触发）

伪态映射（ 必读）：

在伪态块中写的键	实际落到控件的字段
:hover { color } / background-color	hover-color / hover-background-color
:pressed { color } / background-color	pressed-color / pressed-background-color
:pressed { inner-shadow* }	pressed-inner-shadow*（仅按下时绘制）
:focus { border-color } / background-color	focus-border-color / focus-background-color
:disabled { color } / background-color	disabled-color / disabled-background-color

也可直接在基选择器写 hover-* / pressed-* 等键，效果相同。

属性说明（逐键）

本控件支持 YSS 通用属性速查 中的富外壳子集；下表按「文字 → 底板 → 描边 → 渐变/发光/阴影 → 图片/九宫 → 伪态 → 其它」展开。每条写清：作用、取值、绘制时机、注意点。

文字与字体

属性	作用	取值 / 范围	说明与注意
color	常态文字颜色	#RRGGBB / #AARRGGBB	未设时运行时用深色主题默认浅灰白。
font-size	字号	整数像素，如 14	DIP；过小会难读，过大可能裁切。
font-family	字体族	字符串，如 "Microsoft YaHei UI"	含空格须加引号。
font-bold	粗体	true / false
font-italic	斜体	true / false
text-align	水平对齐	left/0 · center/1 · right/2	有图标时与图标位置共同决定布局。
text-gradient-color	文字双色渐变第二色	颜色	与 color 组成线性渐变字。
text-gradient-direction	文字渐变方向	vertical（默认）/ horizontal
text-glow	开关文字发光	true/false/1/0	true 时若未设大小，默认约 glowSize=4。
text-glow-color	文字光晕色	颜色，如 #00E5FF	未设时可能用默认青蓝。
text-glow-size	文字光晕半径	0–64 像素	多层轻微偏移描字；越大越散。
text-3d	立体字	true/false	简易浮雕字，非真 3D。
text-3d-dark-color	立体字暗部色	颜色
text-3d-depth	立体字深度	1–16 像素

底板与透明度

属性	作用	取值 / 范围	说明与注意
background-color / background	常态底板色	颜色；background≡background-color	填充在阴影/外发光之后。
transparent-background	不铺底板	true/false	true 时只画边框/文字/图标；常用于下划线按钮。
opacity	整控不透明度	0–100	100=不透明。
padding	内容区内边距	8 / 8 12 / 8 12 8 12（上右下左）	影响图标+文字排布。
padding-left / padding-top / padding-right / padding-bottom	单侧内边距	像素 0–200
margin	绘制区外边距	语法同 padding	在控件矩形内缩进背景区，不改 HWND 布局。
margin-left / margin-top / margin-right / margin-bottom	单侧外边距	像素

描边

属性	作用	取值 / 范围	说明与注意
show-border	是否画边框	true/false	为 false 时忽略线型与宽度。
border-color	边框色	颜色
border-width	边框宽	像素，如 1–20	默认按钮会再加粗约 1px。
border-radius	圆角	像素，如 0–64	0=直角（像素风）；大值≈胶囊。
border-style	线型	见下表	underline 只画底边，不画四边。
outline-color	焦点环/光晕色	颜色	常与 :focus 一起用。
outline-width	焦点描边宽参考	像素	部分路径会映射到边框宽槽。

border-style 枚举：

值	效果
solid / 0 / 实线	实线四边（默认）
dashed / dash / 1 / 虚线	虚线四边
dotted / dot / 2 / 点线	点线四边
dash-dot / 3	点划线
dash-dot-dot / 4	双点划线
underline / 5 / 下划线	仅底边一条线（极简链接风按钮）

勿与选项卡的 tab-indicator: underline 混淆：后者表示标签指示条样式，不是按钮底边。

背景渐变

属性	作用	取值 / 范围	说明与注意
background-gradient-color	双色渐变第二色	颜色	与 background-color 组成双色线性渐变。
background-gradient / background-gradient-stops	多停渐变	逗号/分号分隔 ≥2 色，最多 8	≥3 色走旁路真多停；悬停/按下若设了单色悬停底则优先单色。
background-gradient-direction	渐变方向	vertical（默认）/ horizontal（或 1）

外发光 · 阴影 · 内阴影

属性	作用	取值 / 范围	说明与注意
outer-glow	开关外发光	true/false	true 时默认 outerGlowSize≈5，色默认青蓝。
outer-glow-color	外发光色	颜色，如 #00E5FF	霓虹风主色。
outer-glow-size	外发光外扩半径	0–64	多层半透明外扩圆角，画在底板之前。
shadow / box-shadow	启用阴影	true/false	true 时若未设模糊，常默认 shadow-blur: 4。
shadow-color	阴影色	颜色	硬阴影时建议不透明深色如 #111111。
shadow-blur	软阴影模糊半径	0–64	0 且 offset≠0 → 自动硬阴影（即使未写 shadow-style）。
shadow-offset-x / shadow-offset-y	阴影偏移	-64–64	硬阴影靠偏移制造「贴地」块影。
shadow-style	阴影风格	soft（柔边，默认）/ hard（不透明偏移，无模糊层）	hard 适合新粗野主义、像素风；旁路表，不改控件 ABI。
inner-shadow	开关/设色内阴影	true/false/none 或颜色	顶边+左侧加深 + 内缩描边环，模拟按压凹下。
inner-shadow-color	内阴影色	颜色，默认近似半透明黑
inner-shadow-blur	内阴影深度	0–32	越大凹感越强。
skew-x / skew-y	平行四边形倾斜（度）	-45–45	设计器与运行时同步倾斜绘制。

阴影决策（运行时）：

1. 显式 shadow-style: hard → 硬阴影
2. 显式 shadow-style: soft → 软阴影
3. 未设 style，且 shadow-blur≤0 且 (offset-x≠0 或 offset-y≠0) → 硬阴影
4. 否则 → 软阴影（drawSoftShadow）

内阴影与 :pressed：
基选择器的 inner-shadow* 常驻；:pressed { inner-shadow* } 仅在按下时叠加。

图片与九宫皮肤

属性	作用	取值 / 范围	说明与注意
image / background-image / image-url	常态图标或底图	路径，如 :/img/btn.png	:/ 相对 exe 根。
image-hover	悬停图	路径
image-pressed	按下图	路径
image-disabled	禁用图	路径
image-mode / image-scaling	缩放模式	stretch/1 · fixed/tile/0 · keep-aspect（等比）
image-spacing	图标与文字间距	像素
nine-slice / nine-slice-image / border-image	九宫格皮肤图	路径	有九宫时优先于纯色/渐变填充。
slice-left / slice-top / slice-right / slice-bottom	九宫切片宽	0–200

过渡与默认按钮

属性	作用	取值 / 范围	说明与注意
transition	伪态动画	如 all 200ms ease-in-out；可写 color / background-color / opacity	缓动：linear/ease/ease-in/ease-out/ease-in-out。设计器静态预览。
default / is-default	窗体默认按钮	true/false	也可用选择器 button:default。回车触发该按钮单击。

伪态配色键（可直接写，也可由伪态块映射）

属性	作用
hover-color	悬停文字色
hover-background-color	悬停底板色
pressed-color	按下文字色
pressed-background-color	按下底板色
focus-border-color	焦点边框色
focus-background-color	焦点底板色
focus-glow-color	焦点外环光晕色
disabled-color	禁用文字色
disabled-background-color	禁用底板色

---

使用示例

基础外壳

button {
    color: #F5F5F5;
    background-color: #3E3E42;
    border-color: #5A5A5A;
    border-width: 1;
    border-radius: 6;
    show-border: true;
    font-size: 14;
    text-align: center;
    transition: all 200ms ease-in-out;
}

霓虹外发光 + 文字微光

button#霓虹 {
    color: #E0F7FF;
    background-color: #0F172A;
    border-radius: 8;
    show-border: true;
    border-color: #00E5FF;
    border-width: 1;
    outer-glow: true;
    outer-glow-color: #00E5FF;
    outer-glow-size: 12;
    text-glow: true;
    text-glow-color: #00E5FF;
    text-glow-size: 3;
}

硬阴影（新粗野）

button#粗野 {
    color: #111111;
    background-color: #FDE047;
    border-color: #111111;
    border-width: 2;
    border-radius: 0;
    show-border: true;
    shadow-color: #111111;
    shadow-blur: 0;
    shadow-offset-x: 4;
    shadow-offset-y: 4;
    shadow-style: hard;
    font-bold: true;
}

极简下划线

button#链接风 {
    color: #2563EB;
    transparent-background: true;
    show-border: true;
    border-color: #2563EB;
    border-width: 2;
    border-style: underline;
    border-radius: 0;
}

内阴影按压

button#按压 {
    color: #FFFFFF;
    background-color: #4B5563;
    border-radius: 8;
    show-border: false;
    inner-shadow: true;
    inner-shadow-color: #000000;
    inner-shadow-blur: 6;
}
button#按压:pressed {
    pressed-background-color: #374151;
    inner-shadow: true;
    inner-shadow-color: #000000;
    inner-shadow-blur: 8;
}

九宫皮肤

button#皮肤按钮 {
    nine-slice: :/img/btn9.png;
    slice-left: 12;
    slice-top: 12;
    slice-right: 12;
    slice-bottom: 12;
}

---

完整示例

button {
    color: #F5F5F5;
    background-color: #3E3E42;
    border-color: #5A5A5A;
    border-width: 1;
    border-radius: 6;
    show-border: true;
    font-size: 14;
    text-align: center;
    transition: all 200ms ease-in-out;
}

button#按钮_确认 {
    background-color: #007ACC;
    background-gradient-color: #005A9E;
    background-gradient-direction: vertical;
    outline-color: #007ACC;
}

button#按钮_确认:hover {
    hover-background-color: #008CDC;
    hover-color: #FFFFFF;
}

button#按钮_确认:pressed {
    pressed-background-color: #005A9E;
}

button#按钮_确认:focus {
    focus-border-color: #007ACC;
    focus-glow-color: #007ACC;
}

button#按钮_确认:disabled {
    disabled-color: #888888;
    disabled-background-color: #3A3A3A;
}

button:default {
    font-bold: true;
    is-default: true;
}

---