开关组件 (SwitchField)

开关组件用于表示两种状态之间的切换。

基本用法

gui_config.add_argument(
    "switch",
    metavar="开关组件",
    help="切换开关状态",
    default=True,
    widget="SwitchField",
    gooey_options={
        "activeValue": True,  # 打开时的值
        "inactiveValue": False,  # 关闭时的值
        "activeText": "开启",  # 打开时的文字
        "inactiveText": "关闭",  # 关闭时的文字
        "activeColor": "#13ce66",  # 打开时的颜色
        "inactiveColor": "#ff4949",  # 关闭时的颜色
        "width": 60,  # 宽度
        "size": "large",  # 大小
        "inlinePrompt": False,  # 是否在按钮中显示文字
        "disabled": False  # 是否禁用
    }
)

属性

属性名	说明	类型	默认值
activeValue	打开时的值	boolean/string/number	true
inactiveValue	关闭时的值	boolean/string/number	false
activeText	打开时的文字	string	-
inactiveText	关闭时的文字	string	-
activeColor	打开时的颜色	string	'#13ce66'
inactiveColor	关闭时的颜色	string	'#ff4949'
width	开关宽度	number	40
size	开关大小	string	'default'
inlinePrompt	是否在按钮中显示文字	boolean	false
disabled	是否禁用	boolean	false

使用场景

开关组件适用于需要用户进行开/关、是/否等二元选择的场景，例如：

• 功能开关
• 模式切换
• 选项启用/禁用
• 状态控制

自定义开关值

开关组件支持自定义打开和关闭时的值，不限于布尔类型：

gui_config.add_argument(
    "mode",
    metavar="模式选择",
    help="选择操作模式",
    default="automatic",
    widget="SwitchField",
    gooey_options={
        "activeValue": "automatic",  # 打开时的值
        "inactiveValue": "manual",   # 关闭时的值
        "activeText": "自动",        # 打开时的文字
        "inactiveText": "手动",      # 关闭时的文字
    }
)

开关状态颜色

通过设置 activeColor 和 inactiveColor 可以自定义开关不同状态的颜色：

gui_config.add_argument(
    "important_switch",
    metavar="重要开关",
    help="开启重要功能",
    default=False,
    widget="SwitchField",
    gooey_options={
        "activeColor": "#67C23A",    # 绿色
        "inactiveColor": "#909399",  # 灰色
    }
)

最佳实践

1. 为开关提供清晰的标签和帮助文本，说明开关控制的功能
2. 使用 activeText 和 inactiveText 提供明确的状态描述
3. 设置合理的默认值，通常情况下，默认关闭（false）较为安全
4. 对于重要的开关，考虑使用醒目的颜色区分状态