Flutter插件(Plugin)开发 - Android视角

13,282 阅读8分钟

前言

上篇文章 Flutter如何和Native通信-Android视角 讲了Flutter app和Native通信的机制。文末提到如果你把某个Native功能(比如蓝牙,GPS什么的)用Platform Channels包装成了完美的Flutter API。那么你可以用插件(Plugin)的形式把你的API开放给Flutter开发者们使用。

Flutter里的包分为插件包(Plugin packages)和Dart包(Dart packages)的区别。

-- 插件包(Plugin packages)是当你需要暴露Native API给别人的时候使用的形式,内部需要使用Platform Channels并包含Androiod/iOS原生逻辑。

-- Dart包(Dart packages)是当你需要开发一个纯Dart组件(比如一个自定义的Weidget)的时候使用的形式,内部没有Native代码。

本文会简单介绍一下怎么从零开始开发一个包装了Android MediaPlayer的Flutter插件。相关代码可以从Github获取。

注意,此插件不包含iOS相关代码,并且只有有限的功能,仅供学习使用,切勿用于正式App开发。

需求

先上一张图说明一下使用场景。

插件使用例子

使用这个插件的Flutter App可以实现一个有以下功能的低配版音乐播放器。

  • 打开手机上的本地音乐文件并自动开始播放。
  • 播放/暂停按钮可以暂停或恢复播放。
  • 界面显示当前已播放时长/总时长。
  • 界面显示播放器状态:就绪/播放中/已暂停/播放结束。

有了以上需求,那我们来考虑插件需要给Flutter App提供哪些接口:

  • 打开本地音乐:"open"
  • 播放:"start"
  • 暂停:"pause"
  • 获取总时长:"getDuration"

上述接口都由Flutter app发起调用,需要MethodChannel实现。此外,插件还需要上报播放器状态和播放时长,上报这类事件由EventChannel实现。

需求搞清楚了,那我们就开始开发这个插件吧。

开发

首先在Android Studio里新建一个Flutter Plugin工程: File > New > New Flutter Project... 在弹出的对话框里选择 "Flutter Plugin"

选择
然后一路 "Next"下去。完成后的工程结构如下:
插件工程结构
整个工程包含4个主目录,android和ios目录下是对应Native代码。lib目录下是插件的Flutter端代码。example目录下是个完整的Flutter App。这个App示范怎么使用你开发的Flutter插件。在本例中,example在手机上跑起来就是上面那个播放器的样子。

插件Native端

照例我们先来看看Native端怎么做,在android目录下,IDE会为你生成一个XXXPlugin.java的文件。打开打开以后可以看到下面这样的示例代码:

/** FlutterMusicPlugin */
public class FlutterMusicPlugin implements MethodCallHandler {
  /** Plugin registration. */
  public static void registerWith(Registrar registrar) {
  final FlutterMusicPlugin plugin = new FlutterMusicPlugin();
    final MethodChannel channel = new MethodChannel(registrar.messenger(), "flutter_music_plugin");
    channel.setMethodCallHandler(plugin);
  }

  @Override
  public void onMethodCall(MethodCall call, Result result) {
     // TODO implement method call handler
  }
}

里面有一个实现了MethodCallHandler的类FlutterPlugin和一个静态函数registerWith。在这个静态函数里,new了一个MethodChannel,然后把FlutterPlugin的实例设置给了这个MehodChannel。换句话说,你的插件里的那些个MethodChannelEventChannel都是通过这个函数注册到Host App的。这样Flutter端在调用的时候才能找到对应的channel。接下来我们要做的就是重写onMethodCall这个函数,把之前定义好的媒体播放的API在这里做路由:

@Override
    public void onMethodCall(MethodCall call, Result result) {
        switch (call.method) {
            case "pause":
                // 暂停
                mMediaPlayer.pause();
                break;
            case "start":
                // 开始播放
                mMediaPlayer.start();
                break;
            case "open":
                //TODO 打开本地音频文件
                break;
            case "getDuration":
                // 获取音频时长
                if (mMediaPlayer != null) {
                    result.success(mMediaPlayer.getDuration());
                } else {
                    result.error("ERROR", "no valid media player", null);
                }
                break;
            default:
                result.notImplemented();
                break;
        }
    }

具体本地MediaPlayer的操作就不细说了,大家可以去看源码。MethodChannel就添加完了。此外我们还需要上报播放器的状态和播放时的进度,这就需要在registerWith里再注册两个EventChannel了

public static void registerWith(Registrar registrar) {
     ...
     // 上报播放器的状态的EventChannel
    EventChannel status_channel = new EventChannel(registrar.messenger(), "flutter_music_plugin.event.status");
        status_channel.setStreamHandler(new EventChannel.StreamHandler() {
            @Override
            public void onListen(Object o, EventChannel.EventSink eventSink) {
                // 把eventSink存起来
                plugin.setStateSink(eventSink);
            }

            @Override
            public void onCancel(Object o) {

            }
        });
        //上报播放进度的EventChannel
        EventChannel position_channel = new EventChannel(registrar.messenger(), "flutter_music_plugin.event.position");
        position_channel.setStreamHandler(new EventChannel.StreamHandler() {
            @Override
            public void onListen(Object o, EventChannel.EventSink eventSink) {
                // 把eventSink存起来
                plugin.setPositionSink(eventSink);
            }

            @Override
            public void onCancel(Object o) {

            }
        });
  }

注册完以后我们就拿到了两个EventSink,当需要的时候就可以用需要的EventSink给Flutter App上报事件了。

Native这边还有一环是打开本地音频文件的操作,这里我偷个懒,用发送Intent的方式来让用户在第三方app中选择音频文件。如果是在Activity中我会用startActivityForResultonActivityResult来获取音频文件,可是我们现在开发的是一个插件,不是Activity怎么办?

回想一下我们用来注册插件的静态函数registerWith,入参的类型是Registrar。看看它里面都有啥?

public interface Registrar {
        //返回 Host app的Activity
        Activity activity();
        //返回 Application Context.
        Context context();
        //返回 活动Context
        Context activeContext();
        //返回 BinaryMessenger 主要用来注册Platform channels
        BinaryMessenger messenger();
        //返回 TextureRegistry,从里面可以拿到SurfaceTexture 
        TextureRegistry textures();
        //返回 当前Host app创建的FlutterView
        FlutterView view();
        //返回Asset对应的文件路径
        String lookupKeyForAsset(String var1);
        //返回Asset对应的文件路径
        String lookupKeyForAsset(String var1, String var2);
        //插件对外发布的一个"值"
        PluginRegistry.Registrar publish(Object var1);
        //注册权限相关的回调
        PluginRegistry.Registrar addRequestPermissionsResultListener(PluginRegistry.RequestPermissionsResultListener var1);
        //注册ActivityResult回调
        PluginRegistry.Registrar addActivityResultListener(PluginRegistry.ActivityResultListener var1);
        //注册NewIntent回调
        PluginRegistry.Registrar addNewIntentListener(PluginRegistry.NewIntentListener var1);
        //注册UserLeaveHint回调
        PluginRegistry.Registrar addUserLeaveHintListener(PluginRegistry.UserLeaveHintListener var1);
        //注册View销毁回调
        PluginRegistry.Registrar addViewDestroyListener(PluginRegistry.ViewDestroyListener var1);
    }

。。。简直就是个宝库啊。里面的中文注释我是照官方英文文档翻译的,有些方法的用途也不太明确,有待大家的发掘。本例中目前只需要两个方法,调用activity()就拿到Host App的Activity。addActivityResultListener设置处理返回结果的回调。代码如下:

// 实现 PluginRegistry.ActivityResultListener
public class FlutterMusicPlugin implements MethodCallHandler, PluginRegistry.ActivityResultListener {
    ...
    private Activity mActivity;
    // 加个构造函数,入参是Activity
    private FlutterMusicPlugin(Activity activity) {
        // 存起来
        mActivity = activity;
    }
    
    public static void registerWith(Registrar registrar) {
        //传入Activity
        final FlutterMusicPlugin plugin = new FlutterMusicPlugin(registrar.activity());
        ...
        // 注册ActivityResult回调
        registrar.addActivityResultListener(plugin);
    }
    
    @Override
    public void onMethodCall(MethodCall call, Result result) {
        switch (call.method) {
            ...
            case "open":
                Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
                intent.addCategory(Intent.CATEGORY_OPENABLE);
                intent.setType("audio/*");
                mActivity.startActivityForResult(intent, REQUEST_CODE_OPEN);
                break;
           ...
        }
    }
    
    @Override
    public boolean onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == REQUEST_CODE_OPEN && resultCode == RESULT_OK) {
            Uri uri = data.getData();
            if (uri != null) {
                // 拿到音频文件uri,开始播放。
                play(uri);
            } else {
                mStateSink.error("ERROR", "invalid media file", null);
            }
            return true;
        }
        return false;
    }
}

我们改造一下FlutterMusicPlugin, 增加以Activity为入参的构造函数,在静态函数registerWith里实例化的时候传入Host app的Activity。同时注册自身来处理onActivityResult回调。 在onMethodCall方法内"open"下启动第三方选择音频文件的页面。当用户选好了某首歌返回的时候,插件这边就会拿到音频文件uri,并开始播放。

至此,Native端的逻辑就完成了,我们再来看看插件的Flutter端怎么做。

插件Flutter端

IDE在lib目录下会帮你自动生成flutter_music_plugin.dart文件,这个就是插件的Flutter代码所在了,内容比较简单,就是对我们定义好的Platform channels的包装。直接上代码:

typedef void EventHandler(Object event);

class FlutterMusicPlugin {
  static const MethodChannel _channel = const MethodChannel('flutter_music_plugin');
  static const EventChannel _status_channel = const EventChannel('flutter_music_plugin.event.status');
  static const EventChannel _position_channel = const EventChannel('flutter_music_plugin.event.position');

  static Future<void> open() async {
    await _channel.invokeMethod('open');
  }

  static Future<void> pause() async {
    await _channel.invokeMethod('pause');
  }

  static Future<void> start() async {
    await _channel.invokeMethod('start');
  }

  static Future<Duration> getDuration() async {
    int duration = await _channel.invokeMethod('getDuration');
    return Duration(milliseconds: duration);
  }

  static listenStatus(EventHandler onEvent, EventHandler onError) {
    _status_channel.receiveBroadcastStream().listen(onEvent, onError: onError);
  }

  static listenPosition(EventHandler onEvent, EventHandler onError) {
  _position_channel.receiveBroadcastStream().listen(onEvent, onError: onError);
  }
}

插件Example App

除了自身的逻辑之外,一个插件还要有示例应用来演示其API怎么使用,同时,示例应用也是我们开发,调试,验证插件的必备工具。本例中的示例可参考example目录下的main.dart文件。使用插件API的主要逻辑都在State中。简要代码如下

  @override
  void initState() {
    super.initState();
    // 在这里注册EventChannles,参数传入响应的回调
    FlutterMusicPlugin.listenStatus(_onPlayerStatus, _onPlayerStatusError);
    FlutterMusicPlugin.listenPosition(_onPosition, _onPlayerStatusError);
  }
  ...
  // 根据播放状态调用pause或start
  void _playPause() {
    switch (_status) {
      case "started":
        FlutterMusicPlugin.pause();
        break;
      case "paused":
      case "completed":
        FlutterMusicPlugin.start();
        break;
    }
  }
  // 打开媒体文件
  void _open() {
    FlutterMusicPlugin.open();
  }
  // MediaPlayer出错事件处理
  void _onPlayerStatusError(Object event) {
    print(event);
  }
  // MediaPlayer状态改变事件处理
  void _onPlayerStatus(Object event) {
    setState(() {
      _status = event;
    });
    if (_status == "started") {
      _getDuration();
    }
  }
  // 获取音频时长
  void _getDuration() async {
    Duration duration = await FlutterMusicPlugin.getDuration();
    setState(() {
      _duration = duration;
    });
  }
  // 播放进度事件处理
  void _onPosition(Object event) {
    Duration position = Duration(milliseconds: event);
    setState(() {
      _position = position;
    });
  }

发布

当你的插件开发测试完成以后,你就可以把你的插件发布出去了。 发布之前,先检查pubspec.yaml, README.mdCHANGELOG.md这几个文件的内容是否完整正确。然后运行下面这个命令检查插件是否可以发布。

$ flutter packages pub publish --dry-run

如果有问题存在的话,会在终端输出相关信息,你需要据此做出修改直到返回成功。具体遇到的问题可以参考官方文档

最后去掉--dry-run以后再运行以上命令。

$ flutter packages pub publish

恭喜你,你的插件终于发布出去了。

插件注册

从前文开发插件的过程中我们知道了在插件Android代码里有一个静态函数registerWith,这个函数可以把插件注册到Host App。那么问题来了,插件是什么时候注册的呢?这个静态函数是被谁调用的呢? 答案就在example app的MainActivity里:

public class MainActivity extends FlutterActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // 插件在这里注册
    GeneratedPluginRegistrant.registerWith(this);
  }
}

onCreate函数里,有这么一行代码GeneratedPluginRegistrant.registerWith(this)。插件就是在这里注册的。再看看GeneratedPluginRegistrant的内容就明白了:

public final class GeneratedPluginRegistrant {
  public static void registerWith(PluginRegistry registry) {
    if (alreadyRegisteredWith(registry)) {
      return;
    }
    //那个注册的静态函数是在这里被调用的
    FlutterMusicPlugin.registerWith(registry.registrarFor("io.github.zhangjianli.fluttermusicplugin.FlutterMusicPlugin"));
  }

  private static boolean alreadyRegisteredWith(PluginRegistry registry) {
    final String key = GeneratedPluginRegistrant.class.getCanonicalName();
    if (registry.hasPlugin(key)) {
      return true;
    }
    registry.registrarFor(key);
    return false;
  }
}

在第一个静态函数里就找到了调用插件的registerWith函数的地方。这个类是IDE帮我们自动生成的。也就是说,插件的注册完全不需要开发者去干预。

总结

本文通过开发一个音乐播放功能的插件简要介绍了Flutter插件包的开发过程。总体来讲,插件的开发过程并不是很复杂,关键的问题还是在能否抹平Android和iOS平台差异上面。另外,Flutter官方维护了一批Flutter插件包,而且是开源的。大家感兴趣的话可以学习一下官方是如何开发插件的。