Android AccessibilityService 辅助功能

1、前言

Android的辅助功能是个比较老的API（since API 4），但是该API真正的开始发展还是在API 16~19（很多常用的方法参数都是在这几个版本逐渐加入以及完善的）版本中。辅助功能我们最常见的是在类似深度休眠，抢红包中使用，模拟点击屏幕view。此次写关于辅助功能的分享是因为在API 24、 API 26中，又增添了几个类以及几个接口。

本文首先介绍关于辅助功能的常见使用方法，然后开始介绍辅助功能新增接口以及类的使用。

2、辅助功能的使用

2.1 辅助功能常规使用方法：###

本小结介绍一般情况下辅助功能的使用（基础用法和方法释义较多，如果需要阅览API > 20 新增方法使用请从2.2开始阅读），API level在20及以下的使用方式。不涉及新增的方法以及类的使用介绍。

2.1.1 使用流程：####

1、Service: 配置自己的辅助功服务（注册、配置）

2、Class: 自己的辅助功能类（对事件的拦截、处理）

2.1.2 Service配置：####

1、在实例化的辅助功能类中：onServiceConnected()中初始化，如下所示。

@Override
protected void onServiceConnected() {
    super.onServiceConnected();
    AccessibilityServiceInfo info = new AccessibilityServiceInfo();
    info.eventTypes = AccessibilityEvent.TYPES_ALL_MASK;
    info.feedbackType = AccessibilityServiceInfo.FEEDBACK_GENERIC;
    info.notificationTimeout = 100;
    info.packageNames = new String[]{"...", "..."};
    info.flags = AccessibilityServiceInfo.FLAG_REPORT_VIEW_IDS;
    setServiceInfo(info);
}

2、使用manifest中添加meta-data的方式（该方式从API 14开始使用）

<?xml version="1.0" encoding="utf-8"?>
<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    android:accessibilityEventTypes=""
    android:accessibilityFeedbackType=""
    android:accessibilityFlags=""
    android:canRequestEnhancedWebAccessibility=""
    android:canRequestFilterKeyEvents=""
    android:canRequestTouchExplorationMode=""
    android:canRetrieveWindowContent=""
    android:description=""
    android:notificationTimeout=""
    android:packageNames=""
    android:settingsActivity=""
    android:summary="" />

由上边两组代码可以看到，前一个配置中单个代码块中，配置属性有限，但灵活的在服务里边初始化，使我们可以随时的改变需要的flag和type及一些其他参数。而后一个（Android 4.0+ / API 14+）的meta-data配置方式，可配置的属性更多。在系统条件符合时（同时不需要更改我们辅助功能的一些参数时），还是推荐使用后一个配置方式进行辅助功能的配置。

2.1.3 AccessibilityServiceInfo 配置参数：####

这里只是对所有的XML attributes进行说明。

XML attributes：

• AccessibilityEventTypes 此服务希望接收的事件类型

• accessibilityFeedbackType 此服务提供的反馈类型

• accessibilityFlags 辅助功能附加的标志，多个使用 ‘ | ‘分隔

• canRequestEnhancedWebAccessibility (boolean)
  辅助功能服务是否能够请求WEB辅助增强的属性。例如: 安装脚本以使应用程序内容更易于访问。

• canRequestFilterKeyEvents (boolean)
  辅助功能服务是否能够请求过滤KeyEvent的属性，是否可以请求KeyEvent事件流。，flagRequestFilterKeyEvents搭配使用

• canRequestTouchExplorationMode (boolean)
  此属性用于，能够让辅助功能服务通过手势，来请求触摸浏览模式，其被触摸的项，将被朗读出来，flagRequestTouchExplorationMode搭配使用

• canRetrieveWindowContent (boolean)
  辅助功能服务是否能够取回活动窗口内容的属性。 与上边的flagRetrieveInteractiveWindows搭配使用，无法在运行时更改此设置。

• description
  辅助功能服务目的或行为的简短描述。

• notificationTimeout
  同一类型的两个辅助功能事件发送到服务的最短间隔（毫秒，两个辅助功能事件之间的最小周期）

• packageNames
  从此服务能接收到事件的软件包名称 (不适合所有软件包)（多个软件包用逗号分隔）。

• settingsActivity
  允许用户修改辅助功能的activity组件名称

• summary
  同description

2.1.4 实现自己的辅助功能类：####

首先需要了解的是AccessibilityService这个类。

Public方法有：

这部分我们只针对API <= 20部分的代码，其中我们常用的方法有：

在使用这些方法时，有三个需要我们了解的地方：

• AccessibilityEvent 在辅助功能event回调方法中，返回的参数。（官方API En）

• AccessibilityNodeInfo 辅助功能中的节点对象(nodeInfo)。（官方API En）

• performGlobalAction(action) 全局事件发送方法（物理按键的点击）

AccessibilityEvent

当用户界面发生某些明显的事件时，AccessibilityEvent代表的无障碍事件会被系统发送，每一种事件类型是由该类暴露出的属性子集表示其特征的。在此类中为每一种事件类型定义了相应的常量。详细的事件类型请参照AccessibilityEvent文档 Zh。

Public Methods 公有方法:

AccessibilityNodeInfo####

该类代表一个窗口内容节点和可以从源请求的操作。从 AccessibilityService的角度看，一个窗口内容被呈现为一个无障碍节点信息树，该树可能与视图层次一一映射，也可能不与视图层次一一映射。换句话说，一个自定义视图可灵活地将自己报告为一个无障碍节点信息树。一旦无障碍节点信息被发送给无障碍服务，该信息将会是不可改变的，且调用状态改变方法将会产生错误。AccessibilityNodeInfo文档 Zh

嵌套类：

• AccessibilityNodeInfo.AccessibilityAction API 21+
  定义了一个可以在 AccessibilityNodeInfo 上执行的操作的类。

• AccessibilityNodeInfo.CollectionInfo
  具有一个节点是否是个集合的信息的类。

• AccessibilityNodeInfo.CollectionItemInfo
  具有一个节点是否是个集合项目的信息的类。

• AccessibilityNodeInfo.RangeInfo
  具有一个节点是否是个范围的信息的类。

常量：
使用nodeInfo.performAction(Int Action)、performAction(Int Action, Bundle bundle)方法

方法：

performGlobalAction####

2.1.5 自定义AccessibilityService类的常规使用

public class MyAccessibilityService extends AccessibilityService {

    @Override
    protected void onServiceConnected() {
        super.onServiceConnected();
    }

    @Override
    public void onAccessibilityEvent(AccessibilityEvent event) {
        // 1.AccessibilityEvent中一些常用的使用方法
        // 这里我们获取到该辅助功能的事件类型
        // 事件类型请参照 2.1.3中AccessibilityEventTypes表
        int eventType = event.getEventType();
        // 输出事件的字符串type
        String typeStr = event.eventTypeToString(eventType);
        // 根据事件类型来分发我们的需要的操作,这里以窗口变化为例
        if(AccessibilityEvent.TYPE_WINDOW_STATE_CHANGED == eventType){
            // 判断我们的辅助功能是否在约定好的应用界面执行，以设置界面为例
            if("com.android.settings".equals(event.getPackageName()){
                // doSomeThing
            }
        } else if(AccessibilityEvent.TYPE_GESTURE_DETECTION_START == eventType) {
            // 在监测到手势的时候
        } else {
            // 在完成操作时，可以关闭自己的服务，下次使用再次开启。
            // API > = 24
            disableSelf();
        }

        // 2.通过event来遍历我们的nodeInfo
        if (VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR2)
            // 这里使用getResource()方法其实是从AccessibilityEvent继承的
            // AccessibilityRecord中抽取AccessibilityNodeInfo
            // 实际调用的是AccessibilityRecord中的方法，返回的是AccessibilityNodeInfo mSourceNode
            AccessibilityNodeInfo info = event.getSource();
        else
            info = getRootInActiveWindow();

        // 3.遍历info中的子节点
        if (info.getChildCount() ！= 0){
            // 通过一个循环将info的子节点遍历
            for (int i = 0; i < info.getChildCount(); i++) {
                // 获取子节点中某个特定的node，这里通过以下方法通过ID查找
                List<AccessibilityNodeInfo> list = info.findAccessibilityNodeInfosByViewId("com.android" +".settings:id/xxxx");
                // 通过text查找
                List<AccessibilityNodeInfo> list = info.findAccessibilityNodeInfosByText("xxxx");
                // 打印nodeinfo的信息
                Log.e("InfoType: " + info.getClassName());
                Log.e("InfoText: " + info.getText());
                Log.e("InfoPkgName: " + info.getPackageName());
                Log.e("InfoViewId: " + info.getViewIdResourceName());
            }
        }

        // 4.为节点添加操作
        // 1) 首先获取到我们的节点
        AccessibilityNodeInfo info = event.getSource();
        // 2) 通过查找指定的ID、text来查找一个系列的节点，返回一个list，需要判断list.size()是否为空
        List<AccessibilityNodeInfo> list = info.findAccessibilityNodeInfosByViewId("pkgName." + "id");
        AccessibilityNodeInfo info = list.get(0);
        // 3) 为节点添加操作，点击事件（事件可参照AccessibilityNodeInfo表）
        info.performAction(AccessibilityNodeInfo.ACTION_CLICK);
        // 4) 添加node可用的action，给node添加一个可清除焦点的操作
        // 通过addAction(AccessibilityNodeInfo.AccessibilityAction action)
        info.addAction(AccessibilityNodeInfo.AccessibilityAction.ACTION_CLEAR_FOCUS);
        // 获取该node上可用的action属性list，可以用来查看该node的属性
        List<AccessibilityNodeInfo.AccessibilityAction> listAction = info.getActionList();
        
        // 5.获取该节点上子节点个数
        int childCount = info.getChildCount();
        
        // 6.操作完成后，回收实例，返回一个下次可用的实例
        info.recycle();

        // 需要注意的是，在node.performAction之后，调用本地广播的话，之后的globeAction不会起作用，例：
        sureStopNode.performAction(AccessibilityNodeInfo.ACTION_CLICK);
        sureStopNode.recycle();
        SystemMessage.getInstance().send(SystemMessage.ACTION_POWER_BOOSTER_NEXT);
        performGlobalAction();// 这句话是不起作用的

        // 7.辅助功能的一些适用场景：
        // 1)部分应用中获取短信验证码（通过开启辅助功能的方式获取）
        //  - 监听通知栏的消息(typeNotificationStateChanged)
        //  - 弹出通知栏的时候获取该通知的节点信息(event.getSource())
        //  - 遍历root节点，取得显示信息的文本Node(info.findAccessibilityNodeInfosByViewId("pkgName." + "id"))
        //  - 通过NodeInfo.getText()方法获取到相应的文本信息，并取出验证码
        //  - 取消掉通知栏弹出框
        //  - 获取到要输入的EditText获取直接在本应用给需要填写验证码的区域设置文本。

        // 2)部分应用中恢复APP的初始设置（清除APP的数据）
        //  - 跳转到应用详情，通过findAccessibilityNodeInfosByViewId查找节点
        //  - 通过节点info.performAction(AccessibilityNodeInfo.ACTION_CLICK)点击清除
        //  - 弹出确定对话框，同上方式找到确定节点，点击后返回
        
        // 3)监测应用是否在前台，APP的启动（通过windowstatechange事件获取到当前的event的pkgName）
        //  - 通过接收typeWindowStateChanged事件，获取event的pkgName确定哪个应用启动或者在最上层显示（悬浮窗不适用）

        // 4)自动安装与卸载软件
        //  - 同3，寻找相应的节点，点击事件

        // 5)自动化UI测试

        // 6)最常见的抢红包

        // 7)通过辅助功能开启一些权限(不需要用户手动点击开启了)
        //  - 在用户确定需要开启权限时，自动跳转，寻找相应的开关按钮
        //  - 需要注意的是，部分开关（switch button， checkbox）可能没有ID，需要通过info.getClassName()来判断，属于那种类型的view。
    }

    @Override
    public void onInterrupt() {
    }
   
}

需要重写的一些方法：

• onServiceConnected() 该方法在初始化辅助功能服务时调用，可以在这时做相应的初始化工作。
• onAccessibilityEvent() 在获取到指定的监听事件时，通过回调这个方法来进行对应的操作
• onInterrupt() 系统想要中断辅助功能时会调用该方法

当然service中的onUnbind()方法也同样适用，在onUnbind()中释放一些资源也是可以的。

Note: 这里需要了解的是辅助功能最重要的就是手机机型的适配。由于各个厂商的系统不一样，导致了我们在获取一些节点时，需要的节点ID不同（通过ID获取节点时一种比较高效的方式）。而我们一般通过Device Monitor中的Hierarchy View获取节点信息。同时在此方式下，很多手机没法获取到节点信息，我们就需要使用添加flagReportViewIds进行手动遍历界面节点的方式获取nodeInfo。

以上是辅助功能常规使用以及使用场景的介绍。下面为辅助功能的注册。

<service
    android:name=".我们自己继承自AccessibilityService的类"
        android:label="@string/app_name"
        android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
        <intent-filter>
            <action android:name="android.accessibilityservice.AccessibilityService"/>
        </intent-filter>

        <meta-data
            android:name="android.accessibilityservice"
            android:resource="@xml/第二个辅助功能配置方式的文件，存放在xml下"/>
</service>

2.2 API > 20 新增方法，接口（预览版）使用探究：###

2.2.1 AccessibilityService新增方法一览：

API 21：

获取屏幕上的窗口。
返回一个有目标的用户可以与之进行交互的窗口，而不是所有的窗口。

为了访问Windows，服务必须通过在其元数据中设置AccessibilityService_canRetrieveWindowContent属性来声明检索窗口内容的功能。此外，服务必须选择通过设置FLAG_RETRIEVE_INTERACTIVE_WINDOWS标志来检索交互式窗口。

使用此方法来获取我们屏幕上最上层的一个窗口根节点。

API 24：

返回AccessibilityService.SoftKeyboardController其中可以使用添加addOnShowModeChangedListener()的方式来进行对键盘的显示隐藏状态监听，通过getShowMode()获取到软键盘的显示隐藏状态，setShowMode(int showMode)设置软键盘的显示隐藏状态。

通过在服务中调用该方法可以将自己的服务停止，同时在辅助功能开启界面上的开关也会随之关闭。

可以通过设定GestureDescription将手势的轨迹显示在触摸屏上，同时可以通过GestureResultCallback回调获得事件的完成情况。

这里的焦点类型有FOCUS_INPUT和FOCUS_ACCESSIBILITY分别代表了输入焦点和无障碍重点。
FOCUS_ACCESSIBILITY这个焦点，是需要使用setAccessibilityFocused(boolean isFocus)方法进行设置过得焦点。

需要注意的是：如果要使用该方法的话，需要先设置AccessibilityService_canRetrieveWindowContent同时添加一个flag：FLAG_RETRIEVE_INTERACTIVE_WINDOWS。

返回：AccessibilityService.MagnificationController。为了控制放大倍数，辅助功能服务必须通过在其元数据中设置AccessibilityService_canControlMagnification属性来声明该功能。

API 26：

返回：AccessibilityButtonController：

当设置FLAG_REQUEST_ACCESSIBILITY_BUTTON时，此类可用于查询辅助功能按钮的状态并注册回调以进行交互，并对可访问性按钮进行状态更改。

注意：此类和FLAG_REQUEST_ACCESSIBILITY_BUTTON不应该被用作通过AccessibilityService为用户提供功能的唯一手段。 一些设备实现可以选择不提供软件呈现的系统导航区域，使得该功能永久不可用。

注意：在支持辅助功能按钮的设备实现中，它可能始终不可用，例如前台应用程序使用SYSTEM_UI_FLAG_HIDE_NAVIGATION时。 用户还可以选择将该按钮分配给另一个可访问性服务或功能。 在每种情况下，将调用注册的AccessibilityButtonController.AccessibilityButtonCallback的onAvailabilityChanged（AccessibilityButtonController，boolean）方法来提供对可访问性按钮对注册服务的可用性的更改的通知。

注意底部导航栏的小人：

image

下面是一个简单的用例：

public class MyAccessibilityService extends AccessibilityService {

    @Override
    protected void onServiceConnected() {
        super.onServiceConnected();
        AccessibilityServiceInfo info = new AccessibilityServiceInfo();
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            info.flags = AccessibilityServiceInfo.FLAG_REQUEST_ACCESSIBILITY_BUTTON;
        } else {
            info.flags = AccessibilityServiceInfo.FLAG_REPORT_VIEW_IDS;
        }
        info.eventTypes = AccessibilityEvent.TYPES_ALL_MASK;
        info.feedbackType = AccessibilityServiceInfo.FEEDBACK_GENERIC;
        info.notificationTimeout = 100;
        setServiceInfo(info);
    }

    @Override
    public void onAccessibilityEvent(AccessibilityEvent event) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            AccessibilityButtonController mAccessibilityButtonController = getAccessibilityButtonController();
            mAccessibilityButtonController.registerAccessibilityButtonCallback(new AccessibilityButtonController.AccessibilityButtonCallback() {
                @Override
                public void onClicked(AccessibilityButtonController controller) {
                    super.onClicked(controller);
                    // 底部导航栏中辅助功能按钮点击事件回调
                    Toast.makeText(MyAccessibilityService.this, "on Click", Toast.LENGTH_SHORT).show();
                }

                @Override
                public void onAvailabilityChanged(AccessibilityButtonController controller, boolean available) {
                    super.onAvailabilityChanged(controller, available);
                    // 辅助功能可用性改变的回调。返回了辅助功能底部按钮是否可用的布尔值，和按钮控制器
                    // available = true 表示该按钮对本服务可用
                    // available = false 是由于设备显示了按钮，或按钮被分配到另一个服务或其他原因。
                }
            });
        }
    }

    @Override
    public void onInterrupt() {
    }
}

在开启辅助功能之后，如果是O系统的话，在底部导航栏会出现一个辅助功能的小人。同时这个小人可以接收到点击事件，和辅助功能可用状态变化。

指纹手势控制器：FingerprintGestureController

只要设备具有能够检测手势的传感器，AccessibilityService可以捕获在设备的指纹传感器上执行的手势。
使用时需要声明CAPABILITY_CAN_CAPTURE_FINGERPRINT_GESTURES同时需要权限USE_FINGERPRINT,由于没有真机调试该方法，待Google发布正式版API后继续研究

支持的四个事件:

公有方法

其中的FingerprintGestureController.FingerprintGestureCallback与之前的辅助功能按钮回调基本相同，都只有两个方法。

2.2.1 AccessibilityNodeInfo新增方法一览：

API 21

以上两个方法需要搭配使用。

通过该方法，我们可以使用一个子节点来重新获取到我们的根节点。在需要多次操作界面元素的情况下（同时没有产生windowstatechange事件），我们可以不通过监听事件来进行下一个节点的操作。

第一个addAction(AccessibilityNodeInfo.AccessibilityAction action)方法是API 21时替代API 20中的addAction(int action)方法。
提供了一个在辅助功能外操作节点的方法，该方法不能在辅助功能服务中调用，不然会报错java.lang.IllegalStateException: Cannot perform this action on a sealed instance.

后三个方法使用的前提都是需要事先在节点中添加了操作，或者视图，不然都不会起作用。要说明的是removeAction方法也需要在服务外调用，不然也要报错

API 22

通过在view的xml属性中添加android:accessibilityTraversalAfter="+id"方式来进行辅助功能遍历时的顺序后，通过本方法获取下一个节点。

通过在view的xml属性中添加android:accessibilityTraversalBefore="+id"方式来进行辅助功能遍历时的顺序，同上。

通过View.setAccessibilityTraversalBefore(+id)方式设置顺序。

API 23

通过View的setContextClickable(Boolean isClickable)方法设置一个View是否可以点击。然后通过该方法，我们可以获取到节点上下文的可否点击状态。

API 24

通过View的XML属性设置android:importantForAccessibility=""状态后，我们可以通过本方法获取到该状态的boolean值。

同样的不能在辅助功能服务中调用该方法。
参考ViewGroup.setChildrenDrawingOrderEnabled()中children的绘制顺序理解。

返回与该节点对应的视图相对于其兄弟姐妹的绘图位置。
返回的数值从1开始，表示相对于父节点中，并列view的绘制顺序。

2.3 API > 20 新增方法，接口（预览版）接口类文档汇总：###

1、GestureDescription使用dispatchGesture(GestureDescription ge, GestureResultCallback cb, Handler handler)方法时需要学习的类，它提供了获取手势的Builder中设置的一些属性。

2、AccessibilityService.GestureResultCallback使用dispatchGesture(GestureDescription ge, GestureResultCallback cb, Handler handler)方法时需要了解的类，提供了手势的回调。

3、AccessibilityService.MagnificationController 使用getMagnificationController()返回的放大控制器。

4、AccessibilityService.SoftKeyboardController使用getSoftKeyboardController()返回的键盘控制器。

5、AccessibilityButtonControllerAndroid O以上的系统返回的导航栏按钮控制器，其中还有导航栏按钮回调需要了解。

6、AccessibilityButtonController.AccessibilityButtonCallback用于与系统导航区域内的辅助功能按钮的状态进行交互和更改的回调。

7、FingerprintGestureControllerAndroid O新增的指纹控制器。

8、FingerprintGestureCallback为手势控制器添加的回调方法。

3、其他一些参考文档##

中文文档：

Android无障碍类：AccessibilityRecord

Android无障碍类：AccessibilityNodeProvider

Android无障碍类：AccessibilityNodeInfo.RangeInfo

Android无障碍类：AccessibilityNodeInfo.CollectionItemInfo

Android无障碍类：AccessibilityNodeInfo.CollectionInfo

Android无障碍类：AccessibilityNodeInfo.AccessibilityAction

Android无障碍类：AccessibilityNodeInfo

Android无障碍类：AccessibilityManager

Android无障碍类：AccessibilityEvent

Android无障碍接口

Android视图无障碍包概览