跳到主要内容

下拉菜单

Material Design 按钮，用于从项目列表中选择。

下拉菜单允许用户从多个项目中选择。它显示当前选定的项目以及打开菜单以选择其他项目的箭头。

示例​

Live 示例

基本下拉菜单​

import flet as ft

def main(page: ft.Page):
    def button_clicked(e):
        t.value = f"Dropdown 值是： {dd.value}"
        page.update()

    t = ft.Text()
    b = ft.ElevatedButton(text="提交", on_click=button_clicked)
    dd = ft.Dropdown(
        width=100,
        options=[
            ft.dropdown.Option("红色"),
            ft.dropdown.Option("绿色"),
            ft.dropdown.Option("蓝色"),
        ],
    )
    page.add(dd, b, t)

ft.app(target=main)

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

import flet as ft

def main(page: ft.Page):
    page.add(
        ft.Dropdown(
            label="颜色",
            hint_text="选择您喜欢的颜色？",
            options=[
                ft.dropdown.Option("红色"),
                ft.dropdown.Option("绿色"),
                ft.dropdown.Option("蓝色"),
            ],
            autofocus=True,
        )
    )

ft.app(target=main)

带 on_change 事件的下拉菜单​

import flet as ft

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

    t = ft.Text()
    dd = ft.Dropdown(
        on_change=dropdown_changed,
        options=[
            ft.dropdown.Option("红色"),
            ft.dropdown.Option("绿色"),
            ft.dropdown.Option("蓝色"),
        ],
        width=200,
    )
    page.add(dd, t)

ft.app(target=main)

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

import flet as ft

def main(page: ft.Page):
    def find_option(option_name):
        for option in d.options:
            if option_name == option.key:
                return option
        return None

    def add_clicked(e):
        d.options.append(ft.dropdown.Option(option_textbox.value))
        d.value = option_textbox.value
        option_textbox.value = ""
        page.update()

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

    d = ft.Dropdown()
    option_textbox = ft.TextField(hint_text="输入项目名称")
    add = ft.ElevatedButton("添加", on_click=add_clicked)
    delete = ft.OutlinedButton("删除所选项目", on_click=delete_clicked)
    page.add(d, ft.Row(controls=[option_textbox, add, delete]))

ft.app(target=main)

alignment​

定义了提示或所选项目在下拉菜单中的位置。

对齐方式是 Alignment 类的实例。

autofocus​

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

bgcolor​

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

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

border​

输入字段周围的边框。值是 InputBorder 。默认是 OUTLINE。

border_color​

边框颜色。可以是 transparent 以隐藏边框。

border_radius​

边框半径是 BorderRadius 类的实例。

border_width​

边框的宽度，以虚拟像素为单位。默认为 1。设置为 0 以完全删除边框。

color​

文本颜色。

content_padding​

输入装饰容器的填充。

counter（计数器）​

一个作为字符计数放置在下方的Control。

如果为None或空字符串，并且未指定counter_text，那么在计数器的位置将不会出现任何内容。

counter_style​

用于 counter_text 的文本样式。

counter_text​

可选的文本，以显示在行下方作为字符计数。

如果为空字符串或 None，并且counter 未指定，则不会出现任何内容。

dense​

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

disabled_hint_content​

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

elevation​

下拉菜单的 elevation。默认为 8。

enable_feedback​

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

默认为 True。

error_style​

用于 error_text 的文本样式。

error_text​

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

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

filled​

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

如果 filled=None（默认），则隐式设置为 True，只要至少一个以下属性不为 null：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 的文本样式。

helper_text​

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

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

hint_content​

当value为None时显示的下拉列表值的占位符Control。

hint_style​

用于 hint_text 的文本样式。

hint_text​

建议输入字段接受的输入类型的文本。

在输入字段为空且未聚焦时显示在输入字段上方，或者在输入字段聚焦时显示在输入字段上方。

icon​

输入字段前以及装饰容器外部要显示的图标名称或Control。

带图标名称的示例：

icon=ft.icons.BOOKMARK

带Control的示例：

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

icon_content​

下拉按钮图标的控制项。默认为Icon(icons.ARROW_DROP_DOWN)。

在 v0.25.0 中已弃用，并将在 v0.28.0 中删除。请改用icon。

icon_enabled_color​

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

在 v0.25.0 中已弃用，并将在 v0.28.0 中删除。请改用select_icon_enabled_color。

icon_disabled_color​

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

在 v0.25.0 中已弃用，并将在 v0.28.0 中删除。请改用select_icon_enabled_color。

icon_size​

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

默认为24.0。

在 v0.25.0 中已弃用，并将在 v0.28.0 中删除。请改用icon。

item_height​

下拉菜单中项目的高度。

label​

输入字段的可选标签。

当输入字段为空且未聚焦时，标签将显示在输入字段上方。 当输入字段聚焦或非空时，标签将移动到输入字段上方，垂直相邻或居中。

label_style​

用于 label 的文本样式。

max_menu_height​

下拉菜单的最大高度。

options​

一个 Option 控件列表，表示下拉菜单中的项目。

options_fill_horizontally​

下拉菜单的内部内容是否水平填充其父容器。默认情况下，此按钮的内部宽度是其内容的最小尺寸。

如果为True，内部宽度将扩展以填充其周围的容器。

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

padding​

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

prefix​

输入字段前的可选控件。

这可以用于添加一些填充到文本中，例如使用 prefix_text 指定的文本，或者添加一个自定义控件在输入字段前面。控件的基线将与输入字段的基线对齐。

只能指定一个 prefix 或 prefix_text。

prefix 将出现在 prefix_icon 之后，如果同时指定了这两个属性。

prefix_icon​

在 prefix 或 prefix_text 之前、在装饰容器内文本字段的可编辑部分之前显示的图标。

prefix_style​

用于 prefix_text 的 TextStyle。

prefix_text​

可选的文本 prefix，用于在输入内容之前显示。

select_icon​

下拉菜单选择按钮图标的图标名称或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。

alignment​

定义下拉菜单中hint或所选项目在其中的位置方式。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​

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

disabled_hint_content​

当下拉菜单的值为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​

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

hint_style​

用于hint_text的TextStyle。

hint_text​

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

icon​

输入字段之前以及装饰容器外部显示的图标名称或Control。

带有图标名称的示例：

icon=ft.icons.BOOKMARK

带有Control的示例：

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

icon_content​

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

在 v0.25.0 中已弃用，并将在 v0.28.0 中删除。请改用icon。

icon_enabled_color​

如果此按钮处于启用状态，icon_content的任何Icon子级的颜色。

在 v0.25.0 中已弃用，并将在 v0.28.0 中删除。请改用select_icon_enabled_color。

icon_disabled_color​

如果此按钮处于禁用状态，icon_content的任何Icon子级的颜色。

在 v0.25.0 中已弃用，并将在 v0.28.0 中删除。请改用select_icon_enabled_color。

icon_size​

包裹icon_content的图标按钮的大小。默认为24.0。

在 v0.25.0 中已弃用，并将在 v0.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​

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

select_icon​

下拉菜单选择按钮图标的图标名称或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​

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

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​

当此选项被点击时触发。