Android 14 新 API：直接监听截屏操作，不用再观察媒体文件了～

android14-base-screenshot
截屏可以说是手机设备最常用的功能了，Android 系统非常重视截屏方面的体验，近几年的更新都不忘去优化这方面的体验。

从一开始仅在通知栏提醒已截屏，到 Android 11 支持在左下角生成截屏缩略图供编辑或分享，再到 Android 12 支持滚动截屏，以及这次的 Android 14 允许 App 直接监听用户的截屏操作。

为打造更加标准的监听截屏体验，Android 14 正式推出了受隐私保护的相关 API。简单来说，该 API 允许 App 以 Activity 为单位注册监听 Callback，当这些 Activity 可见并且被用户截屏的话，系统将回调这些 Callback 并告知用户当前的 App 监听到了截屏操作。

如下是官方提供的效果示例：

需要留意的是：监听截屏 API 并不提供图像数据，意在告诉 App 截屏的时机，你可以选择在这个时机做相应的操作。比如：客服类 App 可以询问用户是否要上传截屏以反馈问题抑或引导用户从相册选择截屏；隐私程度高的 App 则可以提醒用户不要泄露、做好隐私保护等等。

实战

首先要给 App 声明监听截屏的权限： DETECT_SCREEN_CAPTURE 。

<uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />

这个权限是 normal 级别的，无需动态申请，APK 被安装的时候将自动授予。

Allows an application to get notified when a screen capture of its windows is attempted.

Protection level: normal

之后的写法比较简单，即在需要监听截屏的 Activity 里注册回调：

创建 ScreenCaptureCallback 的实例，并在 onScreenCapture() 实现里添加所需逻辑，比如此处为弹出警告 Dialog：

    class ScreenShotActivity : AppCompatActivity() {
        private val screenCaptureCallback = ScreenCaptureCallback {
            Log.d("ScreenShot", "onScreenCaptured()", Throwable())
    
            AlertDialog.Builder(this)
                .setMessage("You have taken a screenshot...")
                .setTitle("Warning")
                .show()
        }
        ...
    }

接着，在该 Activity 的 onStart() 方法里注册上述的 ScreenCaptureCallback 实例，需要指定该回调的执行线程 Executor：

class ScreenShotActivity : AppCompatActivity() {
    ...
    override fun onStart() {
        super.onStart()

        Log.d("ScreenShot", "onStart() registerScreenCaptureCallback")
        registerScreenCaptureCallback(mainExecutor, screenCaptureCallback)
    }
    ...
}

记得在 Activity 的 onStop() 里注销该 ScreenCaptureCallback 实例，避免内存 leak：

class ScreenShotActivity : AppCompatActivity() {
    ...
    override fun onStop() {
        super.onStop()

        Log.d("ScreenShot", "onStop() unregisterScreenCaptureCallback")
        unregisterScreenCaptureCallback(screenCaptureCallback)
    }
    ...
}

而后将目标 Activity 启动，通过 log 可以看到已经注册了监听回调，后面就是操作截屏进行验证。

04-05 21:57:53.904  5230  5230 D ScreenShot: onStart() registerScreenCaptureCallback

可是问题来了：笔者手动没有能够运行 Android 14 的真机，运行 14 的是 Pixel 6 模拟器。

要知道模拟器上你是无法直接同时按下 POWER 键+ VOLUME DOWN 按键来完成截屏的，同时 Pixel ROM 的通知面板也没有提供截屏的 UI 入口。

笔者突然想到了用 adb 模拟按键事件，可苦苦搜寻之后发现 input keyevent 仅支持单个 keyevent 的模拟。就在要放弃的时候，我忽然想到另一种 event 模拟办法，就是 sendevent。

首先通过搜索和尝试获悉 POWER 键的长按输入办法：

adb shell sendevent /dev/input/event0 1 116 1 && adb shell sendevent /dev/input/event0 0 0 0 && sleep 3 && adb shell sendevent /dev/input/event0 1 116 0 && adb shell sendevent /dev/input/event0 0 0 0

再找到 VOLUME DOWN 键的长按输入办法：

adb shell sendevent /dev/input/event12 1 114 1 && adb shell sendevent /dev/input/event12 0 0 0 && sleep 3 && adb shell sendevent /dev/input/event12 1 114 0 && adb shell sendevent /dev/input/event12 0 0 0

两者一结合即可模拟同时长按 POWER 键+ VOLUME DOWN 按键的操作：

adb shell sendevent /dev/input/event0 1 116 1 && adb shell sendevent /dev/input/event0 0 0 0 && adb shell sendevent /dev/input/event12 1 114 1 && adb shell sendevent /dev/input/event12 0 0 0 && sleep 3 && adb shell sendevent /dev/input/event0 1 116 0 && adb shell sendevent /dev/input/event0 0 0 0 && adb shell sendevent /dev/input/event12 1 114 0 && adb shell sendevent /dev/input/event12 0 0 0

需要留意的是上述命令需要在 root 环境下执行，即 adb root 之后再执行 sendevent 命令，当然如果你有真机就无需这么迂回啦。

成功模拟用户截屏操作之后，如愿看到了截屏的缩略图和系统在屏幕下方给用户 App 监听了当前截屏的 Toast 提醒：

以及系统给予当前 App 的截屏操作的回调：

04-05 21:58:04.459  5230  5230 D ScreenShot: onScreenCaptured()

App 也依据回调弹出了代码里拟定的截屏警告 Dialog。

能监听到 adb 等方式发起的截屏吗？

了解 Android 上截屏的朋友会知道，截屏的发起方式有很多种，除了最常用的按键组合外还可以：

代码中使用 DeviceCapture test 框架、MediaProjectionManager、SurfaceControl 发起
调试中使用 adb 命令发起
AS 的 logcat 窗口里的 “Screen Capture” 图标、Emulator 窗口的 “Take Screenshot” 菜单

等等。

那这些场景下的截屏操作，14 的方式是否能监听到呢？

答案是否定的，官方予以了明确说明：

In Android 14, the system API only detects a screenshot if the user performs a specific combination of hardware button presses. The API doesn’t detect screenshots that are taken when running test commands related to screenshots, including ADB, or within instrumentation tests that capture the device’s current screen contents.

笔者也实际尝试了下，无论是 ADB 命令还是 AS 的 UI 入口触发的截屏，都没有回调上述的 ScreenCaptureCallback，系统亦没有截屏的提醒。

理由也可想而知，一般用户不会用这样的方式截屏，这种调试场景下、系统场景下的截屏需求甚至不会在屏幕下方展示缩略图，自然没有必要回调监听的 API 了。

原理

Android 14 的源码尚未公开，但可以打印 ScreenCaptureCallback 的堆栈瞥到相关细节：

04-06 22:35:23.593  4627  4627 D ScreenShot: onScreenCaptured()
04-06 22:35:23.593  4627  4627 D ScreenShot: java.lang.Throwable
04-06 22:35:23.593  4627  4627 D ScreenShot:    at eu.thomaskuenneth.textviewhighlightsdemo.ScreenShotActivity.screenCaptureCallback$lambda-0(ScreenShotActivity.kt:13)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at eu.thomaskuenneth.textviewhighlightsdemo.ScreenShotActivity.$r8$lambda$5lHWf6dEQmh2JMn9HXzbeN068DI(Unknown Source:0)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at eu.thomaskuenneth.textviewhighlightsdemo.ScreenShotActivity$$ExternalSyntheticLambda0.onScreenCaptured(Unknown Source:2)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at android.app.ScreenCaptureCallbackHandler$ScreenCaptureObserver.lambda$onScreenCaptured$0(ScreenCaptureCallbackHandler.java:66)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at android.app.ScreenCaptureCallbackHandler$ScreenCaptureObserver$$ExternalSyntheticLambda0.run(Unknown Source:2)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at android.os.Handler.handleCallback(Handler.java:958)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at android.os.Handler.dispatchMessage(Handler.java:99)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at android.os.Looper.loopOnce(Looper.java:205)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at android.os.Looper.loop(Looper.java:294)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at android.app.ActivityThread.main(ActivityThread.java:8128)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at java.lang.reflect.Method.invoke(Native Method)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:578)
04-06 22:35:23.593  4627  4627 D ScreenShot:    at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:946)

通过上述堆栈，再结合 13 的现有截屏逻辑，可以推测下该 Callback 的实现：

SystemUI 的 TakeScreenshotService 在截屏完成之后通知 AMS，AMS 判断当前 Activity 的 ScreenCaptureCallbackHandler 中是否存在 ScreenCaptureObserver
YES 则意味着注册了 ScreenCaptureCallback，便通过 AIDL 告知 App 进程，App 进程内部通过 Handler 告知 ScreenCaptureCallbackHandler 在预设的 Executor 执行 onScreenCaptured() 回调

总结

ScreenCaptureCallback 监听截屏 API 的使用简单、清晰，以后不需要再通过监听媒体文件的变化等逻辑来迂回实现，采用官方的方式去探测用户的截屏操作并按照文件读写的规范去提取文件。

但需要留意 adb、代码、AS 等方式发起的截屏无法通过该 API 监听得到，笔者以为这些不属于用户操作，没有必要纳入到监听范围中。另外，这个监听 API 并不是 Application 级别的，每个目标 Activity 都得注册，所以可以考虑在 BaseActivity 中完成 API 的注册和注销。

相信这个 API 后续亦会扩展到 Jetpack 当中，届时无论是否升级到了 Android 14 都可以尝试切换到官方的监听截屏方式中来。