借助 Android 5(API 级别 21)中引入的 android.media.projection API,您可以将设备屏幕中的内容截取为可播放、录制或投屏到其他设备(如电视)的媒体流。
Android 14(API 级别 34)引入了应用屏幕共享功能,让用户可以共享单个应用窗口,而不是整个设备屏幕,无论窗口模式如何。应用屏幕共享会从共享显示中排除状态栏、导航栏、通知和其他系统界面元素,即使使用应用屏幕共享来全屏捕获应用也是如此。系统只会共享所选应用的内容。
应用屏幕共享功能可确保用户隐私、提高用户工作效率并增强多任务处理能力,因为它允许用户运行多个应用,但将内容共享限制为仅限单个应用。
三种显示表示
媒体投影会截取设备屏幕或应用窗口中的内容,然后将截取的图像投影到虚拟屏幕上,虚拟屏幕会在 Surface 上呈现该图像。
Surface 的虚拟屏幕。
应用通过 MediaRecorder、SurfaceTexture 或 ImageReader 提供 Surface,这些类会使用所截取屏幕的内容,并使您能够实时管理在 Surface 上呈现的图像。您可以将这些图片保存为录制内容,也可以将其投射到电视或其他设备。
真实显示
通过获取令牌来开始媒体投影会话,该令牌可让您的应用能够截取设备屏幕或应用窗口中的内容。令牌由 MediaProjection 类的实例表示。
在启动新 activity 时,使用 MediaProjectionManager 系统服务的 getMediaProjection() 方法创建 MediaProjection 实例。使用 createScreenCaptureIntent() 方法中的 intent 启动 activity,以指定屏幕截图操作:
val mediaProjectionManager = getSystemService(MediaProjectionManager::class.java) var mediaProjection: MediaProjection? val startMediaProjection = registerForActivityResult( StartActivityForResult() ) { result -> if (result.resultCode == RESULT_OK) { result.data?.let { data -> mediaProjection = mediaProjectionManager .getMediaProjection(result.resultCode, data) } } } startMediaProjection.launch(mediaProjectionManager.createScreenCaptureIntent())
虚拟屏幕
媒体投影的核心是虚拟屏幕,您可以通过对 MediaProjection 实例调用 createVirtualDisplay() 来创建虚拟屏幕:
virtualDisplay = mediaProjection.createVirtualDisplay( "ScreenCapture", width, height, screenDensity, DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR, surface, null, null )
width 和 height 参数用于指定虚拟显示屏的尺寸。如需获取宽度和高度的值,请使用 Android 11(API 级别 30)中引入的 WindowMetrics API。(如需了解详情,请参阅媒体投影大小部分。)
Surface
调整媒体投影 surface 的大小,以生成具有适当分辨率的输出。将投射到电视或计算机显示器的屏幕的 Surface 调大(低分辨率),将录像的设备屏幕 Surface 调小(高分辨率)。
从 Android 12L(API 级别 32)开始,在 Surface 上呈现捕获的内容时,系统会均匀缩放内容,保持宽高比不变,从而使内容的两个维度(宽度和高度)都等于或小于 Surface 的相应维度。然后,捕获的内容会在 Surface 上居中。
Android 12L 缩放方法可最大限度地增加 Surface 图像的大小,同时确保适当的宽高比,从而提升将屏幕投射到电视和其他大屏幕上的显示效果。
前台服务权限
如果您的应用以 Android 14 或更高版本为目标平台,则应用清单必须包含 mediaProjection 前台服务类型的权限声明:
<manifest ...>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
<application ...>
<service
android:name=".MyMediaProjectionService"
android:foregroundServiceType="mediaProjection"
android:exported="false">
</service>
</application>
</manifest>
通过调用 startForeground() 启动媒体投影服务。
如果您未在调用中指定前台服务类型,则该类型默认为清单中定义的前台服务类型的按位整数。如果清单未指定任何服务类型,系统会抛出 MissingForegroundServiceTypeException。
用户意见征求
您的应用必须在每个媒体投影会话之前请求用户同意。会话是对 createVirtualDisplay() 的单次调用。MediaProjection 令牌只能使用一次来发出调用。
在 Android 14 或更高版本中,如果您的应用执行以下任一操作,createVirtualDisplay() 方法会抛出 SecurityException:
- 多次将从
createScreenCaptureIntent()返回的Intent实例传递给getMediaProjection() - 在同一
MediaProjection实例上多次调用createVirtualDisplay()
媒体投影大小
无论采用何种窗口模式,媒体投影都可以截取整个设备屏幕或应用窗口。
初始大小
在全屏媒体投影模式下,您的应用必须确定设备屏幕的大小。在应用屏幕共享中,在用户选择捕获区域之前,您的应用将无法确定捕获的显示区域的大小。因此,任何媒体投影的初始大小都是设备屏幕的大小。
使用平台 WindowManager getMaximumWindowMetrics() 方法为设备屏幕返回 WindowMetrics 对象,即使媒体投影宿主应用处于多窗口模式,仅占据部分屏幕也是如此。
如需向下兼容到 API 级别 14,请使用 Jetpack WindowManager 库中的 WindowMetricsCalculator computeMaximumWindowMetrics() 方法。
调用 WindowMetrics getBounds() 方法,以获取设备显示屏的宽度和高度。
尺寸变化
当设备旋转或用户在应用屏幕共享中选择应用窗口作为捕获区域时,媒体投影的大小可能会发生变化。如果捕获的内容与设置媒体投影时获取的最大窗口指标大小不同,则媒体投影可能会出现黑边。
为确保媒体投影与任何捕获区域的捕获内容大小精确一致,并且在设备旋转时也能保持一致,请使用 onCapturedContentResize() 回调来调整捕获内容的大小。(如需了解详情,请参阅下文的自定义部分)。
自定义
您的应用可以使用以下 MediaProjection.Callback API 自定义媒体投影用户体验:
onCapturedContentVisibilityChanged():使托管应用(启动媒体投影的应用)能够显示或隐藏共享内容。使用此回调可根据用户是否可以看到捕获的区域来自定义应用的界面。例如,如果您的应用对用户可见,并且在应用的界面中显示捕获的内容,而捕获的应用也对用户可见(如通过此回调指示),则用户会看到相同的内容两次。使用回调更新应用的界面,以隐藏捕获的内容,并释放应用中的布局空间以供其他内容使用。
onCapturedContentResize():使宿主应用能够根据捕获的显示区域的大小,更改虚拟显示屏和媒体投影Surface上的媒体投影的大小。每当捕获的内容(单个应用窗口或整个设备显示屏)大小发生变化(由于设备旋转或捕获的应用进入不同的窗口模式)时触发。使用此 API 可同时调整虚拟屏幕和 Surface 的大小,以确保宽高比与捕获的内容相匹配,并且捕获的内容不会出现黑边。
资源回收
您的应用应注册 MediaProjection onStop() 回调,以便在媒体投影会话停止并失效时收到通知。会话停止后,您的应用应释放其持有的资源,例如虚拟显示屏和投影 Surface。已停止的媒体投影会话无法再创建新的虚拟显示屏,即使您的应用之前未为该媒体投影创建虚拟显示屏也是如此。
当媒体投影终止时,系统会调用该回调。导致此终止的原因可能有多种,例如:
- 用户使用应用的界面或系统的媒体投影状态栏条状标签停止会话
- 屏幕正在锁定
- 另一个媒体投影会话开始
- 应用进程被终止
如果您的应用未注册回调,则对 createVirtualDisplay() 的任何调用都会抛出 IllegalStateException。
选择停用
Android 14 或更高版本默认启用应用屏幕共享。每个媒体投影会话都为用户提供了共享应用窗口或整个屏幕的选项。
您的应用可以通过调用 createScreenCaptureIntent(MediaProjectionConfig) 方法并传入从 createConfigForDefaultDisplay() 调用返回的 MediaProjectionConfig 参数,来停用应用屏幕共享。
使用从调用 createConfigForUserChoice() 返回的 MediaProjectionConfig 参数调用 createScreenCaptureIntent(MediaProjectionConfig) 与默认行为(即调用 createScreenCaptureIntent())相同。
可调整大小的应用
请始终确保媒体投影应用可调整大小 (resizeableActivity="true")。可调整大小的应用支持设备配置更改和多窗口模式(请参阅多窗口支持)。
如果您的应用不可调整大小,则必须从窗口上下文查询显示边界,并使用 getMaximumWindowMetrics() 检索应用可用的最大显示区域的 WindowMetrics:
val windowContext = context.createWindowContext( context.display, WindowManager.LayoutParams.TYPE_APPLICATION, null ) val projectionMetrics = windowContext.getSystemService(WindowManager::class.java) .maximumWindowMetrics
状态栏条状标签和自动停止
Screen projection exploits expose private user data such as financial information because users don't realize their device screen is being shared.
For apps running on devices with Android 15 QPR1 or higher, a status bar chip that is large and prominent alerts users to any in‑progress screen projection. Users can tap the chip to stop their screen from being shared, cast, or recorded. Also, screen projection automatically stops when the device screen is locked.
通过启动屏幕共享、投射或录制,测试媒体投影状态栏条状标签的可用性。该条状标签应显示在状态栏中。
为确保您的应用在用户通过与状态栏条状标签互动或通过激活锁屏状态来停止投屏时释放资源并更新界面,请执行以下操作:
创建
MediaProjection.Callback的实例。实现回调
onStop()方法。当屏幕投影停止时,系统会调用此方法。释放应用占用的所有资源,并根据需要更新应用界面。
如需测试回调,请点按状态栏条状标签或锁定设备屏幕以停止屏幕投影。验证是否调用了 onStop() 方法,以及应用是否按预期响应。
其他资源
如需详细了解媒体投影,请参阅录制视频和音频播放内容。