Flet文档全中文翻译

GUI框架

GUI框架大体上可以分为三类：

1. Web-based框架：专用于Web场景下的前端框架，例如Vue.js、React和Angular，大部分和JavaScript语言绑定。Electron、Tauri等技术使得这类框架编写本地程序变得可能。
2. 独立渲染引擎框架：具备自己的渲染引擎的框架，例如Flutter（Skia/Impeller）、GTK（Cairo）、Qt（Raster）。
3. 原生UI：操作系统的图形子系统直接暴露出来的UI接口。例如Windows的Win32 API，MacOS的Cocoa。
   • Linux没有在内核中实现图形栈，所以对于Linux发行版来说，没有一种严格意义上的原生UI。

什么是Flet

Flet是一个基于谷歌开发的Flutter UI的跨平台应用开发框架，允许开发者用自己喜欢的语言（目前是Python和Golang）构建交互式的，多用户的，Web、桌面和移动应用程序，而不需要拥有前端开发的经验。使用Flet，开发者只需在Python中编写一个整体式有状态应用程序，就可以在所有的平台上运行。

在Linux发行版下，Flet需要GStreamer库。

整体结构

Flet应用程序采用声明式UI，设计相当专业。控件被组织在一个层次结构中，其中每个控件都有一个父控件（Page 除外）和容器控件（如 Column），当然，一些控件，比如下拉列表可以包含子控件。

• 任何一个控件都有visible属性，它用于设置控件是否可见。
• 任何一个控件都有disabled属性，它用于设置控件是否可以进行交互。
• 任何一个（具有父控件的）控件都有parent属性，它用于获取父控件。
• 对父控件的属性修改，会递归传递给子控件。

按照类别划分，有以下几类控件：

• 布局类（Layout）：决定页面的整体布局的宏观控件，或者说，“控件的控件”。
• 导航类（Navigation）：一些辅助功能的导航栏，比如顶栏，下导航栏。
• 信息显示类（Information Display）：显示某些静态的内容，比如文字、图标、图片等等。
• 按钮类（Buttons）：显示一个能触发某些功能的按钮。
• 输入和选择类（Input and Selections）：要求用户输入的控件，比如输入框、多选框。
• 模态类（Dialogs Alerts and Panels）：弹出式提醒的模态对话框。
• 动画类（Animations）：实现某些动画效果。
• 功能类（Utility）：实现某些特殊的功能。

我们之后会逐个进行分析。不过现在可以说的是，它们的通用实例化参数有：

• expand：设为True，使控件伸展以填满所有空白区域。设为整数，则按比例使控件伸展以填满所有空白区域。
• disable：禁止可交互控件起作用。
• visible：设为False，则控件不可见。
• offset：偏移量。
• opacity：透明度。是0.0-1.0的浮点数。
• rotate：旋转角，单位为弧度即x * pi。
• scale：放大尺寸，默认为1.0。
• height：强制设置高度。
• width：强制设置宽度。

引用

Flet控件是Python对象，因此如果希望访问它们的属性，我们就不得不保留对这些对象的引用（使用变量保存），就像这样：

text = flet.Text(value='Hello!')
print(text.value)

但是，在很多时候用户需要创建大量控件，如果逐一进行实例化，就会导致main()函数的内容产生大量冗余，给代码阅读带来很多麻烦。对此，Flet提供了Ref类（灵感来自React），允许用户设置对控件的引用：

mytext = flet.Ref[flet.Text]()

在事件处理时使用引用即可，在最终修改页面时才进行控件的分配：

page.add(flet.Text(ref=mytext))

这样我们就可以方便地看到mytext这个控件的类型是什么了。所有的Flet控件都支持ref=实例化参数。

要访问引用的控件，调用它的.current属性即可：

print(mytext.current.value)

可以看出在访问控件时确实要费力一点，这纯粹只是个人编码习惯的问题，Flet只是提供了一种选择。

触发

最简单的触发器就是按钮：

btn = flet.ElevatedButton('Click')

要触发某些事件，只需要编写处理器函数并设置触发属性。注意，处理器函数总是以一个e（用不到的话也可以是_）作为入参：

def click(e):
	...

btn.on_click = click

较为简单的方法是使用lambda函数：

btn.on_click = lambda _: page.go('/')

动画

所有控件都支持animate_xxx的内置动画可以启用，动画属性的参数可以是布尔值，也可以是整数值，如下：

• animate_opacity：不透明渐变动画。
• animate_rotation：旋转动画。
• animate_scale：缩放动画。
• animate_offset：偏移动画。
• animate_position：位置动画。
• animate：容器控件的动画。

使用

基本结构

一个Flet程序的基本结构是：

import flet

def main(page: flet.Page):
	...

if __name__ == '__main__':
	flet.app(target=main)

一个典型的Flet程序以调用flet.app()等待新用户会话结束。函数main()是Flet应用程序的入口。对于每一个用户会话，都会在新线程中将一个Page实例传递给它。

Flet中的（一般是唯一一个）函数代表着页面UI的构建方式，它会以一个flet.Page实例为参数，表示页面本身，这个函数内部也可以定义并使用子函数。页面和页面内的所有内容都会被视为控件对象，在函数中需要对这些对象进行组合与操作，构建一套UI。

在浏览器中运行Flet应用程序时，会为每个打开的选项卡或页面启动一个新的用户会话。作为桌面应用程序运行时，只会创建一个会话。

运行方式

Flet是跨平台的，因此它既支持在本地运行，也支持在浏览器中以Web形式运行：

flet.app(target=主函数[, view=flet.AppView.WEB_BROWSER, port=端口号])

控件详解

用户界面由控件组成，要使控件对用户可见，必须将它们添加到flet.Page或其子控件中。flet.Page是最顶级的控件，相互嵌套的控件之间的关系可以表示为一棵以flet.Page为根的树。

布局类（Layout）

页面（Page）（请和视图一起看）

页面类似于特定用户的“画布”，是用户会话的可视化体现。要构建应用程序的用户界面，需要在页面中添加和删除控件，并且更新其属性。

要向页面中添加控件，将其添加到Page的controls列表中。在添加控件后，必须手动调用page.update()函数使页面更新：

def main(page: flet.Page):
	page.controls.append(flet.Text())
	page.update()

.update()方法足够智能，它只会发送上次更新以来所做的所有更改。但是，进行大量更改时，用户方面可能会发生卡顿。要规避这种情况，可以将页面更新分批处理，实现起来也很简单，就是使用一个for遍历：

for i in range(500):
	page.add(flet.Text())
	if i % 50 == 0:
		page.update()
	# 有时候可能除不尽
	page.update()

不同的视图通过不同的路由URL进行对应，不同的路由之间可以通过导航控件或设备（浏览器和App）自带的导航功能进行切换，切换的过程是按照栈顺序，逐层向下翻。因此，顶层视图也就是当前显示的视图。一个页面至少也得有一个配套的视图，它被称为根视图，当用户打开App时，一个带有配套根视图的页面实例就会被自动创建。

在代码中，页面体现为函数的page参数：

def main(page: flet.Page):
	pass

要修改页面的属性，只需要在视图函数中修改page参数的属性即可。就像这样：

def main(page: flet.Page):
	page.auto_scroll = True

单页面与多页面

应用分为单页面应用（Single Page Application）和多页面应用（Multiple Page Application），究其本质区别，SPA是客户端方渲染（Client-side Render），而MPA是服务端方渲染（Server-side Render）。

• SPA把页面视作一个单例对象（单个HTML文件），在一个页面的DOM上动手脚，在多个视图之间来回切换。这种方式的优点是体验很流畅，但是启动加载较慢。一般用于桌面程序和现代Web开发。
• MPA把每个页面都视为单视图页面，在多个页面（多个HTML文件）之间来回切换实现功能，每次切换页面时，客户端都需要重新发送请求，服务端也需要重新响应。这种方式的优点是打开快，思路直观，但是页面之间的切换需要重新发送请求和构建DOM树，这个过程可能会发生“白屏”。一般用于Web或移动程序开发。

路由模式

MPA需要多个URL实现功能，这并不奇怪；但是实际上，SPA也会有使用多个URL的需要，为什么呢？这是因为，SPA只有单个页面，要使用浏览器（或手机）的导航功能（前进/后退）进行切换的话就会比较麻烦（无法返回或直接退出）。要解决这个问题，SPA使用了名为“路由模式”（Routing）的方法进行解决。

导航和路由是单页面应用（SPA）的基本功能，它允许将应用用户界面组织成虚拟页面（视图），并在应用URL反映应用的当前状态时进行“导航”到这些页面。对于移动应用程序，导航和路由还会用作特定应用程序部分的深度链接。

在过去，这种方式的主要实现方法是使用“锚点”#符号，在URL中，如果#之后的部分发生改变，那么客户端是不会重新发送请求的，但是，运行中的框架仍然可以监听URL的变化，这就确保了页面不需要重新请求就可以发生变化。

在2016年，HTML5引入了新的浏览器API（History API），直接实现了更新URL而不重新发送请求的方法，这使得不用锚点也可以实现路由功能了。

在Flet中，两种方式都是可以支持的，只需要在启动App的函数flet.app()中设置参数：

flet.app(target=main, route_url_strategy='hash|path')

当然，默认为新式的path。

在Flet中，要使用路由和导航比较费力，因为它的实现基于Flutter的Navigator 2.0 API，并且如果要用这种方式开发应用，就需要使用页面+视图的设计抽象取代原先的纯页面抽象。Flutter的导航和路由API有一些重要特性，例如：

1. 对历史堆栈具有编程控制权。
2. 可以拦截对浏览器的“返回”按钮的调用。
3. 与浏览器历史记录的同步。

路由

这里以hash模式为例。

页面路由是#符号后的URL部分。如果用户没有在函数中设置默认路由，那么默认路由就是/，所有路由都会以/开头，例如IP:Port/#/admin。

可以通过读取page.route属性获取当前的路由，每当URL中的路由发生更改（通过编辑URL或使用后退/前进按钮浏览浏览器历史记录）时，会触发page.on_roue_change事件，可以借此设置处理程序。

页面的属性

关联控件类

• overlay：在页面之上额外显示的控件栈，可能的控件包括：
  • Banner控件。
  • AlertDialog控件。
  • BottomSheet控件。
  • Splash控件。
  • SnackBar控件。
• navigation_bar：指定一个下导航栏控件。
• appbar：指定一个上导航栏控件。
• drawer：指定一个左侧导航栏控件。
• end_drawer：指定一个右侧导航栏控件。
• floating_action_button：指定一个始终显示的悬浮按钮，一般用于“回到顶部”。

页面设置类

• title：页面标题。
• scroll：设置页面的滚动模式，有以下可选值：
  • None：禁用滚动。
  • AUTO：页面过长时自动启用滚动。
  • ADAPTIVE：启用滚动，但是只在网页和桌面端显示滚动条。
  • ALWAYS：启用滚动，总是显示滚动条。
  • HIDDEN：启用滚动，但是总是不显示滚动条。
• auto_scroll：布尔值，是否自动滚动到底部。
• horizontal_alignment：设置内置视图中控件的水平排列方式，有五种值：
  • flet.CrossAxisAlignment.START：从最左侧开始排列。
  • flet.CrossAxisAlignment.CENTER：从中央向两侧开始排列。
  • flet.CrossAxisAlignment.END：从最右侧开始排列。
  • flet.CrossAxisAlignment.STRETCH：水平拉伸填满页面。
  • flet.CrossAxisAlignment.BASELINE：按照字符基线对齐。
• vertical_alignment：设置内置视图中控件的垂直排列方式，有五种值：
  • flet.MainAxisAlignment.START：从顶部开始排列。
  • flet.MainAxisAlignment.END：从底部开始排列。
  • flet.MainAxisAlignment.CENTER：从中央向两侧开始排列。
  • flet.MainAxisAlignment.SPACE_BETWEEN：在垂直方向上均匀分布，到顶部与底部的间隔相等，而且等于控件间间隔的一半。
  • flet.MainAxisAlignment.SPACE_AROUND：在垂直方向上均匀分布，和顶部与底部没有间隔。
  • flet.MainAxisAlignment.SPACE_EVENLY：在垂直方向上均匀分布，控件间间隔、到顶部与底部的间隔全部都相等。
• padding：到窗口四周边缘的间隙，单位是像素，默认为0。
• rtl：布尔值，让字符反向排列（从右到左）。
• spacing：控件的竖向间隔，默认为10像素。

客制化类

• design：可选flet.PageDesign.ADAPTIVE、flet.PageDesign.MATERIAL、flet.PageDesign.CUPERTINO，设置整体风格是跟随平台还是强制使用Material。
• theme_mode：可选SYSTEM、LIGHT、DARK，设置亮色或黑暗。
• theme：指定一个theme.Theme的实例，设置亮色主题。
• dark_theme：指定一个theme.Theme的实例，设置黑暗主题。
• bgcolor：指定背景色，可以是#ARGB格式、#RGB格式或flet.colors中定义的别名，默认为#FFFFFF。别名如下：
  • flet.colors.WHITE：白色。
  • flet.colors.BLUE：蓝色。
  • flet.colors.ORANGE：橘色。
  • flet.colors.GREEN：绿色。
  • flet.colors.with_opacity(透明度, 别名)：设置透明颜色。

• fonts：指定使用的字体，可以是ttc、ttf或otf格式。
• splash：加载时的水印控件，可以是一个ProgressBar或ProgressRing。

注：theme.Theme()支持的实例化参数有：

• color_scheme_seed：主题色。
• font_family：字族。
• use_material3：默认为True，设为False使用Material 2。
• visual_density：显示密度，可选STANDARD、COMPACT、COMFORTABLE、ADAPTIVE_PLATFORM_DENSITY。

本地化

• locale_configuration：配置当前的地区。它的值应当是一个flet.LocaleConfiguration()实例，这个实例有两个实例化参数：
  • supported_locales：一个列表，列表中的每一个元素都是flet.Locale()实例，它的实例化参数有：
    • language_code：主语言号。
    • country_code：次语言号。
    • script_code：用于细分的子Unicode Tag。
  • current_locale：当前使用的Locale，应当是一个flet.Locale()实例。

只读类

• web：当前是否以Web形式运行。
• url：当前的URL。
• query：获取URL的?之后的搜索部分。
• client_ip：客户端IP。
• client_user_agent：客户端浏览器类型。
• platform：客户端类型，它的值只可能是ios、android、macos、linux、windows。
• height：窗口高度。
• width：窗口宽度。
• platform_brightness：当前客户端的色彩模式，只能是flet.ThemeMode.LIGHT或flet.ThemeMode.DARK。
• session：会话信息的KV键值对字典。
• session_id：会话ID。

核心类

• route：设置当前路由。
• controls：页面的内置视图的控件列表。
• views：页面的视图栈，栈底是内置视图，它不能被弹出。

可访问性

• show_semantics_debugger：显示辅助功能的细节。

方法

关联控件类

• open(控件)：在页面上快速打开控件。实际上的操作是，将该控件立刻加入page.overlay栈顶，并将其.open属性设为True，并调用page.update()。可能的控件包括：
  • Banner控件。
  • AlertDialog控件。
  • BottomSheet控件。
  • Splash控件。
  • SnackBar控件。
• error(信息)：弹出错误。
• can_launch_url(URL)：检测指定URL能不能运行。
• launch_url(URL)：在网页视图中打开URL。

客户端交互

• get_clipboard()：获取客户端剪贴板。
• set_clipboard('字符串')：设置客户端剪贴板内容。
• get_upload_url(文件名, 过期时间)：生成一个上传URL，需要结合flet.app(target=, upload_dir=)使用。

异步

• run_thread(page.方法)：在新的线程中执行指定的方法。
• executor：当前的主线程执行器。

更新页面

• update()：更新页面，任何变化都必须更新后才能生效。
• go(路由)：切换路由，实际上是先修改了page.route，再执行了.update()。
• add(控件)：在根视图上添加一个控件，实际上是先执行了.control.append()，再执行了.update()
• remove(控件)：在根视图上删除一个控件。
• scroll_to()：滚动页面到特定位置，可以是offset=设置的绝对位置，可以是delta=设置的排列方式，也可以是key=设置的指定控件。
• launch_url(URL, web_window_name='_self|_blank')：打开新的URL，_self表示在当前标签页打开，_blank表示在新的标签页中打开。

登录

Page可以使用OAuth进行认证登录，流程如下：

• 配置OAuth提供程序的客户端ID、客户端密码、重定向URL。
• 调用page.login(provider)，启动OAuth Web流程。
• 用户被重定向到OAuth提供商网站。
• 在提供商网站上，用户登录并同意访问服务API。
• 提供商网站使用授权代码重定向到Flet的OAuth回调URL。
• Flet交换令牌的授权代码并调用page.on_login事件处理程序。
• Flet应用程序可以从page.auth.token属性和用户详细信息中检索出API令牌page.auth.user。

以Github为例：

# 这个URL是固定的
provider = GitHubOAuthProvider(
	client_id='xxx',
	client_secret='xxx',
	redirect_url='http://localhost:8550/api/oauth/redirect'
)

page.add(flet.ElevatedButton('Login', on_click=lambda e: page.login(provider)))

page.on_login = lambda e: print(page.auth.user.id, page.auth.token.access_token)

page.logout()

page.login()方法接受很多参数：

• fetch_user：是否将用户详细信息提取到page.auth.user，默认为True。
• fetch_groups：是否将用户组提取到page.auth.user.groups，默认为False。
• scope：要请求的范围列表。
• saved_token``page.auth.token-从中恢复授权的JSON快照。Token可以序列化page.auth.token.to_json()，加密保存在page.client_storage，见下文。
• on_open_authorization_url：使用授权URL打开浏览器的回调。见下文。
• complete_page_html：“您已成功通过身份验证。立即关闭此页面”页面的自定义HTML内容。
• redirect_to_page：仅当在同一浏览器选项卡中打开授权页面时才与Flet网络应用程序一起使用。

page.auth.token是认证令牌字典，有以下属性：

• access_token：在 API 请求标头中用作授权令牌的访问令牌。
• scope：令牌的范围。
• token_type：访问令牌类型，例如Bearer。
• expires_in：访问令牌过期时的可选秒数。
• expires_at：访问令牌过期时的可选时间 time.time()+expires_in。
• refresh_token：可选的刷新令牌，用于在旧令牌过期时获取新的访问令牌。

page.auth.user是用户信息字典，它至少包括以下属性：

• id：用户ID。

客户端存储

Flet的客户端存储使用了Flutter的shared_preferences包。实际的存储机制取决于Flet应用程序运行的平台：

• Web：本地存储。
• 桌面：JSON文件。
• iOS：NSUserDefaults。
• Android：SharedPreferences。

要保存数据，执行：

page.client_storage.set('键', '值')

值可以是：

• 字符串。
• 数字。
• 布尔值。
• 列表。

检查数据存在性：

page.client_storage.contains_key('键')

获取数据：

page.client_storage.get('键')

获取所有键：

page.client_storage.get_keys()

删除键：

page.client_storage.remove('键')

删除所有数据：

page.client_storage.clear()

会话存储

Flet可以在服务端会话中存储键值对数据。这些数据是暂时的，不会在应用重新启动后保留。格式为：

page.session.set('键', '值')

值可以是字符串，也可以是布尔值或列表。

检查数据存在性：

page.session.contains_key('键')

获取数据：

page.session.get('键')

获取所有键：

page.session.get_keys()

删除键：

page.session.remove('键')

删除所有数据：

page.session.clear()

加密

Flet有简单的加密方法。它们使用了cryptography包中的Fernet实现，该实现是AES 128加上一些额外的强化，并使用PBKDF2从用户口令派生加密密钥。：

• 加密：flet.security.encrypt('字符串', 密钥)
• 解密：flet.security.decrypt('加密字符串', 密钥)

经验上，密钥往往允许用户通过环境变量传入。

广播

Flet可以使用广播-订阅机制构建应用，用于在页面会话之间进行异步通信。典型的模式是：

• 在应用程序会话开始时订阅广播消息或订阅主题。
• 让某些事件触发发送广播消息或发送到某个事件的主题，例如单击“发送”按钮。
• 让某些事件触发取消订阅广播消息或取消订阅某个事件的主题，例如单击“离开”按钮。
• page.on_close时触发取消订阅上的所有内容。

方法如下：

• page.pubsub.subscribe(触发函数)：订阅广播消息。函数应当以message为参数。
• page.pubsub.send_all('消息')：发送广播消息。
• page.pubsub.send_all_on_topic(Topic, '消息')：发送指定主题的消息。
• page.pubsub.subscribe_topic(Topic, 触发函数)：订阅指定主题的消息。
• page.pubsub.send_others('消息')：给除了自己以外的其他人广播消息。
• page.pubsub.send_others_on_topic(Topic, 触发函数)：给除了自己以外的其他人广播指定主题的消息。
• page.pubsub.unsubscribe()：取消订阅消息。
• page.pubsub.unsubscribe_topic(Topic)：取消订阅指定主题消息。
• page.pubsub.unsubscribe_all()：取消订阅所有消息。

事件

一个页面的生命周期中会产生多种事件，每个事件都可以绑定一个事件处理器函数，就像这样：

page.event = func

• on_close：会话过期时触发。
• on_connect：用户重新连接时触发。注意第一次连接时是不会触发的。这一事件也可以用于检测用户临时离线，然后重新在线的情况。
• on_disconnect：用户断开连接时触发，比如关闭窗口或浏览器时。
• on_error：出现任何错误时触发。
• on_keyboard_event：出现特定的键盘输入时触发，注意这一函数应当接受一个e对象为入参，它是一个flet.KeyboardEvent的实例，该实例有以下属性：
  • shift：布尔值，是否按住Shift。
  • ctrl：布尔值，是否按住Ctrl。
  • alt：布尔值，是否按住Alt。
  • meta：布尔值，是否按住Meta。
  • key：具体的键。
• on_platform_brigthness_change：切换明亮/黑暗主题时触发。
• on_resize：调整窗口大小时触发。
• on_scroll：滚动时触发。
  • on_scroll_interval：触发滚动事件（on_scroll）的间隔。
• on_view_pop：点击导航栏的返回时触发。这一函数应当接受一个e对象为入参，它是一个flet.ViewPopEvent的实例，e.view表示当前的视图。
• on_app_lifecycle_state_change：APP状态发生变化时触发。这一函数应当接受一个e对象为入参，它是一个flet.AppLifecycleStateChangeEvent的实例，state属性表示当前窗口的状态，包括：
  • SHOW：窗口进入前台。
  • RESUME：窗口获得焦点。
  • HIDE：窗口被最小化。
  • INACTIVE：窗口失去焦点。在移动端，这意味着有系统对话框弹出。
  • PAUSE：（仅用于移动端）窗口进入后台。
  • DETACH：（仅用于移动端）应用停止。
  • RESTART：（仅用于移动端）窗口重获焦点。

视图（View）（请和页面一起看）

在使用页面-视图的设计方式时，Page就不止是一个单独的页面了。页面成为了视图的容器，多个视图在页面上层叠地进行覆盖，就像千层饼一样：

视图是所有其他控件的容器，视图的集合意味着导航的历史，页面的page.views属性保存了视图的列表（准确地说，是栈）。列表中的最后一个视图就是当前在页面上显示的视图，视图列表中至少有一个元素（根视图）。当用户打开App时，一个带有配套根视图的页面实例就会被自动创建，当使用page.add()直接添加控件时，控件就会被添加到根视图上。

在默认情况下，视图使用Column作为整体布局，也就是说，视图内直接声明的控件会隐含地被转换为flet.Column([控件列表])。

在SPA架构下，页面是一个单例对象，而视图有多个，可以互相切换；在MPA架构下，页面有多个，每个页面一般对应一个视图。这两种开发模式的区别导致视图有一些和页面重合的实例化参数：

• appbar：指定一个上导航栏控件。
• auto_scroll：布尔值，是否自动滚动到底部。
• bgcolor：指定背景色，可以是#ARGB格式、#RGB格式或flet.colors中定义的别名，默认为#FFFFFF。
• controls：视图内的控件列表。
• horizontal_alignment：设置控件的水平排列方式，有五种值：
  • flet.CrossAxisAlignment.START：从最左侧开始排列。
  • flet.CrossAxisAlignment.CENTER：从中央向两侧开始排列。
  • flet.CrossAxisAlignment.END：从最右侧开始排列。
  • flet.CrossAxisAlignment.STRETCH：水平拉伸填满页面。
  • flet.CrossAxisAlignment.BASELINE：按照字符基线对齐。
• vertical_alignment：设置控件的垂直排列方式，有五种值：
  • flet.MainAxisAlignment.START：从顶部开始排列。
  • flet.MainAxisAlignment.END：从底部开始排列。
  • flet.MainAxisAlignment.CENTER：从中央向两侧开始排列。
  • flet.MainAxisAlignment.SPACE_BETWEEN：在垂直方向上均匀分布，到顶部与底部的间隔相等，而且等于控件间间隔的一半。
  • flet.MainAxisAlignment.SPACE_AROUND：在垂直方向上均匀分布，和顶部与底部没有间隔。
  • flet.MainAxisAlignment.SPACE_EVENLY：在垂直方向上均匀分布，控件间间隔、到顶部与底部的间隔全部都相等。
• padding：到窗口四周边缘的间隙，单位是像素，默认为0。
• scroll：设置页面的滚动模式，有以下可选值：
  • None：禁用滚动。
  • AUTO：页面过长时自动启用滚动。
  • ADAPTIVE：启用滚动，但是只在网页和桌面端显示滚动条。
  • ALWAYS：启用滚动，总是显示滚动条。
  • HIDDEN：启用滚动，但是总是不显示滚动条。
• spacing：控件的竖向间隔，默认为10像素。
• scroll_to()：滚动页面到特定位置，可以是offset=设置的绝对位置，可以是delta=设置的排列方式，也可以是key=设置的指定控件。
• on_scroll：滚动时触发的函数。
  • on_scroll_interval：触发滚动事件（on_scroll）的间隔。
• route：视图的路由，目前没有实际作用，但是可以用于标识View对应的Route。

切换视图

不同的路由URL对应不同的视图，实现路由的切换也就是实现视图之间的切换。在构建函数内直接使用page.add()添加的控件会保存在根视图中，在进入App时默认会直接显示：

# 进入这个页面就会直接显示Hello world
def main(page: flet.Page):
	page.add(flet.Text('Hello world!'))

要切换路由时，只需要直接修改page.route：

page.route = '/foo'
page.update()

实际上，这一套操作就等价于：

page.go('/foo')

要实现在切换路由时切换视图，即模拟页面之间的切换，只需要在切换page.route之后，在page.views栈尾压进新视图即可：

page.go('/foo')

# 某些情况下你可能想先清空视图栈...
#page.views.clear()

page.views.append(foo_view)
page.update()

要返回也很简单，出栈并重设路由即可：

page.views.pop()
# 别忘了路由也得返回啊...
page.go(page.views[-1].route)

为了保证代码的规范和一致性，我们可以另外定义一个新的视图并且压到栈里，进行覆盖：

def main(page: flet.Page):
	# 之后就把这个视图视为根视图
	root_view = flet.View(controls=[flet.Text('Hello world!')])
	page.views.append(root_view)
	page.update()

为了构建可可靠的导航，更优雅的方法是，在程序中设置一个根据当前路由构建视图列表的方法，这个方法就是使用处理器函数。路由切换时会触发page.on_route_change事件，按下顶栏的返回按钮时都会触发page.on_view_pop事件，设置对应的处理器函数，让它处理返回逻辑：

# 这个route参数纯粹起到占位作用，没有实际意义
# 可以改为_
def change_route(route):
    # 大部分情况下不应该清空视图栈，因为我们会希望导航键能够正常工作，如果清空了视图栈，那么导航键就会失效
    # 但是如果你不在乎导航键的情况下……
    #page.views.clear()
	# 在这里我们把所有要切换的路由全部罗列出来就好了！
	if page.route == '/':
		page.views.append(root_view)
		page.update()
	elif page.route == '/foo':
		page.views.append(foo_view)
		page.update()

# 这个函数可能会非常常用，在点击AppBar上的返回按钮时触发
# 这个view参数纯粹起到占位作用，没有实际意义
# 可以改为_
def pop_view(view):
	page.views.pop()
	page.go(page.views[-1].route)

# 修改page.route时触发
page.on_route_change = change_route
# 点击AppBar上的返回按钮时触发
page.on_view_pop = pop_view
# 不要忘了手动进入一次根视图，触发函数
page.go('/')
# 这等价于
#page.go(page.route)

Flet还提供了一个基于repath库的类TemplateRoute，它允许匹配路由并解析其参数，例如：

troute = flet.TemplateRoute(page.route)

if troute.match('/book/:id'):
	print(troute.id)

列分布（Column）

以从上到下的形式显示控件。如果在视图中没有特别创建布局控件，那么就隐含了默认状态的列分布。

大部分实例属性都可以在实例化参数中提供，这包括：

• controls：控件列表。
• alignment：设置控件的垂直排列方式，强烈建议和expand=True一起使用，有五种值：
  • flet.MainAxisAlignment.START：从顶部开始排列。
  • flet.MainAxisAlignment.END：从底部开始排列。
  • flet.MainAxisAlignment.CENTER：从中央向两侧开始排列。
  • flet.MainAxisAlignment.SPACE_BETWEEN：在垂直方向上均匀分布，到顶部与底部的间隔相等，而且等于控件间间隔的一半。
  • flet.MainAxisAlignment.SPACE_AROUND：在垂直方向上均匀分布，和顶部与底部没有间隔。
  • flet.MainAxisAlignment.SPACE_EVENLY：在垂直方向上均匀分布，控件间间隔、到顶部与底部的间隔全部都相等。
• horizontal_alignment：设置控件的水平相对位置，强烈建议和expand=True一起使用，有五种值：
  • flet.CrossAxisAlignment.START：左对齐。
  • flet.CrossAxisAlignment.CENTER：中央对齐。
  • flet.CrossAxisAlignment.END：右对齐。
  • flet.CrossAxisAlignment.STRETCH：水平拉伸填满页面。
  • flet.CrossAxisAlignment.BASELINE：按照字符基线对齐。
• spacing：控件的竖向间隔，默认为10像素。
• wrap：设为True则允许划分多列。
  • run_spacing：列间隔。
• tight：设为True则紧密排列控件。

列控件允许有独立的滚动条，因此它还支持以下实例化参数：

• scroll：设置页面的滚动模式，有以下可选值：
  • None：禁用滚动。
  • AUTO：页面过长时自动启用滚动。
  • ADAPTIVE：启用滚动，但是只在网页和桌面端显示滚动条。
  • ALWAYS：启用滚动，总是显示滚动条。
  • HIDDEN：启用滚动，但是总是不显示滚动条。
• auto_scroll：布尔值，是否自动滚动到底部。

这个方法：

• scroll_to()：滚动页面到特定位置，可以是offset=设置的绝对位置，可以是delta=设置的排列方式，也可以是key=设置的指定控件。

以及这个事件：

• on_scroll：滚动时触发。
  • on_scroll_interval：触发滚动事件（on_scroll）的间隔。

行分布（Row）

以从左到右的形式显示控件。

大部分实例属性都可以在实例化参数中提供，这包括：

• controls：控件列表。
• alignment：设置控件的垂直排列方式，强烈建议和expand=True一起使用，有五种值：
  • flet.MainAxisAlignment.START：从最左侧开始排列。
  • flet.MainAxisAlignment.CENTER：从中央向两侧开始排列。
  • flet.MainAxisAlignment.END：从最右侧开始排列。
  • flet.MainAxisAlignment.STRETCH：水平拉伸填满页面。
  • flet.MainAxisAlignment.BASELINE：按照字符基线对齐。
• vertical_alignment：设置控件的垂直相对位置，强烈建议和expand=True一起使用，有五种值：
  • flet.CrossAxisAlignment.START：顶部对齐。
  • flet.CrossAxisAlignment.END：底部对齐。
  • flet.CrossAxisAlignment.CENTER：中央对齐。
  • flet.CrossAxisAlignment.SPACE_BETWEEN：到顶部与底部的间隔相等，而且等于控件间间隔的一半。
  • flet.CrossAxisAlignment.SPACE_AROUND：和顶部与底部没有间隔。
  • flet.CrossAxisAlignment.SPACE_EVENLY：控件间间隔、到顶部与底部的间隔全部都相等。
• spacing：控件的竖向间隔，默认为10像素。
• wrap：设为True则允许划分多行。
  • run_spacing：行间隔。
• tight：设为True则紧密排列控件。

行控件允许有独立的滚动条，因此它还支持以下实例化参数：

• scroll：设置页面的滚动模式，有以下可选值：
  • None：禁用滚动。
  • AUTO：页面过长时自动启用滚动。
  • ADAPTIVE：启用滚动，但是只在网页和桌面端显示滚动条。
  • ALWAYS：启用滚动，总是显示滚动条。
  • HIDDEN：启用滚动，但是总是不显示滚动条。
• auto_scroll：布尔值，是否自动滚动到底部。

这个方法：

• scroll_to()：滚动页面到特定位置，可以是offset=设置的绝对位置，可以是delta=设置的排列方式，也可以是key=设置的指定控件。

以及这个事件：

• on_scroll：滚动时触发。
  • on_scroll_interval：触发滚动事件（on_scroll）的间隔。

自适应行（ResponsiveRow）

可以随着窗口宽度进行变化的自适应行布局。它会把屏幕分为12个虚拟列，每个控件在不同宽度下占用不同的列数。

大部分实例属性都可以在实例化参数中提供，这包括：

• columns：虚拟列数量。一般不需要修改，除非你希望更细粒度的管理。
• controls：控件列表。每个控件都应该是一个提供了col参数的flet.Column对象，col实际上是控件在不同宽度下占用的列数字典，分别有：
  • xs：Extra Small，小于576px。
  • sm：Small，576px-768px。
  • md：Medium，768px-992px。
  • lg：Large，992px-1200px。
  • xl：Extra Large，1200px-1400px。
  • xxl：Extra Extra Large，大于1400px。
• alignment：设置控件的垂直排列方式，强烈建议和expand=True一起使用，有五种值：
  • flet.MainAxisAlignment.START：从最左侧开始排列。
  • flet.MainAxisAlignment.CENTER：从中央向两侧开始排列。
  • flet.MainAxisAlignment.END：从最右侧开始排列。
  • flet.MainAxisAlignment.STRETCH：水平拉伸填满页面。
  • flet.MainAxisAlignment.BASELINE：按照字符基线对齐。
• vertical_alignment：设置控件的垂直相对位置，强烈建议和expand=True一起使用，有五种值：
  • flet.CrossAxisAlignment.START：顶部对齐。
  • flet.CrossAxisAlignment.END：底部对齐。
  • flet.CrossAxisAlignment.CENTER：中央对齐。
  • flet.CrossAxisAlignment.SPACE_BETWEEN：到顶部与底部的间隔相等，而且等于控件间间隔的一半。
  • flet.CrossAxisAlignment.SPACE_AROUND：和顶部与底部没有间隔。
  • flet.CrossAxisAlignment.SPACE_EVENLY：控件间间隔、到顶部与底部的间隔全部都相等。
• spacing：同行控件之间的间隔。
• run_spacing：行之间的间隔。

容器（Container）

一个带有背景的控件容器。

具体来说，容器的结构是这样的：

大部分实例属性都可以在实例化参数中提供，这包括：

• content：内部的控件。
• alignment：控件在容器内的分布，可以是以下几种值：
  • flet.alignment.top_left
  • flet.alignment.top_center
  • flet.alignment.top_right
  • flet.alignment.center_left
  • flet.alignment.center
  • flet.alignment.center_right
  • flet.alignment.bottom_left
  • flet.alignment.bottom_center
  • flet.alignment.bottom_right
• shape：设置容器形状，只能是flet.BoxShape.RECTANGLE或flet.BoxShape.RECTANGLE。
• margin：设置背景四周的空隙。该参数的值应当是一个flet.margin.中包含的函数，包括以下几种：
  • flet.margin.all(宽度)：设置四周间隙。
  • flet.margin.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
  • flet.margin.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
• padding：设置控件四周的空隙。该参数的值应当是一个flet.padding.中包含的函数，包括以下几种：
  • flet.padding.all(宽度)：设置四周间隙，等价于直接设置一个值。
  • flet.padding.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
  • flet.padding.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
• bgcolor：指定背景色，可以是#ARGB格式、#RGB格式或flet.colors中定义的别名，默认为#FFFFFF。
• blur：设置容器控件背景的模糊效果。该参数能选择的值有三类：
  • 整数值，设置模糊程度。
  • 元组，分别设置水平和垂直方向的模糊程度。
  • 一个flet.Blur类的实例。
• animate：设置容器控件发生变化时的动画效果，该参数能选择的值有三类：
  • 布尔值，表示开关默认动画效果。
  • 整数值，表示默认动画效果的持续时间。
  • 一个flet.animation.Animation类的实例。
• border：给容器背景上设置一个边框。该参数的值应当是一个flet.border.中包含的函数，包括以下几种：
  • flet.border.all(宽度, 颜色)：设置四周边框。
  • flet.border.symmetric(vertical=flet.border.BorderSide(宽度, 颜色), horizontal=flet.border.BorderSide(宽度, 颜色))：分别设置垂直和水平方向的边框。
  • flet.border.only(left|right|top|bottom=flet.border.BorderSide(宽度, 颜色))：只设置上下左右的边框。
• border_radius：给容器背景设置圆角。该参数的值应当是一个flet.border_radius.中包含的函数，包括以下几种：
  • flet.border_radius.all(弧度)：设置四周圆角。
  • flet.border_radius.horizontal(left=弧度, right=弧度)：设置水平方向的圆角。
  • flet.border_radius.vertical(top=弧度, bottom=弧度)：设置垂直方向的圆角。
  • flet.border_radius.only=top_left|top_right|bottom_left|bottom_right=弧度：只设置四角之一的圆角。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。
• ink：布尔值，是否设置点击特效。
• url：将容器设为可点击的，并设置目标URL。
• url_target：设置打开URL的方式，可选：
  • _blank：新标签页。
  • _self：当前标签页。

可触发事件如下：

• on_hover：鼠标移动到容器控件时触发的函数。函数必须接受一个e对象为入参，e.data属性在鼠标移动到容器控件时为True。

如果容器是可点击的，那么容器还可以设置额外的触发事件：

• on_click：容器被点击时触发的函数。
• on_long_press：容器被长按时触发的函数。

卡片（Card）

一个Material风格的悬浮卡片。

所有实例属性都可以在实例化参数中提供，这包括：

• color：卡片背景色。
• content：卡片内部的控件。
• elevation：卡片底部的阴影深度。
• shadow_color：阴影颜色。
• surface_tint_color：卡片表层颜色。
• margin：设置背景四周的空隙。该参数的值应当是一个flet.margin.中包含的函数，包括以下几种：
  • flet.margin.all(宽度)：设置四周间隙。
  • flet.margin.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
  • flet.margin.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。

层叠控件（Stack）

把若干个控件叠在一起。这个控件的用途很有限，例如伪水印，或一些动画等等。

所有实例属性都可以在实例化参数中提供，这包括：

• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。
• controls：控件列表。强烈推荐使用flet.Container进行包含。
• alignment：不完全定位的控件在内部的分布位置，可以是以下几种值：
  • flet.alignment.top_left
  • flet.alignment.top_center
  • flet.alignment.top_right
  • flet.alignment.center_left
  • flet.alignment.center
  • flet.alignment.center_right
  • flet.alignment.bottom_left
  • flet.alignment.bottom_center
  • flet.alignment.bottom_right
• fit：如何调整不完全定位的控件的大小，值必须是一个flet.StackFit下属的对象：
  • flet.StackFit.EXPAND：扩展到最大可能大小。
  • flet.StackFit.PASS_THROUGH：不调整未要求的方向。
  • flet.StackFit.LOOSE：松散，随意调整。

位于Stack中的控件可以设置以下额外属性：

• bottom：到底部的距离。
• left：到左方的距离。
• right：到右方的距离。
• top：到顶部的距离。

只读列表（ListView）

批量列出一批只读的数据。

所有实例属性都可以在实例化参数中提供，这包括：

• auto_scroll：布尔值，是否自动滚动到底部。
• controls：控件列表，每个控件都应该是flet.Text的实例。
• divider_thickness：每行之间设置一个指定宽度的分割线。
• first_item_prototype：所有行都拷贝第一行的长宽属性。
• horizontal：设为True则为水平列表。
• item_extent：设置每一行的固定的高度。
• padding：设置控件四周的空隙。该参数的值应当是一个flet.padding.中包含的函数，包括以下几种：
  • flet.padding.all(宽度)：设置四周间隙，等价于直接设置一个值。
  • flet.padding.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
  • flet.padding.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
• spacing：控件的竖向间隔，默认为10像素。
• scroll_to()：滚动页面到特定位置，可以是offset=设置的绝对位置，可以是delta=设置的排列方式，也可以是key=设置的指定控件。
• on_scroll：滚动时触发的函数。
  • on_scroll_interval：触发滚动事件（on_scroll）的间隔。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。

高级列表（ListTile）

带有可选的图标和下拉选项卡的单个列表项控件。

因为每个ListTile控件都仅仅对应单个列表项，所以多个ListTile要想组成列表必须放在flet.Column控件下。

所有实例属性都可以在实例化参数中提供，这包括：

• leading：前导部分，一般是一个图标或一个选项，也就是flet.Image或flet.Radio、flet.Checkbox、flet.Switch控件。
• title：主要内容，一般是一段文字，也就是flet.Text控件。
• subtitle：次要内容，一般也是一段文字，也就是flet.Text控件。
• trailing：后缀内容，一般是一个下拉选项卡，也就是flet.PopupMenuButton控件。
• content_padding：设置四个部分之间的间隙。该参数的值应当是一个flet.padding.中包含的函数，包括以下几种：
  • flet.padding.all(宽度)：设置四周间隙，等价于直接设置一个值。
  • flet.padding.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
  • flet.padding.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
• dense：默认是否折叠。
• is_three_line：是否三行式显示，如果该参数为True，那么subtitle参数不能为空。
• toggle_inputs：点击该项目时切换内部的flet.Radio、flet.Checkbox、flet.Switch控件的状态。
• url：将ListTile设为可点击的，并设置目标URL。
• url_target：设置打开URL的方式，可选：
  • _blank：新标签页。
  • _self：当前标签页。

如果ListTile是可点击的，那么容器还可以设置额外的触发事件：

• on_click：容器被点击时触发的函数。
• on_long_press：容器被长按时触发的函数。

网格列表（GridView）

一个多个小方块组成的网格。

所有实例属性都可以在实例化参数中提供，这包括：

• auto_scroll：布尔值，是否自动滚动到底部。
• controls：控件列表，每个控件都应该是flet.Text的实例。
• horizontal：以竖直方向为主轴排列控件，默认水平方向为主轴。
• spacing：主轴间隔。
• run_spacing：副轴间隔。
• runs_count：每组控件数量。
• child_aspect_ratio：内部控件的长宽比。
• max_extent：内部控件的最大长或宽。
• padding：设置控件四周的空隙。该参数的值应当是一个flet.padding.中包含的函数，包括以下几种：
  • flet.padding.all(宽度)：设置四周间隙，等价于直接设置一个值。
  • flet.padding.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
  • flet.padding.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
• scroll_to()：滚动页面到特定位置，可以是offset=设置的绝对位置，可以是delta=设置的排列方式，也可以是key=设置的指定控件。
• on_scroll：滚动时触发的函数。
  • on_scroll_interval：触发滚动事件（on_scroll）的间隔。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。

数据表（DataTable）

一个带有表头的，数据友好的列表。

所有实例属性都可以在实例化参数中提供，这包括：

• columns：表头列表。每个元素都应该是一个flet.DataColumn对象，它的实例化参数如下：
  • label：表头内容。
  • numeric：该列是否是纯数字列。
  • tooltip：表头的解释性内容。
• rows：每行的数据内容。每个元素都应该是一个flet.DataRow对象，它的实例化参数如下：
  • cells：该行的数据格列表，它的元素数量必须和columns的严格一致，每个元素都应该是一个flet.DataCell对象，它的实例化参数如下：
    • content：该格的数据内容。应当是一个flet.Text或flet.Dropdown对象。
    • placeholder：如果为True，则该格为空。
    • show_edit_icon：为该格显示编辑图标，如果该参数为True，那么必须设置on_tab事件处理函数。
  • color：该行颜色。
  • selected：该行是否已被选中。
• bgcolor：背景色。
• border：表格边线。该参数的值应当是一个flet.border.中包含的函数，包括以下几种：
  • flet.border.all(宽度, 颜色)：设置四周边框。
  • flet.border.symmetric(vertical=flet.border.BorderSide(宽度, 颜色), horizontal=flet.border.BorderSide(宽度, 颜色))：分别设置垂直和水平方向的边框。
  • flet.border.only(left|right|top|bottom=flet.border.BorderSide(宽度, 颜色))：只设置上下左右的边框。
• border_radius：表格圆角。该参数的值应当是一个flet.border_radius.中包含的函数，包括以下几种：
  • flet.border_radius.all(弧度)：设置四周圆角。
  • flet.border_radius.horizontal(left=弧度, right=弧度)：设置水平方向的圆角。
  • flet.border_radius.vertical(top=弧度, bottom=弧度)：设置垂直方向的圆角。
  • flet.border_radius.only=top_left|top_right|bottom_left|bottom_right=弧度：只设置四角之一的圆角。
• column_spacing：列间隔。
• divider_thickness：行间隔厚度。
• data_row_color：数据行填充色。
• data_row_min_height：数据行最小高度。
• data_row_max_height：数据行最大高度。
• data_text_style：数据行字体样式，应当是一个flet.TextStyle实例。
• heading_row_color：表头填充色。
• heading_row_height：表头高度。
• heading_text_style：表头字体样式。
• horizontal_lines：行间隔线的样式，应当是一个flet.BorderSide实例。
• vertical_lines：列间隔线的样式，应当是一个flet.BorderSide实例。
• horizontal_margin：表格上下的间隔。
• show_bottom_border：显示末尾边界线。
• show_checkbox_column：为可选择的行显示一个额外的勾选控件。
• sort_ascending：逆向排序。
• sort_column_index：排序主键列。

可触发事件如下：

• DataColumn：
  • on_sort：排序时触发。
• DataRow：
  • on_long_press：长按触发。
  • on_select_changed：选中/取消选中触发。如果设置了这一选项，那么该行会变得可以被选中。
• DataCell：
  • on_tap：点击时触发。
  • on_double_tap：双击时触发。
  • on_long_press：长按时触发。
  • on_tap_down：按下时触发。
  • on_tap_cancel：取消按下时触发。

选项卡（Tabs）

同一视图内的轻量级分页控件。

所有实例属性都可以在实例化参数中提供，这包括：

• tabs：选项卡列表。每个元素都应当是一个flet.Tab实例，它的实例化参数如下：
  • text：选项卡标题。
  • icon：选项卡的图标，应当是一个flet.icons.下属的对象。
  • tab_content：不是text和icon中任何一个的选项卡样式。
  • content：选项卡的布局与内容。
• selected_index：默认选择的选项卡。
• unselected_label_color：未选择的选项卡颜色。
• scrollable：选项卡可滚动。
• animation_duration：切换动画的延迟。
• divider_color：分界线的颜色。
• indicator_color：下划线颜色。
• indicator_padding：下划线间隔。
• indicator_tab_size：下划线充满整个选项卡。
• label_color：选中的选项卡的颜色。
• overlay_color：设置动效颜色。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。

可触发事件如下：

• on_change：切换选项卡时触发。

水平分界线（Divider）

一个简单的水平线。

所有实例属性都可以在实例化参数中提供，这包括：

• color：线的颜色。
• height：线所处的虚拟方格的高度，默认为16。
• thichness：线的粗细，默认为0。
• leading_indent：开头间隔，默认为0.0。
• trailing_indent：末尾间隔，默认为0.0。

垂直分界线（VerticalDivider）

一个简单的水平线。

所有实例属性都可以在实例化参数中提供，这包括：

• color：线的颜色。
• width：线所处的虚拟方格的宽度，默认为16。
• thichness：线的粗细，默认为0。
• leading_indent：开头间隔，默认为0.0。
• trailing_indent：末尾间隔，默认为0.0。

导航类（Navigation）

顶部导航栏（AppBar）

一个简洁的，Material风格的顶部导航栏。如果当前View是的路由是/，那么它不会显示“返回”按钮，否则会在最左方自动显示一个返回按钮。

所有实例属性都可以在实例化参数中提供，这包括：

• leading：前导部分，一般是一个图标或一个选项，也就是flet.Image或flet.Radio、flet.Checkbox、flet.Switch控件。
• title：主要内容，一般是一段文字，也就是flet.Text控件。
• actions：后缀内容，在标题后显示的控件列表，每个元素都应该是一个flet.IconButtons或flet.PopupMenuButton实例。
• title_spacing：主要部分两侧的间隔。如果希望尽可能使用所有空间，设为0.0。
• automatically_imply_leading：设为True，则在前导部分为空时自动把标题前移。
• center_title：标题居中。
• bgcolor：背景色。
• color：字体色。
• leading_width：前导部分高度，默认为56.0。
• toolbar_height：主要部分高度，默认为56.0。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。
• shadow_color：阴影颜色。
• surface_tint_color：表层颜色。

实例化的AppBar应当被设为view.appbar的值。

侧导航栏（NavigationDrawer）

侧导航栏。

所有实例属性都可以在实例化参数中提供，这包括：

• bgcolor：背景色。
• controls：导航栏中显示的子控件列表，列表的元素可以是以下两类之一：
  • flet.NavigationDrawerDestination的实例。它的实例化参数如下：
    • bgcolor：背景色。
    • icon：使用的图标名称。
    • icon_content：手动设置使用的图标，必须是一个flet.Icon实例。
    • label：图标下的标题名称。
    • selected_icon：选中时改变的图标。
    • selected_icon_content：手动设置选中时改变的图标，必须是一个flet.Icon实例。
  • flet.Divider的实例。
• elevation：底部的阴影深度。
• indicator_color：下划线颜色。
• selected_index：默认情况下选中的选项索引，可以是一个数字或None，-1表示未选中。
• shadow_color：阴影颜色。
• surface_tint_color：表层颜色。
• open：是否显示该导航栏。

选项切换通过触发实现，事件如下：

• on_change：切换选项时触发，函数应当以一个e对象为入参，e.control.selected_index表示目标选项的索引。
• on_dismiss：关闭导航栏时触发。

侧轨道（NavigationRail）

一个优雅的侧轨道。

所有实例属性都可以在实例化参数中提供，这包括：

• leading：前导部分，一般是一个图标或一个选项，也就是flet.Image或flet.Radio、flet.Checkbox、flet.Switch控件。
• destinations：跳转的目标列表。每个元素都应该是一个flet.NavigationRailDestination的实例，它的实例化参数如下：
  • icon：使用的图标名称。
  • icon_content：手动设置使用的图标，必须是一个flet.Icon实例。
  • label：图标下的标题名称。
  • label_content：手动设置图标下的标题，必须是一个flet.Text实例。
  • padding：四周间隔。该参数的值应当是一个flet.padding.中包含的函数，包括以下几种：
    • flet.padding.all(宽度)：设置四周间隙，等价于直接设置一个值。
    • flet.padding.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
    • flet.padding.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
  • selected_icon：选中时改变的图标。
  • selected_icon_content：手动设置选中时改变的图标，必须是一个flet.Icon实例。
• trailing：后缀内容，一般是一个下拉选项卡，也就是flet.PopupMenuButton控件。
• extended：设为True，则默认为展开状态。
• bgcolor：背景色。
• group_alignment：垂直排列方式，-1.0表示从顶部开始排列，1.0表示从底部开始排列。
• label_type：默认情况下标签状态，可选的值包括：
  • flet.NavigationRailLabelType.NONE：一个也不展开。
  • flet.NavigationRailLabelType.ALL：全部展开。
  • flet.NavigationRailLabelType.SELECTED：选中的展开。
• selected_index：默认情况下选中的选项索引，可以是一个数字或None。
• min_width：最小宽度，默认为72。
• min_extended_width：最小展开宽度，默认为256。

选项切换通过触发实现，事件如下：

• on_change：切换选项时触发，函数应当以一个e对象为入参，e.control.selected_index表示目标选项的索引。

底部导航栏（NavigationBar）

一个典型的，移动端风格的底部导航栏。

所有实例属性都可以在实例化参数中提供，这包括：

• destinations：跳转的目标列表。每个元素都应该是一个flet.NavigationRailDestination的实例，它的实例化参数如下：
  • icon：使用的图标名称。
  • icon_content：手动设置使用的图标，必须是一个flet.Icon实例。
  • label：图标下的标题名称。
  • label_content：手动设置图标下的标题，必须是一个flet.Text实例。
  • padding：四周间隔。该参数的值应当是一个flet.padding.中包含的函数，包括以下几种：
    • flet.padding.all(宽度)：设置四周间隙，等价于直接设置一个值。
    • flet.padding.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
    • flet.padding.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
  • selected_icon：选中时改变的图标。
  • selected_icon_content：手动设置选中时改变的图标，必须是一个flet.Icon实例。
• bgcolor：背景色。
• label_behavior：设置标签的状态，必须是flet.NavigationBarLabelBehavior的一个下属对象：
  • flet.NavigationBarLabelBehavior.ALWAYS_SHOW：总是显示。
  • flet.NavigationBarLabelBehavior.ALWAYS_HIDE：总是隐藏。
  • flet.NavigationBarLabelBehavior.ONLY_SHOW_SELECTED：仅在选中时显示。
• selected_index：默认情况下选中的选项索引，可以是一个数字或None。

选项切换通过触发实现，事件如下：

• on_change：切换选项时触发，函数应当以一个e对象为入参，e.control.selected_index表示目标选项的索引。

实例化的NavigationBar应当被设为page.navigation_bar的值。

信息显示类（Information Display）

文本（Text）

一些纯粹的文本。

所有实例属性都可以在实例化参数中提供，这包括：

• value：文本内容。
• style：使用预定义的样式，这包括：
  • flet.TextThemeStyle.DISPLAY_LARGE
  • flet.TextThemeStyle.DISPLAY_MEDIUM
  • flet.TextThemeStyle.DISPLAY_SMALL
  • flet.TextThemeStyle.HEADLINE_LARGE
  • flet.TextThemeStyle.HEADLINE_MEDIUM
  • flet.TextThemeStyle.HEADLINE_SMALL
  • flet.TextThemeStyle.TITLE_LARGE
  • flet.TextThemeStyle.TITLE_MEDIUM
  • flet.TextThemeStyle.TITLE_SMALL
  • flet.TextThemeStyle.LABEL_LARGE
  • flet.TextThemeStyle.LABEL_MEDIUM
  • flet.TextThemeStyle.LABEL_SMALL
  • flet.TextThemeStyle.BODY_LARGE
  • flet.TextThemeStyle.BODY_MEDIUM
  • flet.TextThemeStyle.BODY_SMALL

• size：字号。
• italic：设为True，使用斜体。
• color：字体颜色，可以是#ARGB格式、#RGB格式或flet.colors中定义的别名，默认为#FFFFFF。
• bgcolor：背景色，可以是#ARGB格式、#RGB格式或flet.colors中定义的别名，默认为#FFFFFF。
• font_family：选用字体。
• no_wrap：不进行软换行。
• max_lines：最大行数，超出后会进行截断。
• overflow：超出行数的截断方式，包括：
  • flet.TextOverflow.FADE：渐变隐藏。
  • flet.TextOverflow.ELLIPSIS：显示为省略号。
  • flet.TextOverflow.CLIP：直接剪掉。
  • flet.TextOverflow.VISIBLE：仍然可见。
• selectable：是否可选。
• semantics_label：阅读文本，用于文本阅读器。
• text_align：文本对齐方式，有以下几种：
  • flet.TextAlign.LEFT：左对齐。
  • flet.TextAlign.RIGHT：右对齐。
  • flet.TextAlign.CENTER：居中。
  • flet.TextAlign.JUSTIFY：均匀对齐。
  • flet.TextAlign.START：视文本方向决定，开头对齐。
  • flet.TextAlign.END：与上一个相反。
• weight：字重，这包括：
  • NORMAL
  • BOLD
  • W_100
  • W_200
  • W_300
  • W_400
  • W_500
  • W_600
  • W_700
  • W_800
  • W_900
• spans：文本的富文本属性，它是一个flet.TextSpan对象组成的列表，flet.TextSpan的实例化参数如下：
  • text：文本内容。
  • url：文本对应的链接。点击后会触发on_click事件。
  • url_target：打开链接的方式，有两种：
    • _blank：在新页面打开。
    • _self：在当前页面打开。
  • style：样式，必须是一个flet.TextStyle对象，它的实例化参数如下：
    • bgcolor：背景色。
    • color：字体色。
    • decoration：装饰，包括四种：
      • flet.TextDecoration.NONE：没有装饰。
      • flet.TextDecoration.UNDERLINE：下划线。
      • flet.TextDecoration.OVERLINE：上划线。
      • flet.TextDecoration.LINE_THROUGH：删除线。
    • decoration_color：装饰颜色。
    • decoration_style：装饰样式，包括五种：
      • flet.TextDecorationStyle.SOLID：实线。
      • flet.TextDecorationStyle.DOUBLE：双实线。
      • flet.TextDecorationStyle.DOTTED：点画线。
      • flet.TextDecorationStyle.DASHED：短横线。
      • flet.TextDecorationStyle.WAVY：波浪线。
    • decoration_thickness：装饰厚度。
    • font_family：字体。
    • foreground：前景色，必须是flet.Paint对象。
    • italic：设为True，则使用斜体。
    • size：字号。
    • weight：字重。

TextSpan可触发事件如下：

• on_click：被点击时触发。
• on_enter：接触时触发。
• on_exit：离开时触发。

图标（Icon）

一个Material风格的图标。

所有实例属性都可以在实例化参数中提供，这包括：

• name：使用的图标名称，可以在Icons Browser处查找。
• color：使用的颜色。
• size：图标大小。
• tooltip：悬置在图标上显示的文本。

图片（Image）

一个单纯的本地或远程图片。

所有实例属性都可以在实例化参数中提供，这包括：

• src：文件URL，可以是本地路径，也可以是网络地址。
• sc_base64：图片的BASE64编码，使用这个命令转换：base64 -i image.png -o base64.txt。
• border_radius：给容器背景设置圆角。该参数的值应当是一个flet.border_radius.中包含的函数，包括以下几种：
  • flet.border_radius.all(弧度)：设置四周圆角。
  • flet.border_radius.horizontal(left=弧度, right=弧度)：设置水平方向的圆角。
  • flet.border_radius.vertical(top=弧度, bottom=弧度)：设置垂直方向的圆角。
  • flet.border_radius.only=top_left|top_right|bottom_left|bottom_right=弧度：只设置四角之一的圆角。
• color：将指定颜色与图片混合。
• error_content：图片失效时使用指定Control填充。
• fit：填充方式，有以下几种：
  • flet.ImageFit.NONE：不填充。
  • flet.ImageFit.CONTAIN：缩放填充。
  • flet.ImageFit.COVER：缩放覆盖。
  • flet.ImageFit.FILL：拉伸填满。
  • flet.ImageFit.FIT_HEIGHT：垂直拉伸。
  • flet.ImageFit.FIT_WIDTH：水平拉伸。
  • flet.ImageFit.SCALE_DOWN：仅在图片大于区域时拉伸。
• gapless_playback：是否随源地址更新图片。
• repeat：图片重复方式，有以下几种：
  • flet.ImageRepeat.NO_REPEAT：不重复。
  • flet.ImageRepeat.REPEAT：重复以填满。
  • flet.ImageRepeat.REPEAT_X：重复以填满X轴。
  • flet.ImageRepeat.REPEAT_Y：重复以填满Y轴。

Markdown文本

以指定格式渲染Markdown文本。

所有实例属性都可以在实例化参数中提供，这包括：

• value：Markdown文本的内容。
• auto_follow_links：允许打开文档中的链接。on_tap_link事件会在点击链接时触发。
• auto_follow_links_target：链接的打开方式，有两种选择：
  • _blank：在新标签页中打开。
  • _self：在当前页面中打开。
• selectable：文本是否可选。
• extension_set：设置渲染插件组合，有四种选择：
  • flet.MarkdownExtensionSet.NONE：没有插件。
  • flet.MarkdownExtensionSet.COMMON_MARK：标准插件。
  • flet.MarkdownExtensionSet.GITHUB_WEB：Github Web插件。
  • flet.MarkdownExtensionSet.FLAVORED：Github Flavored插件。
• code_style：文本样式，必须是一个flet.TextStyle实例，实例化参数如下：
  • bgcolor：背景色。
    • color：字体色。
    • decoration：装饰，包括四种：
      • flet.TextDecoration.NONE：没有装饰。
      • flet.TextDecoration.UNDERLINE：下划线。
      • flet.TextDecoration.OVERLINE：上划线。
      • flet.TextDecoration.LINE_THROUGH：删除线。
    • decoration_color：装饰颜色。
    • decoration_style：装饰样式，包括五种：
      • flet.TextDecorationStyle.SOLID：实线。
      • flet.TextDecorationStyle.DOUBLE：双实线。
      • flet.TextDecorationStyle.DOTTED：点画线。
      • flet.TextDecorationStyle.DASHED：短横线。
      • flet.TextDecorationStyle.WAVY：波浪线。
    • decoration_thickness：装饰厚度。
    • font_family：字体。
    • foreground：前景色，必须是flet.Paint对象。
    • italic：设为True，则使用斜体。
    • size：字号。
    • weight：字重。
• code_theme：预定义的语法高亮主题，有以下几种：
  • a11y-dark
  • a11y-light
  • agate
  • an-old-hope
  • androidstudio
  • arduino-light
  • arta
  • ascetic
  • atelier-cave-dark
  • atelier-cave-light
  • atelier-dune-dark
  • atelier-dune-light
  • atelier-estuary-dark
  • atelier-estuary-light
  • atelier-forest-dark
  • atelier-forest-light
  • atelier-heath-dark
  • atelier-heath-light
  • atelier-lakeside-dark
  • atelier-lakeside-light
  • atelier-plateau-dark
  • atelier-plateau-light
  • atelier-savanna-dark
  • atelier-savanna-light
  • atelier-seaside-dark
  • atelier-seaside-light
  • atelier-sulphurpool-dark
  • atelier-sulphurpool-light
  • atom-one-dark-reasonable
  • atom-one-dark
  • atom-one-light
  • brown-paper
  • codepen-embed
  • color-brewer
  • darcula
  • dark
  • default
  • docco
  • dracula
  • far
  • foundation
  • github-gist
  • github (default)
  • gml
  • googlecode
  • gradient-dark
  • grayscale
  • gruvbox-dark
  • gruvbox-light
  • hopscotch
  • hybrid
  • idea
  • ir-black
  • isbl-editor-dark
  • isbl-editor-light
  • kimbie.dark
  • kimbie.light
  • lightfair
  • magula
  • mono-blue
  • monokai-sublime
  • monokai
  • night-owl
  • nord
  • obsidian
  • ocean
  • paraiso-dark
  • paraiso-light
  • pojoaque
  • purebasic
  • qtcreator_dark
  • qtcreator_light
  • railscasts
  • rainbow
  • routeros
  • school-book
  • shades-of-purple
  • solarized-dark
  • solarized-light
  • sunburst
  • tomorrow-night-blue
  • tomorrow-night-bright
  • tomorrow-night-eighties
  • tomorrow-night
  • tomorrow
  • vs
  • vs2015
  • xcode
  • xt256
  • zenburn

可触发事件如下：

• on_tap_link：点击链接时触发事件。

头像（CircleAvatar）

一个简单的圆形头像。

所有实例属性都可以在实例化参数中提供，这包括：

• background_image_src：备用图片。
• content：备用文字。
  • color：字体颜色。
  • bgcolor：背景颜色。
• foreground_image_src：头像图片。
• max_radius：最大大小，默认infinity。
• min_radius：最小大小，默认为0。
• radius：手动设置大小。
• tooltip：悬停时显示的文本。

进度条（ProgressBar）

一个进度条。

所有实例属性都可以在实例化参数中提供，这包括：

• value：进度条的（初始）值，可选值为0.0到1.0，更新该值会使进度条变化。如果设为null，那么这是一个左右跳动的进度条。
• bar_height：进度条宽度。
• color：进度条颜色。
• bgcolor：未填充部分的颜色。
• tooltip：悬停文本。
• border_radius：边框圆角。

进度圈（ProgressRing）

一个圆形的进度条。

所有实例属性都可以在实例化参数中提供，这包括：

• value：进度条的（初始）值，可选值为0.0到1.0，更新该值会使进度条变化。如果设为null，那么这是一个来回跳动的进度条。
• stroke_width：进度条宽度。
• stroke_align：进度条起点的位置，默认为0，即居中。
• stroke_cap：进度条边界风格，必须是flet.StrokeCap.枚举的一个下属对象：
  • flet.StrokeCap.BUTT：平整。
  • flet.StrokeCap.ROUND：半圆。
  • flet.StrokeCap.SQUARE：圆角矩形。
• color：进度条颜色。
• bgcolor：未填充部分的颜色。
• tooltip：悬停文本。

按钮类（Buttons）

悬浮按钮（ElevatedButton）

一个悬浮样式的按钮，适合用于重要选项：

所有实例属性都可以在实例化参数中提供，这包括：

• disabled：设为True，禁用。
• autofocus：是否设为默认焦点。
• bgcolor：背景色。
• color：字体色。
• icon：按钮上显示的图标，应当是一个图标名称。
• icon_color：图标颜色。
• text：按钮上显示的文字。
• content：按钮上显示的控件。
• tooltip：悬置提示。
• url：点击按钮时跳转的URL。点击时会触发on_click事件。
• url_target：打开URL的方式，有两种值：
  • _blank：新标签页。
  • _self：当前标签页。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。

可触发事件如下：

• on_click：被点击时触发。
• on_long_press：长按时触发。
• on_hover：指针接触或离开时触发，函数应当接受一个e对象作为入参，它的data属性在指针接触时为True，离开时为False。

纯色按钮（FilledButton）

一个用鲜艳的纯色填充的按钮，适合用作重要选项：

所有实例属性都可以在实例化参数中提供，这包括：

• disabled：设为True，禁用。
• autofocus：是否设为默认焦点。
• bgcolor：背景色。
• color：字体色。
• icon：按钮上显示的图标，应当接受一个图标名称。
• icon_color：图标颜色。
• text：按钮上显示的文字。
• content：按钮上显示的控件。
• tooltip：悬置提示。
• url：点击按钮时跳转的URL。点击时会触发on_click事件。
• url_target：打开URL的方式，有两种值：
  • _blank：新标签页。
  • _self：当前标签页。

可触发事件如下：

• on_click：被点击时触发。
• on_long_press：长按时触发。
• on_hover：指针接触或离开时触发，函数应当接受一个e对象作为入参，它的data属性在指针接触时为True，离开时为False。

淡色纯色按钮（FilledTonalButton）

一个用较弱色填充的按钮：

所有实例属性都可以在实例化参数中提供，这包括：

• disabled：设为True，禁用。
• autofocus：是否设为默认焦点。
• bgcolor：背景色。
• color：字体色。
• icon：按钮上显示的图标，应当接受一个图标名称。
• icon_color：图标颜色。
• text：按钮上显示的文字。
• content：按钮上显示的控件。
• tooltip：悬置提示。
• url：点击按钮时跳转的URL。点击时会触发on_click事件。
• url_target：打开URL的方式，有两种值：
  • _blank：新标签页。
  • _self：当前标签页。

可触发事件如下：

• on_click：被点击时触发。
• on_long_press：长按时触发。
• on_hover：指针接触或离开时触发，函数应当接受一个e对象作为入参，它的data属性在指针接触时为True，离开时为False。

纯线条按钮（OutlinedButton）

纯线条绘制的按钮，没有填充色，也没什么阴影和悬浮效果：

• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。

纯图标按钮（IconButton）

一个纯图标构成的按钮，没什么好说的。

所有实例属性都可以在实例化参数中提供，这包括：

• selected：如果设置了这一参数，那么按钮会变为开关功能。如果被启用，该属性为True，否则为False。
• selected_icon：表示启用的图标。
• selected_icon_color：表示启用的图标颜色。
• disabled：设为True，禁用。
• autofocus：是否设为默认焦点。
• icon：按钮上显示的图标，应当接受一个图标名称。
• icon_color：图标颜色。
• icon_size：图标大小。
• content：按钮上显示的控件。
• tooltip：悬置提示。
• url：点击按钮时跳转的URL。点击时会触发on_click事件。
• url_target：打开URL的方式，有两种值：
  • _blank：新标签页。
  • _self：当前标签页。
• hover_color：鼠标接触时文本颜色。

可触发事件如下：

• on_click：被点击时触发。
• on_long_press：长按时触发。
• on_hover：指针接触或离开时触发，函数应当接受一个e对象作为入参，它的data属性在指针接触时为True，离开时为False。

纯文字按钮（TextButton）

一个纯文字构成的按钮，鼠标不接触就不会有高亮：

所有实例属性都可以在实例化参数中提供，这包括：

• disabled：设为True，禁用。
• autofocus：是否设为默认焦点。
• icon：按钮上显示的图标，应当接受一个图标名称。
• icon_color：图标颜色。
• text：按钮上显示的文字。
• content：按钮上显示的控件。
• tooltip：悬置提示。
• url：点击按钮时跳转的URL。点击时会触发on_click事件。
• url_target：打开URL的方式，有两种值：
  • _blank：新标签页。
  • _self：当前标签页。

可触发事件如下：

• on_click：被点击时触发。
• on_long_press：长按时触发。
• on_hover：指针接触或离开时触发，函数应当接受一个e对象作为入参，它的data属性在指针接触时为True，离开时为False。

纯图标按钮（IconButton）

一个纯图标构成的按钮，没什么好说的。

所有实例属性都可以在实例化参数中提供，这包括：

• selected：如果设置了这一参数，那么按钮会变为开关功能。如果被启用，该属性为True，否则为False。
• selected_icon：表示启用的图标。
• selected_icon_color：表示启用的图标颜色。
• disabled：设为True，禁用。
• autofocus：是否设为默认焦点。
• icon：按钮上显示的图标，应当接受一个图标名称。
• icon_color：图标颜色。
• icon_size：图标大小。
• content：按钮上显示的控件。
• tooltip：悬置提示。
• url：点击按钮时跳转的URL。点击时会触发on_click事件。
• url_target：打开URL的方式，有两种值：
  • _blank：新标签页。
  • _self：当前标签页。

可触发事件如下：

• on_click：被点击时触发。
• on_long_press：长按时触发。
• on_hover：指针接触或离开时触发，函数应当接受一个e对象作为入参，它的data属性在指针接触时为True，离开时为False。

悬浮动态按钮（FloatingActionButton）

一个在窗口上位置固定的按钮，适合用于“回到顶部”这样的功能：

所有实例属性都可以在实例化参数中提供，这包括：

• disabled：设为True，禁用。
• autofocus：是否设为默认焦点。
• bgcolor：背景色。
• color：字体色。
• icon：按钮上显示的图标，应当接受一个图标名称。
• icon_color：图标颜色。
• text：按钮上显示的文字。
• content：按钮上显示的控件。
• tooltip：悬置提示。
• url：点击按钮时跳转的URL。点击时会触发on_click事件。
• url_target：打开URL的方式，有两种值：
  • _blank：新标签页。
  • _self：当前标签页。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。

可触发事件如下：

• on_click：被点击时触发。
• on_long_press：长按时触发。
• on_hover：指针接触或离开时触发，函数应当接受一个e对象作为入参，它的data属性在指针接触时为True，离开时为False。

弹出菜单按钮（PopupMenuButton）

一个经典的带有弹出式菜单的按钮：

所有实例属性都可以在实例化参数中提供，这包括：

• icon：手动设置按钮的图标，而不是三个点。
• content：手动设置按钮上显示的控件。
• items：菜单项列表，每个元素都必须是flet.PopupMenuItem的实例，它的实例化参数如下：
  • icon：菜单项图标。
  • text：菜单项文字。
  • check：菜单项上带有勾选框。
  • content：手动设置菜单项内容控件。
  • padding：内容间的间隔。
  • 还有一个可触发事件：
    • on_click：该菜单项被点击时触发。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。
• shadow_color：阴影颜色。
• surface_tint_color：表层颜色。
• bgcolor：背景色。
• elevation：底部的阴影深度。
• enable_feedback：是否在长按时提供震动反馈。
• icon_color：图标颜色。
• icon_size：图标大小。
• padding：内容间的间隔。

可触发事件有：

• on_cancel：取消时触发。
• on_open：打开时触发。

输入与选项（Input & Selections）

多选框（Checkbox）

可以多选的选项框。

• autofocus：是否设为默认焦点。
• check_color：打勾的颜色。
• fill_color：填充色。
• label：标签。
• label_position：标签位置，有两个个可选值：
  • flet.LabelPosition.RIGHT
  • flet.LabelPosition.LEFT
• value：当前的状态，可选True和False。
• tristate：该多选框为三态多选框，值可以是None。

可触发事件有：

• on_change：状态改变时触发。
• on_focus：获得焦点时触发。
• on_blur：失去焦点时触发。

单选框（Radio）

一组只能选其中一个的选项列表。

你必须先使用flet.RadioGroup分组：

• value：组内的选项列表，每一个元素都是flet.Radio的实例。

flet.Radio的所有实例属性都可以在实例化参数中提供，这包括：

• autofocus：设为默认焦点。
• fill_color：设置填充色。
• hover_color：鼠标接触时文本颜色。
• label：设置标签文字。
• label_position：标签位置，有两个个可选值：
  • flet.LabelPosition.RIGHT
  • flet.LabelPosition.LEFT
• value：选中时，给flet.RadioGroup设置的值。
• toggleable：该选项是否可以进行选择。
• overlay_color：设置动效颜色。

flet.RadioGroup有以下可触发事件：

• on_change：发生变化时触发。

flet.Radio有以下可触发事件：

• on_blur：失去焦点时触发。
• on_focus：获得焦点时触发。

下拉列表框（Dropdown）

可以进行单选的下拉列表框。

所有实例属性都可以在实例化参数中提供，这包括：

• alignment：选项之间的间隔。
• autofocus：设为默认焦点。
• color：文本颜色。
• bgcolor：背景色。
• border：边框样式。可选值有：
  • flet.InputBorder.OUTLINE：四周边框。
  • flet.InputBorder.UNDERLINE：下划线边框。
  • flet.InputBorder.NONE：无边框。
• border_color：边框颜色。
• border_radius：边框圆角。
• border_width：边框宽度。
• content_padding：文本与边框的间隔。
• counter_text：在下方显示一个文本。
• dense：文本部分是否紧密分布。
• icon：显示的图标。
• label：在上边框显示的类型文本。
• hint_text：没有选择时显示的提示文本。
• helper_text：在下边框上显示的帮助文本。
• error_text：选择不合适时显示的错误提示文本，非空时会覆盖helper_text。
• filled：使用颜色填充该控件。
• focused_color：焦点时文本颜色。
• focused_bgcolor：焦点时背景颜色。
• focused_border_width：焦点时边框宽度。
• focused_border_color：焦点时边框颜色。
• prefix_icon：添加一个前缀图标。
• prefix_text：添加用户不可修改的前缀文本。
• prefix：在输入部分之前显示的前缀控件。
• suffix_icon：添加一个后缀图标。
• suffix_text：添加用户不可修改的后缀文本。
• text_size：文本大小。
• text_style：文本样式。
• value：当前选择值。
• options：选项列表，每一个元素都必须是一个flet.dropdown.Option对象，它的实例化参数如下：
  • alignment：显示文本在内部的分布，可以是以下几种值：
    • flet.alignment.top_left
    • flet.alignment.top_center
    • flet.alignment.top_right
    • flet.alignment.center_left
    • flet.alignment.center
    • flet.alignment.center_right
    • flet.alignment.bottom_left
    • flet.alignment.bottom_center
    • flet.alignment.bottom_right
  • key：选项的键。默认为text的值。
  • text：选项的显示文本。默认为key的值。
  • 可触发事件如下：
    • on_click：点击时触发。

可用方法：

• focus()：获取焦点。

可触发事件有：

• on_change：状态改变时触发。
• on_focus：获得焦点时触发。
• on_blur：失去焦点时触发。

滑动条（Slider）

一个可以用于选值的滑动条。

所有实例属性都可以在实例化参数中提供，这包括：

• autofocus：设为默认焦点。
• active_color：可用时的颜色。
• inavtive_color：不可用时的颜色。
• divisions：离散分段数。如果不设置，那么滑动条是非离散的。
• label：显示的提示文本，必须包含{value}格式化内容。
• max：最大值。
• min：最小值。
• thumb_color：滑块颜色。
• value：当前的值。
• interaction：滑动条的交互方式，值必须是一个flet.SliderInteraction下属的对象：
  • flet.SliderInteraction.TAP_AND_SLIDE：可以点击或滑动。
  • flet.SliderInteraction.TAP_ONLY：只能点击。
  • flet.SliderInteraction.SLIDE_ONLY：只能滑动。
  • flet.SliderInteraction.SLIDE_THUMB：不仅只能滑动，而且只能滑动锚点。
• overlay_color：设置动效颜色。

有以下可触发事件：

• on_blur：失去焦点时触发。
• on_change：发生改变时触发。
• on_focus：获得焦点时触发。

开关（Switch）

一个简单的Material风格的开关。

所有实例属性都可以在实例化参数中提供，这包括：

• autofocus：设为默认焦点。
• active_color：可用时的颜色。
• track_color：可用时的轨道颜色。
• thumb_color：可用时的滑块颜色。
• inavtive_color：不可用时的颜色。
• inactive_track_color：不可用时的轨道颜色。
• inactive_thumb_color：可用时的滑块颜色。
• overlay_color：设置动效颜色。
• hover_color：鼠标接触时文本颜色。
• label：显示的提示文本。
• label_position：标签位置，有两个个可选值：
  • flet.LabelPosition.RIGHT
  • flet.LabelPosition.LEFT
• value：当前值。

可触发事件如下：

• on_blur：失去焦点时触发。
• on_change：发生改变时触发。
• on_focus：获得焦点时触发。

输入框（TextField）

一个Material风格的输入框。

所有实例属性都可以在实例化参数中提供，这包括：

• autocorrect：自动纠正。默认开启。
• enable_suggestions：启用文本提示。
• can_reveal_password：显示一个显示密码按钮。
• capitalization：自动进行大写转换。有四种选项：
  • flet.TextCapitalization.NONE：不转换。
  • flet.TextCapitalization.CHARACTERS：转换所有字符。
  • flet.TextCapitalization.WORDS：转换每个单词的第一个字符。
  • flet.TextCapitalization.SENTENCES：转换每个段落的第一个字符。
• autofocus：获得默认焦点。
• color：文本色。
• bgcolor：背景色。
• border：边框样式。可选值有：
  • flet.InputBorder.OUTLINE：四周边框。
  • flet.InputBorder.UNDERLINE：下划线边框。
  • flet.InputBorder.NONE：无边框。
• border_radius：边框圆角。
• border_width：边框宽度。
• content_padding：文本与边框的间隔。
• cursor_height：指针高度。
• cursor_width：指针宽度。
• cursor_color：指针颜色。
• cursor_radius：指针圆角。
• counter_text：在下方显示一个文本。
• dense：文本部分是否紧密分布。
• icon：显示的图标。
• label：在上边框显示的类型文本。
• hint_text：没有选择时显示的提示文本。
• helper_text：在下边框上显示的帮助文本。
• error_text：输入不合适时显示的错误提示文本，非空时会覆盖helper_text。
• filled：使用颜色填充该控件。
• hover_color：鼠标接触时文本颜色。
• focused_color：焦点时文本颜色。
• focused_bgcolor：焦点时背景颜色。
• focused_border_width：焦点时边框宽度。
• focused_border_color：焦点时边框颜色。
• selection_color：选中部分颜色。
• keyboard_type：输入类型，有以下几个选择：
  • flet.KeyboardType.TEXT：默认，文本。
  • flet.KeyboardType.MULTILINE：多行文本。
  • flet.KeyboardType.NUMBER：纯数字。
  • flet.KeyboardType.PHONE：电话号码。
  • flet.KeyboardType.DATETIME：日期。
  • flet.KeyboardType.EMAIL：电子邮件。
  • flet.KeyboardType.URL：URL。
  • flet.KeyboardType.VISIBLE_PASSWORD：可视密码。
  • flet.KeyboardType.NAME：名字。
  • flet.KeyboardType.STREET_ADDRESS：地址。
  • flet.KeyboardType.NONE：空。
• max_length：最大字符数。
• max_lines：最大行数。默认为1。
• min_lines：最小行数。默认为1。
• multiline：设为True则允许多行输入。
• shift_enter：使用Shift + Enter换行。
• password：设为True则隐藏输入。
• prefix_icon：添加一个前缀图标。
• prefix_text：添加用户不可修改的前缀文本。
• prefix：在输入部分之前显示的前缀控件。
• suffix_icon：添加一个后缀图标。
• suffix_text：添加用户不可修改的后缀文本。
• read_only：是否只读文本。
• smart_dashes_type：允许平台自动补全破折号。默认开启。
• smart_quotes_type：允许平台自动补全引号。默认开启。
• text_align：文本对齐方式，有以下几种：
  • flet.TextAlign.LEFT：左对齐。
  • flet.TextAlign.RIGHT：右对齐。
  • flet.TextAlign.CENTER：居中。
  • flet.TextAlign.JUSTIFY：均匀对齐。
  • flet.TextAlign.START：视文本方向决定，开头对齐。
  • flet.TextAlign.END：与上一个相反。
• text_size：文本大小。
• text_style：文本样式。
• value：当前值。
• focus()：获取焦点。

有以下可触发事件：

• on_blur：失去焦点时触发。
• on_change：发生改变时触发。
• on_focus：获得焦点时触发。
• on_submit：提交时（按下Enter）触发。

模态对话框（Dialogs）

警告对话框（AlertDialog）

一个模态的警告对话框。

所有实例属性都可以在实例化参数中提供，这包括：

• title：标题控件。一般是flet.Text。
• title_padding：标题间隔。
• content：显示的内容，一般来说是flet.Text。
• content_padding：控件到边框的间隔。
• modal：点击空白区域关闭对话框。
• actions：在对话框中显示的动作按钮，一般来说，是flet.TextButton。
• actions_alignment：按钮分布方式，有五种值：
  • flet.CrossAxisAlignment.START：从最左侧开始排列。
  • flet.CrossAxisAlignment.CENTER：从中央向两侧开始排列。
  • flet.CrossAxisAlignment.END：从最右侧开始排列。
  • flet.CrossAxisAlignment.STRETCH：水平拉伸填满页面。
  • flet.CrossAxisAlignment.BASELINE：按照字符基线对齐。
• actions_paadding：设置按钮到文本的间隔。
• open：对话框处于打开状态时，为True。
• shape：对话框的边框类型，有以下几种选项：
  • flet.StadiumBorder：两边是半圆，上下是直线。
  • flet.RoundedRectangleBorder：圆角矩形。
  • flet.CircleBorder：圆形。
  • flet.BeveledRectangleBorder：直角矩形。
  • flet.ContinuousRectangleBorder：尖角-圆角渐变转换的矩形。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。
• shadow_color：阴影颜色。
• surface_tint_color：表层颜色。

可触发事件如下：

• on_dismiss：关闭时触发。

上横幅（Banner）

没什么可说的：

所有实例属性都可以在实例化参数中提供，这包括：

• actions：在对话框中显示的动作按钮列表，一般来说，每个元素都是flet.TextButton实例，这个参数必须存在。
• content：显示的内容，一般来说是flet.Text实例。
• content_padding：控件到边框的间隔。
• force_actions_below：强制让按钮放在文本下方。默认情况下会自动安排位置在下方或右方。
• leading：横幅图标，一般是flet.Icon控件实例，大小建议为40。
• leading_padding：图标间隔。
• color：横幅的背景色。
• open：默认为False，打开时为True。
• margin：设置背景四周的空隙。该参数的值应当是一个flet.margin.中包含的函数，包括以下几种：
  • flet.margin.all(宽度)：设置四周间隙。
  • flet.margin.symmetric(vertical=宽度, horizontal=宽度)：设置水平或垂直方向的间隙。
  • flet.margin.only(left|right|top|bottom=宽度)：单独设置上下左右的间隙。
• elevation：底部的阴影深度。
• divider_color：分界线的颜色。
• shadow_color：阴影颜色。
• surface_tint_color：表层颜色。

底部表单（BottomSheet）

一个很有Material特色的底部弹出式表单。

所有实例属性都可以在实例化参数中提供，这包括：

• content：显示的内容，一般来说是flet.Text实例。
• dismissible：点击空白区域关闭。
• enable_drag：可以拉动调整大小。
• show_drag_handle：显示拉动图标。
• open：打开时为True。
• use_safe_area：仅使用安全区。

可触发事件如下：

• on_dismiss：关闭时触发。

底部信息框（SnackBar）

一个很有Material特色的底部弹出信息框。

所有实例属性都可以在实例化参数中提供，这包括：

• content：显示的内容，一般来说是flet.Text实例。
• action：在信息框中显示的动作按钮，比如，撤回或重试，一般来说，是flet.TextButton实例，注意，这个按钮不应该有取消、退出等含义。
• action_color：动作按钮颜色。
• behavior：信息框的行为，有以下几种选项：
  • flet.SnackBarBehavior.FIXED：固定不变。
  • flet.SnackBarBehavior.FLOATING：自动调整。
• bgcolor：背景色。
• show_close_icon：显示关闭图标。
• close_icon_color：关闭图标颜色。
• dismiss_direction：消失方向，默认是flet.DismissDirection.DOWN。
• duration：停留时间，默认为4000ms。
• open：打开时为True，在经过duration时间后，自动设为False。
• elevation：信息框的阴影厚度，或者说Z轴高度。
• margin：信息框周围的空白部分。
• padding：内容间隔。
• width：宽度。
• clip_behavior：设置对内部控件的微调方式，该参数的值只能是以下四种之一：
  • flet.ClipBehavior.NONE：无微调。
  • flet.ClipBehavior.ANTI_ALIAS：抗锯齿。
  • flet.ClipBehavior.ANTI_ALIAS_WITH_SAVE_LAYER：保留图层抗锯齿。
  • flet.ClipBehavior.HARD_EDGE：硬边缘。

可触发事件如下：

• on_action：点击动作按钮时触发。
• on_visible：信息框第一次可见时触发。

时间选择器（TimePicker）

一个Material风格的时间选择器。

所有实例属性都可以在实例化参数中提供，这包括：

• cancel_text：取消按钮的文本，默认为Cancel。
• confirm_text：确认按钮的文本，默认为OK。
• error_invalid_text：输入不合法时的文本，默认为Enter a valid time。
• hour_label_text：时下显示的文本，默认为Hour。
• minute_label_text：分下显示的文本，默认为minute。
• help_text：帮助文本，默认为Enter time。
• orientation：对话框风格，必须是flet.Orientation的一个下属对象：
  • flet.Orientation.PORTRAIT
  • flet.Orientation.LANDSCAPE
• time_picker_entry_mode：使用的输入模式，必须是flet.TimePickerEntryMode的一个下属对象：
  • DIAL：默认使用点击方式。
  • INPUT：默认使用打字方式。
  • DIAL_ONLY：只允许点击。
  • INPUT_ONLY：只允许打字。
• value：默认时间，默认使用当前时间。

可用方法如下：

• pick_time()：打开时间选择对话框。

可触发事件如下：

• on_change：确认时触发，函数应当以一个e为参数，它有以下属性：
  • data：当前选择的时间。
• on_dismiss：关闭时触发。
• on_entry_mode_change：切换输入模式时触发，函数应当以一个e为参数，它是一个flet.TimePickerEntryModeChangeEvent实例，有以下属性：
  • entry_mode：当前的输入模式，是flet.TimePickerEntryMode的一个下属对象。

图表类（Charts）

折线图（LineChart）

一个或是直线，或是曲线组成的折线图。

所有实例属性都可以在实例化参数中提供，这包括：

• data_series：图表中的线条组成的列表，每个元素都必须是flet.LineChartData的实例，它的实例化参数如下：
  • data_point：每个点组成的列表，每个元素都必须是flet.LineChartDataPoint的实例，它的实例化参数如下：
    • x：X坐标。
    • y：Y坐标。
    • selected：在LineChart.interactive为False时，显示当前点。
    • show_tooltip：指针悬停时显示提示信息。
    • tooltip：显示的提示信息，默认为Y坐标。
    • show_above_line：显示上面的垂线。
    • show_below_line：显示下面的垂线。
  • curve：使用曲线而不是折线。
  • color：颜色。
  • stroke_width：线条宽度。
  • stroke_cap_round：使用圆形边缘的线条。
  • dash_pattern：使用虚线，该参数应当是一个二元列表，含义为[长度, 空白部分]。
  • shadow：设置阴影，必须是flet.Shadow实例。
  • above_line：直通最上方的垂线，必须是flet.ChartPointLine实例，它的实例化参数如下：
    • color：颜色。
    • width：粗细。
    • dash_pattern：使用虚线，该参数应当是一个二元列表，含义为[长度, 空白部分]。
  • below_line：直通最下方X轴的垂线，必须是flet.ChartPointLine实例。
  • selected_below_line：自动显示到X轴的垂线。
• animate：动画效果，可以是布尔值，也可以是整数，表示动画时间（毫秒），还可以是flet.Animation实例。
• interactive：是否可以交互。
• bgcolor：背景色。
• tooltip_bgcolor：悬停提示背景色。
• border：边线类型，必须是flet.Border实例。
• horizonal_grid_lines：水平表格样式，必须是flet.ChartGridLines实例，它的实例化参数如下：
  • interval：间隔，默认为1。
  • color：颜色。
  • width：粗细，默认为1。
  • dash_pattern：使用虚线，该参数应当是一个二元列表，含义为[长度, 空白部分]。
• vertical_grid_lines：水平表格样式，必须是flet.ChartGridLines实例。
• left_axis：左轴，必须是一个flet.ChartAxis实例，实例化参数如下：
  • title：标题控件。一般是flet.Text。
  • title_size：标题区域大小。
  • show_labels：显示标签。
  • labels：标签列表，每个元素都必须是flet.ChartAxisLabel实例，实例化参数如下：
    • value：值。
    • label：标签控件，一般是flet.Text，建议大小为14。
  • labels_interval：自动标签之间的间隔。
  • labels_size：标签区域大小，建议大小为32。
• bottom_axis：下轴，必须是一个flet.ChartAxis实例。
• right_axis：右轴，必须是一个flet.ChartAxis实例。
• top_axis：上轴，必须是一个flet.ChartAxis实例。
• baseline_x：X轴基准线。默认为0。
• min_x：X轴最小值，默认为0。
• max_x：X轴最大值。
• baseline_y：Y轴基准线，默认为0。
• min_y：Y轴最小值，默认为0。
• max_y：Y轴最大值，默认为0。

可触发事件如下：

• on_chart_event：在表格被点击或鼠标接触时触发，函数应当以一个e为参数，它是一个flet.LineChartEvent实例，有以下属性：
  • type：事件类型。
  • bar_index：接触的线的索引。如果没有，则为-1。
  • spot_index：接触的点的索引。如果没有，则为-1。

柱状图（BarChart）

柱状统计图。

所有实例属性都可以在实例化参数中提供，这包括：

• bar_groups：图表中的柱组组成的列表，每个元素都必须是flet.BarChartGroup的实例，具体参数如下：
  • x：X轴坐标。
  • bar_rods：柱组中的柱列表，每个元素都必须是flet.BarChartRod实例，它的实例化参数如下：
    • from_y：Y轴起点。
    • to_y：Y轴终点。
    • width：粗细。
    • color：颜色，默认为cyan。
    • border_radius：圆角。
    • border_side：绘制边缘方向，必须是flet.BorderSide实例。
    • bg_from_y：背景起点Y坐标。
    • bg_to_y：背景终点Y坐标。
    • selected：如果BarChart.interactive为False，则显示当前Bar。
    • show_tooltip：显示悬停时的提示文本。
    • tooltip：提示文本。
  • group_vertically：垂直排列柱组。
  • bars_space：Bar间的间隔。
• groups_space：Bar组间间隔。
• animate：动画效果，可以是布尔值，也可以是整数，表示动画时间（毫秒），还可以是flet.Animation实例。
• interactive：是否可以交互。
• bgcolor：背景色。
• tooltip_bgcolor：悬停提示背景色。
• border：边线类型，必须是flet.Border实例。
• horizonal_grid_lines：水平表格样式，必须是flet.ChartGridLines实例，它的实例化参数如下：
  • interval：间隔，默认为1。
  • color：颜色。
  • width：粗细，默认为1。
  • dash_pattern：使用虚线，该参数应当是一个二元列表，含义为[长度, 空白部分]。
• vertical_grid_lines：水平表格样式，必须是flet.ChartGridLines实例。
• left_axis：左轴，必须是一个flet.ChartAxis实例，实例化参数如下：
  • title：标题控件。一般是flet.Text。
  • title_size：标题区域大小。
  • show_labels：显示标签。
  • labels：标签列表，每个元素都必须是flet.ChartAxisLabel实例，实例化参数如下：
    • value：值。
    • label：标签控件，一般是flet.Text，建议大小为14。
  • labels_interval：自动标签之间的间隔。
  • labels_size：标签区域大小，建议大小为32。
• bottom_axis：下轴，必须是一个flet.ChartAxis实例。
• right_axis：右轴，必须是一个flet.ChartAxis实例。
• top_axis：上轴，必须是一个flet.ChartAxis实例。
• baseline_x：X轴基准线。默认为0。
• min_x：X轴最小值，默认为0。
• max_x：X轴最大值。
• baseline_y：Y轴基准线，默认为0。
• min_y：Y轴最小值，默认为0。
• max_y：Y轴最大值，默认为0。

可触发事件如下：

• on_chart_event：在表格被点击或鼠标接触时触发，函数应当以一个e为参数，它是一个flet.LineChartEvent实例，有以下属性：
  • type：事件类型。
  • bar_index：接触的线的索引。如果没有，则为-1。
  • spot_index：接触的点的索引。如果没有，则为-1。

饼图（PieChart）

一个简单的饼图。

所有实例属性都可以在实例化参数中提供，这包括：

• animate：动画效果，可以是布尔值，也可以是整数，表示动画时间（毫秒），还可以是flet.Animation实例。
• center_space_color：中央部分颜色。
• center_space_radius：中央部分大小。
• sections_space：段间隔线大小。
• start_degree_offset：起点偏移量。
• sections：各段组成的列表，每个元素都必须是flet.PieChartSection实例，实例化参数如下：
  • value：值，单位为占比。
  • radius：半径。
  • color：颜色。
  • border_side：边缘类型。必须是flet.BorderSide实例。
  • title：标题。
  • title_style：标题样式。
  • title_position：标题位置，是一个浮点数。表示到中心距离。
  • badge：一个在段上额外绘制的控件。
  • badge_position：控件位置，是一个浮点数。

可触发事件如下：

• on_chart_event：在表格被点击或鼠标接触时触发，函数应当以一个e为参数，它是一个flet.LineChartEvent实例，有以下属性：
  • type：事件类型。
  • section_index：如果没有鼠标接触，那么为-1。

Matplotlib图（MatplotlibChart）

一个由Matplotlib转换而来的表格。这是一个额外的模块，使用flet.matplotlib_chart.MatplotlibChart调用。

所有实例属性都可以在实例化参数中提供，这包括：

• figure：绘制的Matplotlib对象，这一对象应当使用fig, ax = plt.subplots()函数创建。
  • plt.subplots()函数是创建画板的函数，它会返回两个对象，第一个是画板对象，第二个是绘制的图形对象列表。可以在第二个参数上执行ax[0].plot()，ax[0].setxim()，ax[0].setyin()，ax[0].setxlabel()，ax[0].setylabel()，ax[0].grid()函数。
• isolated：默认情况下，每次更新页面时，图表都需要进行更新，这会影响性能，该属性可以设置独立更新，也就是必须单独调调用图表控件的.update()方法才会更新。
• original_size：不调整图表大小。
• transparent：设置透明。

Plotly图（Plotly）

一个由Matplotlib转换而来的表格。这是一个额外的模块，使用flet.plotly_char.PlotlyChart调用。

所有实例属性都可以在实例化参数中提供，这包括：

• figure：绘制的Plotly对象。
• original_size：不调整图表大小。
• isolated：默认情况下，每次更新页面时，图表都需要进行更新，这会影响性能，该属性可以设置独立更新，也就是必须单独调调用图表控件的.update()方法才会更新。

动画效果（Animation）

动态切换器（AnimatedSwitcher）

一个在不同控件之间进行动态切换的控件。

所有实例属性都可以在实例化参数中提供，这包括：

• content：（初始）控件。
• duration：动画时长。
• switch_in_curve：切入使用的动画类型，必须是flet.AnimationCurve的实例。
• switch_out_curve：切出使用的动画类型，必须是flet.AnimationCurve的实例。
• transition：切换动画类型，必须是flet.AnimatedSwitcherTransition实例。

其他实用工具（Utility）

选择区（SelectionArea）

大部分Flet控件默认都是不能选择并进行交互的，flet.SelectionArea可以提供这一能力，只需要将控件包含在它的内部。

所有实例属性都可以在实例化参数中提供，这包括：

• content：内部控件。如果你希望包含更多控件，那么这个控件往往是flet.Row、flet.Column或flet.Stack这些具备controls属性的控件。

可触发事件如下：

• on_change：点击时触发。

音乐播放器（Audio）

一个在后台播放音乐的控件。它是不可见的，必须使用page.overlay.append()方法添加到page.overlay中。

所有实例属性都可以在实例化参数中提供，这包括：

• balance：左右声道平衡度，为-1到1的浮点数。
• playback_rate：播放速度。必须是0.5-2的以0.5为跨度的浮点数。
• release_mode：释放方式，有三种：
  • flet.ReleaseMode.RELEASE：释放所有资源，就和调用.release()方法一样。
  • flet.ReleaseMode.LOOP：保留目前的播放状态，并进行循环。
  • flet.ReleaseMode.STOP：仅仅只是暂停。
• src：指定音频的URL。
• src_base64：指定音频文件的BASE64编码。
• volume：设置音量。

它还支持以下方法：

• get_current_position()：获取当前播放位置。
• get_duration()：获取音频总时长。
• pause()：暂停。
• play()：从头开始播放。
• release()：解构释放播放器。
• resume()：继续播放。
• seek(position)：跳转到指定毫秒位置。

可触发事件如下：

• on_duration_changed：音乐时长改变时触发。函数应当以一个e实例为参数，它的data属性表示音频的时长。
• on_loaded：音频被夹加载时触发。
• on_position_changed：播放位置改变时触发。
• on_seek_complete：寻址完成时触发。
• on_state_changed：播放状态变化时触发。函数应当以一个e实例为参数，它的data属性表示播放器的状态，有以下几种：
  • stopped
  • playing
  • paused
  • completed
  • disposed

拖拽（Draggable and DragTarget）

分为两个部分：

可拖拽控件（Draggable）

所有实例属性都可以在实例化参数中提供，这包括：

• content：内部控件。
• content_feedback：拖拽时在指针显示的控件。
• content_when_dragging：拖拽时在原位置显示的控件。
• group：所属组，同一组对应同一个DragTarget。

拖拽目标（DragTarget）

所有实例属性都可以在实例化参数中提供，这包括：

• content：显示的控件。
• group：所属组，对应同一组Draggable。

可触发事件如下：

• on_accept：接收到拖拽控件时触发。函数应当以一个e实例为参数，它是一个DragTargetEvent实例，属性如下：
  • src_id：拖拽控件的ID。
• on_leave：指针离开目标时触发。
• on_will_accept：当接触到目标时触发。函数应当以一个e实例为参数，它的data属性表示是否为同一组，如果时则为True。

文件选择器（FilePicker）

建议使用page.overlay.append()添加到page.overlay中。

所有实例属性都可以在实例化参数中提供，这包括：

• allowed_extensions：仅仅允许选择指定后缀的文件，应当是一个列表。
• file_type：仅仅允许选择指定类型的文件，可选择项目如下：
  • flet.FilePickerFileType.ANY：默认，任何类型。
  • flet.FilePickerFileType.IMAGE：图片。
  • flet.FilePickerFileType.VIDEO：视频。
  • flet.FilePickerFileType.MEDIA：图片和视频。
  • flet.FilePickerFileType.AUDIO：音频。
  • flet.FilePickerFileType.CUSTOM：使用allowed_extensions列表。
• allow_multiple：允许选中多个文件。
• dialog_title：对话框标题。
• file_name：仅在保存文件时有效，保存文件名。
• initial_directory：初始目录。
• result：选择文件或目录后该项才会被设置，该项的值是一个flet.FilePickerResultEvent实例，它的属性如下：
  • path：保存文件的情况下，文件路径。
  • files：选择文件的情况下，文件列表，每个元素都是flet.FilePickerFile实例，它的属性如下：
    • name：文件名。
    • path：文件的绝对路径。
    • size；文件大小。

可用方法如下：

• get_directory_path(dialog_title, initial_directory)：获取目录的绝对路径。
• pick_files(dialog_title, initial_directory, file_type, allowed_extensions, allow_multiple)：开始选择文件。
• save_file(dialog_title, initial_directory, file_type, allowed_extensions, allow_multiple)：开始保存文件。
• upload(upload_list)：上传选中的文件。upload_list是一个文件列表，每个元素都是flet.FilePickerUploadFile实例，它的实例化参数如下：
  • name：文件名。
  • upload_url：上传URL，可以通过page.get_upload_url(name, 600)获取。

可触发事件如下：

• on_result：关闭对话框时触发。函数应当以一个e实例为参数，它是一个flet.FilePickerResultEvent实例。
• on_upload：上传时触发。函数应当以一个e实例为参数，它是一个flet.FilePickerUploadEvent实例。它的属性如下：
  • file_name：文件名。
  • progress：进度。
  • error：发生的错误。

悬停提示（Tooltip）

一个带有悬停提示的控件。

所有实例属性都可以在实例化参数中提供，这包括：

• content：显示的控件。
• message：悬停提示文本。
• bgcolor：提示文本背景色。
• border：边框类型。
• border_radius：边框圆角半径。
• enable_feedback：提供音效。
• height：提示框高度。
• margin：文本周围空白。
• padding：内容间的间隔。
• prefer_below：强制显示在下方。
• shape：提示文本框的形状。
• show_duration：显示时间。
• text_align：文本对齐方式，有以下几种：
  • flet.TextAlign.LEFT：左对齐。
  • flet.TextAlign.RIGHT：右对齐。
  • flet.TextAlign.CENTER：居中。
  • flet.TextAlign.JUSTIFY：均匀对齐。
  • flet.TextAlign.START：视文本方向决定，开头对齐。
  • flet.TextAlign.END：与上一个相反。
• text_style：文本样式。
• vertical_offset：垂直偏移量。
• wait_duration：悬停等待时间。

摇晃侦测器（ShakeDetector）

检测设备摇晃。它是不可见的，必须使用page.overlay.append()方法添加到page.overlay中。

所有实例属性都可以在实例化参数中提供，这包括：

• minimum_shake_count：最小摇晃次数。
• shake_count_reset_time_ms：超时间隔。
• shake_slop_time_ms：每次摇晃之间的间隔。
• shake_threshold_gravity：视为摇晃的阈值。

可触发事件如下：

• on_shake：摇晃时触发。

拖拽区域（WindowDragArea）

拖拽窗口的区域。在隐藏标题栏的情况下很有用。

所有实例属性都可以在实例化参数中提供，这包括：

• content：用于拉取/最大化/恢复窗口的控件。
• maximizable：是否可以用于最大化。

用户自定义控件

0.20.0-

用户可以继承flet.UserControl来创建可复用的自定义控件。用户控件可以基于其他已有控件构建。

控件必须实现build(self)方法，它是控件的界面构建方法，应当返回一个Control实例。flet.UserControl类继承自flet.Stack，因此多个子控件默认将堆叠在一起显示。如果希望以某种方式排列控件，必须使用布局控件将其进行包含。例如：

class MyControl(flet.UserControl):
	def build(self):
		return flet.Column([
			flet.Text('This is my control!')
		])

用户控件的任何操作都只能在用户控件内进行，例如打开模态对话框：

class MyControl(flet.UserControl):
	def build(self):
		def open_dialog(e):
			self.page.show_dialog(flet.AlertDialog(title=Text('Dialog!')))

		return flet.Column([
			flet.FilledButton(text=flet.Text('This is my control!'), on_clicked=open_dialog)
		])

用户控件与外部布局隔离，即当父控件的update()方法被调用时，用户控件内部的任何更改都不会被更新。如果用户控件希望将更新推送到页面，必须显式调用self.update()方法：

class MyControl(flet.UserControl):
	def __init__(self):
		# 必须执行父类的构造函数
		super().__init__()
		self.control = flet.Column(controls=[
			flet.Text('This is my control!')
		])

	def build(self):
		return self.control

	def add_control(self):
		self.control.controls.append(flet.Text('New line!'))
		self.update()

我们当然可以将事件处理器函数，或是控件引用定义为类的成员。但是，我们也可以直接将其写在build(self)函数中：

class MyControl(flet.UserControl):
	def build(self):
		def click(e):
			...

		return flet.Column(controls=[
			flet.ElevatedButton('Click!', on_click=click)
		])

• 需要注意的是，counter不能声明为build(self)函数的局部变量，必须被声明为类属性self.counter。

用户控件中可以传递自定义数据，只需要重载构造函数即可：

class MyControl(flet.UserControl):
	def __init__(self, _my_attr):
		super().__init__()
		self.my_attr = _my_attr

• 切记调用super().__init__()。

Flet还给用户控件提供了两种默认的钩子方法：

• did_mount()：在用户控件被添加到页面后调用。
• will_unmount()：在用户控件从页面中被删除之前调用。

0.20.0+

0.20.0以后的版本中，Flet重新设计了用户自定义控件的定义方法。现在，UserControl类已经废弃，用户只需要直接继承一个基础控件：

class MyControl(flet.Column):
	def build(self):
		self.controls.append([
			flet.Text('This is my control!')
		])

build()方法现在也不能返回任何东西了，而是应该直接修改继承自父控件的controls列表属性。

另外：

• 现在可以使用before_update()方法定义在页面更新之前触发的行为。
• did_mount()和will_unmount()方法被保留，而且添加了异步支持。

异步化

Flet应用天然支持asyncio等异步模块的协程，而不需要我们将其进行包装。

默认情况下，Flet 使用threading库在单独的线程中运行用户会话并执行事件处理程序，但是在等待HTTP响应或执行sleep()时，这可能会导致CPU的效率低下。

要切换为使用异步模式，首先需要将main()函数使用异步声明：

async def main(page: flet.Page):
	...

此外，在main()函数中，不能再使用page.add()等同步的页面方法，而必须使用_async()结尾的替代品，例如：

• page.add()→await page.add_async()
• page.update()→await page.update_async()
• page.clean()→await page.clean_async()
• 等等。

事件处理器

事件处理器函数可以是同步的也可以是异步的。如果它们不调用任何异步方法，那就可以是同步的，但是如果它调用了异步逻辑，那就必须是异步的。例如：

async def main(page: flet.Page):
	async def button_click(e):
		await page.add_async(flet.Text('Hello World!'))

而且特别需要注意的是，Python不支持异步Lambda函数，因此对于异步的事件处理器函数，必须特别声明出来。

等待

在异步Flet应用中，必须使用asyncio.slee()而不是time.sleep()进行等待。

线程

从技术上讲，不应该在异步应用程序中使用threading模块。要在后台运行某些内容，先使用async def定义一个异步方法。然后调用page.run_task()方法执行：

def main(page: flet.Page):
	var = 0
	async def background_task():
		var +=1

	page.run_task(page.background_task)

也可以通过page.loop获取当前的事件循环。

ASGI应用

0.21.0以后，Flet支持将应用导出为ASGI应用，并通过Uvicorn、Hypercorn或Daphne运行。只需要在代码中添加：

APP名称 = flet.App(main, export_asgi_app=True)

然后执行：

uvicorn|hypercorn 代码:APP名称

即可。

构建工具

create

flet create --project-name 项目名称 --description 描述  --template minimal|counter [-v] 目录

• 换源：默认使用Github托管的模板，要添加镜像，编辑site-packages/flet/cli/commands/create.py，修改：

  cookiecutter(
      template='https://mirror.ghproxy.com/https://github.com/flet-dev/flet-app-templates',
      ...
  )

run

flet run [-p 端口] [--name 程序名称] 脚本路径

其他选项如下：

• -m：视为模块运行。
• -p：监听端口。
• -d：监听脚本目录。
• -r：递归监听。
• -w：动态Web运行。
• -a ASSETS_DIR：资源路径。
• -n：隐藏窗口。

和普通的python解释器解释执行的区别是，该工具会进行热重载，很方便调试。

pack

使用pyinstaller进行打包。该操作依赖pyinstaller。

flet pack [-D] [-i 图标] [-n 名称] [--dispath 保存位置] [--add-data 其他添加的文件] [--hidden-import 其他导入的模块] [--company-name 署名] 脚本路径

• -D：不打包为单文件（Windows）。
• --distpath 目录名称：保存打包产物的目录。

选项如下：

MacOS：

• --product-name 名称：显示在Dock的名称。
• --product-version 版本号：关于对话框中的版本信息。
• --copyright 版权：关于对话框中的版权信息。
• --bundle-id ID：唯一的包ID。

Windows：

• --product-name 名称：程序名称。
• --product-version 版本号：程序版本信息。
• --copyright 版权：程序版权信息。
• --file-description 描述：程序描述。
• --file-version 版本号：文件版本。

publish

flet publish 项目目录 [-a 资源路径] [--pre] [--dispath 保存位置] [--app-name 名称] [--app-short-name 短名称] [--app-description 描述] [--base-url 根URL] [--web-renderer canvaskit|html] [--use-color-emoji] [--route-url-strategy path|hash]

在没有Flutter SDK的情况下导出静态页面文件。这会在访问时动态下载Python模块，比较慢。

• --pre：允许micropip安装预发布的Python包。
• --distpath 目录名称：保存打包产物的目录。

静态页面使用WASM（Pyodide）运行，性能和兼容性较差，但是方便了部署。

build

调用Flutter SDK进行编译。编译要求目录至少有以下结构：

assets/
    icon.png
main.py
requirements.txt或pyproject.toml

• 其中，main.py代表着Flet应用的入口程序，也就是执行flet.app(target=main)的程序。
• requirements.txt或pyproject.toml用于确定编译时的依赖，优先使用requirements.txt。
• 最简单的办法是直接执行flet create 应用名。
• assets/icon.png会用于所有平台的图标，如果希望设置平台特定图标，使用icon_平台名.png。
• assets/splash.png会用于所有平台的加载海报，如果希望设置平台特定图标，使用splash_平台名.png。
• Windows平台需要Visual Studio 2019+，并且安装C++工具链。
• Android平台需要Android SDK和Android Studio。
• Web平台需要设置CHROME_EXECUTABLE环境变量。

然后需要安装Flutter SDK并确保flutter和dart命令行工具在PATH变量中：Index of /flutter/flutter_infra_release/releases/stable/。

flet build [macos|linux|windows|web|apk|ipa] [Python解释器路径] --template https://mirror.ghproxy.com/https://github.com/flet-dev/flet-build-template [--module-name main.py] [-o|--output 目录名] [--include-packages 包名] [--base-url 根URL] [--web-renderer canvaskit|html] [--use-color-emoji] [--route-url-strategy path|hash]

• --module-name main.py：入点程序，默认为main.py。
• -o 目录名称：生成应用的目录名，默认为build。
• --include-packages 包名：添加额外的包，这包括：
  • Audio控件对应的flet_audio。
  • AudioRecorder控件对应的flet_audio_recorder。
  • Lottie控件对应的flet_lottie。
  • Rive控件对应的flet_rive。
  • Video控件对应的flet_video。
  • WebView控件对应的flet_webview。
• --no-web-splash：针对Web平台禁用海报。
• --no-android-splash：针对安卓平台禁用海报。
• --no-ios-splash：针对iOS平台禁用海报。
• --base-url /：根URL。
• --web-renderer canvaskit|html]：Web渲染方式。
• --use-color-emoji：在ConvasKit中启用彩色Emoji。
• --route-url-strategy path|hash：路由策略。
• --build-number 数字：构建次数。
• --build-version x.y.z：构建版本。
• --project 名称：生成的文件名称。
• --product 名称：程序名称。
• --description 描述：程序描述。
• --org 反向域名：组织名称。
• --company 公司名：公司名称。
• --copyright 版权：程序版权信息。
• --show-platform-matrix：检测当前平台能不能编译成功，然后立刻退出。