Android无障碍服务

Hi I’m Shendi

最近想制作一个记录点击操作并重复播放的工具，用以解放双手，因现在的Android高版本基本上难以Root，所以选择了使用无障碍来实现，在这里记录下来。

Android无障碍

可参考文档：https://informationaccessibilityassociation.github.io/androidAccessibility/services.htm

https://developer.android.google.cn/reference/android/accessibilityservice/AccessibilityService

配置

首先需要在清单文件（AndroidManifest.xml）中进行配置

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    
    <!-- 无障碍服务权限，会有红线，所以标上ignore忽略 -->
    <uses-permission android:name="android.permission.BIND_ACCESSIBILITY_SERVICE"
        tools:ignore="ProtectedPermissions,WrongManifestParent" />
    
    <!-- ... -->
    <application>
        <service android:name=".MyAccessibilityService"
            android:label="@string/accessibility_service_label"
            android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"
            android:exported="true">
            <intent-filter>
                <action android:name="android.accessibilityservice.AccessibilityService" />
            </intent-filter>
            <meta-data
                android:name="android.accessibilityservice"
                android:resource="@xml/accessibility_service_config" />
        </service>
    </application>
</manifest>

上面首先声明了权限，然后在 application 中注册了服务。

其中服务有一个 label，这个label的内容与无障碍中应用名称是一致的，例如我的名称为 AutoImitate - 自动模拟，在手机的无障碍设置页面中，会出现下面这样的东西

在这里插入图片描述

上面还配置了一个配置文件 @xml/accessibility_service_config，资源文件夹xml下的accessibility_service_config.xml

其中内容大致如下

<?xml version="1.0" encoding="utf-8"?>
<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    android:description="@string/accessibility_service_description"
    android:packageNames="com.example.android.apis"
    android:accessibilityEventTypes="typeAllMask"
    android:accessibilityFlags="flagDefault"
    android:accessibilityFeedbackType="feedbackSpoken"
    android:notificationTimeout="100"
    android:canRetrieveWindowContent="true"
    android:settingsActivity="com.example.android.accessibility.ServiceSettingsActivity">


</accessibility-service>

上面这种指定文件的方式是从 Android 4.0 开始被支持的。

除了这种指定文件的方式，还可以使用 AccessibilityServiceInfo 来动态设置，但这种方法并不能配置所有的配置项。

对于哪些配置可以动态设置，参考：https://developer.android.google.cn/reference/android/accessibilityservice/AccessibilityServiceInfo.html

至于上面的配置，功能如下：

android:description

描述信息，会在无障碍页面点击本应用后的最下方显示，如下红色方框部分所示

在这里插入图片描述

android:packageNames

接收指定包名的事件，多个用英文逗号分隔，不设置则接收所有。

android:accessibilityEventTypes

定义服务接收的事件类型，多个使用|分隔。

类型	描述
typeViewClicked	点击了某个视图
typeViewFocused	某个视图获得了焦点
typeViewLongClicked	用户长按了某个视图
typeViewSelected	某个视图被选中，例如在列表或网格中选择了一个项目
typeWindowStateChanged	一个窗口的状态发生了变化，例如一个新的活动（Activity）被打开或关闭
typeNotificationStateChanged	系统的通知状态发生了变化，例如新的通知到达
typeAllMask	所有事件

android:accessibilityFlags

定义一些特殊的行为标志，多个使用 | 分隔

标志	描述
flagDefault	当不设置其他特定标志时，使用这个标志可以保持辅助功能的默认行为。
flagIncludeNotImportantViews	此标志指示辅助功能服务也应接收那些被标记为“不重要”的视图的事件
flagRequestTouchExplorationMode	请求系统启用触摸探索模式，也就是手势监听。
flagRequestEnhancedWebAccessibility	请求增强的网页无障碍功能。这通常意味着在WebView中提供更详细和更准确的无障碍信息
flagRequestFilterKeyEvents	请求能够过滤键事件，这意味着辅助功能服务可以捕获并处理键盘输入事件

android:accessibilityFeedbackType

定义该服务如何为用户提供反馈，多个使用|分隔。

名称	描述
feedbackSpoken	语音反馈，文本转语音（TTS）
feedbackHaptic	触觉反馈，通常是通过设备振动来提供反馈
feedbackSound	声音反馈
feedbackVisual	视觉反馈，在屏幕上显示额外的视觉元素来提供反馈，如闪烁的边框或图标。
feedbackGeneric	一个通用的反馈类型，可能包含上述多种反馈方式的组合。当开发者不确定或想要保持灵活性，不具体到某一种反馈方式时，可以选择这个选项。这样，服务可以根据实际情况选择最合适的反馈方式。
feedbackAllMask	所有反馈

android:notificationTimeout

定义在连续接收两个相同类型的事件之间服务应等待的毫秒数。这有助于防止服务被频繁触发。

android:canRetrieveWindowContent

是否允许无障碍服务访问活动窗口的内容。这对于实现自动化点击等功能至关重要，true或false。

android:settingsActivity

指定一个用于配置无障碍服务的Activity。

更多的可以在这个页面查阅：https://developer.android.google.cn/reference/android/R.styleable.html

无障碍服务

在上面的配置中，注册了服务，而服务名称为 MyAccessibilityService

无障碍服务必须继承AccessibilityService 类，重写该类的函数，有两个函数必须重写。一般重写下面四个函数

/**
 * 自动模拟服务.
 * 创建时间：2024/5/4
 * @author 砷碲
 */
public class MyAccessibilityService extends AccessibilityService {

    private static SLog log = SLog.getLogger(Application.class.getName());

    /** 当前服务的对象,为空代表当前服务未启动 */
    public static MyAccessibilityService instance;

    @Override
    protected void onServiceConnected() {
        super.onServiceConnected();
        instance = this;

        log.d("accessibility connect");
    }

    @Override
    public void onAccessibilityEvent(AccessibilityEvent event) {
        log.d("accessibility event");
    }

    @Override
    public void onInterrupt() {
        log.d("accessibility interrupt");
    }

    @Override
    public boolean onUnbind(Intent intent) {
        log.d("accessibility unbind");
        instance = null;
        return super.onUnbind(intent);
    }
}

onServiceConnected 在打开当前无障碍服务时执行（即手机的无障碍设置页面打开当前无障碍）

onUnbind 在关闭当前无障碍服务时执行（即手机的无障碍设置页面关闭当前无障碍）

下图是打开关闭当前无障碍服务的输出信息

在这里插入图片描述

onAccessibilityEvent（必选）

当系统检测到一个符合无障碍服务设定的无障碍事件过滤参数的事件时，该方法被系统回调。例如，当用户在应用程序中点击一个按钮或聚焦一个用户界面控件时，你的无障碍服务会为此应用程序提供反馈。此时，系统调用这个方法，传递相关联的无障碍事件，无障碍服务就可以翻译和使用该事件为用户提供反馈。在无障碍服务的生命周期中，该方法会被调用多次。

onInterrupt（必选）

当系统想要打断无障碍服务提供的反馈时该方法被调用，一般情况下是响应用户操作，如移动焦点到一个不同的控件。在无障碍服务的生命周期中，该方法会被调用很多次。

检测服务是否打开

通过上面的信息，要检测当前无障碍服务是否开启就很简单了，使用一个全局变量，存储当前对象，在onServiceConnected 时赋值，onUnbind 置空。

接下来，判断就像下面这样就可以了，当为空代表未开启，跳转无障碍页面，跳转失败就跳设置页面

/** 校验无障碍是否开启，未开启则跳转开启页面. */
public static void checkAccessibility(Context context) {
    if (MyAccessibilityService.instance == null) {
        try {
            context.startActivity(new Intent(Settings.ACTION_ACCESSIBILITY_SETTINGS));
        } catch (Exception e) {
            context.startActivity(new Intent(Settings.ACTION_SETTINGS));
            e.printStackTrace();
        }

        Toast.makeText(context, "请开启本软件的无障碍服务：" + context.getString(R.string.accessibility_service_label), Toast.LENGTH_LONG).show();
    }
}

获取事件详情

当监听到事件时（如点击，滑动等），会触发 onAccessibilityEvent 函数，函数接收一个 AccessibilityEvent 对象作为参数。

Android系统通过AccessibilityEvent对象为无障碍服务提供用户界面交互的信息。在Android4.0之前，可从无障碍事件中获得信息，且无障碍事件能够提供用户所选择的界面控件的大量详细信息，但这些信息仅包含有限的上下文信息。在很多情况下，丢失的上下文信息可能是理解已选定控件的意义的关键。

通常，我们需要根据事件来进行后面的操作，例如用户点击某按钮，就自动化做一些操作之类的。

public void onAccessibilityEvent(AccessibilityEvent event) {
    if (event.getEventType() == AccessibilityEvent.TYPE_VIEW_CLICKED) {
        // ...
    }
}

上面的 event.getEventType() 是获取当前事件类型，而 AccessibilityEvent.TYPE_VIEW_CLICKED 代表点击事件，值是1。当有任意元素（可以被点击的）点击后执行（按下+抬起），所以通常需要拿到当前事件对应的元素，分析是否是我们需要关注的，根据这个，再进行下一步。

常用的提取元素信息代码如下

// 获得事件的资源节点
AccessibilityNodeInfo nodeInfo = event.getSource();

if (nodeInfo != null) {
    // 元素基本信息
    System.out.println("元素文本：" + nodeInfo.getText()
            + "\n元素描述：" + nodeInfo.getContentDescription()
            + "\nID资源名称：" + nodeInfo.getViewIdResourceName()
            + "\n元素类名：" + nodeInfo.getClassName()
            + "\n应用包名：" + nodeInfo.getPackageName()
            + "\n是否可点击：" + nodeInfo.isClickable()
            + "\n是否支持长按：" + nodeInfo.isLongClickable()
            + "\n是否对用户可见：" + nodeInfo.isVisibleToUser());
    // ...

    // 位置信息,x,y就是点击中心
    Rect rect = new Rect();
    nodeInfo.getBoundsInScreen(rect);
    System.out.println("[" + rect.centerX() + "," + rect.centerY() + "], 宽：" + (rect.right - rect.left) + "，高：" + (rect.bottom - rect.top));

    // 元素查找操作
    // 找到指定id的所有元素
    List<AccessibilityNodeInfo> nodesById = nodeInfo.findAccessibilityNodeInfosByViewId("view id");
    // 找到指定文本内容的所有元素
    List<AccessibilityNodeInfo> nodesByText = nodeInfo.findAccessibilityNodeInfosByText("砷碲");
    // 父元素
    AccessibilityNodeInfo parentNode = nodeInfo.getParent();
    // 子元素操作
    int childCount = nodeInfo.getChildCount();
    AccessibilityNodeInfo child = nodeInfo.getChild(0);

    // 释放资源
    nodeInfo.recycle();
}

除了上面所说的，还有一些当前无障碍服务对象提供的函数，例如getRootInActiveWindow，获取当前活动窗口的根节点，返回AccessibilityNodeInfo对象

判断元素类型

可以通过 getClassName 获取到当前元素的全类名，例如判断是否为按钮

boolean isBtn = "android.widget.Button".equals(nodeInfo.getClassName());

还可以通过是否可以点击，是否可输入等来进行判断。

手势监听

Android 4.1（API级别16）引入了手势监听功能，允许无障碍服务监听特定手势，并代表用户响应这些手势。

要使用此功能，无障碍服务需要请求激活触摸探索（Explore by Touch）特性，通过在其AccessibilityServiceInfo实例的flags成员中设置FLAG_REQUEST_TOUCH_EXPLORATION_MODE来实现。

激活触摸探索

需要在配置文件的 accessibilityFlags 增加 flagRequestTouchExplorationMode 或者在服务中动态设置

官方文档中有描述，当版本是Android4.3（API 18）及之后版本，那么还需要配置 canRequestTouchExplorationMode 为 true，否则忽略

配置设置

<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    android:accessibilityFlags="flagDefault|flagRequestTouchExplorationMode"
    android:canRequestTouchExplorationMode="true"></accessibility-service>

动态设置

@Override
protected void onServiceConnected() {
    super.onServiceConnected();
    instance = this;

    log.d("accessibility connect");

    // 在 onServiceConnected 中 getServiceInfo 不为null，在onCreate则有可能为null
    if (getServiceInfo() != null) {
        getServiceInfo().flags = AccessibilityServiceInfo.FLAG_REQUEST_TOUCH_EXPLORATION_MODE;
    }
}

配置成功的话，在用户打开无障碍服务的时候，弹出的对话框会新增一项触摸探索…

开启后，交互操作有所改变，比如滑动变成了双指滑动，点击变成了双指点击等

接收手势通知

通过重写 onGesture 函数来实现接收。

Android API 31之前，使用 onGesture(int)，而31及之后，使用 onGesture(AccessibilityGestureEvent)

需要注意的是，API31后，如果回调函数内参数对象的 getDisplayId() == Display.DEFAULT_DISPLAY，那么依然使用onGesture(int)

我使用的是逍遥模拟器，API小于31，所以结果如下图所示

在这里插入图片描述

这部分是给真正需要使用无障碍的人使用的，包括上面的触摸探索，所以这里就不深挖了。

操作

从Android4.0（API级别14）开始，无障碍服务可以代表用户操作，包含改变输入焦点和选择（激活）用户界面元素。在Android4.1（API级别16），操作的范围被扩展至包含滚动列表和与文本域交互。无障碍服务也可采取全局操作，如导航到主界面、按返回按钮、打开屏幕通知和最近应用列表。Android4.1也包含新焦点类型，无障碍焦点，该焦点类型可让所有视觉元素能够被无障碍服务所选择。

这些新的能力让开发者能够开发替代导航模式，如手势导航，提高残障用户对Android设备的控制。

使用AccessibilityNodeInfo对象你的无障碍服务可以浏览视图层次来判定采取什么操作并使用performAction()为用户操作。AccessibilityNodeInfo 对象可以通过 event.getSource() 获取。

除此之外，还可以通过 AccessibilityService 的 performGlobalAction 进行全局操作，示例如下

// 全局操作，以 GLOBAL 开头的都是全局，例如点击主页按钮，返回按钮
performGlobalAction(AccessibilityService.GLOBAL_ACTION_HOME);
performGlobalAction(AccessibilityService.GLOBAL_ACTION_BACK);

// 给元素发送操作，ACTION_之类的，大致操作将后面的翻译一下就知道了
// 还可以通过元素父级子级等获取其他元素来操作其他元素
// 例如给当前元素的父级元素的第一个子元素发送点击事件
AccessibilityNodeInfo nodeInfo = event.getSource();
nodeInfo.getParent().getChild(0).performAction(AccessibilityNodeInfo.ACTION_CLICK);

文本输入操作，AccessibilityNodeInfo需要是EditText之类的

Bundle textBundle = new Bundle();
textBundle.putString(AccessibilityNodeInfo.ACTION_ARGUMENT_SET_TEXT_CHARSEQUENCE, "输入的文本-砷碲");
nodeInfo.performAction(AccessibilityNodeInfo.ACTION_SET_TEXT, textBundle);

滚动操作，是滚动一页，一个往前滚动，一个往后滚动

nodeInfo.performAction(AccessibilityNodeInfo.ACTION_SCROLL_FORWARD);
nodeInfo.performAction(AccessibilityNodeInfo.ACTION_SCROLL_BACKWARD);

一般这样够用了，但是需要精确滚动的话，可以使用模拟手势

模拟手势

有的时候有需求，在指定屏幕位置进行点击等各种操作，而不是对组件，这个时候可以使用模拟手势

模拟手势是通过编程方式模拟用户在屏幕上的触摸和滑动操作

Android API 24及以上可用（即Android 7.0 Nougat）

首先是无障碍中要配置canPerformGestures权限，这样在启动无障碍服务时会增加一项执行手势，代码如下

<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android"
    android:canPerformGestures="true"></accessibility-service>

两个步骤，构建手势描述（GestureDescription）和发送手势（dispatchGesture）

下面列出点击，长按，滑动的示例

Path path = new Path();
path.moveTo(100, 100);

// 长按位置
Path longPath = new Path();
longPath.moveTo(100, 100);

// 滑动位置, 从100,100到300,300
Path scrollPath = new Path();
scrollPath.moveTo(100, 100);
scrollPath.lineTo(300, 300);

// 可以多次addStroke来实现组合动作
// * 但实测，只建议单个addStroke,多个可能会导致APP和系统崩溃...
// StrokeDescription中，第二个参数是开始时间，第三个参数是持续多久，单位毫秒
GestureDescription gd = new GestureDescription.Builder()
        // 点击屏幕，坐标 x=100, y=100。
        .addStroke(new GestureDescription.StrokeDescription(path, 0, 100))
        // 点击完长按屏幕
        .addStroke(new GestureDescription.StrokeDescription(longPath, 100, 10000))
        // 点击，长按完，滑动
        .addStroke(new GestureDescription.StrokeDescription(scrollPath, 1100, 300))
        // 构建
        .build();

// 发送手势，返回手势是否成功发送到了系统以进行执行
// 第二个参数是GestureResultCallback，可选，用来接收手势执行的结果，当手势执行完成后，系统会调用这个回调接口中的方法，并传递一个GestureResult对象作为参数，该对象包含了手势执行的结果信息。通过实现这个接口，你可以在应用程序中处理手势执行的结果，例如根据结果更新UI或执行其他操作。
// 第三个参数Handler，可选，如果你提供了Handler对象，那么GestureResultCallback的回调方法将在该Handler指定的线程中执行。这允许你控制回调方法在哪个线程中运行，以便更好地管理线程和避免潜在的线程冲突问题。如果你没有提供Handler对象，那么回调方法将在系统默认的UI线程中执行。
boolean isRun = dispatchGesture(gd, new GestureResultCallback() {
    @Override
    public void onCompleted(GestureDescription gestureDescription) {
        System.out.println("手势完成");
        super.onCompleted(gestureDescription);
    }

    @Override
    public void onCancelled(GestureDescription gestureDescription) {
        System.out.println("手势取消");
        super.onCancelled(gestureDescription);
    }
}, null);
System.out.println(isRun);