按钮控件 (SButton)¶

按钮是 SOUI 中最常用的交互控件之一，用于触发操作或响应用户点击。

基本信息¶

类名：SButton
控件标签：button
基类：SWindow
皮肤类：SSkinButton

属性说明¶

自身属性¶

属性名	类型	默认值	说明
accel	string	-	快捷键，如 `ctrl+s`、`alt+f4`。由 `SButton::OnAttrAccel` 解析并注册到容器的加速器管理器
animate	bool	false	鼠标移入/移出（Normal ↔ Hover）时是否播放渐变动画
disableAccelIfInvisible	bool	false	控件不可见时是否禁用快捷键（`1` 为禁用）

链式子对象属性（Hover 动画器）¶

SButton 通过 ATTR_CHAIN_PTR(m_pHoverAni, 0) 把未匹配的属性转发给内部的 SByteAnimator（alpha 动画器），因此下面这些属性同样可以写在 <button> 上：

属性名	类型	默认值	说明
valueFrom	uint	0	动画起始 alpha 值（0~255）。按钮触发 hover 动画时会强制设为 `50`
valueTo	uint	255	动画结束 alpha 值（0~255）。按钮触发 hover 动画时会强制设为 `255`
duration	int	250	动画时长（毫秒）。`SValueAnimator` 本身默认 200ms，`SButton` 构造时改为 250ms
animateSteps	int	-	以"帧数"设置时长，实际 `duration = animateSteps × 10`（毫秒）。与 `duration` 二选一
repeatCount	int	0	重复次数，`0` 表示不重复，`-1` 表示无限循环
repeatMode	enum	restart	重复模式：`restart`（每次从头开始）/ `reverse`（反向往复）
interpolator	string	-	插值器名称，用于指定动画速度曲线

animate 与动画属性

只有 animate="1" 时，鼠标进出按钮才会启动 m_pHoverAni；上述动画属性只是配置这个动画器的参数。旧版本中的 animateStep 属性已不存在，请改用 duration 或 animateSteps。

继承自 SWindow / SwndStyle / 布局参数的通用属性，见通用属性。

使用示例¶

基本按钮¶

<button name="btnOK" 
        pos="10,10,110,40" 
        text="确定"/>

带快捷键的按钮¶

<button name="btnSave" 
        pos="10,50,110,80" 
        text="保存"
        accel="ctrl+s"/>

自定义样式按钮¶

<button name="btnCustom" 
        pos="10,90,110,120" 
        text="自定义按钮"
        skin="skin_btn_custom"
        colorText="#333333"
        colorTextHover="#000000"
        colorBorder="#cccccc"
        font="face:微软雅黑,size:14"/>

带动画效果的按钮¶

<button name="btnAnimated" 
        pos="10,50,110,80" 
        text="动画按钮"
        animate="1"
        duration="400"
        repeatCount="0"
        repeatMode="restart"/>

事件处理¶

按钮控件支持以下事件：

事件名	EventID	说明
EVT_CMD	EventCmd::EventID	按钮点击事件

// 事件处理示例
EVENT_MAP_BEGIN()
    EVENT_NAME_COMMAND(L"btnOK", OnBtnOK)
EVENT_MAP_END()

void OnBtnOK()
{
    // 处理按钮点击
}

状态切换¶

按钮有以下几种状态： 1. 正常状态：默认显示状态 2. 悬停状态：鼠标移动到按钮上 3. 按下状态：鼠标点击按钮时 4. 禁用状态：按钮不可用时

状态切换示例¶

// 禁用按钮
SButton *pBtn = FindChildByName2<SButton>(L"btnOK");
if(pBtn) {
    pBtn->EnableWindow(FALSE);
}

// 恢复按钮
pBtn->EnableWindow(TRUE);

自定义按钮¶

自定义皮肤¶

<style>
    <!-- 自定义按钮样式 -->
    <class name="customBtn"
           font="face:微软雅黑,size:14"
           colorText="#333333"
           colorTextHover="#000000"
           colorBorder="#cccccc"
           skin="skin_btn_custom"/>
</style>

<button class="customBtn"
        pos="10,10,110,40"
        text="自定义样式"/>

自定义绘制¶

class CMyButton : public SButton
{
    SOUI_CLASS_NAME(CMyButton, L"mybutton")
public:
    void OnPaint(IRenderTarget *pRT)
    {
        // 自定义绘制代码
    }
};

最佳实践¶

合理使用快捷键：为常用操作的按钮设置快捷键，提升用户体验
状态反馈：通过不同颜色或字体区分按钮的不同状态
动画效果：适当使用动画效果增强交互体验，但避免过度使用
文本对齐：根据按钮用途选择合适的文本对齐方式

常见问题¶

Q: 按钮无法接收快捷键怎么办？¶

A: 检查是否设置了 disableAccelIfInvisible 属性为 true，且按钮当前处于隐藏状态；同时确认 accel 的写法可被 SAccelerator::TranslateAccelKey 解析。

Q: 按钮动画效果不明显怎么办？¶

A: 调大 duration（或 animateSteps）属性值延长过渡时间，并确认已设置 animate="1"。