在 Flet 应用中嵌入网页内容WebView 控件的安装、事件体系与平台适配全指南【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/fletWebView 是 Flet 官方扩展flet-webview提供的一个布局控件用于在 Flet 应用中直接渲染并交互网页内容。本文以 WebView 官方文档 为核心结合仓库内flet-webview扩展的 Python 与 Flutter 两侧源码完整讲解其平台支持、安装方式、核心属性、事件与异步方法以及 Android 明文流量问题的排查思路帮助你在纯 Python 代码中快速集成网页浏览能力。WebView 是什么flet-webview是 Flet 的一个扩展包它封装了 Flutter 生态中成熟的 webview_flutterFlutter 桥接实现位于 sdk/python/packages/flet-webview/src/flutter/flet_webview。从 Python 侧看WebView继承自ft.LayoutControl并通过装饰器ft.control(WebView)注册为 Flet 控件因此它可以像其他布局控件一样参与页面排版、设置expand等布局属性见 webview.py。平台支持原文档给出明确的平台支持矩阵平台WindowsmacOSLinuxiOSAndroidWeb支持情况❌✅❌✅✅✅也就是说WebView目前仅支持 iOS、Android、macOS 以及 Web 四个平台。这一结论在 Flutter 侧源码中也能得到印证在 webview.dart 的WebViewControl.build中按平台分发渲染组件——Web 平台使用WebviewWeb移动端与 macOS 桌面端使用WebviewMobileAndMac而 Windows 与 Linux 桌面端则直接返回ErrorControl并提示Webview is not yet supported on this platform.。同时需要注意即便是支持平台能力也不完全对等详见后文“事件”与“方法”两节例如on_scroll事件仅在 iOS 和 Android 上可用macOS 因底层webview_flutter不暴露滚动回调而不可用见 webview_mobile_and_mac.dart。安装在项目依赖中加入flet-webview即可使用uvuv add flet-webview使用pippip install flet-webview # (1)!安装完成后需要手动将该包添加到项目的requirements.txt或pyproject.toml中以便依赖可复现。安装后包会在 Flutter 侧引入webview_flutter移动端/macOS与webview_flutter_webWeb作为底层渲染引擎见 flet_webview/pubspec.yamlAndroid/iOS 等平台会自动注册对应的原生插件。快速开始加载一个网页仓库自带的可运行示例位于 sdk/python/examples/extensions/web_view/web_view/main.py完整代码如下import flet as ft import flet_webview as fwv def main(page: ft.Page): page.add( ft.SafeArea( expandTrue, contentfwv.WebView( urlhttps://flet.dev, on_page_startedlambda _: print(Page started), on_page_endedlambda _: print(Page ended), on_web_resource_errorlambda e: print(WebView error:, e.data), expandTrue, ), ) ) if __name__ __main__: ft.run(main)要点说明url是 WebView 初始化时加载的页面地址三个事件回调分别监听页面开始加载、加载结束与资源加载出错外层用ft.SafeArea(expandTrue)包裹避免内容侵入移动端状态栏/刘海区域并让 WebView 撑满可用空间ft.run(main)与普通 Flet 应用完全一致无需任何前端代码。核心属性WebView暴露了三个用于配置的属性定义见 webview.py属性类型说明urlOptional[str]要加载的网页 URL。支持file://本地文件 URL但仅限 iOS、Android、macOS此时会加载该文件同级的资源脚本、样式表、图片等价于控件挂载后用load_file()加载同一文件在 Web 平台上只有浏览器允许在 iframe 中加载的 URL 才能正常显示prevent_linksOptional[list[str]]URL 前缀列表命中这些前缀的链接将不被跳转、加载或下载bgcolorOptional[ft.ColorValue]WebView 的背景色prevent_links的拦截逻辑在 Flutter 侧通过NavigationDelegate.onNavigationRequest实现当导航目标 URL 以列表中任一前缀开头时返回NavigationDecision.prevent否则放行见 webview_mobile_and_mac.dart 与 同文件 L127-L131。利用它可以方便地实现“禁止跳出应用”或“阻止下载某些资源”等场景。bgcolor在构建时会通过controller.setBackgroundColor下发到原生 WebView见 同文件 L248-L252。事件体系WebView共提供 8 个事件回调覆盖页面生命周期、资源加载、URL 变化、滚动、控制台与弹窗等维度。除on_scroll外其余事件的Event.data均为字符串或整数事件数据内容可用平台on_page_startedstr页面 URLiOS、Android、macOSon_page_endedstr页面 URLiOS、Android、macOSon_web_resource_errorstr错误信息iOS、Android、macOSon_progressint加载进度值iOS、Android、macOSon_url_changestr新 URLiOS、Android、macOSon_scrollWebViewScrollEventiOS、Androidon_console_messageWebViewConsoleMessageEventiOS、Android、macOSon_javascript_alert_dialogWebViewJavaScriptEventiOS、Android、macOS其中三个事件携带结构化数据类型定义于 types.pyWebViewScrollEvent包含x、y两个float字段分别表示以 WebView 左边缘、上边缘为原点的水平与垂直滚动偏移WebViewConsoleMessageEvent包含message写入控制台的消息与severity_level日志严重级别类型为LogLevelSeverityWebViewJavaScriptEvent包含message页面弹窗要显示的文本与url发起弹窗请求的页面 URL。这些结构化的滚动、控制台与弹窗事件在 Flutter 侧经由triggerEvent回传滚动位置来自setOnScrollPositionChange控制台消息来自setOnConsoleMessage含消息文本与级别名弹窗请求来自setOnJavaScriptAlertDialog见 webview_mobile_and_mac.dart。页面级事件则统一由NavigationDelegate派发onPageStarted→page_started、onPageFinished→page_ended、onWebResourceError→web_resource_error、onProgress→progress、onUrlChange→url_change。异步方法控制 WebView 行为除属性与事件外WebView提供 19 个async方法用于主动控制页面。这些方法全部通过_invoke_method桥接到 Flutter 侧的原生WebViewController方法分派见 webview_mobile_and_mac.dart。方法清单如下方法说明reload()重新加载当前 URLcan_go_back() - bool是否存在后退历史项can_go_forward() - bool是否存在前进历史项go_back()后退一步前提是can_go_back()为Truego_forward()前进一步前提是can_go_forward()为Trueenable_zoom()启用屏幕缩放控件与手势缩放disable_zoom()禁用屏幕缩放控件与手势缩放clear_cache()清除 WebView 使用的全部缓存浏览器 HTTP 缓存、Cache API 缓存、应用缓存clear_local_storage()清除 WebView 使用的本地存储get_current_url() - Optional[str]获取当前显示页面的 URL从未加载过则返回Noneget_title() - Optional[str]获取当前页面的标题get_user_agent() - Optional[str]获取 HTTPUser-Agent:请求头的值load_file(path)加载本地文件path为绝对路径load_request(url, methodGET)发起 HTTP 请求并将响应加载到 WebView 中file://URL 会按本地文件方式加载此时method被忽略load_html(value, base_urlNone)加载 HTML 字符串base_url用于解析其中的相对 URL若为file://URL 则其引用的本地文件会对 WebView 可读run_javascript(value)在当前页面上下文中执行给定 JavaScript 代码scroll_to(x, y)滚动到指定像素坐标scroll_by(x, y)按指定像素增量滚动set_javascript_mode(mode)设置 JavaScript 执行模式默认在首次加载前应用JavaScriptMode.UNRESTRICTED方法平台校验上述方法在 Python 侧均先调用_check_mobile_or_mac_platform()做平台校验若控件尚未挂载到页面self.page is None会抛出RuntimeError若运行于 Web 平台或非 Android/iOS/macOS 平台则会抛出FletUnsupportedPlatformException见 webview.py。因此这些控制方法仅适用于 iOS、Android、macOS 三个原生平台。常用方法与参数load_html是加载动态 HTML 内容的便捷入口base_url参数允许指定file://URL 作为相对路径基准Flutter 侧在检测到该场景时会先调用allowFileAccess(controller)为原生 WebView 授予本地文件读取权限再调用loadHtmlString见 webview_mobile_and_mac.dart。load_request支持显式指定 HTTP 方法配合RequestMethod枚举使用见下文适用于需要以 POST 方式提交并展示结果的场景。配套类型与枚举flet_webview包定义了 2 个枚举与 3 个事件数据类均位于 types.py它们的文档页分别位于 website/docs/controls/webview/types 目录JavaScriptMode—— 控制 WebView 中的 JavaScript 支持状态UNRESTRICTEDJavaScript 执行不受限制默认值首次加载前生效DISABLED禁用 JavaScript 执行。禁用 JavaScript 可能导致页面行为异常该模式可通过set_javascript_mode()在运行时切换。RequestMethod——load_request()可用的 HTTP 方法GETHTTP GETPOSTHTTP POST。LogLevelSeverity—— 控制台消息的日志级别与 JavaScript 控制台方法一一对应ERRORconsole.error产生的错误消息WARNINGconsole.warning产生的警告消息DEBUGconsole.debug产生的调试消息INFOconsole.info产生的信息消息LOGconsole.log产生的普通日志消息。底层实现细节文件访问与 JavaScript 默认值深入 Flutter 侧实现可以解释两个容易踩坑的细节file://本地文件的正确打开方式_load()方法会将file:协议的 URL 专门路由到WebViewController.loadFile而不是loadRequest。原因在于loadFile是唯一能授予平台 WebView 访问本地文件系统能力的入口在 Android 上它会开启WebSettings.allowFileAccess该选项在 targetSdk 30 时默认为false在 iOS/macOS 上则使用loadFileURL:allowingReadAccessToURL:以便同级的脚本、样式表、图片等资源能够被解析。如果对file://URL 直接使用loadRequest在 Android 上会得到net::ERR_ACCESS_DENIED错误见 webview_mobile_and_mac.dart。Android 上 JavaScript 默认关闭Android 的WebSettings.javaScriptEnabled默认为false与 WKWebView、Web 平台不同若不处理页面脚本会静默失效。因此 Flutter 侧在首次加载前会先执行setJavaScriptMode(JavaScriptMode.unrestricted)之后才通过_load发起首次页面加载后续可通过set_javascript_mode随时关闭见 webview_mobile_and_mac.dart。故障排查Android 的 NET::ERR_CLEARTEXT_NOT_PERMITTED在 Android 上如果遇到NET::ERR_CLEARTEXT_NOT_PERMITTED错误说明应用正在尝试访问一个通过明文未加密方式传输信息的网页。出于保护用户数据的目的Android 默认禁止应用这样做。解决办法是修改应用的 manifest 配置具体来说是 manifest application 属性允许明文流量。在 Flet 项目中通过pyproject.toml的[tool.flet.android.manifest_application]段即可完成[tool.flet.android.manifest_application] usesCleartextTraffic true该配置最终会写入 AndroidManifest.xml 中application标签的android:usesCleartextTraffictrue属性。需要说明的是这只应在确实需要访问 HTTP 明文站点时启用因为它会降低传输层安全性更安全的做法是仅在开发环境使用或通过网络安全配置Network Security Config为特定域名单独放行。更详尽的发布配置可参考 Android 发布指南。参考资料官方控件文档website/docs/controls/webview/index.md扩展包说明sdk/python/packages/flet-webview/README.mdPython 控件源码sdk/python/packages/flet-webview/src/flet_webview/webview.py类型与事件定义sdk/python/packages/flet-webview/src/flet_webview/types.pyFlutter 桥接实现sdk/python/packages/flet-webview/src/flutter/flet_webview/lib/src/webview_mobile_and_mac.dart可运行示例sdk/python/examples/extensions/web_view/web_view/main.py类型文档目录website/docs/controls/webview/types【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
