目录

在 Flutter 里使用 Packages

目录

Flutter 支持使用其他开发者向 Flutter 和 Dart 生态系统贡献的共享 package，这意味着你可以快速构建应用而不是一切从零开始。

现有的 package 支持许多使用场景，例如，网络请求 (http)，自定义导航/路由处理 (go_router)，集成设备 API（如 url_launcher 和 battery_plus，以及使用第三方平台的 SDK（如 Firebase 的 (FlutterFire)。

如果你正打算开发新的 package，请参阅 Flutter Packages 的开发和提交。如果你想添加资源、图片或字体，无论是存储在文件中还是 package 中，请参阅 添加资源和图片 这篇文档。

使用 package

#

下面的内容将为你描述如何使用已经发布了的 packages。

搜索 package

#

Package 会被发布到 pub.dev 网站上。

Pub 网站上的 Flutter 页面 展示了与 Flutter 兼容的 package（即声明的依赖通常与 Flutter 兼容），并且所有已发布的 package 都支持搜索。

Pub.dev 上的 Flutter Favorites 页面列出了一系列编写应用时可以首先考虑使用的插件和 package，关于这个项目的更多信息，请查看 Flutter Favorites 项目 页面。

在 pub.dev 网站上你可以同时过滤出适合 Android、iOS、Web、Linux、 Windows 或 macOS 的插件，你也可以通过复选框，过滤出组合结果（适配一个或者多个平台）。

将 package 依赖添加到应用

#

要将 package 'css_colors' 添加到应用：

  1. 添加依赖

    • 打开应用文件夹下的 pubspec.yaml 文件，然后在 pubspec.yaml 下添加 css_colors:。

  2. 安装

    • 在命令行中运行：flutter pub get

    或者

    • 在 VS Code 中点击位于 pubspec.yaml 文件顶部操作功能区右侧的 Get Packages

    • 在 Android Studio/IntelliJ 中点击 pubspec.yaml 文件顶部操作功能区的 Packages get

  3. 导入

    • 在 Dart 代码中添加相关的 import 语句。

  4. 如果有必要，停止并重启应用

    • 如果 package 内有特定平台的代码（Android 的 Java/Kotlin, iOS 的 Swift/Objective-C），代码必须内置到你的应用内。热重载和热重启只对 package 的 Dart 代码执行此操作，所以你需要完全重启应用以避免使用 package 时出现 MissingPluginException 错误。

使用命令 flutter pub add 添加一个 package 依赖

#

将 css_colors 这个 package 添加到工程中：

  1. 在项目根目录执行命令

    • flutter pub add css_colors

  2. 导入

    • 在 Dart 代码中添加相应的 import 语句

  3. 如果有必要，停止并重启应用

    • 如果 package 内有特定平台的代码（Android 的 Java/Kotlin, iOS 的 Swift/Objective-C），代码必须内置到你的应用内。热重载和热重启只对 package 的 Dart 代码执行此操作，所以你需要完全重启应用以避免使用 package 时出现 MissingPluginException 错误。

使用 flutter pub remove 命令移除一个 package 依赖

#

要将 package 'css_colors' 从工程中移除：

  1. 在项目根目录执行命令

    • flutter pub remove css_colors

对于这些步骤，Pub 上任何 package 页面的 Installing tab 选项卡都是一个很方便的参考。

完整示例，参阅下面的 css_colors 示例。

冲突解决

#

假设你想在应用中使用 some_package 和 other_package，并且它们依赖于不同版本的 url_launcher。于是我们便有了潜在的冲突。避免这种情况的最好方法是 package 的作者在指定依赖项时使用 版本范围 而非特定版本。

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 modules 和 CocoaPods 也是用类似的方式解决平台依赖的。

即使 some_package 和 another_package 声明了不兼容的 url_launcher 版本，它们实际上仍可能以兼容的方式使用 url_launcher。在这种情况下，可在 pubspec.yaml 文件中添加一个依赖覆盖声明来强制使用特定版本，从而处理冲突。

为了强制使用版本为 5.4.0 的 url_launcher，你可以对应用的 pubspec.yaml 文件做如下更改：

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

如果依赖冲突项不是 package 自身，而是如 guava 这样特定于 Android 的库，那么依赖的覆盖声明必须添加到 Gradle 的构建逻辑中。

为了强制使用版本为 28.0 的 guava，你可以对 android/build.gradle 文件做如下更改：

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

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

开发新的 package

#

如果某个 package 不适用于你的特定需求，你可以 开发新的自定义 package。

管理 package 的依赖和版本

#

为了使版本冲突的风险最小化，请在 pubspec.yaml 文件中指定一个版本范围。

Package 版本

#

所有 package 都有一个版本号，在它们的 pubspec.yaml 文件中指定。当前的 package 版本会在其名称旁边显示当前版本号。（例如，参阅 url_launcher package）以及所有先前版本的列表： url_launcher 版本列表。

为了确保在更新 package 的时候你的应用不会崩溃，我们建议使用以下格式之一来指定版本范围：

  • **范围限制：**指定一个最小和最大的版本号。

    yaml
    dependencies:
  url_launcher: '>=5.4.0 <6.0.0'

  • 使用 caret语法 的范围约束： 指定最小版本，这包括从该版本到下一个主要版本的所有版本。

    yaml
    dependencies:
  collection: '^5.4.0'

    该语法与第一项中的语法含义相同。

了解更详细的信息，参阅 Pub 版本管理指南。

更新 package 依赖

#

当添加 package 后首次运行 flutter pub get 时， Flutter 将会保存在 pubspec.lock lockfile 中找到的具体 package 版本。这将确保当你或者团队中其他开发者运行 flutter pub get 后能得到相同版本的 package。

如果你想升级到 package 的最新版本，比如使用 package 的最新特性，请运行 flutter pub upgrade。这将检索你在 pubspec.yaml 文件中指定的版本约束所允许的最高可用版本。请注意，flutter upgrade 与 flutter update-packages 是两个不同的命令，但它们都会更新 Flutter。

依赖未发布的 package

#

即使未在 Pub site 上发布，也可以使用 package。对于不用于公开发布的私有插件，或者尚未准备好发布的 package，可以使用其他依赖选项。

Path 依赖
Flutter 应用可以通过文件系统 path: 依赖而依赖于插件。路径可以是相对的，也可以是绝对的。例如，要依赖位于应用相邻目录中的插件 plugin1，可以使用以下语法：

yaml
  dependencies:
  packageA:
    path: ../packageA/

Git 依赖
你也可以依赖存储在 Git 仓库中的 package，如果 package 位于仓库的根目录，可以使用以下语法：

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

通过 SSH 依赖 Git package
如果你需要通过 SSH 连接私有的仓库，你可以用 SSH 链接依赖对应的 package：

yaml
  dependencies:
    packageA:
      git:
        url: git@github.com:flutter/packageA.git

**Git 依赖于文件夹中的 package **
默认情况下，pub 会默认假定 package 位于 Git 仓库的根目录。如果不是这种情况，你可以使用 path 参数指定位置，例如：

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

最后，你可以使用 ref 参数将依赖固定到 git 特定的 commit、branch 或者 tag。更多详细信息，请参阅 Package dependencies。

例子

#

下面的示例将介绍使用 packages 的一些必要步骤。

例子：使用 css_colors package

#

css_colors package 为 CSS 颜色定义颜色常量，允许你在 Flutter 框架中任何需要 Color 类型的地方使用它们。

要使用这个 package：

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

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

    yaml
    dependencies:
  flutter:
    sdk: flutter

    替换为：

    yaml
    dependencies:
  flutter:
    sdk: flutter
  css_colors: ^1.0.0

  3. 在命令行中运行 flutter packages get，或者点击 Intellij 中的 Packages get

  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. 运行应用。当你点击 'Show Flutter homepage' 时，你将看到手机默认浏览器打开并出现 Flutter 主页。

例子：使用 url_launcher package 来打开浏览器

#

url_launcher 插件可以让你在移动平台上打开默认浏览器以显示给定的 URL。它支持 Android、iOS、web、Windows、Linux 以及 macOS。我们将这一类包含各平台特定代码的 package 称为 插件 package 或者 插件。

要使用这个插件：

  1. 新建一个名为 lauchdemo 的新项目；

  2. 打开 pubspec.yaml，然后添加 url_launcher 的依赖：

    yaml
    dependencies:
  flutter:
    sdk: flutter
  url_launcher: ^5.4.0

  3. 在命令行中运行 flutter packages get，或者点击 Intellij 或 Android Studio 中的 Packages get；

  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://flutter.dev'));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: ElevatedButton(
          onPressed: launchURL,
          child: const Text('Show Flutter homepage'),
        ),
      ),
    );
  }
}

  5. 运行应用（如果你的应用在添加插件之前已经运行，请停止并重启应用）。当你点击 Show Flutter homepage 时，你将看到手机默认浏览器打开并出现 Flutter 主页。

除非另有说明，本文档之所提及适用于 Flutter 的最新稳定版本，本页面最后更新时间: 2024-08-05。 查看文档源码 或者 为本页面内容提出建议。