使用包
Flutter 支持使用其他开发者贡献给 Flutter 和 Dart 生态系统的共享包。这允许快速构建应用,而无需从头开始开发所有内容。
现有包支持许多用例——例如,发起网络请求 (http
)、导航/路由处理 (go_router
)、与设备 API 集成 (url_launcher
和 battery_plus
),以及使用第三方平台 SDK(如 Firebase (FlutterFire))。
要编写新包,请参阅开发包。要添加资产、图像或字体,无论它们存储在文件还是包中,请参阅添加资产和图像。
使用包
#以下部分介绍如何使用现有已发布的包。
搜索包
#包发布到 pub.dev。
pub.dev 上的 Flutter 主页显示与 Flutter 兼容的顶级包(那些声明了与 Flutter 大致兼容的依赖项的包),并支持在所有已发布的包中进行搜索。
pub.dev 上的 Flutter 收藏页面列出了被认定为在编写应用时应首先考虑使用的插件和包。有关 Flutter Favorite 含义的更多信息,请参阅 Flutter Favorites 项目。
您还可以通过在 pub.dev 上筛选 Android、iOS、web、Linux、Windows、macOS 或它们的任意组合来浏览包。
使用 flutter pub add
向应用添加包依赖
#将 css_colors
包添加到应用中
在项目目录中使用
pub add
命令flutter pub add css_colors
导入它
- 在 Dart 代码中添加相应的
import
语句。
- 在 Dart 代码中添加相应的
如有必要,停止并重新启动应用
- 如果包引入了平台特定代码(Android 为 Kotlin/Java,iOS 为 Swift/Objective-C),则该代码必须构建到您的应用中。热重载和热重启只更新 Dart 代码,因此在使用包时,可能需要完全重启应用以避免出现
MissingPluginException
等错误。
- 如果包引入了平台特定代码(Android 为 Kotlin/Java,iOS 为 Swift/Objective-C),则该代码必须构建到您的应用中。热重载和热重启只更新 Dart 代码,因此在使用包时,可能需要完全重启应用以避免出现
向应用添加包依赖
#将 css_colors
包添加到应用中
依赖它
- 打开位于应用文件夹内的
pubspec.yaml
文件,并在dependencies
下添加css_colors: ^1.0.0
。
- 打开位于应用文件夹内的
安装它
- 从终端:运行
flutter pub get
。
或者 - 从 VS Code:点击位于
pubspec.yaml
顶部操作功能区右侧,由下载图标指示的获取包。 - 从 Android Studio/IntelliJ:点击
pubspec.yaml
顶部操作功能区中的获取 Pub 包。
- 从终端:运行
导入它
- 在 Dart 代码中添加相应的
import
语句。
- 在 Dart 代码中添加相应的
如有必要,停止并重新启动应用
- 如果包引入了平台特定代码(Android 为 Kotlin/Java,iOS 为 Swift/Objective-C),则该代码必须构建到您的应用中。热重载和热重启只更新 Dart 代码,因此在使用包时,可能需要完全重启应用以避免出现
MissingPluginException
等错误。
- 如果包引入了平台特定代码(Android 为 Kotlin/Java,iOS 为 Swift/Objective-C),则该代码必须构建到您的应用中。热重载和热重启只更新 Dart 代码,因此在使用包时,可能需要完全重启应用以避免出现
使用 flutter pub remove
从应用中移除包依赖
#从应用中移除 css_colors
包
- 在项目目录中使用
pub remove
命令flutter pub remove css_colors
在 pub.dev 上的任何包页面上都可用的安装选项卡,是这些步骤的便捷参考。
有关完整示例,请参阅下面的css_colors 示例。
冲突解决
#假设您想在应用中使用 some_package
和 another_package
,并且这两个包都依赖于 url_launcher
,但版本不同。这可能导致冲突。避免此问题的最佳方法是包作者在指定依赖项时使用版本范围而不是特定版本。
dependencies:
url_launcher: ^5.4.0 # Good, any version >= 5.4.0 but < 6.0.0
image_picker: '5.4.3' # Not so good, only version 5.4.3 works.
如果 some_package
声明了上述依赖项,而 another_package
声明了兼容的 url_launcher
依赖项,例如 '5.4.6'
或 ^5.5.0
,pub 会自动解决该问题。对 Gradle 模块和/或 CocoaPods 的平台特定依赖项也以类似方式解决。
即使 some_package
和 another_package
声明了不兼容的 url_launcher
版本,它们实际上也可能以兼容的方式使用 url_launcher
。在这种情况下,可以通过在应用的 pubspec.yaml
文件中添加依赖覆盖声明来解决冲突,从而强制使用特定版本。
例如,要强制使用 url_launcher
版本 5.4.0
,请对应用的 pubspec.yaml
文件进行以下更改
dependencies:
some_package:
another_package:
dependency_overrides:
url_launcher: '5.4.0'
如果冲突的依赖项本身不是包,而是像 guava
这样的 Android 特定库,则必须将依赖覆盖声明添加到 Gradle 构建逻辑中。
要强制使用 guava
版本 28.0
,请对应用的 android/build.gradle
文件进行以下更改
configurations.all {
resolutionStrategy {
force 'com.google.guava:guava:28.0-android'
}
}
CocoaPods 目前不提供依赖覆盖功能。
开发新包
#如果您的特定用例没有现成的包,您可以编写自定义包。
管理包依赖和版本
#为最大限度地降低版本冲突的风险,请在 pubspec.yaml
文件中指定版本范围。
包版本
#所有包都有版本号,在包的 pubspec.yaml
文件中指定。包的当前版本会显示在其名称旁边(例如,参见 url_launcher
包),以及所有先前版本的列表(参见 url_launcher
版本)。
为确保应用在更新包时不会崩溃,请使用以下格式之一指定版本范围。
范围约束: 指定最低和最高版本。
yamldependencies: url_launcher: '>=5.4.0 <6.0.0'
使用插入符语法的范围约束: 指定作为包含性最低版本的版本。这涵盖从该版本到下一个主要版本的所有版本。
yamldependencies: collection: '^5.4.0'
此语法与第一个要点中提到的含义相同。
要了解更多信息,请查阅包版本控制指南。
更新包依赖
#首次添加包后运行 flutter pub get
时,Flutter 会将 pubspec.lock
锁文件中找到的具体包版本保存起来。这可确保您或团队中的其他开发人员再次运行 flutter pub get
时获得相同的版本。
要升级到包的新版本(例如使用该包中的新功能),请运行 flutter pub upgrade
以检索 pubspec.yaml
中指定的版本约束所允许的包的最高可用版本。请注意,这与 flutter upgrade
或 flutter update-packages
不同,后两者都用于更新 Flutter 本身。
对未发布包的依赖
#即使包未发布到 pub.dev,也可以使用它们。对于私有包或尚未准备好发布的包,有额外的依赖项选项可用
- 路径依赖
Flutter 应用可以使用文件系统
path:
依赖项来依赖包。路径可以是相对路径或绝对路径。相对路径是相对于包含pubspec.yaml
的目录进行评估的。例如,要依赖位于应用旁边目录中的包 packageA,请使用以下语法yamldependencies: packageA: path: ../packageA/
- Git 依赖
您也可以依赖存储在 Git 仓库中的包。如果包位于仓库的根目录,请使用以下语法
yamldependencies: packageA: git: url: https://github.com/flutter/packageA.git
- 使用 SSH 的 Git 依赖
如果仓库是私有的且您可以使用 SSH 连接到它,则可以使用仓库的 SSH URL 来依赖该包
yamldependencies: packageA: git: url: git@github.com:flutter/packageA.git
- 文件夹中包的 Git 依赖
Pub 假定包位于 Git 仓库的根目录。如果不是这种情况,请使用
path
参数指定位置。例如yamldependencies: packageA: git: url: https://github.com/flutter/packages.git path: packages/packageA
最后,使用
ref
参数将依赖项固定到特定的 Git 提交、分支或标签。有关更多详细信息,请参阅包依赖。
示例
#以下示例将逐步介绍使用包的必要步骤。
示例:使用 css_colors 包
#css_colors
包定义了 CSS 颜色的颜色常量,因此在 Flutter 框架期望 Color
类型的地方使用这些常量。
要使用此包
创建一个名为
cssdemo
的新项目。打开
pubspec.yaml
,并添加css-colors
依赖yamldependencies: flutter: sdk: flutter css_colors: ^1.0.0
在终端中运行
flutter pub get
,或在 VS Code 中点击获取包。打开
lib/main.dart
并将其全部内容替换为dartimport 'package:css_colors/css_colors.dart'; import 'package:flutter/material.dart'; void main() { runApp(const MyApp()); } class MyApp extends StatelessWidget { const MyApp({super.key}); @override Widget build(BuildContext context) { return const MaterialApp(home: DemoPage()); } } class DemoPage extends StatelessWidget { const DemoPage({super.key}); @override Widget build(BuildContext context) { return Scaffold(body: Container(color: CSSColors.orange)); } }
- 运行应用。应用的背景现在应该是橙色。
示例:使用 url_launcher 包启动浏览器
#url_launcher
插件包支持在移动平台上打开默认浏览器以显示给定 URL,并支持 Android、iOS、web、Windows、Linux 和 macOS。此包是一种特殊的 Dart 包,称为插件包(或插件),它包含平台特定代码。
要使用此插件
创建一个名为
launchdemo
的新项目。打开
pubspec.yaml
,并添加url_launcher
依赖yamldependencies: flutter: sdk: flutter url_launcher: ^5.4.0
在终端中运行
flutter pub get
,或在 VS Code 中点击获取 Pub 包。打开
lib/main.dart
并将其全部内容替换为以下内容dartimport 'package:flutter/material.dart'; import 'package:path/path.dart' as p; import 'package:url_launcher/url_launcher.dart'; void main() { runApp(const MyApp()); } class MyApp extends StatelessWidget { const MyApp({super.key}); @override Widget build(BuildContext context) { return const MaterialApp(home: DemoPage()); } } class DemoPage extends StatelessWidget { const DemoPage({super.key}); void launchURL() { launchUrl(p.toUri('https://flutterdart.cn')); } @override Widget build(BuildContext context) { return Scaffold( body: Center( child: ElevatedButton( onPressed: launchURL, child: const Text('Show Flutter homepage'), ), ), ); } }
运行应用(如果添加插件前已运行,则停止并重新启动)。点击显示 Flutter 主页。您应该会看到设备上打开默认浏览器,显示 flutter.dev 的主页。