Flutter url_launcher 插件实战指南跨平台 URL 启动、平台配置与源码级解析【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages本指南以 Flutter 官方维护的 url_launcher 插件为核心系统讲解如何在 Flutter 应用中通过launchUrl启动https、mailto、tel、sms、file等各类 URL覆盖 iOS / Android / Web / 桌面端的平台配置LSApplicationQueriesSchemes、queries、沙盒 entitlements、URL 编码陷阱、canLaunchUrl的正确用法以及LaunchMode浏览器与 App 内处理的切换。读完本文你将掌握 url_launcher 从最小示例到生产级落地的完整实践方案并能结合仓库源码理解其底层调用链。url_launcher 是 Flutter 官方插件集packages中负责把 URL 交给操作系统处理的核心组件其职责非常聚焦把调用方传入的 URL 原样透传给宿主平台由平台上的默认应用浏览器、邮件客户端、电话、短信、文件管理器等决定如何处理。根据插件 pubspec.yaml 中的平台声明它通过 federated plugin联邦插件架构将 Android、iOS、Linux、macOS、Web、Windows 六个平台的实现分别委托给url_launcher_android、url_launcher_ios、url_launcher_linux、url_launcher_macos、url_launcher_web、url_launcher_windows六个子包顶层url_launcher包只负责统一 API 与平台接口分发。最小可用示例两行代码启动一个 URL在pubspec.yaml中引入依赖后即可直接使用dependencies: url_launcher: ^6.3.2插件要求 Dart SDK^3.10.0、Flutter3.38.0见 pubspec.yaml。官方 README 给出的最小示例封装在 example/lib/basic.dart 中可整体复制运行import package:flutter/material.dart; import package:url_launcher/url_launcher.dart; final Uri _url Uri.parse(https://flutter.dev); void main() runApp( const MaterialApp( home: Material( child: Center( child: ElevatedButton(onPressed: _launchUrl, child: Text(Show Flutter homepage)), ), ), ), ); Futurevoid _launchUrl() async { if (!await launchUrl(_url)) { throw Exception(Could not launch $_url); } }这段代码的核心是顶层函数launchUrl(Uri url)它接收的是Uri对象而非字符串——这是该插件 API 演进的核心变化。从 lib/src/url_launcher_uri.dart 的源码可以看到launchUrl内部做了两件事参数校验如果请求了LaunchMode.inAppWebView或LaunchMode.inAppBrowserView但 URL 的 scheme 不是http/https会直接抛出ArgumentErrorTo use an in-app web view, you must provide an http(s) URL.。平台分发通过UrlLauncherPlatform.instance.launchUrl(...)把 URL 字符串、LaunchOptions由LaunchMode、WebViewConfiguration、BrowserConfiguration、webOnlyWindowName转换而来交给平台接口实现。返回值为Futurebool成功返回true失败时视情况返回false或抛出PlatformException。因此生产代码通常按上面示例那样对false结果做兜底处理如抛出异常或提示用户。各平台支持矩阵官方 README 明确给出了平台支持范围平台AndroidiOSLinuxmacOSWebWindows支持版本SDK 2413.0任意10.15任意Windows 10注意这里的支持指插件本身可运行不代表所有 URL scheme 都能被处理——最终能否打开取决于设备上是否安装了能处理该 scheme 的应用详见下文支持的 URL scheme一节。平台配置让canLaunchUrl返回 true 的关键插件默认可以调用launchUrl但如果你需要调用canLaunchUrl做运行时探测就必须先在宿主工程里完成包可见性/应用可见性配置否则在主流移动平台上会一直返回false。这是官方 README 花费最多篇幅讲解的部分也是新手最容易踩坑的地方。iOS配置LSApplicationQueriesSchemes在 iOS 上任何传给canLaunchUrl的 URL scheme 都必须登记进Info.plist的LSApplicationQueriesSchemes否则查询会直接返回falsekeyLSApplicationQueriesSchemes/key array stringsms/string stringtel/string /array该机制对应 UIKit 的-[UIApplication canOpenURL:]iOS 出于隐私考虑限制应用探测系统内已安装应用未声明的 scheme 一律视为不可用。因此凡是你会传给canLaunchUrl的 schemesms、tel、mailto等都要在此登记。示例工程的 example/ios/Runner/Info.plist 即为配置参考。Android配置queries元素从 Android 11API 30开始系统默认隐藏应用间的包可见性。因此传给canLaunchUrl的任何 scheme 都必须以queries形式声明在AndroidManifest.xml的根元素下否则大多数情况下查询返回false。此外supportsLaunchMode(LaunchMode.inAppBrowserView)的探测也依赖queries声明缺少时会一直返回false。官方示例工程 example/android/app/src/main/AndroidManifest.xml 给出了完整配置!-- Provide required visibility configuration for API level 30 and above -- queries !-- If your app checks for SMS support -- intent action android:nameandroid.intent.action.VIEW / data android:schemesms / /intent !-- If your app checks for call support -- intent action android:nameandroid.intent.action.VIEW / data android:schemetel / /intent !-- If your application checks for inAppBrowserView launch mode support -- intent action android:nameandroid.support.customtabs.action.CustomTabsService / /intent /queries要点归纳queries必须是根元素manifest的直接子元素每探测一个 scheme就声明一条包含android.intent.action.VIEWaction 与对应data android:scheme...的intent需要探测inAppBrowserViewAndroid Custom Tabs时额外声明android.support.customtabs.action.CustomTabsServiceaction 的intent注意示例工程中https的queries声明仅用于该包自身的集成测试integration test真实应用通常不需要因为系统默认对http/https之外的大多数 scheme 限制可见性而对已安装浏览器可见但如果你的集成测试依赖它可参考该文件中的写法。Web浏览器限制Web 端没有上述清单配置但存在浏览器层面的限制URL 启动通常必须由用户手势如点击按钮触发程序自动调用会被浏览器拦截。更详细的 Web 平台说明见 url_launcher_web 包的 limitations 文档。支持的 URL scheme 与运行时探测常用 scheme 一览插件把 URL 原样交给宿主平台处理因此支持哪些 scheme 取决于平台与设备上安装的应用。官方 README 汇总了常用 schemeScheme示例动作https:URLhttps://flutter.dev用默认浏览器打开URLmailto:email address?subjectsubjectbodybodymailto:smithexample.org?subjectNewsbodyNew%20plugin在默认邮件应用中向email address写邮件tel:phone numbertel:1-555-010-999用默认电话应用拨打phone numbersms:phone numbersms:5550101234用默认短信应用向phone number发短信file:pathfile:/home用系统默认关联应用打开文件或目录桌面端支持scheme 是否可用取决于设备上是否有对应的应用。典型反例iOS 模拟器默认没有邮件和电话应用因此无法打开tel:或mailto:链接。canLaunchUrl运行时探测的正确姿势如果需要在运行时确认某个 scheme 是否保证可用例如据此调整 UI决定是否展示某个按钮可以用canLaunchUrlfinal bool canLaunch await canLaunchUrl(Uri.parse(sms:5550101234));但官方 README 明确提醒canLaunchUrl返回false不代表launchUrl一定失败。典型场景Web 应用上canLaunchUrl几乎只对少数假定支持的 scheme如http(s)返回true因为网页永远不允许探测已安装应用移动端如果没有按上文完成queries/LSApplicationQueriesSchemes配置探测也会返回false。从 lib/src/url_launcher_uri.dart 源码可见canLaunchUrl同样是委托UrlLauncherPlatform.instance.canLaunch(...)实现返回true只表示能够确认存在可处理的处理器false则既可能是没有处理器也可能是没有权限查询。因此官方建议在能提供兜底行为时优先直接调用launchUrl并处理失败而不是依赖canLaunchUrl决定是否禁用按钮。例如一个发送反馈邮件的按钮mailto探测失败时不应直接禁用按钮而应改用https打开网页版反馈表单。URL 编码避开Uri.queryParameters的已知 BugURL 必须正确编码尤其是包含空格或特殊字符时。多数情况下Dart 的Uri类 会自动处理编码。但有一个著名例外对于http/https之外的 scheme如mailto、tel构造Uri时不要使用queryParameters命名参数而应使用query参数配合自写的encodeQueryParameters函数。原因是一个已知的 Dart SDK Bugdart-lang/sdk#43838Uri编码查询参数时会把空格转成导致邮件主题等参数解析错误。官方在 example/lib/encoding.dart 中给出了正确写法String? encodeQueryParameters(MapString, String params) { return params.entries .map( (MapEntryString, String e) ${Uri.encodeComponent(e.key)}${Uri.encodeComponent(e.value)}, ) .join(); } // ··· final emailLaunchUri Uri( scheme: mailto, path: smithexample.com, query: encodeQueryParameters(String, String{ subject: Example Subject Symbols are allowed!, }), ); launchUrl(emailLaunchUri);encodeQueryParameters用Uri.encodeComponent逐一对 key 和 value 做组件级编码空格编码为%20而非再以连接。这样Example Subject Symbols are allowed!这样的含空格与的主题也能被邮件客户端正确解析。极少数场景无法用Uri表达的 URL宿主系统可能认为某些 URL 合法但 Dart 的Uri无法解析它们例如非常规格式的字符串。此时需要导入字符串版 APIimport package:url_launcher/url_launcher_string.dart; Futurebool launchUrlString( String urlString, { LaunchMode mode LaunchMode.platformDefault, WebViewConfiguration webViewConfiguration const WebViewConfiguration(), BrowserConfiguration browserConfiguration const BrowserConfiguration(), String? webOnlyWindowName, }) async { /* ... */ } Futurebool canLaunchUrlString(String urlString) async { /* ... */ }字符串版 API 定义在 lib/src/url_launcher_string.dart对外统一从 lib/url_launcher_string.dart 导出。强烈建议只在上述极少数场景使用插件旧版 API 接受字符串传无效 URL 字符串是历史上最常见的报错来源。字符串版对无效 URL 不做任何修正行为完全由平台决定——有的平台会尽力解释有的会直接失败。常规场景一律使用Uri版 API从编译期就保证 URL 合法。桌面端file:scheme先检查文件存在再启动file:scheme 可用于 Windows、macOS、Linux 三个桌面平台。官方 README 建议在调用launchUrl前先确认文件或目录真实存在。示例见 example/lib/files.dartfinal String filePath testFile.absolute.path; final uri Uri.file(filePath); if (!File(uri.toFilePath()).existsSync()) { throw Exception($uri does not exist!); } if (!await launchUrl(uri)) { throw Exception(Could not launch $uri); }要点Uri.file()负责把本地路径正确转换为file:URIuri.toFilePath()可反向还原为文件系统路径做存在性校验。macOS 沙盒注意entitlements 配置macOS 上如果你的应用需要访问沙盒之外的文件必须配置相应的 entitlementsApp Sandbox 权限。这与 Flutter 桌面应用的标准沙盒机制一致应用默认只能访问沙盒内文件跨沙盒访问需要显式声明权限。浏览器 vs 应用内打开LaunchMode详解在部分平台上Web URL 既可以在应用内 WebView 打开也可以在系统默认浏览器打开。默认行为因平台而异且可能随版本变化——因此需要特定模式的应用应显式传入LaunchMode而不是依赖默认行为。LaunchMode枚举定义在 lib/src/types.dart枚举值含义platformDefault交由平台实现决定默认值inAppWebView在应用内 WebView 中加载如 Android WebViewinAppBrowserView在应用内浏览器视图中加载如 Android Custom Tabs、iOS SFSafariViewControllerexternalApplication交给操作系统由其他应用处理externalNonBrowserApplication交给操作系统由其他非浏览器应用处理使用示例await launchUrl( Uri.parse(https://flutter.dev), mode: LaunchMode.inAppBrowserView, );配套配置类针对inAppWebView与inAppBrowserViewlib/src/types.dart 还定义了两个不可变配置类WebViewConfigurationenableJavaScript默认true、enableDomStorage默认true、headers附加请求头默认空。其中headers在 Android 上即使不加载应用内 WebView 也可能生效通过Browser.EXTRA_HEADERSintent extra但并非所有浏览器都支持因此不保证被采用。BrowserConfigurationshowTitle是否显示网页标题默认false适用于inAppBrowserView。模式降级与探测 API平台不支持请求的LaunchMode时会自动降级到受支持的模式通常是platformDefault因此不强制要求先探测。但如果你的业务逻辑必须避免降级可以先用supportsLaunchMode探测if (await supportsLaunchMode(LaunchMode.inAppBrowserView)) { await launchUrl(url, mode: LaunchMode.inAppBrowserView); }对应的 API 与语义均定义在 lib/src/url_launcher_uri.dartsupportsLaunchMode(LaunchMode)当前平台是否支持指定模式closeInAppWebView()关闭此前由launchUrl打开的应用内 WebView仅当supportsCloseForLaunchMode对所用模式返回true时有效supportsCloseForLaunchMode(LaunchMode)指定模式下closeInAppWebView是否可用。Web 端窗口目标launchUrl还有一个 Web 专用参数webOnlyWindowName用于指定启动窗口目标支持标准链接目标名_blank在新标签页打开默认行为、_self在当前标签页打开。注意 Web 浏览器不允许非用户手势触发新窗口/标签页打开这也是前文 Web 限制的底层原因。源码视角API 分层与旧版 API 弃用理解 url_launcher 的源码分层有助于你在升级依赖时快速定位问题对外统一入口lib/url_launcher.dart 仅做导出聚合了legacy_api.dart旧版、types.dart类型与url_launcher_uri.dart新版 URI API。新版 URI APIlib/src/url_launcher_uri.dart 提供launchUrl/canLaunchUrl/closeInAppWebView/supportsLaunchMode/supportsCloseForLaunchMode全部委托UrlLauncherPlatform.instance。旧版字符串 API已弃用lib/src/legacy_api.dart 中的launch/canLaunch/closeWebView均带有Deprecated(Use launchUrl instead)注解并保留 iOSforceSafariVC、universalLinksOnly、statusBarBrightness等历史参数。新代码应迁移到launchUrl。从源码看旧launch仍保留了对 iOS 状态栏亮度statusBarBrightness的兼容处理属于历史包袱不建议新项目使用。Link 组件lib/link.dart 导出LinkWidget实现在 lib/src/link.dart。它在 Web 上渲染为真正的链接在原生平台通过launchUrl打开对于无 scheme 的 URI 会被视为应用内路由名走 Flutter 导航压栈而不是交给浏览器。适合需要语义化链接 原生打开的场景。另外插件的单元测试覆盖了 URI API、字符串 API 与旧版 API 的兼容行为分别位于 test/src/url_launcher_uri_test.dart、test/src/url_launcher_string_test.dart 与 test/src/legacy_api_test.dart阅读这些测试可以帮助你理解各 API 在边界条件下的预期行为端到端集成测试见 example/integration_test/url_launcher_test.dart。实践清单上线前检查要点综合以上内容整理一份可直接对照检查的落地清单入口 API一律使用launchUrl(Uri)传Uri.parse构造的对象仅在无法用Uri表达 URL 时才 importurl_launcher_string.dart使用字符串版 API。iOS 配置所有传给canLaunchUrl的 scheme 登记到Info.plist的LSApplicationQueriesSchemes。Android 配置所有传给canLaunchUrl的 scheme 在AndroidManifest.xml根元素下声明queries需要探测inAppBrowserView时声明 Custom Tabs 的queries。探测策略能提供兜底就优先launchUrl 失败处理别让canLaunchUrl的false直接禁用功能。URL 编码非http(s)scheme 的查询参数用encodeQueryParametersquery参数绕开Uri.queryParameters的空格转Bug。file schemelaunchUrl前用File.existsSync()确认文件存在macOS 跨沙盒访问需配置 entitlements。启动模式需要应用内打开时显式传LaunchMode用supportsLaunchMode规避不支持的降级使用inAppWebView/inAppBrowserView时只能传http(s)URL否则源码层会抛ArgumentError。Web 限制启动必须由用户手势触发需要指定窗口时用webOnlyWindowName。按此清单配置url_launcher 即可在六个平台上稳定工作并正确区分应用内打开与系统浏览器打开两类体验。【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Flutter url_launcher 插件实战指南：跨平台 URL 启动、平台配置与源码级解析
Flutter url_launcher 插件实战指南跨平台 URL 启动、平台配置与源码级解析【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages本指南以 Flutter 官方维护的 url_launcher 插件为核心系统讲解如何在 Flutter 应用中通过launchUrl启动https、mailto、tel、sms、file等各类 URL覆盖 iOS / Android / Web / 桌面端的平台配置LSApplicationQueriesSchemes、queries、沙盒 entitlements、URL 编码陷阱、canLaunchUrl的正确用法以及LaunchMode浏览器与 App 内处理的切换。读完本文你将掌握 url_launcher 从最小示例到生产级落地的完整实践方案并能结合仓库源码理解其底层调用链。url_launcher 是 Flutter 官方插件集packages中负责把 URL 交给操作系统处理的核心组件其职责非常聚焦把调用方传入的 URL 原样透传给宿主平台由平台上的默认应用浏览器、邮件客户端、电话、短信、文件管理器等决定如何处理。根据插件 pubspec.yaml 中的平台声明它通过 federated plugin联邦插件架构将 Android、iOS、Linux、macOS、Web、Windows 六个平台的实现分别委托给url_launcher_android、url_launcher_ios、url_launcher_linux、url_launcher_macos、url_launcher_web、url_launcher_windows六个子包顶层url_launcher包只负责统一 API 与平台接口分发。最小可用示例两行代码启动一个 URL在pubspec.yaml中引入依赖后即可直接使用dependencies: url_launcher: ^6.3.2插件要求 Dart SDK^3.10.0、Flutter3.38.0见 pubspec.yaml。官方 README 给出的最小示例封装在 example/lib/basic.dart 中可整体复制运行import package:flutter/material.dart; import package:url_launcher/url_launcher.dart; final Uri _url Uri.parse(https://flutter.dev); void main() runApp( const MaterialApp( home: Material( child: Center( child: ElevatedButton(onPressed: _launchUrl, child: Text(Show Flutter homepage)), ), ), ), ); Futurevoid _launchUrl() async { if (!await launchUrl(_url)) { throw Exception(Could not launch $_url); } }这段代码的核心是顶层函数launchUrl(Uri url)它接收的是Uri对象而非字符串——这是该插件 API 演进的核心变化。从 lib/src/url_launcher_uri.dart 的源码可以看到launchUrl内部做了两件事参数校验如果请求了LaunchMode.inAppWebView或LaunchMode.inAppBrowserView但 URL 的 scheme 不是http/https会直接抛出ArgumentErrorTo use an in-app web view, you must provide an http(s) URL.。平台分发通过UrlLauncherPlatform.instance.launchUrl(...)把 URL 字符串、LaunchOptions由LaunchMode、WebViewConfiguration、BrowserConfiguration、webOnlyWindowName转换而来交给平台接口实现。返回值为Futurebool成功返回true失败时视情况返回false或抛出PlatformException。因此生产代码通常按上面示例那样对false结果做兜底处理如抛出异常或提示用户。各平台支持矩阵官方 README 明确给出了平台支持范围平台AndroidiOSLinuxmacOSWebWindows支持版本SDK 2413.0任意10.15任意Windows 10注意这里的支持指插件本身可运行不代表所有 URL scheme 都能被处理——最终能否打开取决于设备上是否安装了能处理该 scheme 的应用详见下文支持的 URL scheme一节。平台配置让canLaunchUrl返回 true 的关键插件默认可以调用launchUrl但如果你需要调用canLaunchUrl做运行时探测就必须先在宿主工程里完成包可见性/应用可见性配置否则在主流移动平台上会一直返回false。这是官方 README 花费最多篇幅讲解的部分也是新手最容易踩坑的地方。iOS配置LSApplicationQueriesSchemes在 iOS 上任何传给canLaunchUrl的 URL scheme 都必须登记进Info.plist的LSApplicationQueriesSchemes否则查询会直接返回falsekeyLSApplicationQueriesSchemes/key array stringsms/string stringtel/string /array该机制对应 UIKit 的-[UIApplication canOpenURL:]iOS 出于隐私考虑限制应用探测系统内已安装应用未声明的 scheme 一律视为不可用。因此凡是你会传给canLaunchUrl的 schemesms、tel、mailto等都要在此登记。示例工程的 example/ios/Runner/Info.plist 即为配置参考。Android配置queries元素从 Android 11API 30开始系统默认隐藏应用间的包可见性。因此传给canLaunchUrl的任何 scheme 都必须以queries形式声明在AndroidManifest.xml的根元素下否则大多数情况下查询返回false。此外supportsLaunchMode(LaunchMode.inAppBrowserView)的探测也依赖queries声明缺少时会一直返回false。官方示例工程 example/android/app/src/main/AndroidManifest.xml 给出了完整配置!-- Provide required visibility configuration for API level 30 and above -- queries !-- If your app checks for SMS support -- intent action android:nameandroid.intent.action.VIEW / data android:schemesms / /intent !-- If your app checks for call support -- intent action android:nameandroid.intent.action.VIEW / data android:schemetel / /intent !-- If your application checks for inAppBrowserView launch mode support -- intent action android:nameandroid.support.customtabs.action.CustomTabsService / /intent /queries要点归纳queries必须是根元素manifest的直接子元素每探测一个 scheme就声明一条包含android.intent.action.VIEWaction 与对应data android:scheme...的intent需要探测inAppBrowserViewAndroid Custom Tabs时额外声明android.support.customtabs.action.CustomTabsServiceaction 的intent注意示例工程中https的queries声明仅用于该包自身的集成测试integration test真实应用通常不需要因为系统默认对http/https之外的大多数 scheme 限制可见性而对已安装浏览器可见但如果你的集成测试依赖它可参考该文件中的写法。Web浏览器限制Web 端没有上述清单配置但存在浏览器层面的限制URL 启动通常必须由用户手势如点击按钮触发程序自动调用会被浏览器拦截。更详细的 Web 平台说明见 url_launcher_web 包的 limitations 文档。支持的 URL scheme 与运行时探测常用 scheme 一览插件把 URL 原样交给宿主平台处理因此支持哪些 scheme 取决于平台与设备上安装的应用。官方 README 汇总了常用 schemeScheme示例动作https:URLhttps://flutter.dev用默认浏览器打开URLmailto:email address?subjectsubjectbodybodymailto:smithexample.org?subjectNewsbodyNew%20plugin在默认邮件应用中向email address写邮件tel:phone numbertel:1-555-010-999用默认电话应用拨打phone numbersms:phone numbersms:5550101234用默认短信应用向phone number发短信file:pathfile:/home用系统默认关联应用打开文件或目录桌面端支持scheme 是否可用取决于设备上是否有对应的应用。典型反例iOS 模拟器默认没有邮件和电话应用因此无法打开tel:或mailto:链接。canLaunchUrl运行时探测的正确姿势如果需要在运行时确认某个 scheme 是否保证可用例如据此调整 UI决定是否展示某个按钮可以用canLaunchUrlfinal bool canLaunch await canLaunchUrl(Uri.parse(sms:5550101234));但官方 README 明确提醒canLaunchUrl返回false不代表launchUrl一定失败。典型场景Web 应用上canLaunchUrl几乎只对少数假定支持的 scheme如http(s)返回true因为网页永远不允许探测已安装应用移动端如果没有按上文完成queries/LSApplicationQueriesSchemes配置探测也会返回false。从 lib/src/url_launcher_uri.dart 源码可见canLaunchUrl同样是委托UrlLauncherPlatform.instance.canLaunch(...)实现返回true只表示能够确认存在可处理的处理器false则既可能是没有处理器也可能是没有权限查询。因此官方建议在能提供兜底行为时优先直接调用launchUrl并处理失败而不是依赖canLaunchUrl决定是否禁用按钮。例如一个发送反馈邮件的按钮mailto探测失败时不应直接禁用按钮而应改用https打开网页版反馈表单。URL 编码避开Uri.queryParameters的已知 BugURL 必须正确编码尤其是包含空格或特殊字符时。多数情况下Dart 的Uri类 会自动处理编码。但有一个著名例外对于http/https之外的 scheme如mailto、tel构造Uri时不要使用queryParameters命名参数而应使用query参数配合自写的encodeQueryParameters函数。原因是一个已知的 Dart SDK Bugdart-lang/sdk#43838Uri编码查询参数时会把空格转成导致邮件主题等参数解析错误。官方在 example/lib/encoding.dart 中给出了正确写法String? encodeQueryParameters(MapString, String params) { return params.entries .map( (MapEntryString, String e) ${Uri.encodeComponent(e.key)}${Uri.encodeComponent(e.value)}, ) .join(); } // ··· final emailLaunchUri Uri( scheme: mailto, path: smithexample.com, query: encodeQueryParameters(String, String{ subject: Example Subject Symbols are allowed!, }), ); launchUrl(emailLaunchUri);encodeQueryParameters用Uri.encodeComponent逐一对 key 和 value 做组件级编码空格编码为%20而非再以连接。这样Example Subject Symbols are allowed!这样的含空格与的主题也能被邮件客户端正确解析。极少数场景无法用Uri表达的 URL宿主系统可能认为某些 URL 合法但 Dart 的Uri无法解析它们例如非常规格式的字符串。此时需要导入字符串版 APIimport package:url_launcher/url_launcher_string.dart; Futurebool launchUrlString( String urlString, { LaunchMode mode LaunchMode.platformDefault, WebViewConfiguration webViewConfiguration const WebViewConfiguration(), BrowserConfiguration browserConfiguration const BrowserConfiguration(), String? webOnlyWindowName, }) async { /* ... */ } Futurebool canLaunchUrlString(String urlString) async { /* ... */ }字符串版 API 定义在 lib/src/url_launcher_string.dart对外统一从 lib/url_launcher_string.dart 导出。强烈建议只在上述极少数场景使用插件旧版 API 接受字符串传无效 URL 字符串是历史上最常见的报错来源。字符串版对无效 URL 不做任何修正行为完全由平台决定——有的平台会尽力解释有的会直接失败。常规场景一律使用Uri版 API从编译期就保证 URL 合法。桌面端file:scheme先检查文件存在再启动file:scheme 可用于 Windows、macOS、Linux 三个桌面平台。官方 README 建议在调用launchUrl前先确认文件或目录真实存在。示例见 example/lib/files.dartfinal String filePath testFile.absolute.path; final uri Uri.file(filePath); if (!File(uri.toFilePath()).existsSync()) { throw Exception($uri does not exist!); } if (!await launchUrl(uri)) { throw Exception(Could not launch $uri); }要点Uri.file()负责把本地路径正确转换为file:URIuri.toFilePath()可反向还原为文件系统路径做存在性校验。macOS 沙盒注意entitlements 配置macOS 上如果你的应用需要访问沙盒之外的文件必须配置相应的 entitlementsApp Sandbox 权限。这与 Flutter 桌面应用的标准沙盒机制一致应用默认只能访问沙盒内文件跨沙盒访问需要显式声明权限。浏览器 vs 应用内打开LaunchMode详解在部分平台上Web URL 既可以在应用内 WebView 打开也可以在系统默认浏览器打开。默认行为因平台而异且可能随版本变化——因此需要特定模式的应用应显式传入LaunchMode而不是依赖默认行为。LaunchMode枚举定义在 lib/src/types.dart枚举值含义platformDefault交由平台实现决定默认值inAppWebView在应用内 WebView 中加载如 Android WebViewinAppBrowserView在应用内浏览器视图中加载如 Android Custom Tabs、iOS SFSafariViewControllerexternalApplication交给操作系统由其他应用处理externalNonBrowserApplication交给操作系统由其他非浏览器应用处理使用示例await launchUrl( Uri.parse(https://flutter.dev), mode: LaunchMode.inAppBrowserView, );配套配置类针对inAppWebView与inAppBrowserViewlib/src/types.dart 还定义了两个不可变配置类WebViewConfigurationenableJavaScript默认true、enableDomStorage默认true、headers附加请求头默认空。其中headers在 Android 上即使不加载应用内 WebView 也可能生效通过Browser.EXTRA_HEADERSintent extra但并非所有浏览器都支持因此不保证被采用。BrowserConfigurationshowTitle是否显示网页标题默认false适用于inAppBrowserView。模式降级与探测 API平台不支持请求的LaunchMode时会自动降级到受支持的模式通常是platformDefault因此不强制要求先探测。但如果你的业务逻辑必须避免降级可以先用supportsLaunchMode探测if (await supportsLaunchMode(LaunchMode.inAppBrowserView)) { await launchUrl(url, mode: LaunchMode.inAppBrowserView); }对应的 API 与语义均定义在 lib/src/url_launcher_uri.dartsupportsLaunchMode(LaunchMode)当前平台是否支持指定模式closeInAppWebView()关闭此前由launchUrl打开的应用内 WebView仅当supportsCloseForLaunchMode对所用模式返回true时有效supportsCloseForLaunchMode(LaunchMode)指定模式下closeInAppWebView是否可用。Web 端窗口目标launchUrl还有一个 Web 专用参数webOnlyWindowName用于指定启动窗口目标支持标准链接目标名_blank在新标签页打开默认行为、_self在当前标签页打开。注意 Web 浏览器不允许非用户手势触发新窗口/标签页打开这也是前文 Web 限制的底层原因。源码视角API 分层与旧版 API 弃用理解 url_launcher 的源码分层有助于你在升级依赖时快速定位问题对外统一入口lib/url_launcher.dart 仅做导出聚合了legacy_api.dart旧版、types.dart类型与url_launcher_uri.dart新版 URI API。新版 URI APIlib/src/url_launcher_uri.dart 提供launchUrl/canLaunchUrl/closeInAppWebView/supportsLaunchMode/supportsCloseForLaunchMode全部委托UrlLauncherPlatform.instance。旧版字符串 API已弃用lib/src/legacy_api.dart 中的launch/canLaunch/closeWebView均带有Deprecated(Use launchUrl instead)注解并保留 iOSforceSafariVC、universalLinksOnly、statusBarBrightness等历史参数。新代码应迁移到launchUrl。从源码看旧launch仍保留了对 iOS 状态栏亮度statusBarBrightness的兼容处理属于历史包袱不建议新项目使用。Link 组件lib/link.dart 导出LinkWidget实现在 lib/src/link.dart。它在 Web 上渲染为真正的链接在原生平台通过launchUrl打开对于无 scheme 的 URI 会被视为应用内路由名走 Flutter 导航压栈而不是交给浏览器。适合需要语义化链接 原生打开的场景。另外插件的单元测试覆盖了 URI API、字符串 API 与旧版 API 的兼容行为分别位于 test/src/url_launcher_uri_test.dart、test/src/url_launcher_string_test.dart 与 test/src/legacy_api_test.dart阅读这些测试可以帮助你理解各 API 在边界条件下的预期行为端到端集成测试见 example/integration_test/url_launcher_test.dart。实践清单上线前检查要点综合以上内容整理一份可直接对照检查的落地清单入口 API一律使用launchUrl(Uri)传Uri.parse构造的对象仅在无法用Uri表达 URL 时才 importurl_launcher_string.dart使用字符串版 API。iOS 配置所有传给canLaunchUrl的 scheme 登记到Info.plist的LSApplicationQueriesSchemes。Android 配置所有传给canLaunchUrl的 scheme 在AndroidManifest.xml根元素下声明queries需要探测inAppBrowserView时声明 Custom Tabs 的queries。探测策略能提供兜底就优先launchUrl 失败处理别让canLaunchUrl的false直接禁用功能。URL 编码非http(s)scheme 的查询参数用encodeQueryParametersquery参数绕开Uri.queryParameters的空格转Bug。file schemelaunchUrl前用File.existsSync()确认文件存在macOS 跨沙盒访问需配置 entitlements。启动模式需要应用内打开时显式传LaunchMode用supportsLaunchMode规避不支持的降级使用inAppWebView/inAppBrowserView时只能传http(s)URL否则源码层会抛ArgumentError。Web 限制启动必须由用户手势触发需要指定窗口时用webOnlyWindowName。按此清单配置url_launcher 即可在六个平台上稳定工作并正确区分应用内打开与系统浏览器打开两类体验。【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考