Flutter 支持使用其他开发者贡献给 Flutter 和 Dart 生态系统的共享包。这允许快速构建应用,而无需从头开始开发所有内容。

现有包支持许多用例——例如,发起网络请求 (http)、导航/路由处理 (go_router)、与设备 API 集成 (url_launcherbattery_plus),以及使用第三方平台 SDK(如 Firebase (FlutterFire))。

要编写新包,请参阅开发包。要添加资产、图像或字体,无论它们存储在文件还是包中,请参阅添加资产和图像

使用包

#

以下部分介绍如何使用现有已发布的包。

搜索包

#

包发布到 pub.dev

pub.dev 上的 Flutter 主页显示与 Flutter 兼容的顶级包(那些声明了与 Flutter 大致兼容的依赖项的包),并支持在所有已发布的包中进行搜索。

pub.dev 上的 Flutter 收藏页面列出了被认定为在编写应用时应首先考虑使用的插件和包。有关 Flutter Favorite 含义的更多信息,请参阅 Flutter Favorites 项目

您还可以通过在 pub.dev 上筛选 AndroidiOSwebLinuxWindowsmacOS 或它们的任意组合来浏览包。

使用 flutter pub add 向应用添加包依赖

#

css_colors 包添加到应用中

  1. 在项目目录中使用 pub add 命令

    • flutter pub add css_colors
  2. 导入它

    • 在 Dart 代码中添加相应的 import 语句。
  3. 如有必要,停止并重新启动应用

    • 如果包引入了平台特定代码(Android 为 Kotlin/Java,iOS 为 Swift/Objective-C),则该代码必须构建到您的应用中。热重载和热重启只更新 Dart 代码,因此在使用包时,可能需要完全重启应用以避免出现 MissingPluginException 等错误。

向应用添加包依赖

#

css_colors 包添加到应用中

  1. 依赖它

    • 打开位于应用文件夹内的 pubspec.yaml 文件,并在 dependencies 下添加 css_colors: ^1.0.0
  2. 安装它

    • 从终端:运行 flutter pub get
      或者
    • 从 VS Code:点击位于 pubspec.yaml 顶部操作功能区右侧,由下载图标指示的获取包
    • 从 Android Studio/IntelliJ:点击 pubspec.yaml 顶部操作功能区中的获取 Pub 包
  3. 导入它

    • 在 Dart 代码中添加相应的 import 语句。
  4. 如有必要,停止并重新启动应用

    • 如果包引入了平台特定代码(Android 为 Kotlin/Java,iOS 为 Swift/Objective-C),则该代码必须构建到您的应用中。热重载和热重启只更新 Dart 代码,因此在使用包时,可能需要完全重启应用以避免出现 MissingPluginException 等错误。

使用 flutter pub remove 从应用中移除包依赖

#

从应用中移除 css_colors

  1. 在项目目录中使用 pub remove 命令
    • flutter pub remove css_colors

在 pub.dev 上的任何包页面上都可用的安装选项卡,是这些步骤的便捷参考。

有关完整示例,请参阅下面的css_colors 示例

冲突解决

#

假设您想在应用中使用 some_packageanother_package,并且这两个包都依赖于 url_launcher,但版本不同。这可能导致冲突。避免此问题的最佳方法是包作者在指定依赖项时使用版本范围而不是特定版本。

yaml
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_packageanother_package 声明了不兼容的 url_launcher 版本,它们实际上也可能以兼容的方式使用 url_launcher。在这种情况下,可以通过在应用的 pubspec.yaml 文件中添加依赖覆盖声明来解决冲突,从而强制使用特定版本。

例如,要强制使用 url_launcher 版本 5.4.0,请对应用的 pubspec.yaml 文件进行以下更改

yaml
dependencies:
  some_package:
  another_package:
dependency_overrides:
  url_launcher: '5.4.0'

如果冲突的依赖项本身不是包,而是像 guava 这样的 Android 特定库,则必须将依赖覆盖声明添加到 Gradle 构建逻辑中。

要强制使用 guava 版本 28.0,请对应用的 android/build.gradle 文件进行以下更改

groovy
configurations.all {
    resolutionStrategy {
        force 'com.google.guava:guava:28.0-android'
    }
}

CocoaPods 目前不提供依赖覆盖功能。

开发新包

#

如果您的特定用例没有现成的包,您可以编写自定义包

管理包依赖和版本

#

为最大限度地降低版本冲突的风险,请在 pubspec.yaml 文件中指定版本范围。

包版本

#

所有包都有版本号,在包的 pubspec.yaml 文件中指定。包的当前版本会显示在其名称旁边(例如,参见 url_launcher 包),以及所有先前版本的列表(参见 url_launcher 版本)。

为确保应用在更新包时不会崩溃,请使用以下格式之一指定版本范围。

  • 范围约束: 指定最低和最高版本。

    yaml
    dependencies:
      url_launcher: '>=5.4.0 <6.0.0'
  • 使用插入符语法的范围约束: 指定作为包含性最低版本的版本。这涵盖从该版本到下一个主要版本的所有版本。

    yaml
    dependencies:
      collection: '^5.4.0'

    此语法与第一个要点中提到的含义相同。

要了解更多信息,请查阅包版本控制指南

更新包依赖

#

首次添加包后运行 flutter pub get 时,Flutter 会将 pubspec.lock 锁文件中找到的具体包版本保存起来。这可确保您或团队中的其他开发人员再次运行 flutter pub get 时获得相同的版本。

要升级到包的新版本(例如使用该包中的新功能),请运行 flutter pub upgrade 以检索 pubspec.yaml 中指定的版本约束所允许的包的最高可用版本。请注意,这与 flutter upgradeflutter update-packages 不同,后两者都用于更新 Flutter 本身。

对未发布包的依赖

#

即使包未发布到 pub.dev,也可以使用它们。对于私有包或尚未准备好发布的包,有额外的依赖项选项可用

路径依赖

Flutter 应用可以使用文件系统 path: 依赖项来依赖包。路径可以是相对路径或绝对路径。相对路径是相对于包含 pubspec.yaml 的目录进行评估的。例如,要依赖位于应用旁边目录中的包 packageA,请使用以下语法

yaml
  dependencies:
  packageA:
    path: ../packageA/
Git 依赖

您也可以依赖存储在 Git 仓库中的包。如果包位于仓库的根目录,请使用以下语法

yaml
  dependencies:
    packageA:
      git:
        url: https://github.com/flutter/packageA.git
使用 SSH 的 Git 依赖

如果仓库是私有的且您可以使用 SSH 连接到它,则可以使用仓库的 SSH URL 来依赖该包

yaml
  dependencies:
    packageA:
      git:
        url: git@github.com:flutter/packageA.git
文件夹中包的 Git 依赖

Pub 假定包位于 Git 仓库的根目录。如果不是这种情况,请使用 path 参数指定位置。例如

yaml
dependencies:
  packageA:
    git:
      url: https://github.com/flutter/packages.git
      path: packages/packageA

最后,使用 ref 参数将依赖项固定到特定的 Git 提交、分支或标签。有关更多详细信息,请参阅包依赖

示例

#

以下示例将逐步介绍使用包的必要步骤。

示例:使用 css_colors 包

#

css_colors 包定义了 CSS 颜色的颜色常量,因此在 Flutter 框架期望 Color 类型的地方使用这些常量。

要使用此包

  1. 创建一个名为 cssdemo 的新项目。

  2. 打开 pubspec.yaml,并添加 css-colors 依赖

    yaml
    dependencies:
      flutter:
        sdk: flutter
      css_colors: ^1.0.0
  3. 在终端中运行 flutter pub get,或在 VS Code 中点击获取包

  4. 打开 lib/main.dart 并将其全部内容替换为

    dart
    import '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));
      }
    }
  1. 运行应用。应用的背景现在应该是橙色。

示例:使用 url_launcher 包启动浏览器

#

url_launcher 插件包支持在移动平台上打开默认浏览器以显示给定 URL,并支持 Android、iOS、web、Windows、Linux 和 macOS。此包是一种特殊的 Dart 包,称为插件包(或插件),它包含平台特定代码。

要使用此插件

  1. 创建一个名为 launchdemo 的新项目。

  2. 打开 pubspec.yaml,并添加 url_launcher 依赖

    yaml
    dependencies:
      flutter:
        sdk: flutter
      url_launcher: ^5.4.0
  3. 在终端中运行 flutter pub get,或在 VS Code 中点击获取 Pub 包

  4. 打开 lib/main.dart 并将其全部内容替换为以下内容

    dart
    import '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'),
            ),
          ),
        );
      }
    }
  5. 运行应用(如果添加插件前已运行,则停止并重新启动)。点击显示 Flutter 主页。您应该会看到设备上打开默认浏览器,显示 flutter.dev 的主页。