Skip to main content
Contents

使用包

Contents

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

现有的包支持许多用例——例如，进行网络请求（http）、导航/路由处理（go_router）、与设备 API 集成（url_launcher 和 battery_plus）以及使用 Firebase 等第三方平台 SDK（FlutterFire）。

要编写新的包，请参阅开发包。要添加存储在文件或包中的资产、图像或字体，请参阅添加资产和图像。

使用包

#

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

搜索包

#

包发布到pub.dev。

pub.dev 上的Flutter 首页 显示与 Flutter 兼容的顶级包（声明通常与 Flutter 兼容的依赖项的包），并支持在所有已发布的包中搜索。

pub.dev 上的Flutter 精选 页面列出了已被识别为编写应用时应首先考虑使用的插件和包。有关成为 Flutter 精选的含义的更多信息，请参阅Flutter 精选计划。

您还可以通过按Android、iOS、web、Linux、Windows、macOS或任何组合进行筛选来浏览 pub.dev 上的包。

使用 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 get。

  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_package 和 another_package，并且这两个包都依赖于 url_launcher，但版本不同。这会导致潜在冲突。避免此问题的最佳方法是包作者在指定依赖项时使用版本范围 而不是特定版本。

yaml
dependencies:
  url_launcher: ^5.4.0    # 好，任何 >= 5.4.0 但 < 6.0.0 的版本
  image_picker: '5.4.3'   # 不太好，只有 5.4.3 版本有效。

如果 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 文件进行以下更改：

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

如果冲突的依赖项本身不是包，而是 Android 特定的库（例如 guava），则必须将依赖项覆盖声明添加到 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 upgrade 或 flutter update-packages 不同，这两个命令都会更新 Flutter 本身。

对未发布包的依赖

#

即使未在 pub.dev 上发布，也可以使用包。对于私有包或尚未准备好发布的包，可以使用其他依赖项选项：

路径依赖

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

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

您还可以依赖于存储在 Git 存储库中的包。如果包位于 repo 的根目录，

使用以下语法：

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

如果存储库是私有的，并且您可以使用 SSH 连接到它，请使用 repo 的 SSH url 依赖于该包：

yaml
  dependencies:
    packageA:
      git:
        url: [email protected]: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 中单击获取包 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. 运行应用（如果在添加插件之前应用已经在运行，则停止并重新启动它）。单击显示 Flutter 首页。您应该会看到设备上的默认浏览器打开，显示 flutter.dev 的主页。

除非另有说明，否则本网站上的文档反映的是 Flutter 的最新稳定版本。页面最后更新于 2025-01-30。 查看源代码 或 报告问题。