单选下拉框 (Dropdown)

单选下拉框用于从预定义选项列表中选择单个选项。

基本用法

gui_config.add_argument(
    "--dropdownbox",
    metavar="单选下拉框",
    help="选择你需要的",
    choices=["选择一", "选择二", "选项三", "选项四", "选项五"],
    default="选择一",
    widget="Dropdown",
    gooey_options={
        "filterable": True,  # 是否可搜索
        "placeholder": "请选择一个选项",  # 占位文本
        "clearable": True,  # 是否可清空
        "remote": False,  # 是否为远程搜索
        "loading": False,  # 是否加载中
        "loadingText": "加载中...",  # 加载中文本
        "noMatchText": "无匹配数据",  # 无匹配文本
        "noDataText": "无数据",  # 无数据文本
        "reserveKeyword": True,  # 是否保留搜索关键字
        "size": "large"  # 大小
    }
)

属性

属性名	说明	类型	默认值
filterable	是否可搜索	boolean	false
placeholder	占位文本	string	-
clearable	是否可清空	boolean	false
remote	是否为远程搜索	boolean	false
loading	是否加载中	boolean	false
loadingText	加载中文本	string	'加载中...'
noMatchText	无匹配文本	string	'无匹配数据'
noDataText	无数据文本	string	'无数据'
reserveKeyword	是否保留搜索关键字	boolean	true
size	下拉框大小	string	'default'

使用场景

单选下拉框适合于需要用户从固定选项中选择单个值的场景，如：

• 状态选择
• 类型选择
• 配置选项
• 排序方式选择

可搜索下拉框

当选项较多时，可以启用搜索功能帮助用户快速找到需要的选项：

gui_config.add_argument(
    "--country",
    metavar="国家/地区",
    help="选择国家或地区",
    choices=["中国", "美国", "英国", "法国", "德国", "日本", "韩国", "俄罗斯", "加拿大", "澳大利亚"],
    default="中国",
    widget="Dropdown",
    gooey_options={
        "filterable": True,  # 启用搜索
        "placeholder": "请选择国家/地区"
    }
)

可清空下拉框

通过设置 clearable 属性，可以允许用户清空已选择的选项：

gui_config.add_argument(
    "--optional_setting",
    metavar="可选设置",
    help="选择一个可选设置（可不选）",
    choices=["设置A", "设置B", "设置C"],
    widget="Dropdown",
    gooey_options={
        "clearable": True,  # 允许清空
        "placeholder": "请选择一个设置（可选）"
    }
)

动态加载选项

单选下拉框支持动态加载选项，可以通过在后端返回选项列表来实现：

def get_options(self):
    """获取动态选项列表"""
    return {
        "status": 0,
        "msg": "success",
        "data": [
            {"label": "选项1", "value": "option1"},
            {"label": "选项2", "value": "option2"},
            {"label": "选项3", "value": "option3"}
        ]
    }

最佳实践

1. 通过 choices 参数提供选项列表
2. default 值必须是 choices 中的值，否则会出现错误
3. 对于选项较多的场景，启用 filterable 属性以便用户搜索
4. 对于可选字段，启用 clearable 属性允许用户清空选择
5. 设置合适的 placeholder 提示用户选择内容