跳到主要内容

编辑框 TextField

材料设计的文本字段。

文本字段允许用户使用硬件键盘或屏幕键盘输入文本。

示例​

实时示例

基本的文本字段​

import flet as ft

def main(page: ft.Page):
    def button_clicked(e):
        t.value = f"文本框的值为：'{tb1.value}', '{tb2.value}', '{tb3.value}', '{tb4.value}', '{tb5.value}'。"
        page.update()

    t = ft.Text()
    tb1 = ft.TextField(label="标准")
    tb2 = ft.TextField(label="禁用", disabled=True, value="名字")
    tb3 = ft.TextField(label="只读", read_only=True, value="姓氏")
    tb4 = ft.TextField(label="带占位符", hint_text="请输入文本")
    tb5 = ft.TextField(label="带图标", icon=ft.icons.EMOJI_EMOTIONS)
    b = ft.ElevatedButton(text="提交", on_click=button_clicked)
    page.add(tb1, tb2, tb3, tb4, tb5, b, t)

ft.app(target=main)

带有on_change事件的文本字段​

import flet as ft

def main(page: ft.Page):
    def textbox_changed(e):
        t.value = e.control.value
        page.update()

    t = ft.Text()
    tb = ft.TextField(
        label="带有'change'事件的文本框：",
        on_change=textbox_changed,
    )

    page.add(tb, t)

ft.app(target=main)

带有显示按钮的密码字段​

import flet as ft

def main(page: ft.Page):
    page.add(
        ft.TextField(
            label="带有显示按钮的密码字段", password=True, can_reveal_password=True
        )
    )

ft.app(target=main)

多行文本字段​

import flet as ft

def main(page: ft.Page):
    page.add(
        ft.TextField(label="标准", multiline=True),
        ft.TextField(
            label="禁用",
            multiline=True,
            disabled=True,
            value="第一行\n第二行\n第三行\n第四行\n第五行",
        ),
        ft.TextField(
            label="自动调整高度，带有最大行数",
            multiline=True,
            min_lines=1,
            max_lines=3,
        ),
    )

ft.app(target=main)

有下划线和无边框的文本字段​

import flet as ft

def main(page: ft.Page):
    page.add(
        ft.TextField(label="下划线", border="underline", hint_text="在此输入文本"),
        ft.TextField(
            label="填充的下划线",
            border=ft.InputBorder.UNDERLINE,
            filled=True,
            hint_text="在此输入文本",
        ),
        ft.TextField(label="无边框", border="none", hint_text="在此输入文本"),
        ft.TextField(
            label="填充的无边框",
            border=ft.InputBorder.NONE,
            filled=True,
            hint_text="在此输入文本",
        ),
    )

ft.app(target=main)

带有前缀和后缀的文本框​

import flet as ft

def main(page: ft.Page):
    page.add(
        ft.TextField(label="带有前缀", prefix_text="https://"),
        ft.TextField(label="带有后缀", suffix_text=".com"),
        ft.TextField(
            label="带有前缀和后缀", prefix_text="https://", suffix_text=".com"
        ),
        ft.TextField(
            label="我最喜欢的颜色",
            icon=ft.icons.FORMAT_SIZE,
            hint_text="输入你最喜欢的颜色",
            helper_text="你只能输入一个颜色",
            counter_text="已输入0个字符",
            prefix_icon=ft.icons.COLOR_LENS,
            suffix_text="...是你的颜色",
        ),
    )

ft.app(target=main)

属性​

autocorrect​

是否启用自动纠正。默认为 True。

autofocus​

如果设置为 True，则该控件将作为初始焦点选中。如果页面上有多个设置了 autofocus 的控件，则会选择首先添加到页面的控件来获得焦点。

bgcolor​

文本框的背景颜色。

border​

输入框周围的边框 - InputBorder 枚举，可选值为：OUTLINE（默认值）、UNDERLINE、NONE。

border_color​

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

border_radius​

有关边框半径的更多信息，请参阅 Container.border_radius 属性文档。

border_width​

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

can_reveal_password​

显示一个切换图标按钮，允许显示输入的密码。

capitalization​

启用输入文本的自动大小写更正。

属性值为 TextCapitalization 枚举，具有以下值：

  • NONE（默认值）- 不更改输入的文本。
  • CHARACTERS - 将每个输入的字符大写。
  • WORDS - 将每个单词的首字母大写。
  • SENTENCES - 将每个句子的首字母大写。

color​

文本的颜色。

content_padding​

输入装饰容器的内边距。

有关内边距和可能的值，请参阅 Container.padding。

counter_style​

用于 counter_text 的样式。

counter_text​

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

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

cursor_color​

文本框光标的颜色。

cursor_height​

设置光标高度。

cursor_radius​

设置光标半径。

cursor_width​

设置光标宽度。

dense​

文本框是否属于紧凑表单（即使用较少的垂直空间）。

enable_suggestions​

是否显示输入建议。

该标志仅影响 Android。在 iOS 上，建议与 autocorrect 直接关联，因此只有在 autocorrect 为 True 时才会显示建议。在 Android 上，自动更正和建议是分别控制的。默认为 True。

error_style​

用于 error_text 的样式。

error_text​

显示在输入框下方的文本。

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

filled​

如果为 True，则装饰容器将填充为主题的填充颜色。

focused_bgcolor​

文本框在聚焦状态下的背景颜色。

focused_border_color​

聚焦状态下的边框颜色。

focused_border_width​

聚焦状态下的边框宽度。

focused_color​

文本框聚焦时的文本颜色。

helper_style​

用于 helper_text 的样式。

helper_text​

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

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

hint_style​

用于hint_text的样式。

hint_text​

提示输入字段接受的输入类型。

当输入字段为空且未聚焦时，提示文本显示在输入字段的顶部（即在可以输入文本的位置上方）。当输入字段获得焦点（或字段非空）时，提示文本移到上方，垂直相邻于输入字段或居中于输入字段。

icon​

在输入字段之前和装饰容器之外显示的图标名称。

input_filter​

在TextField中提供实时过滤/验证。它通过将匹配（或不匹配）特定模式（regex_string）的字符替换为给定的replacement_string来阻止插入字符。 当此参数更改时，新的过滤器将在下次用户插入或删除文本时才应用。 请注意，与on_change回调类似，当以编程方式更改文本时，输入过滤器不会应用。

input_filter是InputFilter类的一个实例，它有3个参数：

  • regex_string：过滤器的正则表达式模式
  • allow：一个布尔值，指示是否允许或拒绝/阻止匹配的模式，默认为True
  • replacement_string：用于替换被禁止/拒绝的模式的字符串，默认为空字符串。

同样提供以下辅助类：

  • NumbersOnlyInputFilter()：仅允许数字
  • TextOnlyInputFilter()：仅允许文本字符

使用示例：

ft.TextField(
    label="Only numbers are allowed :)",
    input_filter=ft.InputFilter(allow=True, regex_string=r"[0-9]", replacement_string=""),
    # input_filter=ft.NumbersOnlyInputFilter()
)

keyboard_type​

用于编辑文本的键盘类型。属性值为KeyboardType枚举，具有以下值：

  • TEXT（默认）
  • MULTILINE
  • NUMBER
  • PHONE
  • DATETIME
  • EMAIL
  • URL
  • VISIBLE_PASSWORD
  • NAME
  • STREET_ADDRESS
  • NONE

label​

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

当输入字段为空且未聚焦时，标签显示在输入字段的顶部（即在屏幕上可以输入文本的位置上方）。当输入字段获得焦点（或字段非空）时，标签移到上方，垂直相邻于输入字段或居中于输入字段。

label_style​

用于label的样式。

max_length​

限制可以输入到TextField中的最大字符数。

max_lines​

一次显示的最大行数，如果需要则换行。

这会影响字段本身的高度，不限制可以输入到字段中的行数。

如果这是1（默认值），文本不会换行，而是水平滚动。

min_lines​

内容跨越较少行时要占用的最小行数。

这会影响字段本身的高度，不限制可以输入到字段中的行数。

默认值为1。

multiline​

如果TextField可以包含多行文本，则为True。

password​

是否隐藏正在编辑的文本。默认为False。

prefix​

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

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

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

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

prefix_icon​

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

prefix_style​

用于prefix_text的样式。

prefix_text​

在输入之前的可选文本prefix。

read_only​

文本是否可以更改。

当设置为True时，文本无法通过任何快捷方式或键盘操作修改。文本仍然可选。

默认为False。

selection_color​

TextField选择的颜色。

shift_enter​

将multiline TextField中的Enter按钮的行为更改为类似于聊天，即可以使用Shift+Enter添加新行，只按Enter键会触发on_submit事件。

smart_dashes_type​

是否允许平台自动格式化破折号。

此标志仅影响iOS 11及更高版本。例如，两个连续的连字符将自动替换为一个短划线，三个连字符将变为一个长划线。默认为True。

smart_quotes_type​

是否允许平台自动格式化引号。

此标志仅影响iOS。例如，标准垂直双引号字符将自动替换为左引号或右引号，具体取决于其在单词中的位置。默认为True。

suffix​

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

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

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

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

suffix_icon​

在可编辑部分的文本字段之后和suffix或suffix_text之后，在装饰容器内显示的图标。

suffix_style​

用于suffix_text的样式。

suffix_text​

在输入之后的可选文本suffix。

text_align​

文本在水平方向上的对齐方式。

属性值为TextAlign枚举，具有以下值：

  • LEFT（默认）
  • RIGHT
  • CENTER
  • JUSTIFY
  • START
  • END

text_size​

虚拟像素中的文本大小。

text_style​

正在编辑的文本的样式。

value​

TextField的当前值。

方法​

focus()​

将焦点移到TextField。

事件​

on_blur​

当控件失去焦点时触发。

on_change​

当TextField的输入发生更改时触发。

on_focus​

当控件获得焦点时触发。

on_submit​

当用户在焦点在TextField上按下ENTER键时触发。