多选下拉框 (Listbox)

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

基本用法

gui_config.add_argument(
    "--filteroption",
    metavar="多选下拉",
    help="选择要筛选数据的列名",
    choices=["选项一", "选项二", "选项三", "选项四", "选项五"],
    required=True,
    widget="Listbox",
    nargs="*",
    default=["选项一", "选项二"],
    gooey_options={
        "full_width": True,  # 是否占满宽度
        "height": 100,  # 高度
        "filterable": True,  # 是否可搜索
        "collapseTags": True,  # 是否折叠标签
        "collapseTagsTooltip": True,  # 是否在折叠标签时显示tooltip
        "placeholder": "请选择多个选项",  # 占位文本
        "multipleLimit": 0,  # 0表示不限制
        "size": "large"  # 大小
    }
)

属性

属性名	说明	类型	默认值
full_width	是否占满宽度	boolean	true
height	下拉框高度	number	-
filterable	是否可搜索	boolean	false
collapseTags	是否折叠标签	boolean	false
collapseTagsTooltip	是否在折叠标签时显示tooltip	boolean	false
placeholder	占位文本	string	-
multipleLimit	多选时用户最多可以选择的项目数，0表示不限制	number	0
size	下拉框大小	string	'default'

使用场景

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

• 用户权限选择
• 标签选择
• 筛选条件设置
• 类别多选

动态加载选项

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

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

折叠标签

当选择项较多时，可以通过设置 collapseTags 属性来折叠显示已选项：

gui_config.add_argument(
    "--tags",
    metavar="标签选择",
    help="选择多个标签",
    choices=["标签1", "标签2", "标签3", "标签4", "标签5", "标签6", "标签7", "标签8"],
    widget="Listbox",
    nargs="*",
    gooey_options={
        "collapseTags": True,  # 折叠标签
        "collapseTagsTooltip": True  # 在折叠标签时显示tooltip
    }
)

最佳实践

1. 必须设置 nargs="*" 才能正确处理多选值
2. 通过 choices 参数提供选项列表
3. default 值必须是 choices 中的值，否则会出现错误
4. 多选下拉框的 default 应该是一个列表
5. 对于选项较多的场景，启用 filterable 属性以便用户搜索
6. 当选择项可能很多时，使用 collapseTags 优化显示效果