跳到主要内容

DropdownM2

一种用于从列表中选择项目的材料设计按钮。

下拉菜单允许用户从多个项目中进行选择。下拉菜单显示当前选中的项目以及一个箭头，点击箭头可打开菜单选择其他项目。

信息

从 0.27.0 版本开始，Flet 使用DropdownMenu Flutter 小部件用于Dropdown控件，这是先前使用的 DropdownButton 的 Material 3 版本。

先前版本的 Dropdown 实现的一些属性在新版本中不可用，并被“存根化”——它们不会破坏你的程序，但也不会执行任何操作。请在此处查看已弃用属性的列表[/docs/controls/dropdown/#deprecated-dropdown-properties-and-events]。

先前版本的 Dropdown 控件可作为DropdownM2控件使用，并将在 Flet 0.30.0 中被删除。

示例​

实时示例

基本下拉菜单​

import flet as ft

def main(page: ft.Page):
    def button_clicked(e):
        t.value = f"下拉菜单的值是：{dd.value}"
        page.update()

    t = ft.Text()
    b = ft.ElevatedButton(文本="提交", on_click=button_clicked)
    dd = ft.DropdownM2(
        宽度=100,
        选项=[
            ft.dropdownm2.Option("红色"),
            ft.dropdownm2.Option("绿色"),
            ft.dropdownm2.Option("蓝色"),
        ],
    )
    page.add(dd, b, t)

ft.app(main)

带有标签和提示的下拉菜单​

import flet as ft

def main(page: ft.Page):
    page.add(
        ft.DropdownM2(
            标签="颜色",
            提示文本="选择你最喜欢的颜色？",
            选项=[
                ft.dropdownm2.Option("红色"),
                ft.dropdownm2.Option("绿色"),
                ft.dropdownm2.Option("蓝色"),
            ],
            自动聚焦=True,
        )
    )

ft.app(main)

带有on_change事件的下拉菜单​

import flet as ft

def main(page: ft.Page):
    def dropdown_changed(e):
        t.value = f"下拉菜单更改为{dd.value}"
        page.update()

    t = ft.Text()
    dd = ft.DropdownM2(
        on_change=dropdown_changed,
        选项=[
            ft.dropdownm2.Option("红色"),
            ft.dropdownm2.Option("绿色"),
            ft.dropdownm2.Option("蓝色"),
        ],
        宽度=200,
    )
    page.add(dd, t)

ft.app(main)

在下拉菜单选项中更改项目​

import flet as ft

def main(page: ft.Page):
    def find_option(选项名称):
        for 选项 in d.选项:
            if 选项名称 == 选项.key:
                return 选项
        return None

    def add_clicked(e):
        d.选项.append(ft.dropdown.Option(选项文本框.value))
        d.value = 选项文本框.value
        选项文本框.value = ""
        page.update()

    def delete_clicked(e):
        选项 = find_option(d.value)
        if 选项!= None:
            d.选项.remove(选项)
            # d.value = None
            page.update()

    d = ft.DropdownM2()
    选项文本框 = ft.TextField(提示文本="输入项目名称")
    添加 = ft.ElevatedButton("添加", on_click=add_clicked)
    删除 = ft.OutlinedButton("删除所选", on_click=delete_clicked)
    page.add(d, ft.Row(控件=[选项文本框, 添加, 删除]))

ft.app(main)

alignment​

定义提示或所选项目在这个下拉菜单中的位置方式。

对齐方式是Alignment类的一个实例。

autofocus​

如果该控件将被选为初始焦点，则为 True。如果页面上有多个设置了自动聚焦的控件，则第一个添加到页面的控件将获得焦点。

bgcolor​

下拉按钮及其菜单的背景颜色。

要为下拉按钮设置不同的背景颜色，请使用fill_color或focused_bgcolor属性。

border​

输入周围的边框。

值是InputBorder类型，默认为InputBorder.OUTLINE。

border_color​

边框颜色。可以设置为transparent以隐藏边框。

border_radius​

边框半径是BorderRadius类的一个实例。

border_width​

边框的宽度（以虚拟像素为单位）。设置为0可完全移除边框。

默认为1。

color​

文本颜色。

content_padding​

输入装饰容器的填充。

counter​

一个Control，作为字符计数放置在输入线下方。

如果为None或空字符串，并且未指定counter_text，则计数器位置不会显示任何内容。

counter_style​

用于counter_text的TextStyle。

counter_text​

可选的文本，作为字符计数放置在输入线下方。

如果为None或空字符串，并且未指定counter，则计数器位置不会显示任何内容。如果指定了counter并且可见，则此counter_text将被忽略。

dense​

文本字段是否是密集表单的一部分（即，使用较少的垂直空间）。

disabled_hint_content​

当value为None且下拉菜单被禁用时，显示为下拉菜单值的占位符Control。

elevation​

下拉菜单的高度。

默认为8。

enable_feedback​

检测到的手势是否应提供声学和/或触觉反馈。例如，在 Android 上，将此设置为True会产生点击声音，长按会产生短暂振动。

默认为True。

error_style​

用于error_text的TextStyle。

error_text​

出现在输入边框下方的文本。

如果不为null，边框颜色将动画变为红色，并且helper_text不会显示。

filled​

如果为True，装饰容器将用主题fill_color填充。

如果filled=None（默认值），则当以下至少一个不为None时，它将隐式设置为True：fill_color、focused_bgcolor和bgcolor。

fill_color​

下拉按钮的背景颜色。如果filled=False，则不可见。

focused_bgcolor​

下拉菜单处于聚焦状态时的背景颜色。如果filled=False，则不可见。

focused_border_color​

处于聚焦状态时的边框颜色。

focused_border_width​

处于聚焦状态时的边框宽度。

focused_color​

下拉菜单聚焦时的文本颜色。

helper_style​

用于helper_text的TextStyle。

helper_text​

提供关于输入值上下文的文本，例如值将如何使用。

如果不为null，文本将显示在输入装饰器下方，与error_text在同一位置。如果指定了非null的error_text值，则不会显示辅助文本。

hint_content​

当value为None时，显示为下拉菜单值的占位符Control。

hint_style​

用于hint_text的TextStyle。

hint_text​

提示输入字段接受何种输入的文本。

当输入为空且未聚焦时，显示在输入上方。如果label为null或者输入获得焦点，则显示在输入上方。

icon​

图标名称[/docs/reference/icons]或在输入字段之前以及装饰容器外部显示的Control。

使用图标名称的示例：

icon=ft.Icons.BOOKMARK

使用Control的示例：

icon=ft.Icon(ft.Icons.BOOKMARK)

icon_content​

用于下拉按钮图标的控件。默认为Icon(icons.ARROW_DROP_DOWN)。

在 0.25.0 版本中已弃用，并将在 0.28.0 版本中删除。请使用icon代替。

icon_enabled_color​

如果此按钮启用，icon_content的任何Icon后代的颜色。

在 0.25.0 版本中已弃用，并将在 0.28.0 版本中删除。请使用select_icon_enabled_color代替。

icon_disabled_color​

如果此按钮禁用，icon_content的任何Icon后代的颜色。

在 0.25.0 版本中已弃用，并将在 0.28.0 版本中删除。请使用select_icon_enabled_color代替。

icon_size​

包裹icon_content的图标按钮的大小。

默认为24.0。

在 0.25.0 版本中已弃用，并将在 0.28.0 版本中删除。请使用icon代替。

item_height​

下拉菜单中项目/选项的高度。

label​

描述输入字段的可选文本。

当输入字段为空且未聚焦时，标签显示在输入字段上方（即在屏幕上可以在输入字段中输入文本的同一位置）。当输入字段获得焦点（或者如果字段不为空）时，标签向上移动，要么垂直相邻于输入字段，要么位于输入字段的中心。

label_style​

用于label的TextStyle。

max_menu_height​

下拉菜单的最大高度。

options​

表示此下拉菜单中的项目的Option控件列表。

options_fill_horizontally​

下拉菜单的内部内容是否水平填充其父容器。

默认情况下，此按钮的内部宽度是其内容的最小尺寸。如果为True，内部宽度将扩展以填充其周围容器。

值的类型为bool，默认为False。

padding​

此下拉菜单可见部分周围的填充。

prefix​

可选的Control，放置在输入线之前。

例如，这可以用于为原本将使用prefix_text指定的文本添加一些填充，或者在输入之前添加自定义控件。该控件的基线与输入基线对齐。

只能指定prefix和prefix_text中的一个。

如果同时指定了prefix_icon，则prefix出现在prefix_icon之后。

prefix_icon​

在prefix或prefix_text之前以及文本字段的可编辑部分之前出现的图标，在装饰容器内。

prefix_style​

用于prefix_text的TextStyle。

prefix_text​

可选的文本前缀，放置在输入线之前。

select_icon​

用于下拉选择按钮图标的图标名称[/docs/reference/icons]或Control。默认为Icon(ft.Icons.ARROW_DROP_DOWN)。

使用图标名称的示例：

icon=ft.Icons.BOOKMARK

使用Control的示例：

icon=ft.Icon(ft.Icons.BOOKMARK)

select_icon_enabled_color​

如果此按钮启用，select_icon的任何Icon后代的颜色。

select_icon_disabled_color​

如果此按钮禁用，select_icon的任何Icon后代的颜色。

select_icon_size​

包裹select_icon的图标按钮的大小。

默认为24.0。

suffix​

可选的Control，放置在输入线之后。

例如，这可以用于为原本将使用suffix_text指定的文本添加一些填充，或者在输入之后添加自定义控件。该控件的基线与输入基线对齐。

只能指定suffix和suffix_text中的一个。

如果同时指定了suffix_icon，则suffix出现在suffix_icon之前。

suffix_icon​

在文本字段的可编辑部分之后以及suffix或suffix_text之后出现的图标，在装饰容器内。

suffix_style​

用于suffix_text的TextStyle。

suffix_text​

可选的文本后缀，放置在输入线之后。

text_size​

文本大小（以虚拟像素为单位）。

text_style​

用于此下拉按钮和点击按钮时出现的下拉菜单中的文本的TextStyle。

value​

所选选项的key值。

focus()​

将焦点移动到这个下拉菜单。

on_blur​

当控件失去焦点时触发。

on_change​

当此下拉菜单的所选项目更改时触发。

on_click​

当此下拉菜单被点击时触发。

on_focus​

当控件获得焦点时触发。

Option属性​

表示下拉菜单中的一个项目。必须指定key或text，否则将引发AssertionError。

alignment​

定义此选项在其容器中的对齐方式。

值是Alignment类型，默认为alignment.center_left。

content​

要在此选项中显示的Control。如果未指定，则将text用作备用，否则text将被忽略。

key​

选项的键。如果未指定，则将text用作备用。

text​

选项的显示文本。如果未指定，则将key用作备用。

text_style​

定义text的样式。

值是TextStyle类型。

Option事件​

on_click​

当此选项被点击时触发。