支持新的 Android 的 API

备忘 You might be directed to this page if the framework detects that your app uses a plugin based on the old Android APIs.

If you don’t write or maintain a Flutter plugin,you can skip this page.

As of the 1.10.17 release, new plugin APIs are available on themaster and dev channels. The old APIs won’t be immediatelydeprecated, but we encourage you to migrate to the new APIs.Over time, plugins using the old APIs might produce strangebehaviors when embedding Flutter into an Android app.Most of the Flutter plugins provided by flutter.dev havebeen migrated already. (Learn how to become a[verified publisher][] on pub.dev!) For an example ofa plugin that uses the new APIs, see thebattery package.

Upgrade steps

The following instructions outline the steps for supporting the new API:

  • Update the main plugin class (*Plugin.java) to implementFlutterPlugin. For more complex plugins, you can separate theFlutterPlugin and MethodCallHandler into two classes. See the nextsection, Basic plugin, for more details on accessing app resources withthe latest version (v2) of embedding.Also, note that the plugin should still contain the static registerWith()method to remain compatible with apps that don’t use the v2 embedding. Theeasiest thing to do (if possible) is move the logic from registerWith()into a private method that both registerWith() and onAttachedToEngine()can call. Either registerWith() or onAttachToEngine() will be called, notboth.If you are creating channels in your onAttachToEngine(), there is no needto cleanup those creations in onDetachFromEngine(), and creating them againthe second time onAttachToEngine() is called is fine.In addition, you should document all non-overridden public members within theplugin. In an add-to-app scenario, these classes will be accessible to adeveloper and require documentation.

  • (Optional) If your plugin needs an Activity reference,also implement ActivityAware.

  • (Optional) If your plugin is expected to be held in abackground Service at any point in time,implement ServiceAware.

  • Update the example app’s MainActivity.java to use thev2 embedding FlutterActivity. You may have to make apublic constructor for you plugin class if one didn’texist already. For example:

  1. package io.flutter.plugins.firebasecoreexample;
  3. import io.flutter.embedding.android.FlutterActivity;
  4. import io.flutter.embedding.engine.FlutterEngine;
  5. import io.flutter.plugins.firebase.core.FirebaseCorePlugin;
  7. public class MainActivity extends FlutterActivity {
  8.   // TODO(<github-username>): Remove this once v2 of
  9.   // GeneratedPluginRegistrant rolls to stable.
  10.   // https://github.com/flutter/flutter/issues/42694
  11.   @Override
  12.   public void configureFlutterEngine(FlutterEngine flutterEngine) {
  13.     flutterEngine.getPlugins().add(new FirebaseCorePlugin());
  14.   }
  15. }
  • (Optional) Use ShimPluginRegistry to add plugins that don’t yetsupport the v2 embedding. For example:
  1. ShimPluginRegistry shimPluginRegistry = new ShimPluginRegistry(flutterEngine);
  2. PathProviderPlugin.registerWith(
  3.         shimPluginRegistry.registrarFor("io.flutter.plugins.pathprovider.PathProviderPlugin"));
  4. VideoPlayerPlugin.registerWith(
  5.         shimPluginRegistry.registrarFor("io.flutter.plugins.videoplayer.VideoPlayerPlugin"));
  • Create an EmbeddingV1Activity.java file that uses the v1embedding in the same folder as MainActivity. For example:
  1. package io.flutter.plugins.firebasecoreexample;
  3. import android.os.Bundle;
  4. import io.flutter.app.FlutterActivity;
  5. import io.flutter.plugins.GeneratedPluginRegistrant;
  7. public class EmbeddingV1Activity extends FlutterActivity {
  8.  @Override
  9.  protected void onCreate(Bundle savedInstanceState) {
  10.    super.onCreate(savedInstanceState);
  11.    GeneratedPluginRegistrant.registerWith(this);
  12.  }
  13. }
  • Add the EmbeddingV1Activity to the /example/android/app/src/main/AndroidManifest.xml.For example:
  1. <activity
  2.     android:name=".EmbeddingV1Activity"
  3.     android:theme="@style/LaunchTheme"
  4.          android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale"
  5.     android:hardwareAccelerated="true"
  6.     android:windowSoftInputMode="adjustResize">
  7. </activity>
  • To have the plugin support Flutter on branches master and stable, include this gradle script in /android/build.gradle.
  1. // TODO(<github-username>): Remove this hack once androidx
  2. // lifecycle is included on stable.
  3. // https://github.com/flutter/flutter/issues/42348
  5. afterEvaluate {
  6.     def containsEmbeddingDependencies = false
  7.     for (def configuration : configurations.all) {
  8.         for (def dependency : configuration.dependencies) {
  9.             if (dependency.group == 'io.flutter' &&
  10.                     dependency.name.startsWith('flutter_embedding') &&
  11.                     dependency.isTransitive())
  12.             {
  13.                 containsEmbeddingDependencies = true
  14.                 break
  15.             }
  16.         }
  17.     }
  18.     if (!containsEmbeddingDependencies) {
  19.         android {
  20.             dependencies {
  21.                 def lifecycle_version = "1.1.1"
  22.                 compileOnly "android.arch.lifecycle:runtime:$lifecycle_version"
  23.                 compileOnly "android.arch.lifecycle:common:$lifecycle_version"
  24.                 compileOnly "android.arch.lifecycle:common-java8:$lifecycle_version"
  25.             }
  26.         }
  27.     }
  28. }

Testing your plugin

The remaining steps address testing your plugin, which we encourage,but aren’t required.

  • Update <plugin_name>/example/android/app/build.gradleto replace references to android.support.test with androidx.test:
  1. defaultConfig {
  2.    ...
  3.   testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
  4.   ...
  5. }
  1. dependencies {
  2. ...
  3. androidTestImplementation 'androidx.test:runner:1.2.0'
  4. androidTestImplementation 'androidx.test:rules:1.2.0'
  5. androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'
  6. ...
  7. }
  • Add tests files for MainActivity and EmbeddingV1Activityin <plugin_name>/example/android/app/src/androidTest/java/<plugin_path>/.You will need to create these directories. For example:
  1. package io.flutter.plugins.firebase.core;
  3. import androidx.test.rule.ActivityTestRule;
  4. import dev.flutter.plugins.e2e.FlutterRunner;
  5. import io.flutter.plugins.firebasecoreexample.MainActivity;
  6. import org.junit.Rule;
  7. import org.junit.runner.RunWith;
  9. @RunWith(FlutterRunner.class)
  10. public class MainActivityTest {
  11.   @Rule public ActivityTestRule<MainActivity> rule = new ActivityTestRule<>(MainActivity.class);
  12. }
  1. package io.flutter.plugins.firebase.core;
  3. import androidx.test.rule.ActivityTestRule;
  4. import dev.flutter.plugins.e2e.FlutterRunner;
  5. import io.flutter.plugins.firebasecoreexample.EmbeddingV1Activity;
  6. import org.junit.Rule;
  7. import org.junit.runner.RunWith;
  9. @RunWith(FlutterRunner.class)
  10. public class EmbeddingV1ActivityTest {
  11.   @Rule
  12.   public ActivityTestRule<EmbeddingV1Activity> rule =
  13.       new ActivityTestRule<>(EmbeddingV1Activity.class);
  14. }
  • Add e2e and flutter_driver dev_dependencies to<plugin_name>/pubspec.yaml and<plugin_name>/example/pubspec.yaml.
  1. e2e: ^0.2.1
  2. flutter_driver:
  3.   sdk: flutter
  • Manually register the E2E plugin in MainActivity.javaalongside any other plugins used by the example app.
  1. package io.flutter.plugins.packageinfoexample;
  3. import dev.flutter.plugins.e2e.E2EPlugin;
  4. import io.flutter.embedding.android.FlutterActivity;
  5. import io.flutter.embedding.engine.FlutterEngine;
  6. import io.flutter.plugins.packageinfo.PackageInfoPlugin;
  8. public class MainActivity extends FlutterActivity {
  9.   // TODO(jackson): Remove this once v2 of GeneratedPluginRegistrant
  10.   // rolls to stable.
  11.   // https://github.com/flutter/flutter/issues/42694
  12.   @Override
  13.   public void configureFlutterEngine(FlutterEngine flutterEngine) {
  14.     flutterEngine.getPlugins().add(new PackageInfoPlugin());
  15.     flutterEngine.getPlugins().add(new E2EPlugin());
  16.   }
  17. }
  • Update minimum Flutter version of environment in<plugin_name>/pubspec.yaml. All plugins movingforward will set the minimum version to 1.9.1+hotfix.4which is the minimum version for which we can guarantee support.For example:
  1. environment:
  2.   sdk: ">=2.0.0-dev.28.0 <3.0.0"
  3.   flutter: ">=1.9.1+hotfix.4 <2.0.0"
  • Create a simple test in <plugin_name>/test/<plugin_name>_e2e.dart.For the purpose of testing the PR that adds the v2 embedding support,we’re trying to test some very basic functionality of the plugin.This is a smoke test to ensure that the plugin properly registerswith the new embedder. For example:
  1. import 'package:flutter_test/flutter_test.dart';
  2. import 'package:battery/battery.dart';
  3. import 'package:e2e/e2e.dart';
  5. void main() {
  6.   E2EWidgetsFlutterBinding.ensureInitialized();
  8.   testWidgets('Can get battery level', (WidgetTester tester) async {
  9.     final Battery battery = Battery();
  10.     final int batteryLevel = await battery.batteryLevel;
  11.     expect(batteryLevel, isNotNull);
  12.   });
  13. }
  • Test run the e2e tests locally. In a terminal,do the following:
  1. cd <plugin_name>/example
  2. flutter build apk
  3. cd android
  4. ./gradlew app:connectedAndroidTest -Ptarget=`pwd`/../../test/<plugin_name>_e2e.dart

Basic plugin

To get started with a Flutter Android plugin in code,start by implementing FlutterPlugin.

  1. public class MyPlugin implements FlutterPlugin {
  2.   @Override
  3.   public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
  4.     // TODO: your plugin is now attached to a Flutter experience.
  5.   }
  7.   @Override
  8.   public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {
  9.     // TODO: your plugin is no longer attached to a Flutter experience.
  10.   }
  11. }

As shown above, your plugin may or may not be associated witha given Flutter experience at any given moment in time.You should take care to initialize your plugin’s behaviorin onAttachedToEngine(), and then cleanup your plugin’s referencesin onDetachedFromEngine().

The FlutterPluginBinding provides your plugin with a fewimportant references:

  • binding.getFlutterEngine()
  • Returns the FlutterEngine that your plugin is attached to,providing access to components like the DartExecutor,FlutterRenderer, and more.
  • binding.getApplicationContext()
  • Returns the Android application’s Context for the running app.
  • binding.getLifecycle()
  • Returns a reference that can be used to obtain a Lifecycle object.If you need to use this lifecycle reference then you need add aproject dependency on Flutter’s Android lifecycle package.

UI/Activity plugin

If your plugin needs to interact with the UI,such as requesting permissions, or altering Android UI chrome,then you need to take additional steps to define your plugin.You must implement the ActivityAware interface.

  1. public class MyPlugin implements FlutterPlugin, ActivityAware {
  2.   //...normal plugin behavior is hidden...
  4.   @Override
  5.   public void onAttachedToActivity(ActivityPluginBinding activityPluginBinding) {
  6.     // TODO: your plugin is now attached to an Activity
  7.   }
  9.   @Override
  10.   public void onDetachedFromActivityForConfigChanges() {
  11.     // TODO: the Activity your plugin was attached to was
  12.     // destroyed to change configuration.
  13.     // This call will be followed by onReattachedToActivityForConfigChanges().
  14.   }
  16.   @Override
  17.   public void onReattachedToActivityForConfigChanges(ActivityPluginBinding activityPluginBinding) {
  18.     // TODO: your plugin is now attached to a new Activity
  19.     // after a configuration change.
  20.   }
  22.   @Override
  23.   public void onDetachedFromActivity() {
  24.     // TODO: your plugin is no longer associated with an Activity.
  25.     // Clean up references.
  26.   }
  27. }

To interact with an Activity, your ActivityAware plugin mustimplement appropriate behavior at 4 stages. First, your pluginis attached to an Activity. You can access that Activity anda number of its callbacks through the provided ActivityPluginBinding.

Since Activitys can be destroyed during configuration changes,you must cleanup any references to the given Activity inonDetachedFromActivityForConfigChanges(),and then re-establish those references inonReattachedToActivityForConfigChanges().

Finally, in onDetachedFromActivity() your plugin should cleanup all references related to Activity behavior and return toa non-UI configuration.

Service plugin

TODO

ContentProvider plugin

TODO

[verified publisher]: {“api”=>”https://api.dart.dev”, “sdk”=>{“channel”=>”stable”}}/tools/pub/verified-publishers