EventBus 中文文档

9,859 阅读11分钟

野生 EventBus 文档!闲来无事翻了下,感觉很神奇

简单三步上手 EventBus

EventBus 的 API 就像数数一样,一、二、三,嗯!

在开始之前,确保已经把 EventBus 添加到项目依赖了。

第一步:定义事件

事件(Event) 是没有 是没有任何特殊要求的 POJO(Plain Old Java Object)。

public class MessageEvent {
    public final String message;
    public MessageEvent(String message) {
        this.message = message;
    }
}

第二步:准备 Subscriber (订阅者)

订阅者实现了事件处理方法(也称为“订阅者方法”),这些方法将在事件被发布时调用。Subscriber 方法使用 @subscribe 注解定义。注意,对于 EventBus 3,方法名可以自由选择(没有 EventBus 2 中的命名约定)。

// This method will be called when a MessageEvent is posted (in the UI thread for Toast)
@Subscribe(threadMode = ThreadMode.MAIN)
public void onMessageEvent(MessageEvent event) {
    Toast.makeText(getActivity(), event.message, Toast.LENGTH_SHORT).show();
}
// This method will be called when a SomeOtherEvent is posted
@Subscribe
public void handleSomethingElse(SomeOtherEvent event) {
    doSomethingWith(event);
}

Subscriber 需要从“总线”来“注册”和“解注册”。Subscriber 只有在注册后才可以接收到事件。对于 Android ,在 Activity 和 Fragment 中通常应该根据生命周期注册。对于大多数情况,分别在 onStart 和 onStop 注册和解注册就可以:

@Override
public void onStart() {
    super.onStart();
    EventBus.getDefault().register(this);
}
@Override
public void onStop() {
    EventBus.getDefault().unregister(this);
    super.onStop();
}

第三步:发布事件

代码中的任意部分都可以发布事件。所有已注册并且匹配该类型的 Subscriber(订阅者)都会收到该事件:

EventBus.getDefault().post(new MessageEvent("Hello everyone!"));

深入了解

继续阅读,或者点击这个链接来认识 EventBus 的更多特性。

配置 EventBus

EventBusBuilder 类用来配置 EventBus 的各个方面。例如,以下是如何构建 EventBus,以便在发布的事件没有 Subscriber 时保持冷静:

EventBus eventBus = EventBus.builder()
    .logNoSubscriberMessages(false)
    .sendNoSubscriberEvent(false)
    .build();

另一个例子是,当 Subscriber 抛出异常时崩溃:

EventBus eventBus = EventBus.builder().throwSubscriberException(true).build();

默认情况下,EventBus 会捕获从 Subscriber 的回调方法抛出的异常,并发出一个 SubscriberExceptionEvent 。这个事件可以处理,也可以不处理。

更详细的使用参见:EventBusBuilder 的文档

配置默认的 EventBus 实例

使用 EventBus.getdefault() 可以很容易的从应用程序中的任何位置获取同一个 EventBus 实例。EventBusBuilder 还允许使用 installDefaultEventBus() 方法配置此默认实例。

例如,可以配置默认的 EventBus 实例来重新抛出 Subscriber 方法中发生的异常,并且仅针对调试构建,因为重新抛出异常可能会导致应用程序异常崩溃:

EventBus.builder().throwSubscriberException(BuildConfig.DEBUG).installDefaultEventBus();

只能在第一次使用默认的 EventBus 实例之前可用,这只能调用一次。随后调用installDefaultEventBus 会引发异常。这确保了应用程序的行为一致。Application 类是配置默认 EventBus 实例的好地方。

交付线程 (Delivery Threads, ThreadMode)

EventBus 帮您可以处理线程问题:事件可以发布到与发布线程不同的线程中。一个常见的用例是处理 UI 变化。对于 Android,UI 改变必须发生在 UI(main)线程中。另一方面,网络请求或其他任何耗时的任务不得在主线程上运行。EventBus 可以帮助你处理这些问题,并与 UI 线程保持协调(您不必深入到线程转换,比如使用 AsyncTask 等)。在 EventBus 中,您可以使用四种线程模式之一来指定调用事件处理方法的线程。

ThreadMode.POSTING(默认)

Subscriber 方法会在发布该事件的同一线程被调用。这是默认行为。事件交付是同步完成的,并且一旦事件发送结束,所有的 Subscriber 方法都会被调用。由于彻底杜绝了线程切换,这种 ThreadMode 意味着最小的开销。因此对于只需很短的时间完成并且不需要用到主线程的简单任务而言,这是推荐的模式。使用这种模式的事件回调应该迅速返回以防阻塞发送事件的线程(可能是主线程)。

// Called in the same thread (default)
// ThreadMode is optional here
@Subscribe(threadMode = ThreadMode.POSTING)
public void onMessage(MessageEvent event) {
    log(event.message);
}

ThreadMode.MAIN

Subscriber 会在 Android 的主线程(有时也成为 UI 线程)被调用。如果发送事件的线程是主线程的话,会直接调用 Subscriber 方法(同步调用,表现同 ThreadMode.POSTING)。使用这种模式的事件回调必须迅速返回以防阻塞发送事件的线程。

// Called in Android UI's main thread
@Subscribe(threadMode = ThreadMode.MAIN)
public void onMessage(MessageEvent event) {
    textField.setText(event.message);
}

ThreadMode.MAIN_ORDERED

Subscriber 会在 Android 的主线程被调用。事件总是排队等待以传递给 Subscriber,所以对发出事件的调用将立即返回。这保证了事件处理有一个更严格一致的顺序(因此叫做 MAIN_ORDERED)。比如,在 ThreadMode.MAIN 模式下,处理事件的时候发布另一个事件,则第二个事件将先于第一个事件被处理完成(此处为同步调用,可与方法调用类比)。而对于 MAIN_ORDERED,第一个事件将先被完成处理,然后第二个事件在稍后的时间点(一旦主线程有处理能力时)被处理。

使用这种模式的事件回调必须迅速返回以防阻塞发送事件的线程。

// Called in Android UI's main thread
@Subscribe(threadMode = ThreadMode.MAIN_ORDERED)
public void onMessage(MessageEvent event) {
    textField.setText(event.message);
}

ThreadMode.BACKGROUND

事件回调将在后台线程中被调用。如果发布事件的线程不是主线程,事件回调将直接在发布线程被调用。否则,EventBus 使用一个后台线程(单例)来按序调用每个回调。使用这种模式的事件回调应该尝试快速返回以尽量不要阻塞后台线程。

// Called in the background thread
@Subscribe(threadMode = ThreadMode.BACKGROUND)
public void onMessage(MessageEvent event){
    saveToDisk(event.message);
}

##ThreadMode: ASYNC

事件回调方法总是在单独的线程被调用。这些线程不会是发布事件的线程,也不会是主线程。向此模式的回调方法 post 事件永远不会发生等待。如果回调方法执行网络请求之类的耗时操作的话则应该使用这种模式。避免同时触发大量长时间运行的异步任务来限制并发线程的数量,EventBus 使用线程池有效地重用已完成的异步任务线程。

// Called in a separate thread
@Subscribe(threadMode = ThreadMode.ASYNC)
public void onMessage(MessageEvent event){
    backend.send(event.message);
}

Sticky Events (粘性事件)

对于某些事件,在其被 post 之后我们仍然关心它携带的信息。例如,表示某些初始化已完成的事件。或者,对于传感器数据或位置信息,想要保存最近一次的值。可以使用 Sticky Events, 而不是自己去实现一个缓存。EventBus 会将最后一个特定类型的粘性事件保存在内存中,这个粘性事件可以传递给 Subscriber 或者被直接查询。因此,不需要任何特殊的代码来考虑早已存在的数据。

粘性事件示例

比方说,我们之前 post 了一个粘性事件:

EventBus.getDefault().postSticky(new MessageEvent("Hello everyone!"));

现在一个新的 Activity 启动了。所有订阅粘性时间的方法在注册的时候就会立即收到之前 post 的粘性事件:

@Override
public void onStart() {
    super.onStart();
    EventBus.getDefault().register(this);
}
// UI updates must run on MainThread
@Subscribe(sticky = true, threadMode = ThreadMode.MAIN)
public void onEvent(MessageEvent event) {   
    textField.setText(event.message);
}
@Override
public void onStop() {
    EventBus.getDefault().unregister(this);    
    super.onStop();
}

手动获取/移除粘性事件

如您所见,最近的粘性事件会在匹配的 Subscriber 方法注册时自动发送给它们
。但有时候手动检查粘性事件可能会更方便,以及删除(消耗)粘性事件,以使它们不再被传递。例如:

MessageEvent stickyEvent = EventBus.getDefault().getStickyEvent(MessageEvent.class);
// Better check that an event was actually posted before
if(stickyEvent != null) {
    // "Consume" the sticky event
    EventBus.getDefault().removeStickyEvent(stickyEvent);
    // Now do something with it
}

removeStickyEvent 方法是被重载过的:传入一个类,会返回之前持有的对应粘性事件。由此,我们可以改进前面的例子:

MessageEvent stickyEvent = EventBus.getDefault().removeStickyEvent(MessageEvent.class);
// Better check that an event was actually posted before
if(stickyEvent != null) {
    // Now do something with it
}

优先级 和 事件的取消

大多数 EventBus 的使用都既不会用到优先级, 也不会取消事件, 但是在一些特殊情况下还是可能用到的. 比如, 当 app 在前台的时候触发某些更新 UI 的代码, 否则做些其他的事情.

Subscriber 的优先级

可以在注册 Subscriber 的时候提供优先级来改变事件传递的顺序:

@Subscribe(priority = 1);
public void onEvent(MessageEvent event) {
    ...
}

在同一个 ThreadMode 下, 更高优先级的 Subscriber 会比低优先级的更先收到事件. 默认的优先级是 0.

优先级只影响相同 ThreadMode 中的 Subscriber.

取消事件的传递

可以通过在 Subscriber 的事件处理线程调用 cancelEventDelivery(Object event) 来取消事件传递. 进一步的事件传递将被取消,接下来的 Subscriber 都不会接收到事件。

// Called in the same thread (default)
@Subscribe
public void onEvent(MessageEvent event){
    // Process the event
    ...
    // Prevent delivery to other subscribers
    EventBus.getDefault().cancelEventDelivery(event) ;
}

事件通常被被高优先级的 Subscriber 取消。事件取消仅限于用在 ThreadMode.PostThread 模式下的事件处理方法。

Subscriber 索引

Subscriber 索引是 EventBus 3 的新特性。是为了加速首次 subscriber 注册过程的可选优化

Subscriber 索引可以在编译期由 EventBus 注解处理器来创建。虽然使用索引不是必需,但是推荐在 Android 使用以求最佳性能。

索引的前提条件

需要注意的是,只有 subscriber 和 event 类均为 public 的时候,@Subscriber 方法才可以被索引。同样,由于 Java 注解处理本身的限制,内部类中的 @Subscriber 方法不会被识别。

当 EventBus 不能使用索引时,会自动回退到“运行时反射”的实现。这仍然不妨碍 EventBus 工作,只是会稍微有点慢。

如何生成索引

使用 annotationProcessor

如果 Gradle 插件版本低于 2.2.0,使用 android-apt 来配置。

在当前构建的配置文件使用 annotationProcessor 属性添加 EventBus 注解处理器。同时使用 eventBusIndex 参数来指定所生成索引类的全限定名。在 gradle 构建脚本中添加类似下面的代码段:

android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = [ eventBusIndex : 'com.example.myapp.MyEventBusIndex' ]
            }
        }
    }
}
dependencies {
    compile 'org.greenrobot:eventbus:3.1.1'
    annotationProcessor 'org.greenrobot:eventbus-annotation-processor:3.1.1'
}

使用 kapt

如果在 Kotlin 代码中使用 EventBus, 需要用 kapt 代替 annotationProcessor:

apply plugin: 'kotlin-kapt' // ensure kapt plugin is applied
dependencies {
    compile 'org.greenrobot:eventbus:3.1.1'
    kapt 'org.greenrobot:eventbus-annotation-processor:3.1.1'
}
kapt {
    arguments {
        arg('eventBusIndex', 'com.example.myapp.MyEventBusIndex')
    }
}

使用 android-apt

如果上述方法都没用的话, 可以使用 (android-apt)(一个 Gradle 插件). 向 Gradle 构建脚本添加下列代码块:

buildscript {
    dependencies {
        classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'
    }
}
apply plugin: 'com.neenbedankt.android-apt'
dependencies {
    compile 'org.greenrobot:eventbus:3.1.1'
    apt 'org.greenrobot:eventbus-annotation-processor:3.1.1'
}
apt {
    arguments {
        eventBusIndex "com.example.myapp.MyEventBusIndex"
    }
}

如何使用索引

成功编译项目后, 会生成 eventBusIndex 指定的类. 然后用这个类来初始化 EventBus:

EventBus eventBus = EventBus.builder().addIndex(new MyEventBusIndex()).build();

或者这样添加全局索引:

EventBus.builder().addIndex(new MyEventBusIndex()).installDefaultEventBus();
// Now the default instance uses the given index. Use it like this:
EventBus eventBus = EventBus.getDefault();

建立索引

建立索引也是适用于库(library)的代码的. 这样的话, 可能会有多个索引类, 在配置 EventBus 的时候, 可以把这些类一起加上:

EventBus eventBus = EventBus.builder()
    .addIndex(new MyEventBusAppIndex())
    .addIndex(new MyEventBusLibIndex()).build();

ProGuard

ProGuard 会混淆方法名甚至移除没有被调用的方法(dead code removal). 由于 Subscriber 方法一般情况下并不会被直接调用, 所以 ProGuard 假定它们是”无用的”. 因此当打开 ProGuard 的最小化开关之后, 必须明确指定保留这些 Subscriber 方法.
在 ProGuard 配置文件添加下列规则:

-keepattributes *Annotation*
-keepclassmembers class ** {
    @org.greenrobot.eventbus.Subscribe <methods>;
}
-keep enum org.greenrobot.eventbus.ThreadMode { *; }
# Only required if you use AsyncExecutor
-keepclassmembers class * extends org.greenrobot.eventbus.util.ThrowableFailureEvent {
    <init>(java.lang.Throwable);
}

无论是否使用 Subscriber 索引都需要进行此项配置.

AsyncExecutor

AsyncExecutor 类似于线程池,区别在于带有异常处理。AsyncExecutor 会将抛出的异常包装在一个事件里,然后自动 post 出去。

免责声明: AsyncExecutor 不是核心的工具类。如果您需要带有错误处理的后台线程,使用它可以让您少写一些代码。但是…… ,它不是一个核心的 EventBus 类。

通常情况,通过 AsyncExecutor.create() 来创建一个实例并且保存在 Application 生命周期,然后将实现了 RunnableEx 接口的实例传入 AsyncExecutor 的 execute(...) 方法来执行任务。不同于 RunnableRunnableEx 会抛出异常。

如果 RunnableEx 抛出了异常,异常会被捕获并包装进一个 ThrowableFailureEvent ,然后这个事件会被发布出去。

样例,执行:

AsyncExecutor.create().execute(
    new AsyncExecutor.RunnableEx() {
        @Override
        public void run() throws LoginException {
            // No need to catch any Exception (here: LoginException)
            remote.login();
            EventBus.getDefault().postSticky(new LoggedInEvent());
        }
    }
);

样例,接收:

@Subscribe(threadMode = ThreadMode.MAIN)
public void handleLoginEvent(LoggedInEvent event) {
    // do something
}
@Subscribe(threadMode = ThreadMode.MAIN)
public void handleFailureEvent(ThrowableFailureEvent event) {
    // do something
}

AsyncExecutor.Builder

如果要定制 AsyncExecutor 实例,通过 AsyncExecutor.builder() 方法来获取一个 Builder 以定制 EventBus 示例、线程池以及异常事件类。

另一个定制选项是“执行范围(Execution Scope)”,执行范围给出了错误事件的上下文信息。例如,一个错误事件可能仅与特定 Activity 实例或者某个类相关。

如果自己编写的错误事件类实现了 HasExecutionScope 接口,AsyncExecutor 会自动设置 Execution Scope。同样,Subscriber 可以查询错误事件的 Execution Scope,然后据此做出反应。


Happy Coding… :smile:

via @boileryao