feat(documents): 更新文档并添加新功能说明

- 更新 AssistsWindowManager 相关文档
- 新增 MPManager 和 OpencvWrapper 的详细说明
- 添加使用示例和注意事项

Author: ven-coder

assists-mp/src/main/java/com/ven/assists_mp/MPManager.kt

@@ -34,25 +34,38 @@ import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
 import java.io.File
 
+/**
+ * 屏幕录制管理器
+ * 负责处理屏幕录制相关的功能，包括权限请求、截图和图像处理
+ */
 object MPManager {
+    /** 媒体投影请求码 */
     const val REQUEST_CODE = "request_code_media_projection"
+    /** 媒体投影请求数据 */
     const val REQUEST_DATA = "request_data_media_projection"
 
+    /** 存储Activity和其对应的结果启动器映射 */
     private var requestLaunchers = hashMapOf<Activity, ActivityResultLauncher<Intent>>()
 
+    /** 服务启用回调 */
     var onEnable: ((service: MPService, intent: Intent, flags: Int, startId: Int) -> Unit)? = null
+    /** 异步等待服务启用的Deferred对象 */
     private var completableDeferredEnable: CompletableDeferred<Boolean>? = null
+    /** 自动允许权限的协程Job */
     private var autoAllowJob: Job? = null
 
+    /** 图像读取器实例 */
     private var imageReader: ImageReader? = null
 
+    /** 屏幕录制是否已启用 */
     var isEnable = false
         private set
         get() {
             field = imageReader?.let { return@let true } ?: false
             return field
         }
 
+    /** Activity生命周期回调，用于管理结果启动器 */
     private val activityLifecycleCallbacks = object : Application.ActivityLifecycleCallbacks {
         override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {
             if (activity is ComponentActivity && requestLaunchers[activity] == null) {
@@ -82,13 +95,24 @@ object MPManager {
         }
     }
 
+    /**
+     * 处理服务启动命令
+     * @param service MPService实例
+     * @param intent 启动意图
+     * @param flags 启动标志
+     * @param startId 启动ID
+     */
     private fun onStartCommand(service: MPService, intent: Intent, flags: Int, startId: Int) {
         onCreateImageReader(service, intent, flags, startId)
         onEnable?.invoke(service, intent, flags, startId)
         completableDeferredEnable?.complete(true)
         completableDeferredEnable = null
     }
 
+    /**
+     * 处理权限请求结果
+     * @param result 活动结果
+     */
     private fun onResult(result: ActivityResult) {
         if (result.resultCode == Activity.RESULT_OK) {
             MPService.onStartCommand = ::onStartCommand
@@ -100,6 +124,13 @@ object MPManager {
         }
     }
 
+    /**
+     * 创建并初始化图像读取器
+     * @param service MPService实例
+     * @param intent 启动意图
+     * @param flags 启动标志
+     * @param startId 启动ID
+     */
     private fun onCreateImageReader(service: MPService, intent: Intent, flags: Int, startId: Int) {
         imageReader?.close()
         val mediaProjectionManager = service.getSystemService(MEDIA_PROJECTION_SERVICE) as MediaProjectionManager
@@ -127,12 +158,22 @@ object MPManager {
         }
     }
 
+    /**
+     * 初始化管理器
+     * @param application Application实例
+     */
     fun init(application: Application) {
         requestLaunchers.clear()
         application.unregisterActivityLifecycleCallbacks(activityLifecycleCallbacks)
         application.registerActivityLifecycleCallbacks(activityLifecycleCallbacks)
     }
 
+    /**
+     * 请求屏幕录制权限
+     * @param autoAllow 是否自动允许权限弹窗，默认为true
+     * @param timeOut 超时时间，默认5000毫秒
+     * @return 权限是否获取成功
+     */
     suspend fun request(autoAllow: Boolean = true, timeOut: Long = 5000): Boolean {
         var projectionManager: MediaProjectionManager? = null
         AssistsService.instance?.let {
@@ -179,6 +220,10 @@ object MPManager {
         return completableDeferredEnable?.await() ?: false
     }
 
+    /**
+     * 获取当前屏幕截图
+     * @return 屏幕截图位图，如果失败返回null
+     */
     fun takeScreenshot2Bitmap(): Bitmap? {
         imageReader?.let {
             val image: Image = it.acquireLatestImage()
@@ -193,6 +238,11 @@ object MPManager {
         } ?: let { throw RuntimeException("Please request permission for screen recording first") }
     }
 
+    /**
+     * 获取指定元素的截图
+     * @param screenshot 完整的屏幕截图
+     * @return 元素区域的位图，如果失败返回null
+     */
     fun AccessibilityNodeInfo.getBitmap(screenshot: Bitmap): Bitmap? {
         runCatching {
             getBoundsInScreen().let {
@@ -205,6 +255,12 @@ object MPManager {
         return null
     }
 
+    /**
+     * 将指定元素的截图保存到文件
+     * @param screenshot 完整的屏幕截图
+     * @param file 保存的目标文件，默认保存到应用内部文件目录
+     * @return 保存成功返回文件对象，失败返回null
+     */
     fun AccessibilityNodeInfo.takeScreenshot2File(
         screenshot: Bitmap,
         file: File = File(
@@ -220,6 +276,11 @@ object MPManager {
         return null
     }
 
+    /**
+     * 将当前屏幕截图保存到文件
+     * @param file 保存的目标文件，默认保存到应用内部文件目录
+     * @return 保存成功返回文件对象，失败返回null
+     */
     fun takeScreenshot2File(
         file: File = File(
             PathUtils.getInternalAppFilesPath(),
@@ -234,6 +295,11 @@ object MPManager {
         return null
     }
 
+    /**
+     * 将Image对象转换为Bitmap
+     * @param image 要转换的Image对象
+     * @return 转换后的Bitmap对象
+     */
     private fun imageToBitmap(image: Image): Bitmap {
         val planes = image.planes
         val buffer = planes[0].buffer
@@ -249,5 +315,4 @@ object MPManager {
         bitmap.copyPixelsFromBuffer(buffer)
         return bitmap
     }
-
 }

assists-mp/src/main/java/com/ven/assists_mp/MPService.kt

@@ -13,14 +13,12 @@ import androidx.annotation.RequiresApi
 import androidx.core.app.NotificationCompat
 import com.ven.assists.base.R
 
-
-/**
- * 屏幕录制服务
- */
 class MPService : Service() {
 
     companion object {
-        var onStartCommand: ((service: MPService, intent: Intent, flags: Int, startId: Int) -> Unit)? = null
+        var onStartCommand:
+                ((service: MPService, intent: Intent, flags: Int, startId: Int) -> Unit)? =
+            null
     }
 
     override fun onCreate() {
@@ -32,105 +30,33 @@ class MPService : Service() {
         return super.onStartCommand(intent, flags, startId)
     }
 
-    private fun captureScreen(mediaProjection: MediaProjection) {
-
-//        val screenWidth = ScreenUtils.getScreenWidth()
-//        val screenHeight = ScreenUtils.getScreenHeight()
-//        val screenDensityDpi = ScreenUtils.getScreenDensityDpi()
-//
-//        imageReader = ImageReader.newInstance(screenWidth, screenHeight, PixelFormat.RGBA_8888, 2)
-//
-//        mediaProjection.createVirtualDisplay(
-//            "ScreenCapture",
-//            screenWidth,
-//            screenHeight,
-//            screenDensityDpi,
-//            DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
-//            imageReader?.surface,
-//            null,
-//            null
-//        )
-    }
-
-
-//    fun saveBitmap(): File? {
-//        val image: Image? = imageReader?.acquireLatestImage()
-//
-//        try {
-//            val width = ScreenUtils.getScreenWidth()
-//            val height = ScreenUtils.getScreenHeight()
-//            val planes: Array<Image.Plane> = image?.planes ?: return null
-//            val buffer: ByteBuffer = planes[0].buffer
-//            val pixelStride: Int = planes[0].pixelStride
-//            val rowStride: Int = planes[0].rowStride
-//            val rowPadding = rowStride - pixelStride * width
-//            val bitmap = Bitmap.createBitmap(
-//                width + rowPadding / pixelStride,
-//                height,
-//                Bitmap.Config.ARGB_8888
-//            )
-//            bitmap.copyPixelsFromBuffer(buffer)
-//            val file = File(PathUtils.getInternalAppCachePath(), "${System.currentTimeMillis()}.png")
-//            val fileOutputStream = FileOutputStream(file)
-//            bitmap.compress(Bitmap.CompressFormat.PNG, 100, fileOutputStream)
-//            fileOutputStream.flush()
-//            fileOutputStream.close()
-//            image.close()
-//            return file
-//        } catch (e: Throwable) {
-//            return null
-//        } finally {
-//            image?.close()
-//        }
-//    }
-
-//    fun toBitmap(): Bitmap? {
-//        val image: Image? = imageReader?.acquireLatestImage()
-//
-//        return try {
-//            val width = ScreenUtils.getScreenWidth()
-//            val height = ScreenUtils.getScreenHeight()
-//            val planes: Array<Image.Plane> = image?.planes ?: return null
-//            val buffer: ByteBuffer = planes[0].buffer
-//            val pixelStride: Int = planes[0].pixelStride
-//            val rowStride: Int = planes[0].rowStride
-//            val rowPadding = rowStride - pixelStride * width
-//            val bitmap = Bitmap.createBitmap(
-//                width + rowPadding / pixelStride,
-//                height,
-//                Bitmap.Config.ARGB_8888
-//            )
-//            bitmap.copyPixelsFromBuffer(buffer)
-//            return bitmap
-//        } catch (e: Throwable) {
-//            null
-//        } finally {
-//            image?.close()
-//        }
-//    }
-
     private fun initNotificationChannel() {
-        val channelId = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            createNotificationChannel()
-        } else {
-            ""
-        }
+        val channelId =
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                createNotificationChannel()
+            } else {
+                ""
+            }
         val builder = NotificationCompat.Builder(this, channelId)
-        val notification = builder.setOngoing(true)
-            .setSmallIcon(R.mipmap.ic_launcher)
-            .setPriority(NotificationCompat.PRIORITY_MIN)
-            .setCategory(Notification.CATEGORY_SERVICE)
-            .build()
+        val notification =
+            builder.setOngoing(true)
+                .setSmallIcon(R.mipmap.ic_launcher)
+                .setPriority(NotificationCompat.PRIORITY_MIN)
+                .setCategory(Notification.CATEGORY_SERVICE)
+                .build()
         startForeground(1, notification)
     }
 
-    /**
-     * 创建通知通道
-     */
+    /** 创建通知通道 */
     @RequiresApi(Build.VERSION_CODES.O)
     private fun createNotificationChannel(): String {
         val channelId = "mirror.hsl"
-        val chan = NotificationChannel(channelId, "ForegroundService", NotificationManager.IMPORTANCE_NONE)
+        val chan =
+            NotificationChannel(
+                channelId,
+                "ForegroundService",
+                NotificationManager.IMPORTANCE_NONE
+            )
         chan.lightColor = Color.BLUE
         chan.lockscreenVisibility = Notification.VISIBILITY_PRIVATE
         val service = getSystemService(NOTIFICATION_SERVICE) as NotificationManager
@@ -145,4 +71,4 @@ class MPService : Service() {
     override fun onDestroy() {
         super.onDestroy()
     }
-}
+}