TextField 继承自：FormFieldControl, AdaptiveControl, LayoutControl, Control, BaseControl

TextField 让用户输入文本，可以使用硬件键盘或屏幕键盘。

示例：

ft.TextField(label="Name", hint_text="Jane Doe")

示例

import flet as ft


def main(page: ft.Page):
    def handle_button_click(e: ft.Event[ft.Button]):
        message.value = (
            f"Textboxes values are:  '{tb1.value}', '{tb2.value}', "
            f"'{tb3.value}', '{tb4.value}', '{tb5.value}'."
        )

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    tb1 := ft.TextField(label="Standard"),
                    tb2 := ft.TextField(
                        label="Disabled",
                        disabled=True,
                        value="First name",
                    ),
                    tb3 := ft.TextField(
                        label="Read-only",
                        read_only=True,
                        value="Last name",
                    ),
                    tb4 := ft.TextField(
                        label="With placeholder",
                        hint_text="Please enter text here",
                    ),
                    tb5 := ft.TextField(
                        label="With an icon",
                        icon=ft.Icons.EMOJI_EMOTIONS,
                    ),
                    ft.Button(content="Submit", on_click=handle_button_click),
                    message := ft.Text(),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    def handle_field_change(e: ft.Event[ft.TextField]):
        message.value = e.control.value

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.TextField(
                        key="handling_change_textfield",
                        label="Textbox with 'change' event:",
                        on_change=handle_field_change,
                    ),
                    message := ft.Text(),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    page.title = "Text selection"

    def handle_selection_change(e: ft.TextSelectionChangeEvent[ft.TextField]):
        selection.value = (
            f"Selection: '{e.selected_text}'" if e.selected_text else "No selection."
        )
        selection_details.value = f"start={e.selection.start}, end={e.selection.end}"
        caret.value = f"Caret position: {e.selection.end}"

    async def select_characters(e: ft.Event[ft.Button]):
        await field.focus()
        field.selection = ft.TextSelection(
            base_offset=0, extent_offset=len(field.value)
        )

    async def move_caret(e: ft.Event[ft.Button]):
        await field.focus()
        field.selection = ft.TextSelection(base_offset=0, extent_offset=0)

    page.add(
        ft.SafeArea(
            content=ft.Column(
                spacing=10,
                controls=[
                    field := ft.TextField(
                        value=(
                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
                        ),
                        multiline=True,
                        min_lines=3,
                        autofocus=True,
                        on_selection_change=handle_selection_change,
                    ),
                    selection := ft.Text("Select some text from the field."),
                    selection_details := ft.Text(),
                    caret := ft.Text("Caret position: -"),
                    ft.Button(
                        content="Select all text",
                        on_click=select_characters,
                    ),
                    ft.Button(
                        content="Move caret to start",
                        on_click=move_caret,
                    ),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    page.add(
        ft.SafeArea(
            content=ft.TextField(
                key="password_textfield",
                label="Password with reveal button",
                password=True,
                can_reveal_password=True,
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.TextField(
                        key="multiline_standard",
                        label="Standard",
                        multiline=True,
                    ),
                    ft.TextField(
                        label="Disabled",
                        multiline=True,
                        disabled=True,
                        value="line1\nline2\nline3\nline4\nline5",
                    ),
                    ft.TextField(
                        key="multiline_auto_height",
                        label="Auto adjusted height with max lines",
                        multiline=True,
                        min_lines=1,
                        max_lines=3,
                    ),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.TextField(
                        key="underlined_field",
                        label="Underlined",
                        border=ft.UnderlineInputBorder(),
                        hint_text="Enter text here",
                    ),
                    ft.TextField(
                        key="underlined_filled_field",
                        label="Underlined filled",
                        border=ft.UnderlineInputBorder(),
                        filled=True,
                        hint_text="Enter text here",
                    ),
                    ft.TextField(
                        key="borderless_field",
                        label="Borderless",
                        border=ft.NoInputBorder(),
                        hint_text="Enter text here",
                    ),
                    ft.TextField(
                        key="borderless_filled_field",
                        label="Borderless filled",
                        border=ft.NoInputBorder(),
                        filled=True,
                        hint_text="Enter text here",
                    ),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    def handle_button_click(e: ft.Event[ft.Button]):
        message.value = (
            "Textboxes values are: "
            f"'{prefix_field.value}', "
            f"'{suffix_field.value}', "
            f"'{prefix_suffix_field.value}', "
            f"'{color_field.value}'."
        )

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    prefix_field := ft.TextField(
                        key="prefix_field",
                        label="With prefix",
                        prefix="https://",
                    ),
                    suffix_field := ft.TextField(
                        key="suffix_field",
                        label="With suffix",
                        suffix=".com",
                    ),
                    prefix_suffix_field := ft.TextField(
                        key="prefix_suffix_field",
                        label="With prefix and suffix",
                        prefix="https://",
                        suffix=".com",
                        enable_interactive_selection=True,
                    ),
                    color_field := ft.TextField(
                        key="color_field",
                        label="My favorite color",
                        icon=ft.Icons.FORMAT_SIZE,
                        hint_text="Type your favorite color",
                        helper="You can type only one color",
                        counter="{value_length}/{max_length} chars used",
                        prefix_icon=ft.Icons.COLOR_LENS,
                        suffix="...is your color",
                        max_length=20,
                    ),
                    ft.Button(
                        key="submit_button",
                        content="Submit",
                        on_click=handle_button_click,
                    ),
                    message := ft.Text(),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


async def main(page: ft.Page):
    page.padding = 50

    tf = ft.TextField(
        key="styled_textfield",
        text_size=30,
        cursor_color=ft.Colors.RED,
        selection_color=ft.Colors.YELLOW,
        color=ft.Colors.PINK,
        bgcolor=ft.Colors.BLACK_26,
        filled=True,
        focused_color=ft.Colors.GREEN,
        focused_bgcolor=ft.Colors.CYAN_200,
        border={
            ft.ControlState.DEFAULT: ft.OutlineInputBorder(
                border_radius=30,
                side=ft.BorderSide(color=ft.Colors.GREEN_800),
            ),
            ft.ControlState.FOCUSED: ft.OutlineInputBorder(
                border_radius=30,
                side=ft.BorderSide(width=2, color=ft.Colors.GREEN_ACCENT_400),
            ),
        },
        max_length=20,
        capitalization=ft.TextCapitalization.CHARACTERS,
    )

    page.add(
        ft.SafeArea(
            content=tf,
        )
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    page.theme_mode = ft.ThemeMode.LIGHT

    def handle_field_change(e: ft.Event[ft.TextField]):
        message.value = e.control.value

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.TextField(
                        key="label_hint_helper_counter_textfield",
                        on_change=handle_field_change,
                        text_style=ft.TextStyle(
                            size=15,
                            italic=True,
                            color=ft.Colors.DEEP_ORANGE_600,
                            bgcolor=ft.Colors.LIME_ACCENT_200,
                        ),
                        label="Label",
                        label_style=ft.TextStyle(
                            size=17,
                            weight=ft.FontWeight.BOLD,
                            italic=True,
                            color=ft.Colors.BLUE,
                            bgcolor=ft.Colors.RED_700,
                        ),
                        hint_text="Hint",
                        hint_style=ft.TextStyle(
                            size=15,
                            weight=ft.FontWeight.BOLD,
                            italic=True,
                            color=ft.Colors.PINK_ACCENT,
                            bgcolor=ft.Colors.BROWN_400,
                        ),
                        helper="Helper",
                        helper_style=ft.TextStyle(
                            size=14,
                            weight=ft.FontWeight.BOLD,
                            color=ft.Colors.DEEP_PURPLE,
                            bgcolor=ft.Colors.BLUE_50,
                        ),
                        counter="Counter",
                        counter_style=ft.TextStyle(
                            size=14,
                            italic=True,
                            color=ft.Colors.YELLOW,
                            bgcolor=ft.Colors.GREEN_500,
                        ),
                    ),
                    message := ft.Text(),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

属性

名称	类型	默认值	说明
value	str	''	此 TextField 的当前值。
selection	Optional[TextSelection]	None	表示字段中当前的文本选区或光标位置。 当用户选择文本时，此属性会更新以反映所选范围。如果未选中任何文本，则它包含一个空范围，表示光标位置。 设置此属性会以可视化方式将字段的选区更新为给定值，因此会触发 on_selection_change 事件。为确保选区可见且事件被触发，文本字段必须获得焦点。在设置此属性之前先对字段调用 focus。
keyboard_type	KeyboardType	KeyboardType.TEXT	用于编辑文本的键盘类型。
multiline	bool	False	此字段是否可以包含多行文本。
min_lines	Annotated[Optional[int], V.gt(0), V.le_field('max_lines')]	None	当内容行数少于该值时至少占用的行数。 这会影响字段自身的高度，但不限制可输入字段的行数。 默认为 1。 抛出异常： ValueError：如果它不严格大于 0。 ValueError：当两者都设置时，如果它不小于或等于 max_lines。
max_lines	Annotated[Optional[int], V.gt(0), V.ge_field('min_lines')]	None	一次最多显示的行数，必要时换行。 这会影响字段自身的高度，但不限制可输入字段的行数。 如果为 1（默认值），文本不会换行，而是水平滚动。 抛出异常： ValueError：如果它不严格大于 0。 ValueError：当两者都设置时，如果它不大于或等于 min_lines。
max_length	Annotated[Optional[int], V.or_(V.gt(0), V.eq(-1), message='max_length must be either strictly greater than 0 or equal to -1')]	None	限制可输入 TextField 的最大字符数。 抛出异常： ValueError：如果它不严格大于 0 或不等于 -1。
password	bool	False	是否隐藏正在编辑的文本。
can_reveal_password	bool	False	显示一个切换图标按钮，用于显示已输入的密码。当 password 和 can_reveal_password 都为 True 时显示。 该图标显示在与 suffix 相同的位置；如果同时提供了 can_reveal_password/password 和 suffix，则不会显示 suffix。
read_only	bool	False	文本是否可更改。 当设为 True 时，无法通过任何快捷键或键盘操作修改文本。文本仍可选中。
shift_enter	bool	False	将 multiline 文本字段中 Enter 按钮的行为改为类似聊天，即可以用 Shift+Enter 添加新行，而仅按 Enter 会触发 on_submit 事件。
ignore_up_down_keys	bool	False	此字段获得焦点时是否拦截上箭头和下箭头键。 当设为 True 时，按这些键不会分别将光标移动到文本的开头或结尾。
text_align	Optional[TextAlign]	None	文本应如何水平对齐。 默认为 LEFT。
autofocus	bool	False	若设为 True，则此控件会被选为初始焦点。如果页面上有多个设置了 autofocus 的控件，则最先添加到页面的控件会获得焦点。
capitalization	Optional[TextCapitalization]	None	启用输入文本的自动即时大小写转换。 默认为 NONE。
autocorrect	bool	True	是否启用自动更正。
enable_suggestions	bool	True	是否在用户输入时显示输入建议。 此标志仅影响 Android。在 iOS 上，建议直接与 autocorrect 绑定，因此只有在 autocorrect 为 True 时才显示建议。在 Android 上，自动更正和建议是分开控制的。
smart_dashes_type	bool	True	是否允许平台自动格式化破折号。 此标志仅影响 iOS 11 及以上版本。举例来说，两个连续的连字符会被自动替换为一个短破折号（en dash），三个连续的连字符会变成一个长破折号（em dash）。
smart_quotes_type	bool	True	是否允许平台自动格式化引号。 此标志仅影响 iOS。举例来说，标准的垂直双引号字符会根据其在单词中的位置被自动替换为左双引号或右双引号。
show_cursor	bool	True	是否显示字段的光标。
cursor_color	Optional[ColorValue]	None	TextField 光标的颜色。
cursor_error_color	Optional[ColorValue]	None	字段显示错误时文本光标的颜色。 如果未设置，则光标颜色回退到错误文本样式，再回退到主题的错误颜色。
cursor_width	Number	2.0	设置光标宽度。
cursor_height	Optional[Number]	None	设置光标高度。
cursor_radius	Optional[Number]	None	设置光标圆角半径。
selection_color	Optional[ColorValue]	None	TextField 选区的颜色。
input_filter	Optional[InputFilter]	None	提供逐字符的过滤/校验。 与 on_change 回调类似，当字段内容被以编程方式更改时不会应用输入过滤器。
obscuring_character	str	'•'	当 password 为 True 时用于遮蔽文本的单个字符。
enable_interactive_selection	bool	True	是否启用交互式文本选择。 启用后，用户可以移动光标、选择文本并使用剪切/复制/粘贴菜单。禁用后，无法交互式调整选区，剪切/复制/粘贴的编辑快捷键也会被抑制。
enable_ime_personalized_learning	bool	True	是否允许输入法从用户的输入中学习。 此设置仅影响 Android，控制个性化数据，例如输入历史和用户词典条目。
can_request_focus	bool	True	此字段是否可以请求焦点。 如果设为 False，则点击字段或显示其上下文菜单时字段不会请求焦点，也无法通过键盘焦点遍历到达。
ignore_pointers	bool	False	此字段是否忽略指针事件。
enable_stylus_handwriting	bool	True	此字段是否支持手写笔手写输入。 在支持的设备上，用户可以直接用手写笔在字段上书写，而无需通过键盘输入。
animate_cursor_opacity	Optional[bool]	None	文本光标在每次闪烁时是否在透明与不透明之间动画。 如果未设置，则默认遵循 Flet 使用的平台行为。
always_call_on_tap	bool	False	是否每次点击都调用 on_click。 默认情况下，只有一连串点击中的第一次点击会触发 on_click。启用后，连续的点击也会触发。
scroll_padding	PaddingValue	20	当外围可滚动控件将此字段滚动到可见区域时，围绕字段保留的内边距。 当字段获得焦点且被部分隐藏（例如被屏幕键盘遮挡）时，此内边距有助于在滚动后保持字段与外围可滚动控件边缘之间的间距。
clip_behavior	ClipBehavior	ClipBehavior.HARD_EDGE	字段内容应如何裁剪。 可用的裁剪模式见 ClipBehavior。
keyboard_brightness	Optional[Brightness]	None	屏幕键盘使用的亮度。 此设置仅在 iOS 上生效。
mouse_cursor	Optional[MouseCursor]	None	悬停在字段上时显示的鼠标指针。 如果未设置，则使用标准的文本光标。
strut_style	Optional[StrutStyle]	None	用于垂直文本布局的 StrutStyle。 Strut 样式会建立可预期的最小行高，当输入的文本在字体度量或文字系统上可能不一致时非常有用。
autofill_hints	Optional[Union[AutofillHint, list[AutofillHint]]]	None	帮助自动填充服务识别此文本输入的类型。 更多信息见此处。
text_size	Optional[Number]	None	文本大小（虚拟像素）。
text_style	Optional[TextStyle]	None	用于正在编辑文本的 TextStyle。
text_vertical_align	Optional[Union[VerticalAlignment, Number]]	None	定义文本应如何垂直对齐。 值可以是范围从 -1.0（最顶部位置）到 1.0（最底部位置）的数字，也可以是 VerticalAlignment 类型。默认为 VerticalAlignment.CENTER。
label	Optional[StrOrControl]	None	描述输入字段的可选文本。 当输入字段为空且未获得焦点时，标签显示在输入字段之上（即与可输入文本的屏幕位置相同）。当输入字段获得焦点（或字段非空）时，标签上移，要么垂直紧邻输入字段，要么移到输入字段的中央。
label_style	Optional[TextStyle]	None	用于 label 的文本样式。
icon	Optional[IconDataOrControl]	None	显示在输入字段之前、且位于装饰容器之外的图标。
border	Optional[ControlStateValue[InputBorder]]	None	围绕装饰后输入区域绘制的边框。 接受单个 InputBorder 或一个将 ControlState 映射到 InputBorder 的字典。支持的状态键有 DEFAULT、FOCUSED、ERROR 和 DISABLED。 单个边框为所有状态定义形状。如果未设置其 side，Material 主题会按状态解析边框颜色和宽度（例如，聚焦边框使用主题的主色）；显式的 side 会应用于启用状态，而其他状态仍由主题解析。 在字典形式中，DEFAULT 条目的行为与单一边框形式相同；每个没有显式 side 的状态条目会回退到 DEFAULT 条目的 side（如果已设置）。
border_radius	Annotated[Optional[BorderRadiusValue], V.deprecated('border', version='1.0.0', delete_version='1.3.0', reason='Use border=OutlineInputBorder(border_radius=...) instead.', docs_reason='Use :attr:border with an :class:~flet.OutlineInputBorder instead.')]	None	将轮廓边框的角变圆。
border_width	Annotated[Optional[Number], V.deprecated('border', version='1.0.0', delete_version='1.3.0', reason='Use border=OutlineInputBorder(side=BorderSide(width=...)) instead.', docs_reason='Use :attr:border with a :class:~flet.BorderSide instead.')]	None	边框的宽度（虚拟像素）。
border_color	Annotated[Optional[ColorValue], V.deprecated('border', version='1.0.0', delete_version='1.3.0', reason='Use border=OutlineInputBorder(side=BorderSide(color=...)) instead.', docs_reason='Use :attr:border with a :class:~flet.BorderSide instead.')]	None	边框颜色。
focused_border_width	Annotated[Optional[Number], V.deprecated('border', version='1.0.0', delete_version='1.3.0', reason='Use border={ControlState.FOCUSED: OutlineInputBorder(...)} instead.', docs_reason='Use :attr:border with an :attr:flet.ControlState.FOCUSED entry instead.')]	None	聚焦状态下的边框宽度。
focused_border_color	Annotated[Optional[ColorValue], V.deprecated('border', version='1.0.0', delete_version='1.3.0', reason='Use border={ControlState.FOCUSED: OutlineInputBorder(...)} instead.', docs_reason='Use :attr:border with an :attr:flet.ControlState.FOCUSED entry instead.')]	None	聚焦状态下的边框颜色。
color	Optional[ColorValue]	None	文本颜色。
bgcolor	Optional[ColorValue]	None	TextField 背景色。 注意： 如果 filled 为 False，则不可见。
focused_color	Optional[ColorValue]	None	获得焦点时文本的颜色。
focused_bgcolor	Optional[ColorValue]	None	聚焦状态下的背景色。 注意： 如果 filled 为 False，则不可见。
content_padding	Optional[PaddingValue]	None	输入装饰容器的内边距。
dense	Optional[bool]	None	此控件是否属于紧凑表单（即使用更少的垂直空间）。
filled	Optional[bool]	None	装饰容器的背景是否用 fill_color 填充。 如果 filled=None（默认值），则当以下至少一项不为 None 时，它会隐式设为 True：fill_color、focused_bgcolor、hover_color 和 bgcolor。
fill_color	Optional[ColorValue]	None	TextField 的背景色。 注意： 如果 filled 为 False，则不可见。
focus_color	Optional[ColorValue]	None	控件获得输入焦点时装饰容器的填充色。 注意： 文本字段通常通过改变聚焦边框而不是填充色来指示焦点。在 Flet 中，当需要明确的聚焦状态样式时，优先使用 focused_bgcolor 和聚焦的 border 状态（例如 border={ft.ControlState.FOCUSED: ft.OutlineInputBorder(...)}）。
align_label_with_hint	Optional[bool]	None	浮动标签是否应与 hint_text 对齐。 对于多行文本输入，通常将其设为 True，使标签与提示的顶部对齐，而不是垂直居中。
hover_color	Optional[ColorValue]	None	TextField 被悬停时的背景色。 注意： 如果 filled 为 False，则不可见。
hint_text	Optional[str]	None	提示字段接受何种输入的文本。 当输入为空且满足以下之一时显示在输入之上：(a) label 为 None，或 (b) 输入已获得焦点。
hint_style	Optional[TextStyle]	None	用于 hint_text 的文本样式。
hint_fade_duration	Optional[DurationValue]	None	hint_text 淡入和淡出动画的时长。
hint_max_lines	Optional[int]	None	hint_text 可占用的最大行数。
helper	Optional[StrOrControl]	None	提供关于输入值上下文的文本，例如该值将如何使用。 如果非 null，该文本显示在输入装饰器下方，与 error 相同的位置。如果指定了非 null 的 error 值，则不显示辅助文本。
helper_style	Optional[TextStyle]	None	用于 helper 的文本样式。
helper_max_lines	Optional[int]	None	helper 可占用的最大行数。
counter	Optional[StrOrControl]	None	放在该行下方作为字符计数的 Control。 如果为 None 或空字符串，则计数器位置不会显示任何内容。
counter_style	Optional[TextStyle]	None	用于 counter 的文本样式。
error	Optional[StrOrControl]	None	显示在输入边框下方的文本。 如果非 null，边框颜色会动画变为红色，且不显示 helper。
error_style	Optional[TextStyle]	None	用于 error 的文本样式。
error_max_lines	Optional[int]	None	error 可占用的最大行数。 默认情况下，软换行会被省略号截断，而显式换行会被保留。设置此属性可为长错误文本启用换行。
prefix	Optional[StrOrControl]	None	放在输入之前同一行上的 Control。 如果同时指定了 prefix_icon，它显示在 prefix_icon 之后。 例如，可以用它为本来通过 prefix 指定的文本添加一些内边距，或在输入前面添加自定义控件。该控件的基线会与输入基线对齐。
prefix_icon	Optional[IconDataOrControl]	None	显示在文本字段可编辑部分之前、装饰容器之内的图标。 如果指定了 prefix 且可见，此图标会显示在其左侧。
prefix_icon_size_constraints	Optional[BoxConstraints]	None	prefix_icon 周围区域的大小约束。 可用于缩小或扩大默认图标框。默认情况下，最小宽度和高度为 48 像素，更紧的约束通常与紧凑装饰搭配使用。
prefix_style	Optional[TextStyle]	None	用于 prefix 的文本样式。
suffix	Optional[StrOrControl]	None	放在输入之后同一行上的 Control。 如果同时指定了 suffix_icon，它显示在 suffix_icon 之前。 例如，可以用它为本来通过 suffix 指定的文本添加一些内边距，或在输入后面添加自定义控件。该控件的基线会与输入基线对齐。
suffix_icon	Optional[IconDataOrControl]	None	显示在文本字段可编辑部分之后、且位于 suffix 之后、装饰容器之内的图标。
suffix_icon_size_constraints	Optional[BoxConstraints]	None	suffix_icon 周围区域的大小约束。 可用于缩小或扩大默认图标框。默认情况下，最小宽度和高度为 48 像素，更紧的约束通常与紧凑装饰搭配使用。
size_constraints	Optional[BoxConstraints]	None	定义输入装饰器的最小和最大尺寸。
collapsed	Optional[bool]	None	装饰是否应与输入字段尺寸相同。 折叠装饰会移除装饰器通常添加的额外内边距。 注意： 折叠装饰不支持 label、error、counter、icon、prefix 和 suffix。
fit_parent_size	bool	False	可编辑区域是否应扩展以填满其父级的高度。 对于支持扩展文本输入的控件（如 TextField），将此设为 True 会将可编辑区域扩展以填满父级，并清除行数约束。 注意： 启用时，min_lines 和 max_lines 必须实际上保持未设置。
suffix_style	Optional[TextStyle]	None	用于 suffix 的文本样式。
width	Optional[Number]	None	控件的强制宽度（以虚拟像素为单位）。
height	Optional[Number]	None	控件的强制高度（以虚拟像素为单位）。
left	Optional[Number]	None	子控件左边缘相对于 Stack 左侧的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。
top	Optional[Number]	None	子控件上边缘相对于 Stack 顶部的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。
right	Optional[Number]	None	子控件右边缘相对于 Stack 右侧的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。
bottom	Optional[Number]	None	子控件下边缘相对于 Stack 底部的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。
align	Optional[Alignment]	None	控件在其父级中的对齐方式。
margin	Optional[MarginValue]	None	设置控件的外边距。
rotate	Optional[RotateValue]	None	围绕控件中心旋转来变换此控件。 rotate 属性的值可以是以下类型之一： * number —— 顺时针旋转的弧度值。整圈 360° 为 math.pi * 2 弧度，90° 为 pi / 2，45° 为 pi / 4，以此类推。 * Rotate —— 允许同时指定旋转 angle 和 alignment，即旋转中心的位置。 示例： python ft.Image( src="https://picsum.photos/100/100", width=100, height=100, border_radius=5, rotate=Rotate(angle=0.25 * pi, alignment=ft.Alignment.CENTER_LEFT) )
scale	Optional[ScaleValue]	None	沿二维平面缩放此控件。默认缩放因子为 1.0，表示不缩放。 例如，将此属性设为 0.5 会让控件缩小一半，而设为 2.0 则会放大一倍。 通过将 Control.scale 属性设为 Scale 类的实例，可以为 x 和 y 轴指定不同的缩放倍数。可以指定 scale，或者指定 scale_x 和 scale_y，但不能同时指定全部。 示例： python ft.Image( src="https://picsum.photos/100/100", width=100, height=100, border_radius=5, scale=ft.Scale(scale_x=2, scale_y=0.5) )
offset	Optional[OffsetValue]	None	在绘制控件之前应用平移变换。 平移量表示为按控件尺寸缩放的 Offset。例如，Offset(x=0.25, y=0) 会使控件沿水平方向平移其宽度的四分之一。 示例 下面的示例把容器显示在 Stack 的 0, 0 左上角，因为变换对控件应用了 -1 * 100, -1 * 100（即 offset * control's size）的水平与垂直平移： python import flet as ft def main(page: ft.Page): page.add( ft.Stack( width=1000, height=1000, controls=[ ft.Container( bgcolor=ft.Colors.RED, width=100, height=100, left=100, top=100, offset=ft.Offset(-1, -1), ) ], ) ) ft.run(main)
flip	Optional[Flip]	None	水平方向和/或垂直方向翻转此控件。 设为 Flip 的实例即可沿 x 轴、y 轴或两者镜像翻转。
transform	Optional[Transform]	None	对此控件应用通用矩阵变换。 设为带 Matrix4 记录的 Transform 实例，用以描述任意的变换序列。
aspect_ratio	Optional[Number]	None	控件的宽高比，定义为 width 与 height 的比值。 注意： 在当前实现中，如果设置了 aspect_ratio，同一控件上的 width 和 height 将在最终渲染尺寸中被忽略。
animate_opacity	Optional[AnimationValue]	None	启用 opacity 属性的隐式动画。 更多信息见此处。
animate_size	Optional[AnimationValue]	None	启用此控件尺寸的隐式动画。 如果设置了 width 或 height，则这些维度的变化会以动画呈现。如果两者都未设置，则对控件自然尺寸的变化进行动画。 更多信息见此处。
animate_position	Optional[AnimationValue]	None	启用定位属性（left、right、top 和 bottom）的隐式动画。 更多信息见此处。
animate_align	Optional[AnimationValue]	None	启用 align 属性的隐式动画。 更多信息见此处。
animate_margin	Optional[AnimationValue]	None	启用 margin 属性的隐式动画。 更多信息见此处。
animate_rotation	Optional[AnimationValue]	None	启用 rotate 属性的隐式动画。 更多信息见此处。
animate_scale	Optional[AnimationValue]	None	启用 scale 属性的隐式动画。 更多信息见此处。
animate_offset	Optional[AnimationValue]	None	启用 offset 属性的隐式动画。 更多信息见此处。
size_change_interval	int	10	on_size_change 事件的采样间隔（毫秒）。 设为 0 时，每次变化都会立即调用 on_size_change。
expand	Annotated[Optional[Union[bool, int]], V.instance_of((bool, int))]	None	指定此控件是否／如何扩展以填满父布局中的可用空间。 更多信息见此处。 注意： 仅当此控件的直接父级是以下控件或其子类时才生效：Column、Row、View、Page。 抛出异常： ValueError：如果它不是 bool 或 int 类型。
expand_loose	bool	False	允许控件在主轴方向有可用空间时扩展，但不要求它填满所有可用空间。 更多信息见此处。 注意： 如果 expand_loose 为 True，则仅在以下条件满足时才生效： - expand 不为 None，且 - 此控件的直接父级是以下控件或其子类之一：Column、Row、View、Page。
col	ResponsiveNumber	12	如果此控件的父级是 ResponsiveRow，则此属性决定该控件在屏幕上跨越多少虚拟列。 可以是一个数字，也可以是一个按断点配置不同值的字典，例如 col={"sm": 6}。 值为 0 时会在该断点隐藏控件，因此它不会占用父级 ResponsiveRow 中的任何列。 此控件默认跨越 12 个虚拟列。 | 断点 | 尺寸 | |---|---| | xs | <576px | | sm | ≥576px | | md | ≥768px | | lg | ≥992px | | xl | ≥1200px | | xxl | ≥1400px |
opacity	Annotated[Number, V.between(0.0, 1.0)]	1.0	定义控件的透明度。 取值范围从 0.0（完全透明）到 1.0（完全不透明，无任何透明感）。 抛出异常： ValueError：如果它不在 0.0 到 1.0（含）之间。
tooltip	Optional[TooltipValue]	None	鼠标悬停在此控件上时显示的工具提示。
badge	Optional[BadgeValue]	None	显示在此控件顶部的徽章。
visible	bool	True	每个控件都有 visible 属性，默认为 True —— 控件会渲染在页面上。将 visible 设为 False 会彻底阻止控件（及其所有子控件，如果有）渲染到页面画布上。隐藏的控件无法通过键盘或鼠标获得焦点或选中，也不会触发任何事件。
disabled	bool	False	每个控件都有 disabled 属性，默认为 False —— 控件及其所有子控件都处于启用状态。 注意： 此属性的值会递归向下传播到所有子控件。 示例： 例如，如果你有一个包含多个输入控件的表单，可以通过禁用容器来一并禁用它们： python ft.Column( disabled = True, controls=[ ft.TextField(), ft.TextField() ] )
rtl	bool	False	控件的文本方向是否为从右到左（RTL）。
data	Any	skip_	任意类型的自定义数据。
key	Optional['KeyValue']	None	用于在更新之间保持控件标识稳定的键。
adaptive	Optional[bool]	None	启用平台特定渲染，或从父控件继承自适应能力。

只读属性

名称	类型	默认值	说明
parent	Optional['BaseControl']	—	此控件的直接祖先（父级）。 默认为 None，只有在此控件被挂载（加入页面树）后才有值。 Page 控件（页面树的根）是个例外 —— 它的 parent 始终为 None。
page	'Page'	—	此控件所属的页面。

事件

名称	类型	默认值	说明
on_change	Optional[ControlEventHandler['TextField']]	None	当 TextField 输入的文本发生变化时调用。
on_selection_change	Optional[EventHandler[TextSelectionChangeEvent['TextField']]]	None	当文本选区或光标位置发生变化时调用。 这可以由用户交互（选择文本或移动光标）触发，也可以由程序触发（通过 selection 属性）。
on_click	Optional[ControlEventHandler['TextField']]	None	当字段被点击时调用。 如果 always_call_on_tap 为 True，则连续的点击也会触发此事件。
on_submit	Optional[ControlEventHandler['TextField']]	None	当焦点位于 TextField 上时用户按下 ENTER 触发。
on_focus	Optional[ControlEventHandler['TextField']]	None	当此控件获得焦点时调用。
on_blur	Optional[ControlEventHandler['TextField']]	None	当此控件失去焦点时调用。
on_tap_outside	Optional[ControlEventHandler['TextField']]	None	当字段获得焦点时，在字段外部发生指针按下事件时调用。 可用于在用户点击字段外部时做出响应。 注意： 此回调仅作为通知，不包含指针事件详情。
on_size_change	Optional[EventHandler[LayoutSizeChangeEvent['LayoutControl']]]	None	当此控件的尺寸发生变化时调用。 size_change_interval 定义此事件的调用频率。
on_animation_end	Optional[ControlEventHandler['LayoutControl']]	None	动画完成时调用。 可用于串联多个动画。 事件处理器参数的 data 属性包含动画名称。 更多信息见此处。

方法

名称	类型	默认值	说明
before_update	—	—	—
focus	—	—	为此控件请求焦点。 示例： python async def main(page: ft.Page): page.add(ctf := ft.TextField()) await ctf.focus()
is_isolated	—	—	返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
init	—	—	在控件实例初始化之后、首次 build/update 循环之前调用。 重写此钩子以执行依赖已初始化字段的轻量级设置。不要在此处调用 update()。
build	—	—	在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。
before_event	—	—	在事件处理器执行之前拦截事件。 返回 False 可取消分发。返回 True 或 None 则继续正常的事件处理。
did_mount	—	—	在控件挂载到页面树之后调用。 重写此方法以启动需要已挂载页面的资源，例如订阅、定时器或服务监听器。
will_unmount	—	—	在控件从页面树移除之前调用。 重写此方法以释放 did_mount() 中创建的资源，例如订阅、定时器或外部句柄。
get_data_channel	—	—	解析为此 widget 在 Dart 侧分配的 [DataChannel]。模式： on_data_channel_open: Optional[ft.EventHandler[DataChannelOpenEvent]] = None def init(self): self.on_data_channel_open = self._on_open def _on_open(self, e): self._channel = self.get_data_channel(e.channel_id) 幂等 —— 底层的 Connection 会按 id 缓存 DataChannel，因此重复调用会返回同一实例。没有错误路径：该 id 始终来自框架触发的事件，所以当此方法运行时，通道在两端都已存在。
update	None	—	为此控件请求一次 UI 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。