跳到主要内容

页面 Page

Page（页面）是 View 控件的容器。

在新的用户会话开始时，会自动创建一个页面实例和根视图。

属性​

auto_scroll​

如果子项更新时滚动条应自动移动到末尾，则为 True。对于 scroll_to() 方法工作，必须为 False。

appbar​

要在页面顶部显示的 AppBar 控件。

要在页面顶部显示的 Banner 控件。

bgcolor​

页面的背景颜色。

颜色值可以是 #ARGB 格式的十六进制值（例如 #FFCC0000），也可以是 #RGB 格式的十六进制值（例如 #CC0000），或者是 flet.colors 模块中的命名颜色。

bottom_sheet​

要显示的 BottomSheet 控件。

client_ip​

🌎 仅适用于 Web。连接用户的 IP 地址。

client_user_agent​

🌎 仅适用于 Web。连接用户的浏览器详细信息。

controls​

要在页面上显示的控件列表。

例如，要向页面添加一个新控件：

page.controls.append(ft.Text("Hello!"))
page.update()

或者使用 page.add() 快捷方法获得相同的结果：

page.add(ft.Text("Hello!"))

要删除页面上最顶部的控件：

page.controls.pop()
page.update()

dark_theme​

将此属性设置为 theme.Theme 的实例，以自定义暗色主题。

debug​

如果 Flet 应用的 Flutter 客户端处于调试模式，则为 True。

design​

保留供将来使用。

dialog​

要显示的 AlertDialog 控件。

drawer​

要作为从页面起始边缘滑出的面板显示的 NavigationDrawer 控件。

end_drawer​

要作为从页面结束边缘滑出的面板显示的 NavigationDrawer 控件。

floating_action_button​

要在页面内容上方显示的 FloatingActionButton 控件。

floating_action_button_location​

定义 FloatingActionButton 的位置。

属性值是 FloatingActionButtonLocation 枚举，具有以下值（示意图在此）：

  • CENTER_DOCKED
  • CENTER_FLOAT
  • CENTER_TOP
  • END_CONTAINED
  • END_DOCKED
  • END_FLOAT（默认值）
  • END_TOP
  • MINI_CENTER_DOCKED
  • MINI_CENTER_FLOAT
  • MINI_CENTER_TOP
  • MINI_END_DOCKED
  • MINI_END_FLOAT
  • MINI_END_TOP
  • MINI_START_DOCKED
  • MINI_START_FLOAT
  • MINI_START_TOP
  • START_DOCKED
  • START_FLOAT

fonts​

允许导入自定义字体，并在 Text.font_family 中使用它们，或通过 theme.font_family 应用于整个应用程序。

以下字体格式可用于 Flet：

  • .ttc
  • .ttf
  • .otf

fonts 属性的值是一个字典，其中键是引用该字体的字体族名称，值是要导入的字体文件的 URL。

可以通过提供绝对 URL 从外部资源导入字体，或者通过提供相对 URL 和 assets_dir 从应用程序资产中导入字体。

在 flet.app() 调用中指定 assets_dir 来设置应用程序可用的资产的位置。assets_dir 可以是相对于您的 main.py 目录的路径，也可以是绝对路径。例如，考虑以下程序结构：

/assets
   /fonts
       /OpenSans-Regular.ttf
main.py

现在，以下程序从 GitHub 加载 "Kanit" 字体，并从资产中使用 "Open Sans"。"Kanit" 被设置为默认应用程序字体，"Open Sans" 用于特定的 Text 控件：

import flet as ft

def main(page: ft.Page):
    page.fonts = {
        "Kanit": "https://raw.githubusercontent.com/google/fonts/master/ofl/kanit/Kanit-Bold.ttf",
        "Open Sans": "/fonts/OpenSans-Regular.ttf"
    }

    page.theme = Theme(font_family="Kanit")

    page.add(
      ft.Text("This is rendered with Kanit font"),
      ft.Text("This is Open Sans font example", font_family="Open Sans")
    )

ft.app(target=main, assets_dir="assets")
备注

目前仅支持静态字体，即仅包含一种特定宽度/粗细/样式组合的字体，例如 "Open Sans Regular" 或 "Roboto Bold Italic"。

可变字体的支持仍在开发中。

但是，如果您需要在应用程序中使用可变字体，可以使用 fonttools 在特定权重上创建静态的 "实例"，然后使用这些实例：

fonttools varLib.mutator ./YourVariableFont-VF.ttf wght=140 wdth=85

要查看可用的字体特性（例如 wght 的可能选项），请使用 Wakamai Fondue 在线工具。

height​

Web 页面或包含 Flet 应用的本机操作系统窗口的内容区域的高度。此属性是只读的。通常在 page.on_resize 处理程序中使用。

horizontal_alignment​

子控件在水平方向上的对齐方式。

默认值为 CrossAxisAlignment.START，表示在页面的左侧。

属性值是 CrossAxisAlignment 枚举，具有以下值：

  • START（默认值）
  • CENTER
  • END
  • STRETCH
  • BASELINE

name​

页面名称，如在 ft.app() 调用中指定的。页面名称在 Flet 应用作为 Web 应用程序运行时设置。这是主机名后的一部分 URL。

要在页面底部显示的 NavigationBar 控件。

on_scroll_interval​

on_scroll 事件的节流时间间隔（以毫秒为单位）。默认值为 10。

overlay​

作为堆栈显示在主页面内容上方的 Control 列表。

padding​

页面内容与边缘之间的空间。默认值为每个边缘的10像素。要设置零填充：

page.padding = 0
page.update()

有关更多信息和可能的值，请参阅Container.padding。

platform​

应用程序运行的操作系统：

  • ios
  • android
  • macos
  • linux
  • windows

platform_brightness​

主机平台的当前亮度模式：ft.ThemeMode.LIGHT或ft.ThemeMode.DARK。

pubsub​

用于在应用程序会话之间传递消息的简单PubSub实现。

subscribe(handler)​

订阅当前应用程序会话以接收广播（无主题）消息。handler是一个带有单个message参数的函数或方法，例如：

def main(page: ft.Page):

    def on_broadcast_message(message):
        print(message)

    page.pubsub.subscribe(on_broadcast_message)

subscribe_topic(topic, handler)​

订阅当前应用程序会话以接收特定主题的消息。handler是一个带有两个参数topic和message的函数或方法，例如：

def main(page: ft.Page):

    def on_message(topic, message):
        print(topic, message)

    page.pubsub.subscribe_topic("general", on_message)

send_all(message)​

向所有订阅者广播消息。message可以是任何内容：一个简单的文字或一个类实例，例如：

@dataclass
class Message:
    user: str
    text: str

def main(page: ft.Page):

    def on_broadcast_message(message):
        page.add(ft.Text(f"{message.user}: {message.text}"))

    page.pubsub.subscribe(on_broadcast_message)

    def on_send_click(e):
        page.pubsub.send_all(Message("John", "Hello, all!"))

    page.add(ft.ElevatedButton(text="Send message", on_click=on_send_click))

send_all_on_topic(topic, message)​

向特定主题的所有订阅者发送消息。

send_others(message)​

将消息广播给除发送者以外的所有订阅者。

send_others_on_topic(topic, message)​

将消息发送给特定主题的所有订阅者，但不包括发送者。

unsubscribe()​

取消订阅当前应用程序会话的广播消息，例如：

@dataclass
class Message:
    user: str
    text: str

def main(page: ft.Page):

    def on_leave_click(e):
        page.pubsub.unsubscribe()

    page.add(ft.ElevatedButton(text="Leave chat", on_click=on_leave_click))

unsubscribe_topic(topic)​

取消订阅当前应用程序会话的特定主题。

unsubscribe_all()​

取消订阅当前应用程序会话的广播消息和所有主题，例如：

def main(page: ft.Page):
    def client_exited(e):
        page.pubsub.unsubscribe_all()

    page.on_close = client_exited

pwa​

如果应用程序作为渐进式Web应用程序（PWA）运行，则为True。只读。

query​

?之后的应用程序URL的一部分。该值是一个QueryString的实例，具有用于获取查询参数的辅助方法。

route​

获取或设置页面的导航路由。有关更多信息和示例，请参阅导航和路由部分。

rtl​

将文本方向设置为从右到左的True。默认值为False。

scroll​

启用页面的垂直滚动，以防止内容溢出。

属性值是一个可选的 ScrollMode 枚举，默认为 None。

支持的值:

  • None（默认值）- 行不可滚动，其内容可能溢出。
  • AUTO - 启用滚动，并且只在发生滚动时显示滚动条。
  • ADAPTIVE - 启用滚动，并且在 Web 或桌面上运行时始终显示滚动条。
  • ALWAYS - 启用滚动，并且始终显示滚动条。
  • HIDDEN - 启用滚动，但始终隐藏滚动条。

session​

用于会话数据的简单 KV 存储。

session_id​

用户会话的唯一 ID。此属性只读。

spacing​

控件之间的垂直间距。默认值为 10 个虚拟像素。只有当 alignment 设置为 start、end 或 center 时才会应用间距。

splash​

在页面内容上方显示的 Control。可以使用 ProgressBar 或 ProgressRing 作为某些耗时操作的指示器，例如：

from time import sleep
import flet as ft

def main(page: ft.Page):
    def button_click(e):
        page.splash = ft.ProgressBar()
        btn.disabled = True
        page.update()
        sleep(3)
        page.splash = None
        btn.disabled = False
        page.update()

    btn = ft.ElevatedButton("执行一些耗时的任务！", on_click=button_click)
    page.add(btn)

ft.app(target=main)

show_semantics_debugger​

True 打开一个覆盖层，显示框架报告的辅助功能信息。

theme​

将此属性设置为 theme.Theme 的实例以自定义亮色主题。目前，主题只能从“种子”颜色自动生成。例如，从绿色生成亮色主题：

page.theme = theme.Theme(color_scheme_seed="green")
page.update()

Theme 类具有以下属性:

  • color_scheme_seed - 用于从中派生其余主题颜色的种子颜色。
  • color_scheme - ft.ColorScheme 类的实例，允许自定义从 color_scheme_seed 派生的 Material 颜色方案。
  • text_theme - ft.TextTheme 类的实例，用于自定义与卡片和画布颜色形成对比的文本样式。
  • primary_text_theme - ft.TextTheme 类的实例，描述与主色形成对比的文本主题。
  • scrollbar_theme - ft.ScrollbarTheme 类的实例，自定义整个应用程序中滚动条的外观。
  • tabs_theme - ft.TabsTheme 类的实例，自定义应用程序中 Tabs 控件的外观。
  • font_family - 所有 UI 元素的基本字体。
  • use_material3 - True（默认值）使用 Material 3 设计；否则使用 Material 2。
  • visual_density - ThemeVisualDensity 枚举：STANDARD（默认值）、COMPACT、COMFORTABLE、ADAPTIVE_PLATFORM_DENSITY。
  • page_transitions - PageTransitionsTheme 的实例，允许为不同平台自定义导航页面过渡效果。请参阅下面的 导航过渡效果。

:::注意 如果想在 font_family 中使用系统字体，请阅读这个关于系统字体的注释。 :::

ColorScheme 类​

ColorScheme 类基于Material规范，提供了一组包含30种颜色的配置，用于设置大多数组件的颜色属性。在Flutter文档中可以了解更多关于 ColorScheme 的信息。

ColorScheme 类具有以下属性：

  • primary - 应用程序中最常用的颜色。
  • on_primary - 在 primary 上绘制时清晰可读的颜色。
  • primary_container - 用于需要比 primary 强调度更低的元素的颜色。
  • on_primary_container - 在 primary_container 上绘制时清晰可读的颜色。
  • secondary - 用于UI中不太突出的组件的强调色。
  • on_secondary - 在 secondary 上绘制时清晰可读的颜色。
  • secondary_container - 用于需要比 secondary 强调度更低的元素的颜色。
  • on_secondary_container - 在 secondary_container 上绘制时清晰可读的颜色。
  • tertiary - 用作对比强调色，可以平衡 primary 和 secondary 颜色，或者将注意力集中在元素上，例如输入字段。
  • on_tertiary - 在 tertiary 上绘制时清晰可读的颜色。
  • tertiary_container - 用于需要比 tertiary 强调度更低的元素的颜色。
  • on_tertiary_container - 在 tertiary_container 上绘制时清晰可读的颜色。
  • error - 用于输入验证错误的颜色，例如 TextField.error_text。
  • on_error - 在 error 上绘制时清晰可读的颜色。
  • error_container - 用于需要比 error 强调度更低的错误元素的颜色。
  • on_error_container - 在 error_container 上绘制时清晰可读的颜色。
  • background - 通常出现在可滚动内容后面的颜色。
  • on_background - 在 background 上绘制时清晰可读的颜色。
  • surface - Card 等小部件的背景颜色。
  • on_surface - 在 surface 上绘制时清晰可读的颜色。
  • surface_variant - surface 的颜色变体，可用于与使用 surface 的组件区分开来。
  • on_surface_variant - 在 surface_variant 上绘制时清晰可读的颜色。
  • outline - 创建边界和强调以提高可用性的实用颜色。
  • outline_variant - 创建装饰元素的边界的实用颜色，不需要3:1的对比度，例如分隔线或装饰元素。
  • shadow - 用于绘制凸起组件的阴影的颜色。
  • scrim - 用于绘制模态组件周围的暗纱的颜色。
  • inverse_surface - 用于显示与周围UI相反的表面颜色，例如 SnackBar 中的警报。
  • on_inverse_surface - 在 inverse_surface 上绘制时清晰可读的颜色。
  • inverse_primary - 用于在 inverse_surface 背景上显示突出颜色的强调色，例如 SnackBar 中的按钮文本。
  • surface_tint - 用作放置在表面颜色上的覆盖层，以指示组件的提升程度。

TextTheme 类​

自定义文本样式。

TextTheme 类具有以下 ft.TextStyle 类型的属性：

  • body_large - 最大的正文样式。正文样式用于较长的文本段落。
  • body_medium - 正文样式的中等大小。Material的默认文本样式。
  • body_small - 最小的正文样式。
  • display_large - 最大的显示样式。作为屏幕上最大的文本，显示样式适用于短小的重要文本或数字。在大屏幕上效果最好。
  • display_medium - 显示样式的中等大小。
  • display_small - 最小的显示样式。
  • headline_large - 最大的标题样式。标题样式比显示样式小。最适合在较小屏幕上显示短小的高强调文本。
  • headline_medium - 标题样式的中等大小。
  • headline_small - 最小的标题样式。
  • label_large - 最大的标签样式。标签样式是较小的实用样式，用于UI中的组件内部的文本或内容体中非常小的辅助文本，如标题。用于 ElevatedButton、TextButton 和 OutlinedButton 上的文本。
  • label_medium - 标签样式的中等大小。
  • label_small - 最小的标签样式。
  • title_large - 最大的标题样式。标题比标题样式小，适用于较短的中强调文本。
  • title_medium - 标题样式的中等大小。
  • title_small - 最小的标题样式。

ScrollbarTheme 类​

自定义应用程序中滚动条的颜色、厚度和形状。

ScrollbarTheme 类具有以下属性：

  • thumb_visibility - 指示滚动条拇指是否可见，即使没有滚动也是如此。当为 False 时，滚动条将在滚动期间显示，并在其他情况下淡出。当为 True 时，滚动条将始终可见，不会淡出。属性值可以是单个布尔值，也可以是以 ft.MaterialState 为键、布尔值为值的字典。
  • thickness - 滚动条在滚动区域的交叉轴上的厚度。属性值可以是单个浮点数，也可以是以 ft.MaterialState 为键、浮点数为值的字典。
  • track_visibility - 指示滚动条轨道是否可见。当为 True 时，只要拇指可见，滚动条轨道就始终可见。如果滚动条拇指不可见，则轨道也不可见。当为 None 时，默认为 False。如果此属性为 None，则使用 Theme.scrollbar_theme 的 ScrollbarTheme.track_visibility。如果那也是 None，则默认值为 False。属性值可以是单个布尔值，也可以是以 ft.MaterialState 为键、布尔值为值的字典。
  • radius - 滚动条拇指圆角的半径。
  • thumb_color - 覆盖滚动条拇指的默认颜色。值可以是单个颜色字符串或 ft.MaterialState 字典。
  • track_color - 覆盖滚动条轨道的默认颜色。值可以是单个颜色字符串或 ft.MaterialState 字典。
  • track_border_color - 覆盖滚动条轨道边框的默认颜色。值可以是单个颜色字符串或 ft.MaterialState 字典。
  • cross_axis_margin - 滚动条拇指与最近的交叉轴边缘之间的距离（以逻辑像素为单位）。滚动条轨道占用此空间。不能为空，默认为 0。
  • main_axis_margin - 滚动条拇指的开始和结束与视口边缘的距离（以逻辑像素为单位）。它影响可用的绘制区域。滚动条轨道占用此空间。不能为空，默认为 0。
  • min_thumb_length - 当总滚动范围较大、当前可见视口较小且视口未过度滚动时，滚动条拇指可以缩小到的首选最小尺寸。
  • interactive - 滚动条是否应该是交互式的，是否对拇指拖动或在轨道区域点击作出响应。当为 False 时，滚动条不会响应手势或悬停事件，并允许通过点击穿透它。当为 None 时，默认为 True，除非在 Android 上，默认为 False。

TabsTheme 类​

自定义应用程序中 Tabs 控件的外观。

TabsTheme 类具有以下属性：

  • divider_color - 分隔线的颜色。
  • indicator_border_radius - 指示器圆角的半径。
  • indicator_border_side - 在选定的选项卡下方绘制的水平线的颜色和粗细。
  • indicator_padding - 将选定的选项卡下划线定位相对于选项卡的边界。可以使用 indicator_tab_size 属性以选项卡部件的（居中）边界来定义选项卡指示器的边界，或者使用 True 来定义整个选项卡的边界。
  • indicator_color - 在选定的选项卡下方显示的线的颜色。
  • indicator_tab_size - True 表示指示器占用整个选项卡。
  • label_color - 选定选项卡标签的颜色。
  • unselected_label_color - 未选中选项卡标签的颜色。
  • overlay_color - 定义墨水响应的焦点、悬停和涟漪颜色。如果指定，它会与 MaterialState.FOCUSED、MaterialState.HOVERED 和 MaterialState.PRESSED 中的一个进行解析。

导航过渡效果​

theme.page_transitions 允许自定义不同平台的导航页面过渡效果。该值是 PageTransitionsTheme 类的一个实例，具有以下可选属性：

  • android（默认值为 FADE_UPWARDS）
  • ios（默认值为 CUPERTINO）
  • macos（默认值为 ZOOM）
  • linux（默认值为 ZOOM）
  • windows（默认值为 ZOOM）

支持的过渡效果是 ft.PageTransitionTheme 枚举：NONE（没有任何动画的零延迟过渡）、FADE_UPWARDS、OPEN_UPWARDS、ZOOM、CUPERTINO。

一个简单的示例：

theme = ft.Theme()
theme.page_transitions.android = ft.PageTransitionTheme.OPEN_UPWARDS
theme.page_transitions.ios = ft.PageTransitionTheme.CUPERTINO
theme.page_transitions.macos = ft.PageTransitionTheme.FADE_UPWARDS
theme.page_transitions.linux = ft.PageTransitionTheme.ZOOM
theme.page_transitions.windows = ft.PageTransitionTheme.NONE
page.theme = theme
page.update()

theme_mode​

页面主题。

属性值是一个可选的 ThemeMode 枚举，默认值为 SYSTEM。

支持的值：SYSTEM（默认）、LIGHT 或 DARK。

title​

浏览器或本机操作系统窗口的标题，例如：

page.title = "我的应用程序"
page.update()

url​

完整的 Web 应用程序 URL。

vertical_alignment​

子控件在垂直方向上的对齐方式。

例如，MainAxisAlignment.START 是默认值，将子控件放置在页面顶部。

属性值是 MainAxisAlignment 枚举，具有以下值：

  • START（默认值）
  • END
  • CENTER
  • SPACE_BETWEEN
  • SPACE_AROUND
  • SPACE_EVENLY

views​

一个 View 控件的列表，用于构建导航历史。

列表中的最后一个视图是在页面上显示的视图。

第一个视图是一个“根”视图，不能被弹出。

web​

如果应用程序在Web浏览器中运行，则为 True。

width​

Web页面或包含 Flet 应用程序的本机操作系统窗口的内容区域的宽度。此属性是只读的。通常在 page.on_resize 处理程序中使用。

window_always_on_top​

🖥️ 仅适用于桌面版。设置窗口是否始终显示在其他窗口之上。默认值为 False。

window_bgcolor​

🖥️ 仅适用于桌面版。设置应用程序窗口的背景颜色。

与 page.bgcolor 一起使用可以使窗口透明：

import flet as ft

def main(page: ft.Page):
    page.window_bgcolor = ft.colors.TRANSPARENT
    page.bgcolor = ft.colors.TRANSPARENT
    page.window_title_bar_hidden = True
    page.window_frameless = True
    page.window_left = 400
    page.window_top = 200
    page.add(ft.ElevatedButton("I'm a floating button!"))

ft.app(target=main)

window_focused​

🖥️ 仅适用于桌面版。设置为 True 以使包含 Flet 应用程序的本机操作系统窗口获得焦点。

window_frameless​

🖥️ 仅适用于桌面版。设置为 True 以使应用程序窗口无边框。

window_full_screen​

🖥️ 仅适用于桌面版。设置为 True 以将应用程序的本机操作系统窗口切换到全屏模式。默认值为 False。

window_height​

🖥️ 仅适用于桌面版。获取或设置包含 Flet 应用程序的本机操作系统窗口的高度。

window_left​

🖥️ 仅适用于桌面版。获取或设置本机操作系统窗口的水平位置 - 距离屏幕左边缘的虚拟像素距离。

window_maximizable​

🖥️ 仅适用于桌面版。设置为 False 以隐藏/禁用本机操作系统窗口的“最大化”按钮。默认值为 True。

window_maximized​

🖥️ 仅适用于桌面版。如果包含 Flet 应用程序的本机操作系统窗口已最大化，则为 True；否则为 False。将此属性设置为 True 可以以编程方式最大化窗口，将其设置为 False 可以取消最大化。

window_max_height​

🖥️ 仅适用于桌面版。获取或设置包含 Flet 应用程序的本机操作系统窗口的最大高度。

window_max_width​

🖥️ 仅适用于桌面版。获取或设置包含 Flet 应用程序的本机操作系统窗口的最大宽度。

window_minimizable​

🖥️ 仅适用于桌面应用。设置为 False 以隐藏/禁用操作系统窗口的“最小化”按钮。默认值为 True。

window_minimized​

🖥️ 仅适用于桌面应用。如果包含 Flet 应用的操作系统窗口最小化，则为 True；否则为 False。将此属性设置为 True 可以编程方式最小化窗口，并将其设置为 False 可以还原窗口。

window_min_height​

🖥️ 仅适用于桌面应用。获取或设置包含 Flet 应用的操作系统窗口的最小高度。

window_min_width​

🖥️ 仅适用于桌面应用。获取或设置包含 Flet 应用的操作系统窗口的最小宽度。

window_movable​

🖥️ 仅适用于桌面应用。仅适用于 macOS。设置为 False 可防止用户更改包含 Flet 应用的操作系统窗口的位置。默认值为 True。

window_opacity​

🖥️ 仅适用于桌面应用。设置操作系统窗口的不透明度。值必须介于 0.0（完全透明）和 1.0（完全不透明）之间。

window_resizable​

🖥️ 仅适用于桌面应用。设置为 False 可防止用户调整包含 Flet 应用的操作系统窗口的大小。默认值为 True。

window_title_bar_hidden​

🖥️ 仅适用于桌面应用。设置为 True 以隐藏窗口标题栏。参见 WindowDragArea 控件，该控件允许在隐藏标题栏的情况下移动应用窗口。

window_title_bar_buttons_hidden​

🖥️ 仅适用于桌面应用。设置为 True 以在隐藏标题栏时隐藏窗口操作按钮。仅适用于 macOS。

window_top​

🖥️ 仅适用于桌面应用。获取或设置操作系统窗口的垂直位置 - 距离屏幕顶部边缘的虚拟像素距离。

window_prevent_close​

🖥️ 仅适用于桌面应用。设置为 True 以拦截操作系统的关闭信号。可以与 page.on_window_event (close) 事件处理程序和 page.window_destroy() 一起使用，以实现应用程序退出确认逻辑 - 请参阅 page.window_destroy() 的代码示例。

window_progress_bar​

🖥️ 仅适用于桌面应用。将值设置为介于 0.0 和 1.0 之间的值，以在任务栏（Windows）或 Dock（macOS）应用程序按钮上显示进度条。

window_skip_task_bar​

🖥️ 仅适用于桌面应用。设置为 True 以隐藏应用程序在任务栏（Windows）或 Dock（macOS）中的显示。

window_visible​

🖥️ 仅适用于桌面应用。将其设置为 True 以使应用程序窗口可见。在应用程序启动时隐藏窗口时使用。

以下程序在隐藏窗口的情况下启动，并在 3 秒后使其可见：

from time import sleep

import flet as ft


def main(page: ft.Page):

    page.add(
        ft.Text("Hello!")
    )

    sleep(3)
    page.window_visible = True
    page.update()  

ft.app(target=main, view=ft.AppView.FLET_APP_HIDDEN)

请注意 view=ft.AppView.FLET_APP_HIDDEN，它在启动时隐藏应用程序窗口。

window_width​

🖥️ 仅适用于桌面应用。获取或设置包含 Flet 应用的操作系统窗口的宽度。

方法​

can_launch_url(url)​

检查设备上是否可以处理指定的 URL。

如果能够验证存在处理程序，则返回 True。返回值为 False 可能表示没有可用的处理程序，或者应用程序没有权限进行检查。例如：

  • 在较新版本的 Android 和 iOS 上，除非应用程序已配置为允许查询系统的启动支持，否则将始终返回 False。
  • 在 Web 上，除了一些特定的方案始终假定受支持（如 http(s)），否则将始终返回 False，因为 Web 页面不允许查询已安装的应用程序。

close_banner()​

关闭当前横幅。

close_bottom_sheet()​

关闭当前活动的底部表单。

close_dialog()​

关闭当前活动的对话框。

close_drawer()​

关闭当前活动的抽屉。

close_end_drawer()​

关闭当前活动的结束抽屉。

close_in_app_web_view()​

📱 仅适用于移动设备。关闭使用 launch_url() 打开的应用内网页视图。

error(message)​

显示错误消息。

fetch_page_details()​

获取页面详情。

get_clipboard()​

获取客户端上保存的最后一次复制的文本值。

get_control(id)​

获取指定 id 的控件。

get_upload_url(file_name, expires)​

生成内置上传存储的预签名上传 URL：

  • file_name - 相对于上传存储路径的文件名。
  • expires - URL 的有效时间，以秒为单位。

例如：

upload_url = page.get_upload_url("dir/filename.ext", 60)

要启用内置上传存储，请在 flet.app() 调用中提供 upload_dir 参数：

ft.app(target=main, upload_dir="uploads")

go(route)​

一个辅助方法，用于更新 page.route，调用 page.on_route_change 事件处理程序来更新视图，最后调用 page.update()。

insert(at, *controls)​

在 page.controls 列表的特定索引位置插入控件。

launch_url(url)​

在新的浏览器窗口中打开 url。

可选的方法参数：

  • web_window_name - 打开 URL 的窗口标签/名称：_self - 在相同的浏览器标签中打开，_blank - 在新的浏览器标签中打开（或在移动设备上的外部应用程序中打开），或 <your name> - 命名的标签。
  • web_popup_window - 设置为 True 以在浏览器弹出窗口中显示 URL。默认为 False。
  • window_width - 可选，弹出窗口的宽度。
  • window_height - 可选，弹出窗口的高度。

login(provider, fetch_user, fetch_groups, scope, saved_token, on_open_authorization_url, complete_page_html, redirect_to_page, authorization)​

开始 OAuth 流程。有关更多信息和示例，请参阅身份验证指南。

logout()​

清除当前的身份验证上下文。有关更多信息和示例，请参阅身份验证指南。

remove(*controls)​

从 page.controls 列表中移除指定的控件。

remove_at(index)​

从 page.controls 列表中的特定索引位置移除控件。

scroll_to(offset, delta, key, duration, curve)​

将滚动位置移动到绝对 offset、相对 delta 或跳转到具有指定 key 的控件。

有关方法详细信息和示例，请参阅 Column.scroll_to()。

set_clipboard(data)​

在客户端（用户的网络浏览器或桌面）上设置剪贴板数据，例如：

page.set_clipboard("This value comes from Flet app")

show_banner(banner: Banner)​

在页面顶部显示横幅。

show_bottom_sheet(bottom_sheet: BottomSheet)​

在页面底部显示底部弹出窗口。

show_dialog(dialog: AlertDialog)​

显示对话框。

show_drawer(drawer: NavigationDialog)​

显示 drawer。

show_end_drawer(drawer: NavigationDialog)​

显示 end_drawer。

show_snack_bar(snack_bar: SnackBar)​

在页面底部显示 SnackBar。

snack_bar - 一个 SnackBar 控件，显示在页面底部。

window_center()​

🖥️ 仅适用于桌面。将应用程序的本机操作系统窗口移动到屏幕中心。

window_close()​

🖥️ 仅适用于桌面。关闭应用程序窗口。

window_destroy()​

🖥️ 仅适用于桌面。强制关闭应用程序的本机操作系统窗口。可以与 page.window_prevent_close = True 结合使用以实现应用程序退出确认：

import flet as ft

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

    def window_event(e):
        if e.data == "close":
            page.dialog = confirm_dialog
            confirm_dialog.open = True
            page.update()

    page.window_prevent_close = True
    page.on_window_event = window_event

    def yes_click(e):
        page.window_destroy()

    def no_click(e):
        confirm_dialog.open = False
        page.update()

    confirm_dialog = ft.AlertDialog(
        modal=True,
        title=ft.Text("请确认"),
        content=ft.Text("您确定要退出此应用程序吗？"),
        actions=[
            ft.ElevatedButton("是", on_click=yes_click),
            ft.OutlinedButton("否", on_click=no_click),
        ],
        actions_alignment=ft.MainAxisAlignment.END,
    )

    page.add(ft.Text('尝试通过点击窗口的 "关闭" 按钮退出此应用程序！'))

ft.app(target=main)

window_to_front()​

🖥️ 仅适用于桌面。将应用程序窗口置于前台。

事件​

on_close​

在配置的时间段后（默认为60分钟）会话过期时触发。

on_connect​

当Web用户重新连接到页面会话时触发。当页面刷新或Flet Web客户端在计算机解锁后重新连接时，不会触发此事件。可以使用此事件来检测Web用户何时变为“在线”。

on_disconnect​

当Web用户断开与页面会话的连接时触发，即关闭浏览器选项卡/窗口。

on_error​

当发生未处理的异常时触发。

on_keyboard_event​

当按下键盘键时触发。事件对象 e 是 KeyboardEvent 类的实例：

@dataclass
class ft.KeyboardEvent:
    key: str
    shift: bool
    ctrl: bool
    alt: bool
    meta: bool

查看 简单使用示例。

on_login​

在OAuth授权流程成功或失败后触发。有关详细信息和示例，请参阅 身份验证 指南。

on_logout​

在调用 page.logout() 后触发。

on_platform_brigthness_change​

当应用程序主机平台的亮度发生变化时触发。

on_resize​

当包含 Flet 应用程序的浏览器或本机操作系统窗口由用户调整大小时触发，例如：

def page_resize(e):
    print("New page size:", page.window_width, page.window_height)

page.on_resize = page_resize

on_route_change​

当页面路由发生变化时触发，无论是通过编程方式、编辑应用程序URL还是使用浏览器的后退/前进按钮。

事件对象 e 是 RouteChangeEvent 类的实例：

class RouteChangeEvent(ft.ControlEvent):
    route: str     # 新的页面路由

on_scroll​

当页面的滚动位置由用户更改时触发。

有关事件详细信息和示例，请参阅 Column.on_scroll。

on_view_pop​

当用户单击 AppBar 控件的自动“返回”按钮时触发。

事件对象 e 是 ViewPopEvent 类的实例：

class ViewPopEvent(ft.ControlEvent):
    view: ft.View

其中 view 是包含 AppBar 的 View 控件的实例。

on_window_event​

当应用程序的本机操作系统窗口更改其状态（位置、大小、最大化、最小化等）时触发。

data 包含窗口的事件名称：

  • close
  • focus
  • blur
  • maximize
  • unmaximize
  • minimize
  • restore
  • resize
  • resized（仅适用于 macOS 和 Windows）
  • move
  • moved（仅适用于 macOS 和 Windows）
  • enterFullScreen
  • leaveFullScreen