开发包和插件

包支持创建可轻松共享的模块化代码。一个最小化的包包含以下内容：

pubspec.yaml

一个元数据文件，声明包的名称、版本、作者等。

lib

lib 目录包含包的公共代码，最少包含一个 <package-name>.dart 文件。

包可以包含多种类型的内容

Dart 包

用 Dart 编写的通用包，例如 path 包。其中一些可能包含 Flutter 特定的功能，因此依赖于 Flutter 框架，从而限制其仅在 Flutter 中使用，例如 fluro 包。

插件包

一种专门的 Dart 包，包含用 Dart 代码编写的 API，以及一个或多个特定于平台的实现。

插件包可以为 Android（使用 Kotlin 或 Java）、iOS（使用 Swift 或 Objective-C）、Web、macOS、Windows 或 Linux 编写，或它们的任意组合。

一个具体的例子是 url_launcher 插件包。要了解如何使用 url_launcher 包，以及如何扩展它以支持 Web，请参阅 Harry Terkelsen 的 Medium 文章 如何编写 Flutter Web 插件，第一部分。

FFI 插件包

一种专门的 Dart 包，包含用 Dart 代码编写的 API，以及一个或多个使用 Dart FFI 的特定平台实现（Android、iOS、macOS）。

以下说明将解释如何编写 Flutter 包。

要创建入门级的 Flutter 包，请在 flutter create 命令中使用 --template=package 标志。

flutter create --template=package hello

这会在 hello 文件夹中创建一个包项目，包含以下内容：

LICENSE

一个（大部分）空的许可证文本文件。

test/hello_test.dart

包的 单元测试。

hello.iml

IntelliJ IDE 使用的配置文件。

.gitignore

一个隐藏文件，告诉 Git 项目中要忽略哪些文件或文件夹。

.metadata

一个隐藏文件，IDE 用来跟踪 Flutter 项目的属性。

pubspec.yaml

一个包含元数据的 yaml 文件，指定了包的依赖项。由 pub 工具使用。

README.md

一个入门级的 markdown 文件，简要描述了包的用途。

lib/hello.dart

一个包含包 Dart 代码的入门级应用。

.idea/modules.xml, .idea/workspace.xml

一个隐藏文件夹，包含 IntelliJ IDE 的配置文件。

CHANGELOG.md

一个（大部分）空的 markdown 文件，用于跟踪包的版本变更。

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

要测试该包，请在 test 目录中添加 单元测试。

有关如何组织包内容的更多详细信息，请参阅 Dart 库包 文档。

如果你想开发一个调用平台特定 API 的包，你需要开发一个插件包。

API 使用 平台通道 连接到特定平台的实现。

联邦插件是将不同平台的支持拆分到单独的包中的一种方式。因此，一个联邦插件可以为 iOS 使用一个包，为 Android 使用另一个包，为 Web 使用另一个包，再为汽车（作为 IoT 设备的一个例子）使用另一个包。除其他好处外，这种方法允许领域专家扩展现有插件以适用于他们最了解的平台。

联邦插件需要以下包：

面向应用的包

插件用户依赖以使用插件的包。此包指定了 Flutter 应用使用的 API。

平台包

一个或多个包含特定平台实现代码的包。面向应用的包调用这些包——它们不会包含在应用中，除非它们包含最终用户可访问的特定平台功能。

平台接口包

将面向应用的包与平台包粘合在一起的包。此包声明一个接口，任何平台包都必须实现该接口才能支持面向应用的包。拥有一个定义此接口的包可确保所有平台包以统一的方式实现相同的功能。

理想情况下，当向联邦插件添加平台实现时，您将与包作者协调以包含您的实现。这样，原始作者会推荐您的实现。

例如，假设你为（虚构的）foobar 插件编写了一个 foobar_windows 实现。在一个推荐的插件中，原始的 foobar 作者会将你的 Windows 实现添加为面向应用的包的 pubspec 的依赖项。然后，当开发者将 foobar 插件包含在他们的 Flutter 应用中时，Windows 实现以及其他推荐的实现将自动提供给应用。

如果你因为任何原因无法获得你的实现被原始插件作者添加，那么你的插件就不是推荐的。开发者仍然可以使用你的实现，但必须手动将该插件添加到应用的 pubspec.yaml 文件中。

dependencies:
  foobar: ^1.0.0
  foobar_windows: ^1.0.0 # Non-endorsed plugin implementation

此方法也适用于覆盖 foobar 已推荐的插件实现。

有关联邦插件的更多信息，它们为何有用，以及如何实现它们，请参阅 Harry Terkelsen 的 Medium 文章 如何编写 Flutter Web 插件，第二部分。

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

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

添加更多平台的插件实现时，应相应地更新 platforms map。例如，当更新以添加对 macOS 和 Web 的支持时，hello 插件的 pubspec 文件中的 map 如下所示：

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

平台包使用相同的格式，但包含一个 implements 条目，指示它实现的面向应用的包。例如，一个包含 hello 的 Windows 实现的 hello_windows 插件将具有以下 flutter: map：

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

面向应用的包可以通过添加对平台包的依赖项，并将其包含在 platforms: map 的 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

请注意，如所示，面向应用的包可以将一些平台实现包含在其自身包中，而其他平台则包含在推荐的联邦实现中。

许多框架同时支持 iOS 和 macOS，具有相同或几乎相同的 API，因此有可能使用相同的代码库为 iOS 和 macOS 实现一些插件。通常，每个平台的实现都在其自己的文件夹中，但 sharedDarwinSource 选项允许 iOS 和 macOS 使用同一个文件夹。

flutter:
  plugin:
    platforms:
      ios:
        pluginClass: HelloPlugin
        sharedDarwinSource: true
      macos:
        pluginClass: HelloPlugin
        sharedDarwinSource: true

environment:
  sdk: ^3.0.0
  # Flutter versions prior to 3.7 did not support the
  # sharedDarwinSource option.
  flutter: ">=3.7.0"

启用 sharedDarwinSource 后，iOS 和 macOS 将使用一个共享的 darwin 文件夹来存放所有代码和资源，而不是各自的 ios 和 macos 目录。启用此选项时，你需要将 ios 和 macos 中的任何现有文件移到共享目录。你还需要更新 podspec 文件以设置两个平台的依赖项和部署目标，例如：

  s.ios.dependency 'Flutter'
  s.osx.dependency 'FlutterMacOS'
  s.ios.deployment_target = '13.0'
  s.osx.deployment_target = '10.15'

要创建插件包，请在 flutter create 命令中使用 --template=plugin 标志。

使用 --platforms= 选项后跟逗号分隔的列表，指定插件支持的平台。可用平台包括：android、ios、web、linux、macos 和 windows。如果未指定平台，则生成的项目不支持任何平台。

使用 --org 选项，以反向域名表示法指定你的组织。此值用于生成插件代码中的各种包和捆绑包标识符。

默认情况下，插件项目对 iOS 代码使用 Swift，对 Android 代码使用 Kotlin。如果你偏好 Objective-C 或 Java，可以使用 -i 为 iOS 指定语言，使用 -a 为 Android 指定语言。请选择以下一种：

flutter create --org com.example --template=plugin --platforms=android,ios,linux,macos,windows -a kotlin hello

flutter create --org com.example --template=plugin --platforms=android,ios,linux,macos,windows -a java hello

flutter create --org com.example --template=plugin --platforms=android,ios,linux,macos,windows -i objc hello

flutter create --org com.example --template=plugin --platforms=android,ios,linux,macos,windows -i swift hello

这会在 hello 文件夹中创建一个插件项目，包含以下特定内容：

lib/hello.dart

插件的 Dart API。

android/src/main/java/com/example/hello/HelloPlugin.kt

Kotlin 语言的插件 API 的 Android 特定实现。

ios/Classes/HelloPlugin.m

Objective-C 语言的插件 API 的 iOS 特定实现。

example/

一个依赖于该插件的 Flutter 应用，并演示了如何使用它。

由于插件包包含多种编程语言编写的多个平台代码，因此需要一些特定步骤来确保顺畅的体验。

插件包的 API 在 Dart 代码中定义。在您喜欢的 Flutter 编辑器 中打开主 hello/ 文件夹。找到文件 lib/hello.dart。

建议使用 Android Studio 编辑 Android 代码。

在 Android Studio 中编辑 Android 平台代码之前，请确保代码至少已构建一次（换句话说，从 IDE/编辑器运行示例应用，或在终端中执行 cd hello/example; flutter build apk --config-only）。

然后按照以下步骤操作：

1. 启动 Android Studio。
2. 在“欢迎使用 Android Studio”对话框中选择“打开现有的 Android Studio 项目”，或从菜单中选择“文件 > 打开”，然后选择 hello/example/android/build.gradle 文件。
3. 在“Gradle 同步”对话框中，选择“确定”。
4. 在“Android Gradle 插件更新”对话框中，选择“对此项目不再提醒”。

插件的 Android 平台代码位于 hello/java/com.example.hello/HelloPlugin。

你可以通过按运行（▶）按钮从 Android Studio 运行示例应用。

建议使用 Xcode 编辑 iOS 代码。

在 Xcode 中编辑 iOS 平台代码之前，请确保代码至少已构建一次（换句话说，从 IDE/编辑器运行示例应用，或在终端中执行 cd hello/example; flutter build ios --no-codesign --config-only）。

然后按照以下步骤操作：

1. 启动 Xcode。
2. 选择“文件 > 打开”，然后选择 hello/example/ios/Runner.xcworkspace 文件。

插件的 iOS 平台代码位于项目导航器中的 Pods/Development Pods/hello/../../example/ios/.symlinks/plugins/hello/ios/Classes。（如果你使用 sharedDarwinSource，路径将以 hello/darwin/Classes 结尾。）

你可以通过按运行（▶）按钮运行示例应用。

使用以下说明添加版本为 0.0.1 的 HelloPod：

1. 在 ios/hello.podspec 的末尾指定依赖项：

   ruby

   s.dependency 'HelloPod', '0.0.1'

   对于私有 pod，请参考 私有 CocoaPods 以确保仓库访问权限。

   ruby

   s.source = {
       # For pods hosted on GitHub
       :git => "https://github.com/path/to/HelloPod.git",
       # Alternatively, for pods hosted locally
       # :path => "file:///path/to/private/repo",
       :tag => s.version.to_s
     }`

2. 安装插件

   • 在项目的 pubspec.yaml 依赖项中添加插件。
   • 运行 flutter pub get。
   • 在项目的 ios/ 目录中，运行 pod install。

Pod 应出现在安装摘要中。

如果你的插件需要隐私清单，例如，如果它使用任何必需的理由 API，请更新 PrivacyInfo.xcprivacy 文件以描述你的插件对隐私的影响，并在 podspec 文件的底部添加以下内容：

s.resource_bundles = {'your_plugin_privacy' => ['your_plugin/Sources/your_plugin/Resources/PrivacyInfo.xcprivacy']}

有关更多信息，请查看 Apple 开发者网站上的 隐私清单文件。

建议使用支持 C++ 集成的 IDE 来编辑 Linux 代码。以下说明适用于已安装“C/C++”和“CMake”扩展的 Visual Studio Code，但可以根据其他 IDE 进行调整。

在 IDE 中编辑 Linux 平台代码之前，请确保代码至少已构建一次（换句话说，从 Flutter IDE/编辑器运行示例应用，或在终端中执行 cd hello/example; flutter build linux）。

然后按照以下步骤操作：

1. 启动 Visual Studio Code。
2. 打开 hello/example/linux/ 目录。
3. 在询问“是否要配置项目“linux”？”的提示中选择“是”。这将允许 C++ 自动完成工作。

插件的 Linux 平台代码位于 flutter/ephemeral/.plugin_symlinks/hello/linux/。

你可以使用 flutter run 运行示例应用。注意：在 Linux 上创建可运行的 Flutter 应用需要 flutter 工具的一部分步骤，因此即使你的编辑器提供了 CMake 集成，通过这种方式构建和运行也无法正常工作。

建议使用 Xcode 编辑 macOS 代码。

在 Xcode 中编辑 macOS 平台代码之前，请确保代码至少已构建一次（换句话说，从 IDE/编辑器运行示例应用，或在终端中执行 cd hello/example; flutter build macos --config-only）。

然后按照以下步骤操作：

1. 启动 Xcode。
2. 选择“文件 > 打开”，然后选择 hello/example/macos/Runner.xcworkspace 文件。

插件的 macOS 平台代码位于项目导航器中的 Pods/Development Pods/hello/../../example/macos/Flutter/ephemeral/.symlinks/plugins/hello/macos/Classes。（如果你使用 sharedDarwinSource，路径将以 hello/darwin/Classes 结尾。）

你可以通过按运行（▶）按钮运行示例应用。

建议使用 Visual Studio 编辑 Windows 代码。

在 Visual Studio 中编辑 Windows 平台代码之前，请确保代码至少已构建一次（换句话说，从 IDE/编辑器运行示例应用，或在终端中执行 cd hello/example; flutter build windows）。

然后按照以下步骤操作：

1. 启动 Visual Studio。
2. 选择“打开项目或解决方案”，然后选择 hello/example/build/windows/hello_example.sln 文件。

插件的 Windows 平台代码位于解决方案资源管理器中的 hello_plugin/Source Files 和 hello_plugin/Header Files。

你可以通过在解决方案资源管理器中右键单击 hello_example 并选择“设置为启动项目”，然后按运行（▶）按钮来运行示例应用。重要提示：在对插件代码进行更改后，必须先选择“生成 > 生成解决方案”，然后才能再次运行，否则将运行插件的旧副本而不是包含你更改的最新版本。

最后，你需要将用 Dart 代码编写的 API 与特定平台的实现连接起来。这通过 平台通道 或通过平台接口包中定义的接口来完成。

要为现有插件项目添加对特定平台的支持，请在项目目录中再次运行 flutter create 命令，并附带 --template=plugin 标志。例如，要为现有插件添加 Web 支持，请运行：

flutter create --template=plugin --platforms=web .

如果此命令显示有关更新 pubspec.yaml 文件的消息，请按照提供的说明操作。

在许多情况下，非 Web 平台实现仅使用特定平台语言，如上所示。但是，平台实现也可以使用特定平台的 Dart。

在某些情况下，某些平台可以完全用 Dart 实现（例如，使用 FFI）。对于非 Web 平台以外的平台的纯 Dart 实现，请将 pubspec.yaml 中的 pluginClass 替换为 dartPluginClass。以下是上面 hello_windows 示例修改为纯 Dart 实现的情况：

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

在这种版本中，你将没有 C++ Windows 代码，而是将 hello 插件的 Dart 平台接口类子类化为一个名为 HelloPluginWindows 的类，该类包含一个静态的 registerWith() 方法。此方法在启动时调用，可用于注册 Dart 实现。

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

平台实现还可以同时使用 Dart 和特定平台的语言。例如，一个插件可以为每个平台使用不同的平台通道，以便可以按平台自定义通道。

混合实现同时使用了上面描述的两种注册系统。以下是上面 hello_windows 示例修改为混合实现的情况：

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

Dart 的 HelloPluginWindows 类将使用上面为纯 Dart 实现显示的 registerWith()，而 C++ 的 HelloPlugin 类将与纯 C++ 实现相同。

我们鼓励你通过自动化测试来测试你的插件，以确保在代码更改时功能不会回归。

要了解有关测试插件的更多信息，请参阅 测试插件。如果你正在为 Flutter 应用编写测试，并且插件导致崩溃，请参阅 插件测试中的 Flutter。

如果你想开发一个使用 Dart 的 FFI 调用原生 API 的包，你需要开发一个 FFI 插件包。

FFI 插件包和非 FFI 插件包都支持打包原生代码。但是，FFI 插件包不支持方法通道，但它们确实支持方法通道注册代码。要实现同时使用方法通道和 FFI 的插件，请使用非 FFI 插件。每个平台都可以使用 FFI 或非 FFI 平台。

要创建入门级的 FFI 插件包，请在 flutter create 命令中使用 --template=plugin_ffi 标志。

flutter create --template=plugin_ffi hello

这会在 hello 文件夹中创建一个 FFI 插件项目，包含以下特定内容：

lib：定义插件 API 并使用 dart:ffi 调用原生代码的 Dart 代码。

src：原生源代码，以及一个用于将该源代码构建成动态库的 CMakeLists.txt 文件。

平台文件夹（android、ios、windows 等）：用于将原生代码库与平台应用程序构建和打包的构建文件。

pubspec.yaml 文件如下定义 FFI 插件：

  plugin:
    platforms:
      some_platform:
        ffiPlugin: true

此配置调用针对各种目标平台的原生构建，并将二进制文件打包到使用这些 FFI 插件的 Flutter 应用程序中。

这可以与 dartPluginClass 结合使用，例如当 FFI 用于联邦插件中某个平台的实现时：

  plugin:
    implements: some_other_plugin
    platforms:
      some_platform:
        dartPluginClass: SomeClass
        ffiPlugin: true

插件可以同时包含 FFI 和方法通道。

  plugin:
    platforms:
      some_platform:
        pluginClass: SomeName
        ffiPlugin: true

FFI（和方法通道）插件调用的原生构建系统是：

• 对于 Android：Gradle，它调用 Android NDK 进行原生构建。
  • 请参阅 android/build.gradle 中的文档。
• 对于 iOS 和 macOS：Xcode，使用 CocoaPods。
  • 请参阅 ios/hello.podspec 中的文档。
  • 请参阅 macos/hello.podspec 中的文档。
• 对于 Linux 和 Windows：CMake。
  • 请参阅 linux/CMakeLists.txt 中的文档。
  • 请参阅 windows/CMakeLists.txt 中的文档。

要使用原生代码，需要 Dart 中的绑定。

为了避免手动编写这些绑定，它们是从头文件（src/hello.h）由 package:ffigen 生成的。有关如何安装此包的信息，请参考 ffigen 文档。

要重新生成绑定，请运行以下命令：

dart run ffigen --config ffigen.yaml

非常短的本地函数可以直接从任何 isolate 调用。有关示例，请参阅 lib/hello.dart 中的 sum。

较长的函数应在 辅助 isolate 上调用，以避免在 Flutter 应用中掉帧。有关示例，请参阅 lib/hello.dart 中的 sumAsync。

建议对所有包添加以下文档：

1. 一个 README.md 文件，介绍该包
2. 一个 CHANGELOG.md 文件，记录每个版本的更改
3. 一个包含该包许可条款的 LICENSE 文件
4. 所有公共 API 的 API 文档（有关详细信息，请参见下文）

发布包时，API 文档会自动生成并发布到 pub.dev/documentation。例如，请参阅 device_info_plus 的文档。

如果你想在本地开发机器上生成 API 文档，请使用以下命令：

1. 切换目录到你的包所在的位置

   cd ~/dev/mypackage

2. 告诉文档工具 Flutter SDK 的位置（修改以下命令以反映你放置的位置）：

      export FLUTTER_ROOT=~/dev/flutter  # on macOS or Linux
   
      set FLUTTER_ROOT=~/dev/flutter     # on Windows

3. 运行 `dart doc` 工具（包含在 Flutter SDK 中），如下所示：

      $FLUTTER_ROOT/bin/cache/dart-sdk/bin/dart doc   # on macOS or Linux
   
      %FLUTTER_ROOT%\bin\cache\dart-sdk\bin\dart doc  # on Windows

有关如何编写 API 文档的技巧，请参阅 Effective Dart Documentation。

LICENSE 文件中的单个许可证应每行用 80 个连字符分隔。

如果 LICENSE 文件包含多个组件许可证，则每个组件许可证必须以适用于该组件许可证的包名称开头，每个包名称独占一行，并且包名称列表与实际许可证文本之间用一个空行分隔。（包的名称不必与 pub 包的名称匹配。例如，一个包本身可能包含来自多个第三方来源的代码，并且可能需要包含每个来源的许可证。）

以下示例显示了一个组织良好的许可证文件：

package_1

<some license text>

--------------------------------------------------------------------------------
package_2

<some license text>

以下是另一个组织良好的许可证文件示例：

package_1

<some license text>

--------------------------------------------------------------------------------
package_1
package_2

<some license text>

以下是一个组织不佳的许可证文件示例：

<some license text>

--------------------------------------------------------------------------------
<some license text>

另一个组织不佳的许可证文件示例：

package_1

<some license text>
--------------------------------------------------------------------------------
<some license text>

实现包后，你可以在 pub.dev 上发布它，以便其他开发者可以轻松使用。

在发布之前，请确保审查 pubspec.yaml、README.md 和 CHANGELOG.md 文件，以确保其内容完整且正确。此外，为了提高包的质量和可用性（并使其更有可能达到 Flutter Favorites 的状态），请考虑包含以下项目：

• 多样化的代码使用示例
• 截图、动画 GIF 或视频
• 指向相应代码存储库的链接

接下来，在 dry-run 模式下运行 publish 命令，查看是否所有分析都通过：

flutter pub publish --dry-run

下一步是发布到 pub.dev，但请确保你已准备好，因为发布是永久性的。

flutter pub publish

有关发布的更多详细信息，请参阅 dart.dev 上的 发布文档。

如果你正在开发一个依赖于另一个包暴露的 Dart API 的 hello 包，你需要将该包添加到 pubspec.yaml 文件的 dependencies 部分。下面的代码使 url_launcher 插件的 Dart API 对 hello 可用：

dependencies:
  url_launcher: ^6.3.2

现在你可以在 hello 的 Dart 代码中 import 'package:url_launcher/url_launcher.dart' 并使用 launch(someUrl)。

这与你在 Flutter 应用或其他 Dart 项目中包含包的方式没有区别。

但是，如果 hello 碰巧是一个*插件*包，其特定平台代码需要访问 url_launcher 暴露的特定平台 API，你还需要将适当的依赖项声明添加到你的特定平台构建文件中，如下所示。

以下示例在 hello/android/build.gradle 中为 url_launcher 设置了依赖项：

android {
    // lines skipped
    dependencies {
        compileOnly rootProject.findProject(":url_launcher")
    }
}

现在你可以在 hello/android/src 的源代码中 import io.flutter.plugins.urllauncher.UrlLauncherPlugin 并访问 UrlLauncherPlugin 类。

有关 build.gradle 文件的更多信息，请参阅 Gradle 文档中的构建脚本。

以下示例在 hello/ios/hello.podspec 中为 url_launcher 设置了依赖项：

Pod::Spec.new do |s|
  # lines skipped
  s.dependency 'url_launcher'

现在你可以在 hello/ios/Classes 的源代码中 #import "UrlLauncherPlugin.h" 并访问 UrlLauncherPlugin 类。

有关 .podspec 文件的更多详细信息，请参阅 CocoaPods 文档。

所有 Web 依赖项都由 pubspec.yaml 文件处理，就像其他 Dart 包一样。