Flet中文文档

主题

在你的 Flet 应用中，用 WebView 显示网页内容。

它由 Flutter 的 webview_flutter 和 webview_flutter_web 包提供支持。

平台支持 ​

平台WindowsmacOSLinuxiOSAndroidWeb
支持❌✅❌✅✅✅

用法 ​

把 flet-webview 添加到项目依赖中：

uv

bash
uv add flet-webview

pip

bash
pip install flet-webview  [^1]

[^1]: 之后你需要手动把这个包添加到 requirements.txt 或 pyproject.toml 中。

示例 ​

python
import flet as ft
import flet_webview as fwv


def main(page: ft.Page):
    page.add(
        ft.SafeArea(
            expand=True,
            content=fwv.WebView(
                url="https://flet.dev",
                on_page_started=lambda _: print("Page started"),
                on_page_ended=lambda _: print("Page ended"),
                on_web_resource_error=lambda e: print("WebView error:", e.data),
                expand=True,
            ),
        )
    )


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

故障排查 ​

NET::ERR_CLEARTEXT_NOT_PERMITTED 错误 ​

如果你在 Android 上遇到 NET::ERR_CLEARTEXT_NOT_PERMITTED 错误， 说明你正在使用的应用试图访问一个想要传输明文（未加密）信息的网页。 Android 会阻止应用这样做，以避免用户数据被泄露。

更多细节见此处 和此处。

要修复它，需要修改你应用的配置 （确切地说是清单应用属性）， 如下所示：

pyproject.toml

toml
[tool.flet.android.manifest_application]
usesCleartextTraffic = "true"

描述 ​

WebView 继承自：ft.LayoutControl, Control, BaseControl

轻松加载网页，同时允许用户交互。

注意： 仅在以下平台上受支持：iOS、Android、macOS 和 Web。 关于 Windows 和 Linux 支持，请订阅此 issue。

属性 ​

名称类型默认值说明
urlOptional[str]None要加载的网页 URL。 注意： 指向本地文件的 file:// URL 仅在以下平台上受支持：iOS、Android 和 macOS。它还会加载该文件的同级静态资源（脚本、样式表、图片），效果等同于在此控件挂载后用同一文件调用 load_file。在 Web 上，只有浏览器能在 iframe 中加载的 URL 才有效。
prevent_linksOptional[list[str]]None不应被跟随/加载/下载的 url 前缀列表。
bgcolorOptional[ft.ColorValue]None定义 WebView 的背景色。
widthOptional[Number]None控件的强制宽度（以虚拟像素为单位）。
heightOptional[Number]None控件的强制高度（以虚拟像素为单位）。
leftOptional[Number]None子控件左边缘相对于 Stack 左侧的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。
topOptional[Number]None子控件上边缘相对于 Stack 顶部的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。
rightOptional[Number]None子控件右边缘相对于 Stack 右侧的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。
bottomOptional[Number]None子控件下边缘相对于 Stack 底部的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。
alignOptional[Alignment]None控件在其父级中的对齐方式。
marginOptional[MarginValue]None设置控件的外边距。
rotateOptional[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) )
scaleOptional[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) )
offsetOptional[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)
flipOptional[Flip]None水平方向和/或垂直方向翻转此控件。 设为 Flip 的实例即可沿 x 轴、y 轴或两者镜像翻转。
transformOptional[Transform]None对此控件应用通用矩阵变换。 设为带 Matrix4 记录的 Transform 实例，用以描述任意的变换序列。
aspect_ratioOptional[Number]None控件的宽高比，定义为 width 与 height 的比值。 注意： 在当前实现中，如果设置了 aspect_ratio，同一控件上的 width 和 height 将在最终渲染尺寸中被忽略。
animate_opacityOptional[AnimationValue]None启用 opacity 属性的隐式动画。 更多信息见此处。
animate_sizeOptional[AnimationValue]None启用此控件尺寸的隐式动画。 如果设置了 width 或 height，则这些维度的变化会以动画呈现。如果两者都未设置，则对控件自然尺寸的变化进行动画。 更多信息见此处。
animate_positionOptional[AnimationValue]None启用定位属性（left、right、top 和 bottom）的隐式动画。 更多信息见此处。
animate_alignOptional[AnimationValue]None启用 align 属性的隐式动画。 更多信息见此处。
animate_marginOptional[AnimationValue]None启用 margin 属性的隐式动画。 更多信息见此处。
animate_rotationOptional[AnimationValue]None启用 rotate 属性的隐式动画。 更多信息见此处。
animate_scaleOptional[AnimationValue]None启用 scale 属性的隐式动画。 更多信息见此处。
animate_offsetOptional[AnimationValue]None启用 offset 属性的隐式动画。 更多信息见此处。
size_change_intervalint10on_size_change 事件的采样间隔（毫秒）。 设为 0 时，每次变化都会立即调用 on_size_change。
expandAnnotated[Optional[Union[bool, int]], V.instance_of((bool, int))]None指定此控件是否／如何扩展以填满父布局中的可用空间。 更多信息见此处。 注意： 仅当此控件的直接父级是以下控件或其子类时才生效：Column、Row、View、Page。 抛出异常： ValueError：如果它不是 bool 或 int 类型。
expand_looseboolFalse允许控件在主轴方向有可用空间时扩展，但不要求它填满所有可用空间。 更多信息见此处。 注意： 如果 expand_loose 为 True，则仅在以下条件满足时才生效： - expand 不为 None，且 - 此控件的直接父级是以下控件或其子类之一：Column、Row、View、Page。
colResponsiveNumber12如果此控件的父级是 ResponsiveRow，则此属性决定该控件在屏幕上跨越多少虚拟列。 可以是一个数字，也可以是一个按断点配置不同值的字典，例如 col={"sm": 6}。 值为 0 时会在该断点隐藏控件，因此它不会占用父级 ResponsiveRow 中的任何列。 此控件默认跨越 12 个虚拟列。 | 断点 | 尺寸 | |---|---| | xs | <576px | | sm | ≥576px | | md | ≥768px | | lg | ≥992px | | xl | ≥1200px | | xxl | ≥1400px |
opacityAnnotated[Number, V.between(0.0, 1.0)]1.0定义控件的透明度。 取值范围从 0.0（完全透明）到 1.0（完全不透明，无任何透明感）。 抛出异常： ValueError：如果它不在 0.0 到 1.0（含）之间。
tooltipOptional[TooltipValue]None鼠标悬停在此控件上时显示的工具提示。
badgeOptional[BadgeValue]None显示在此控件顶部的徽章。
visibleboolTrue每个控件都有 visible 属性，默认为 True —— 控件会渲染在页面上。将 visible 设为 False 会彻底阻止控件（及其所有子控件，如果有）渲染到页面画布上。隐藏的控件无法通过键盘或鼠标获得焦点或选中，也不会触发任何事件。
disabledboolFalse每个控件都有 disabled 属性，默认为 False —— 控件及其所有子控件都处于启用状态。 注意： 此属性的值会递归向下传播到所有子控件。 示例： 例如，如果你有一个包含多个输入控件的表单，可以通过禁用容器来一并禁用它们： python ft.Column( disabled = True, controls=[ ft.TextField(), ft.TextField() ] )
rtlboolFalse控件的文本方向是否为从右到左（RTL）。
dataAnyskip_任意类型的自定义数据。
keyOptional['KeyValue']None用于在更新之间保持控件标识稳定的键。

只读属性 ​

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

事件 ​

名称类型默认值说明
on_page_startedOptional[ft.ControlEventHandler['WebView']]None当 webview 页面的第一次加载过程刚开始时触发。 事件处理器参数的 data 属性类型为 str，包含该 URL。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
on_page_endedOptional[ft.ControlEventHandler['WebView']]None当 webview 页面的所有加载过程都结束时触发。 事件处理器参数的 data 属性类型为 str，包含该 URL。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
on_web_resource_errorOptional[ft.ControlEventHandler['WebView']]None当加载 webview 页面资源出错时触发。 事件处理器参数的 data 属性类型为 str，包含错误消息。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
on_progressOptional[ft.ControlEventHandler['WebView']]None当 webview 页面的加载进度变化时触发。 事件处理器参数的 data 属性类型为 int，包含进度值。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
on_url_changeOptional[ft.ControlEventHandler['WebView']]None当 webview 页面的 URL 变化时触发。 事件处理器参数的 data 属性类型为 str，包含新的 URL。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
on_scrollOptional[ft.EventHandler[WebViewScrollEvent]]None当网页的滚动位置发生变化时触发。 注意： 仅在以下平台上有效：iOS 和 Android。
on_console_messageOptional[ft.EventHandler[WebViewConsoleMessageEvent]]None当有日志消息写入 JavaScript 控制台时触发。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
on_javascript_alert_dialogOptional[ft.EventHandler[WebViewJavaScriptEvent]]None当网页尝试显示 JavaScript alert() 对话框时触发。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
on_size_changeOptional[EventHandler[LayoutSizeChangeEvent['LayoutControl']]]None当此控件的尺寸发生变化时调用。 size_change_interval 定义此事件的调用频率。
on_animation_endOptional[ControlEventHandler['LayoutControl']]None动画完成时调用。 可用于串联多个动画。 事件处理器参数的 data 属性包含动画名称。 更多信息见此处。

方法 ​

名称类型默认值说明
reload——重新加载当前 URL。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
can_go_backbool—是否存在后退历史项。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 返回： 如果存在后退历史项则返回 True，否则返回 False。
can_go_forwardbool—是否存在前进历史项。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 返回： 如果存在前进历史项则返回 True，否则返回 False。
go_back——如果 can_go_back() 为 True，则在 webview 的历史记录中后退。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
go_forward——如果 can_go_forward 为 True，则在 webview 的历史记录中前进。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
enable_zoom——启用通过屏幕上的缩放控件和手势进行缩放。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
disable_zoom——禁用通过屏幕上的缩放控件和手势进行缩放。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
clear_cache——清除 WebView 使用的所有缓存。会清除以下缓存： - 浏览器 HTTP 缓存 - Cache API 缓存。Service worker 通常使用此缓存。 - Application cache 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
clear_local_storage——清除 WebView 使用的本地存储。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
get_current_urlOptional[str]—获取 WebView 当前显示的 URL；如果从未加载过 URL，则返回 None。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 返回： WebView 当前显示的 URL；如果从未加载过 URL，则返回 None。
get_titleOptional[str]—获取当前已加载页面的标题。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 返回： 当前已加载页面的标题。
get_user_agentOptional[str]—获取用于 HTTP User-Agent: 请求头的值。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 返回： 用于 HTTP User-Agent: 请求头的值。
load_file——加载提供的本地文件。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 参数： path：文件的绝对路径。
load_request——发起一次 HTTP 请求并在 webview 中加载响应。 参数： url：要加载的 URL。file:// URL 会像 load_file 那样作为本地文件加载。 method：要使用的 HTTP 方法。对 file:// URL 会被忽略。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
run_javascript——在当前页面的上下文中运行给定的 JavaScript。 参数： value：要运行的 JavaScript 代码。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。
load_htmlSelf—加载提供的 HTML 字符串。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 参数： value：要加载的 HTML 字符串。 base_url：解析 value 中相对 URL 时使用的基 URL。可以是 file:// URL，此时被引用的本地文件会变得对 webview 可读。
scroll_to——滚动到指定的 webview 像素位置。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 参数： x：滚动位置的 x 坐标。 y：滚动位置的 y 坐标。
scroll_by——按指定的 webview 像素数滚动。 注意： 仅在以下平台上有效：iOS、Android 和 macOS。 参数： x：在 x 轴上滚动的像素数。 y：在 y 轴上滚动的像素数。
set_javascript_mode——设置 WebView 的 JavaScript 模式。 注意： - 仅在以下平台上有效：iOS、Android 和 macOS。 - 在页面上禁用 JavaScript 执行可能导致网页行为异常。 - 默认为 UNRESTRICTED，会在首次页面加载之前应用。 参数： mode：要设置的 JavaScript 模式。
is_isolated——返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
init——在控件实例初始化之后、首次 build / update 循环之前调用。 重写此钩子可在依赖已初始化字段时执行轻量级设置。不要在此处调用 update()。
build——在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。
before_update——每当此控件被更新时都会调用此方法。 注意： 务必不要在此处调用或请求 update()。
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 始终来自框架触发的事件，所以当此方法运行时，通道在两端都已存在。
updateNone—为此控件请求一次 UI 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。

关注我，学习大模型、大数据、Python等热门技术。

footer-banner