Flutter之Package教程

参考链接

名称	链接
官方package管理地址	The official repository for Dart and Flutter packages.

一、使用package

1. 搜索 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 的插件，你也可以通过复选框，过滤出组合结果（适配一个或者多个平台）。

2. 将 package 依赖添加到应用

要将 package '

css_colors' 添加到应用：

添加依赖
- 打开应用文件夹下的 pubspec.yaml 文件，然后在 pubspec.yaml 下添加 css_colors:。
安装
- 在命令行中运行：flutter pub get
或者
- 在 VS Code 中点击位于 pubspec.yaml 文件顶部操作功能区右侧的 Get Packages
- 在 Android Studio/IntelliJ 中点击 pubspec.yaml 文件顶部操作功能区的 Packages get
导入
- 在 Dart 代码中添加相关的 import 语句。
如果有必要，停止并重启应用
- 如果 package 内有特定平台的代码（Android 的 Java/Kotlin, iOS 的 Swift/Objective-C），代码必须内置到你的应用内。热重载和热重启只对 package 的 Dart 代码执行此操作，所以你需要完全重启应用以避免使用 package 时出现 MissingPluginException 错误。

2.1 使用命令添加依赖

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

在项目根目录执行命令
- flutter pub add css_colors
导入
- 在 Dart 代码中添加相应的 import 语句
如果有必要，停止并重启应用
- 如果 package 内有特定平台的代码（Android 的 Java/Kotlin, iOS 的 Swift/Objective-C），代码必须内置到你的应用内。热重载和热重启只对 package 的 Dart 代码执行此操作，所以你需要完全重启应用以避免使用 package 时出现 MissingPluginException 错误。

2.2 使用命令移除依赖

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

在项目根目录执行命令
- flutter pub remove css_colors

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

3. 管理 package 的依赖和版本

所有 package 都有一个版本号，在它们的 pubspec.yaml 文件中指定。当前的 package 版本会在其名称旁边显示当前版本号。

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

范围限制：指定一个最小和最大的版本号，例如：
```
dependencies:
  url_launcher: '>=5.4.0 <6.0.0'
```
使用 caret语法的范围约束与常规的范围约束类似：
```
dependencies:
  collection: '^5.4.0'
```

4. 更新 package 依赖

当你添加一个 package 后首次运行 flutter pub get（IntelliJ 或 Android Studio 中的 Packages Get ）， Flutter 将会保存在 pubspec.lock lockfile 中找到的具体 package 版本。

这将确保当你或者团队中其他开发者运行 flutter pub get 后能得到相同版本的 package。

如果你想升级到 package 的最新版本，比如使用 package 的最新特性，请运行 flutter pub upgrade。

这将检索你在 pubspec.yaml 文件中指定的版本约束所允许的最高可用版本。请注意，flutter upgrade 与 flutter update-packages 是两个不同的命令，但它们都会更新 Flutter。

5. 依赖未发布的 package

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

5.1 Path 依赖

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

    dependencies:
    packageA:
      path: ../packageA/

5.2 Git 依赖

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

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

5.3 SSH Git 依赖

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

5.4 Git 依赖于文件夹中的 package

默认情况下，pub 会默认假定 package 位于 Git 仓库的根目录。

如果不是这种情况，你可以使用 path 参数指定位置，例如：

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

二、开发package

2.1 纯 Dart 的 package

2.1.1 创建 package

|-------------------------------------------------|
| flutter create --template=package hello |

2.2.2 实现 package

对于纯 Dart 库的 package，只要在 lib/<package name>.dart 文件中添加功能实现，或在 lib 目录中的多个文件中添加功能实现。

如果要对 package 进行测试，在 test 目录下添加单元测试。

2.2 原生插件类型的 package

2.2.1 联合插件

Federated plugins (联合插件) 是一种将对不同平台的支持分为单独的软件包。所以，联合插件能够使用针对 iOS、Android、Web 分别使用对应的 package。

除了这些好处之外，它还能够让领域专家在他们最了解的平台上扩展现有平台插件。

联合插件需要以下 package：

面向应用的 package

该 package 是用户使用插件的的直接依赖。它指定了 Flutter 应用使用的 API。

平台 package

一个或多个包含特定平台代码的 package。面向应用的 package 会调用这些平台 package------ 除非它们带有一些终端用户需要的特殊平台功能，否则它们不会包含在应用中。

平台接口 package

将面向应用的 package 与平台 package 进行整合的 package。该 package 会声明平台 package 需要实现的接口，供面向应用的 package 使用。使用单一的平台接口 package 可以确保所有平台 package 都按照各自的方法实现了统一要求的功能。

假设你开发了 foobar_windows 插件，用于对应 foobar 插件的实现。在整合的联合插件里，foobar 的原作者会将你的 Windows 实现作为依赖添加在 pubspec 文件中，供面向应用的 package 调用。

而后在开发者使用 foobar 插件时，Windows 及已包含的其他平台的实现就自动可用了。

2.2.2 指定一个插件支持的平台

插件可以通过向 pubspec.yaml 中的 platforms map 添加 keys 来指定其支持的平台。例如，以下是 hello 插件的 flutter: map，它仅支持 Android 和 iOS：

flutter:
  plugin:
    platforms:
      android:
        package: com.example.hello
        pluginClass: HelloPlugin
      ios:
        pluginClass: HelloPlugin
当为更多平台添加插件实现时，应相应地更新 platforms map，例如这是支持 Android、iOS、macOS 和 web 的 hello 插件的 map：

flutter:
  plugin:
    platforms:
      android:
        package: com.example.hello
        pluginClass: HelloPlugin
      ios:
        pluginClass: HelloPlugin
      macos:
        pluginClass: HelloPlugin
      web:
        pluginClass: HelloPlugin
        fileName: hello_web.dart

2.2.3 联合平台 package

平台 package 有着同样的格式，但会包含 implements 入口，用于指明 package 实现的平台。例如，实现了 hello package 的 Windows 平台的 hello_windows 插件，会在 flutter: 映射下包含以下内容：

flutter:
  plugin:
    implements: hello
    platforms:
      windows:
        pluginClass: HelloPlugin

2.2.4 认可的实现

复制代码

提供给 App 项目使用的 package 可以通过在 platform: 映射下声明 default_package，认可一个平台实现插件。如果 hello 插件认可了 hello_windows，它看起来会是这样：

复制代码

flutter:
  plugin:
    platforms:
      android:
        package: com.example.hello
        pluginClass: HelloPlugin
      ios:
        pluginClass: HelloPlugin
      windows:
        default_package: hello_windows

dependencies:
  hello_windows: ^1.0.0

注意如上所示，面向 App 项目的 package 可能已经包含了某些平台的实现，同时也有认可的其他平台的实现。

2.2.5 创建 package

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| #使用 --platforms= 命令行选项指定插件支持的平台，后面参数是用逗号分隔的列表 #使用 --org 选项，以反向域名表示法来指定你的组织。该值用于生成的 Android 及 iOS 代码 #使用 -a 选项指定 Android 的语言，或使用 -i 选项指定 iOS 的语言 flutter create --org com.example --template=plugin --platforms=android,ios -a kotlin hello flutter create --org com.example --template=plugin --platforms=android,ios -a java hello flutter create --org com.example --template=plugin --platforms=android,ios -i objc hello flutter create --org com.example --template=plugin --platforms=android,ios -i swift hello |

2.2.6 实现 package

由于原生插件类型的 package 包含了使用多种编程语言编写的多个平台代码，因此需要一些特定步骤来保证体验的流畅性。

定义 package API（.dart）

原生插件类型 package 的 API 在 Dart 代码中要首先定义好，找到 lib/hello.dart 文件。

添加 Android 平台代码

我们建议你使用 Android Studio 来编辑 Android 代码。

启动 Android Studio；
在 Android Studio 的欢迎菜单 (Welcome to Android Studio ) 对话框中选择打开现有的 Android Studio 项目 (Open an existing Android Studio Project )，或在菜单中选择 File > Open ，然后选择 hello/example/android/build.gradle 文件；
在Gradle Sync 对话框中，选择 OK；
在"Android Gradle Plugin Update"对话框中，选择"Don't remind me again for this project"。

插件中与 Android 系统徐相关的代码在 hello/java/com.example.hello/HelloPlugin 这个文件里。

添加 iOS 平台代码

我们建议你使用 Xcode 来编辑 iOS 代码。

使用 Xcode 编辑 iOS 平台代码之前，首先确保代码至少被构建过一次（即从 IDE/编辑器执行示例程序，或在终端中执行以下命令： cd hello/example; flutter build ios --no-codesign）。

接下来执行下面步骤：

启动 Xcode
选择"File > Open"，然后选择 hello/example/ios/Runner.xcworkspace 文件。

复制代码

你的插件的iOS平台代码位于Classes目录下

2.2.7 纯 Dart 平台的实现

在某些场景下，部分平台可能会完全使用 Dart 进行实现（例如使用 FFI）。若需要仅 Dart 的平台实现，你可以将 pubspec.yaml 里的 pluginClass 替换为 dartPluginClass。下面是 hello_windows 示例替换为仅 Dart 实现的代码：

flutter:
  plugin:
    implements: hello
    platforms:
      windows:
        dartPluginClass: HelloPluginWindows

方法的 HelloPluginWindows 类进行实现。该方法会在启动时调用，用于注册 Dart 实现：

|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| class HelloPluginWindows extends HelloPluginPlatform { /// Registers this class as the default instance of [HelloPluginPlatform]. static void registerWith() { HelloPluginPlatform.instance = HelloPluginWindows(); } |

三、发布package

一旦完成了 package 的实现，你便可以将其提交到 pub.dev 上，以便其他开发者可以轻松地使用它。

发布你的 package 之前，确保检查了这几个文件：pubspec.yaml、README.md 和 CHANGELOG.md，确保它们完整且正确，另外，为了提高 package 的可用性，可以考虑加入如下的内容：

代码的示例用法
屏幕截图，GIF 动画或者视频
代码库的正确指向链接

接下来，运行 dry-run 命令以检验是否所有内容都通过了分析：

|---------------------------------------|
| flutter pub publish --dry-run |

最后一步是发布，请注意：发布是永久性的，运行以下提交命令：

|-----------------------------|
| flutter pub publish |

设置了中国镜像的开发者们请注意：目前所存在的镜像都不能（也不应该）进行 package 的上传。

如果你设置了镜像，执行上述发布代码可能会造成发布失败。网络设定好后，无需取消中文镜像，执行下述代码可直接上传：

|---------------------------------------------------------------|
| flutter pub publish --server=https://pub.dartlang.org |