开发包与插件

包可以实现模块化代码的创建，并能轻松共享。一个最小化的包包含以下内容：

pubspec.yaml

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

lib

lib 目录包含包中的公共代码，最少包含一个 <包名>.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 插件，第 1 部分 (How to Write a Flutter Web Plugin, Part 1)。

FFI 包

一种专门的 Dart 包，能够使用 dart:ffi 调用原生代码。这些包在独立的 Dart 环境中运行，不需要特定于操作系统的构建文件。它们通过 flutter create --template=package_ffi 命令创建（请参阅创建 FFI 包）。这是自 Flutter 3.38 以来构建和打包原生代码的推荐方法。

以下说明解释了如何编写 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/<包名>.dart 文件中，或在 lib 目录下的多个文件中添加功能即可。

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

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

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

API 通过平台通道 (platform channel) 连接到特定平台的实现。

联合插件 (Federated plugins) 是一种将插件 API 分割为平台接口、该接口的独立平台实现，以及使用运行平台注册实现的面向应用的接口的方法。

包分离式联合插件 (Package-separated federated plugins) 是指将平台接口、平台实现和面向应用的接口分别放入各自的 Dart 包中的联合插件。

因此，一个包分离式联合插件可以为 iOS 使用一个包，为 Android 使用另一个，为 Web 使用另一个，甚至为汽车（作为物联网设备示例）使用另一个。除了其他好处外，这种方法还允许领域专家扩展现有插件，以支持他们最熟悉的平台。

联合插件需要以下内容：

面向应用的接口 (app-facing interface)

插件用户在使用插件时与之交互的接口。该接口指定了 Flutter 应用使用的 API。在包分离式联合插件中，这是插件用户为了使用插件所依赖的包。

平台实现 (platform implementation(s))

一个或多个包含特定平台实现代码的实现。面向应用的接口会调用这些实现——除非它们包含终端用户可访问的特定平台功能，否则在应用中不会直接使用或依赖它们（当采用包分离式结构时）。

平台接口 (platform interface)

连接面向应用接口与平台实现的接口。它声明了任何平台实现必须实现的内容，以支持面向应用的接口。拥有一个定义此接口的独立包，可确保所有平台包以统一的方式实现相同的功能。

理想情况下，在向包分离式联合插件添加平台实现时，你会与包作者协调，将你的实现包含在内。这样，原始作者就背书 (endorses) 了你的实现。

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

如果由于某种原因你无法让原始插件作者添加你的实现，那么你的插件就是非背书的。开发者仍然可以使用你的实现，但必须手动将该插件添加到应用的 pubspec.yaml 文件中。

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

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

有关联合插件的更多信息、它们为何有用以及如何实现，请参阅 Harry Terkelsen 在 Medium 上发表的文章：如何编写 Flutter Web 插件，第 2 部分 (How To Write a Flutter Web Plugin, Part 2)。

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

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

当为更多平台添加插件实现时，应相应地更新 platforms 映射。例如，这是 hello 插件在更新以添加对 macOS 和 Web 支持后的 pubspec 文件中的映射：

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: 映射：

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

面向应用的包可以通过添加对平台包的依赖，并将其作为 platforms: 映射中的 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

请注意，如这里所示，面向应用的包可以在包内实现某些平台，而在背书的联合实现中实现其他平台。

许多框架使用相同或基本相同的 API 同时支持 iOS 和 macOS，这使得用相同的代码库实现某些针对 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 的 ios 目录和 macOS 的 macos 目录，而是使用一个共享的 darwin 目录存放所有代码和资源。启用此选项时，你需要将任何现有文件从 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

插件 API 的 Android 特定平台实现（使用 Kotlin）。

ios/Classes/HelloPlugin.m

插件 API 的 iOS 特定平台实现（使用 Objective-C）。

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. 在 Welcome to Android Studio 对话框中选择 Open an existing Android Studio Project，或者从菜单中选择 File > Open，然后选择 hello/example/android/build.gradle 或 hello/example/android/build.gradle.kts 文件。
3. 在 Gradle Sync 对话框中，选择 OK。
4. 在 Android Gradle Plugin Update 对话框中，选择 Don't remind me again for this project。

插件的 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. 选择 File > Open，并选择 hello/example/ios/Runner.xcworkspace 文件。

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

你可以通过按下运行 (▶) 按钮运行示例应用。

Flutter 使用 Swift Package Manager 作为管理原生 iOS 和 macOS 依赖的主要策略。

要使用 Swift Package Manager 将依赖项添加到你的插件中：

1. 在插件的 ios/my_plugin_name 或 macos/my_plugin_name 目录中创建一个 Package.swift 文件。
2. 在 Package.swift 描述文件的 dependencies 数组中声明你的原生依赖项：

dependencies: [
    .package(url: "https://github.com/path/to/HelloLibrary.git", from: "1.0.0")
]

有关构造原生文件夹、资源打包或处理混合设置的完整详细信息和说明，请访问插件作者的 Swift Package Manager 指南。

Flutter 继续支持 CocoaPods 以实现向后兼容。如果你的插件需要支持尚未迁移到 Swift Package Manager 的开发者，请在 ios/hello.podspec 的末尾指定你的 CocoaPods 依赖项：

s.dependency 'HelloPod', '0.0.1'

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

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
  }

要获取并链接插件的依赖项，请将插件添加到你应用项目的 pubspec.yaml 依赖项中，并运行 flutter pub get。Flutter 会在原生应用构建步骤中自动解析并连接 Swift Package Manager 描述符或 CocoaPods pod 文件。

如果你的插件需要隐私清单（例如，如果你使用了任何必需理由 API），请更新 PrivacyInfo.xcprivacy 文件以描述你的插件对隐私的影响，并将以下内容添加到你的 podspec 文件末尾：

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

更多信息，请查看 Apple 开发者网站上的 隐私清单文件 (Privacy manifest files)。

建议使用带有 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. 在询问 Would you like to configure project "linux"? 的提示中选择 Yes。这将允许 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. 选择 File > Open，并选择 hello/example/macos/Runner.xcworkspace 文件。

插件的 macOS 平台代码位于 Project Navigator 中的 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. 选择 Open a project or solution，并选择 hello/example/build/windows/hello_example.sln 文件。

插件的 Windows 平台代码位于 Solution Explorer 中的 hello_plugin/Source Files 和 hello_plugin/Header Files。

你可以通过在 Solution Explorer 中右键点击 hello_example 并选择 Set as Startup Project，然后按下运行 (▶) 按钮来运行示例应用。重要： 对插件代码进行更改后，必须先选择 Build > Build Solution，然后再重新运行，否则运行的将是已构建插件的过期版本，而不是包含你更改的最新版本。

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

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

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

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

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

在某些情况下，某些平台可以完全用 Dart 实现（例如，使用 FFI）。对于非 Web 平台上的仅 Dart 平台实现，请用 dartPluginClass 替换 pubspec.yaml 中的 pluginClass。这是上面修改后的 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++ 实现中的相同。

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

要了解有关测试插件的更多信息，请查看测试插件 (Testing plugins)。如果你正在为 Flutter 应用编写测试，而插件导致崩溃，请查看插件测试中的 Flutter (Flutter in plugin tests)。

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

要创建 FFI 入门包，请在 flutter create 中使用 --template=package_ffi 标志：

$ flutter create --template=package_ffi hello

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

lib：定义包 API 的 Dart 代码，它使用 dart:ffi 调用原生代码。

src：原生源代码。

hook/build.dart：编译原生代码的构建钩子脚本。

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

为了避免手动编写，它们由 package:ffigen 从头文件 (src/hello.h) 生成。请参考 ffigen 文档以获取有关如何安装此包的信息。

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

$ dart run tool/ffigen.dart

运行时间极短的原生函数可以直接从任何隔离区 (isolate) 调用。例如，请参见 lib/hello.dart 中的 sum。

运行时间较长的函数应在辅助隔离区 (helper 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
   

   content_copy

2. 告诉文档工具 Flutter SDK 的位置（修改以下命令以反映其实际位置）

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

   content_copy
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
   

   content_copy

有关如何编写 API 文档的建议，请参阅 Effective Dart 文档。

每个 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 的状态），请考虑包含以下内容：

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

接下来，以 dry-run（试运行）模式运行发布命令，查看一切是否通过分析：

$ 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 依赖项都像任何其他 Dart 包一样由 pubspec.yaml 文件处理。