@unif/react-native-hms-scan 0.6.2 → 1.0.0

package/README.md

@@ -27,12 +27,13 @@ Android 内置识别引擎，不要求华为手机或 HMS Core。两端均不需
 ```ts
 import { decodeImage } from '@unif/react-native-hms-scan';
 
-const results = await decodeImage('file:///path/to/photo.jpg', {
+const results = await decodeImage({
+  uri: 'file:///path/to/photo.jpg',
   formats: ['QR_CODE'],
 });
 ```
 
-正常识别但没有发现码时返回 `[]`；读取或解码失败抛出 `HmsScanError`。函数不下载网络图片，应用需先准备本地文件。
+正常识别但没有发现码时返回 `[]`；读取或解码失败抛出 `ScanError`。函数不下载网络图片，应用需先准备本地文件。
 
 ## 文档与开发
 

package/android/src/main/AndroidManifest.xml

@@ -3,15 +3,6 @@
   <!-- Camera preview / scanning (RemoteView). -->
   <uses-permission android:name="android.permission.CAMERA" />
 
-  <!-- Reading a local image for decodeImage().
-       Android 13+ (API 33) uses the scoped media permission; older devices fall
-       back to READ_EXTERNAL_STORAGE (capped at API 32 so the merger doesn't
-       force it on newer OS versions). -->
-  <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
-  <uses-permission
-    android:name="android.permission.READ_EXTERNAL_STORAGE"
-    android:maxSdkVersion="32" />
-
   <!-- Camera is used but not strictly required (gallery decode works without it). -->
   <uses-feature
     android:name="android.hardware.camera"

package/android/src/main/java/com/unif/reactnativehmsscan/HmsScanImage.kt

@@ -0,0 +1,135 @@
+package com.unif.reactnativehmsscan
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Matrix
+import android.media.ExifInterface
+import android.net.Uri
+import java.io.Closeable
+import java.io.File
+import java.io.FileInputStream
+import java.io.IOException
+
+internal class ScanImageFailure(
+  val code: String,
+  message: String,
+) : IOException(message)
+
+/** Owns one upright bitmap; points are returned in the upright original image. */
+internal class HmsScanImage private constructor(
+  val bitmap: Bitmap,
+  val scaleX: Double,
+  val scaleY: Double,
+) : Closeable {
+  override fun close() {
+    if (!bitmap.isRecycled) bitmap.recycle()
+  }
+
+  companion object {
+    // At most 32 MiB per ARGB bitmap, temporarily 64 MiB during EXIF rotation.
+    // The vendor has additional working memory. Only one image job runs at once.
+    private const val MAX_PIXELS = 8_388_608L
+    private const val MAX_SOURCE_PIXELS = 268_435_456L
+    private const val MAX_SOURCE_EDGE = 32_768
+    private const val MAX_FILE_BYTES = 128L * 1024 * 1024
+
+    fun read(uri: String): HmsScanImage {
+      val parsed = Uri.parse(uri)
+      val path = parsed.path
+      if (!parsed.scheme.equals("file", ignoreCase = true) || path.isNullOrEmpty()) {
+        throw ScanImageFailure("E_INVALID_INPUT", "需要可读的 file URI")
+      }
+      val file = File(path)
+      if (!file.isFile || !file.canRead()) {
+        throw ScanImageFailure("E_IMAGE_LOAD_FAILED", "无法读取本地图片")
+      }
+      if (file.length() > MAX_FILE_BYTES) {
+        throw ScanImageFailure("E_INVALID_INPUT", "图片文件超过 128 MiB")
+      }
+      val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+      BitmapFactory.decodeFile(path, bounds)
+      val width = bounds.outWidth
+      val height = bounds.outHeight
+      if (width <= 0 || height <= 0) {
+        throw ScanImageFailure("E_IMAGE_LOAD_FAILED", "无法读取图片尺寸")
+      }
+      if (width > MAX_SOURCE_EDGE || height > MAX_SOURCE_EDGE || width.toLong() * height > MAX_SOURCE_PIXELS) {
+        throw ScanImageFailure("E_INVALID_INPUT", "图片尺寸超过安全解码范围")
+      }
+      var sample = 1
+      while (((width + sample - 1) / sample).toLong() * ((height + sample - 1) / sample) > MAX_PIXELS) {
+        sample *= 2
+      }
+      val options =
+        BitmapFactory.Options().apply {
+          inSampleSize = sample
+          inPreferredConfig = Bitmap.Config.ARGB_8888
+        }
+      var bitmap =
+        BitmapFactory.decodeFile(path, options)
+          ?: throw ScanImageFailure("E_IMAGE_LOAD_FAILED", "无法解码本地图片")
+      try {
+        if (bitmap.width.toLong() * bitmap.height > MAX_PIXELS || bitmap.allocationByteCount.toLong() > MAX_PIXELS * 4) {
+          throw ScanImageFailure("E_INVALID_INPUT", "图片解码超过内存预算")
+        }
+        // Unsupported/missing optional EXIF does not discard an otherwise valid image.
+        val orientation =
+          try {
+            FileInputStream(file).use {
+              ExifInterface(it).getAttributeInt(ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL)
+            }
+          } catch (_: IOException) {
+            ExifInterface.ORIENTATION_NORMAL
+          }
+        val matrix = Matrix()
+        when (orientation) {
+          ExifInterface.ORIENTATION_FLIP_HORIZONTAL -> {
+            matrix.setScale(-1f, 1f)
+          }
+
+          ExifInterface.ORIENTATION_ROTATE_180 -> {
+            matrix.setRotate(180f)
+          }
+
+          ExifInterface.ORIENTATION_FLIP_VERTICAL -> {
+            matrix.setScale(1f, -1f)
+          }
+
+          ExifInterface.ORIENTATION_TRANSPOSE -> {
+            matrix.setRotate(90f)
+            matrix.postScale(-1f, 1f)
+          }
+
+          ExifInterface.ORIENTATION_ROTATE_90 -> {
+            matrix.setRotate(90f)
+          }
+
+          ExifInterface.ORIENTATION_TRANSVERSE -> {
+            matrix.setRotate(270f)
+            matrix.postScale(-1f, 1f)
+          }
+
+          ExifInterface.ORIENTATION_ROTATE_270 -> {
+            matrix.setRotate(270f)
+          }
+        }
+        if (orientation in ExifInterface.ORIENTATION_FLIP_HORIZONTAL..ExifInterface.ORIENTATION_ROTATE_270) {
+          val upright = Bitmap.createBitmap(bitmap, 0, 0, bitmap.width, bitmap.height, matrix, true)
+          if (upright !== bitmap) {
+            bitmap.recycle()
+            bitmap = upright
+          }
+        }
+        val swapsAxes = orientation in ExifInterface.ORIENTATION_TRANSPOSE..ExifInterface.ORIENTATION_ROTATE_270
+        return HmsScanImage(
+          bitmap,
+          (if (swapsAxes) height else width).toDouble() / bitmap.width,
+          (if (swapsAxes) width else height).toDouble() / bitmap.height,
+        )
+      } catch (error: Throwable) {
+        if (!bitmap.isRecycled) bitmap.recycle()
+        throw error
+      }
+    }
+  }
+}

package/android/src/main/java/com/unif/reactnativehmsscan/HmsScanModule.kt

@@ -3,200 +3,216 @@ package com.unif.reactnativehmsscan
 import android.Manifest
 import android.app.Activity
 import android.content.pm.PackageManager
-import android.graphics.Bitmap
-import android.graphics.BitmapFactory
-import android.net.Uri
 import androidx.core.app.ActivityCompat
 import androidx.core.content.ContextCompat
+import com.facebook.react.bridge.LifecycleEventListener
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.UiThreadUtil
 import com.facebook.react.modules.core.PermissionAwareActivity
 import com.facebook.react.modules.core.PermissionListener
 import com.huawei.hms.hmsscankit.ScanUtil
 import com.huawei.hms.ml.scan.HmsScan
 import com.huawei.hms.ml.scan.HmsScanAnalyzerOptions
-import java.io.File
-import java.io.InputStream
-
-/**
- * TurboModule "HmsScan". Implements the codegen-generated [NativeHmsScanSpec]:
- *   - decodeImage(): decode a local image into a ScanResult[] JSON string.
- *   - getCameraPermissionStatus() / requestCameraPermission(): camera permission.
- */
+import java.util.concurrent.ArrayBlockingQueue
+import java.util.concurrent.RejectedExecutionException
+import java.util.concurrent.ThreadPoolExecutor
+import java.util.concurrent.TimeUnit
+
+/** Independent image decoding and camera permission boundaries. */
 class HmsScanModule(
   reactContext: ReactApplicationContext,
-) : NativeHmsScanSpec(reactContext) {
-  override fun getName(): String = NAME
+) : NativeHmsScanSpec(reactContext),
+  LifecycleEventListener {
+  // One allocated image at a time, with at most four waiting file borrowers.
+  private val imageQueue =
+    ThreadPoolExecutor(1, 1, 0, TimeUnit.MILLISECONDS, ArrayBlockingQueue(4)) { work ->
+      Thread(work, "HmsScan-image").apply { isDaemon = true }
+    }
 
-  // ── decodeImage ──────────────────────────────────────────────────────────
+  @Volatile private var invalidated = false
+
+  // Permission requests and host callbacks are serialized on the UI thread.
+  private class PermissionBatch(
+    val activity: Activity,
+    val promises: MutableList<Promise>,
+  )
+
+  private var permissionBatch: PermissionBatch? = null
+
+  override fun getName(): String = NAME
 
-  /**
-   * Decode barcodes/QR codes from a local image. Loads the bitmap from a
-   * file:// / content:// URI or an absolute path, runs ScanUtil.decodeWithBitmap
-   * (photo mode), and resolves the ScanResult[] JSON. Never rejects on "no code
-   * found" — it resolves an empty array, matching the JS contract.
-   */
   override fun decodeImage(
     uri: String,
     formatsCsv: String,
     promise: Promise,
   ) {
-    val bitmap = loadBitmap(uri)
-    if (bitmap == null) {
-      promise.reject(E_IMAGE_LOAD_FAILED, "Failed to load image from uri: $uri")
-      return
+    val work = ImageWork(uri, formatsCsv, promise)
+    synchronized(imageQueue) {
+      if (invalidated) {
+        work.rejectUnavailable()
+        return
+      }
+      try {
+        imageQueue.execute(work)
+      } catch (_: RejectedExecutionException) {
+        work.rejectUnavailable()
+      }
     }
+  }
 
-    try {
-      val types = HmsScanResultMapper.parseFormatsCsv(formatsCsv)
-      val optionsCreator = HmsScanAnalyzerOptions.Creator().setPhotoMode(true)
-      if (types != null && types.isNotEmpty()) {
-        val first = types.first()
-        val rest = if (types.size > 1) types.copyOfRange(1, types.size) else IntArray(0)
-        optionsCreator.setHmsScanTypes(first, *rest)
-      } else {
-        optionsCreator.setHmsScanTypes(HmsScan.ALL_SCAN_TYPE)
+  private inner class ImageWork(
+    val uri: String,
+    val formatsCsv: String,
+    val promise: Promise,
+  ) : Runnable {
+    fun rejectUnavailable() {
+      promise.reject("E_UNAVAILABLE", "图片识别不可用或等待队列已满")
+    }
+
+    override fun run() {
+      if (invalidated) {
+        rejectUnavailable()
+        return
       }
-      val options = optionsCreator.create()
-
-      val scans = ScanUtil.decodeWithBitmap(reactApplicationContext, bitmap, options)
-      promise.resolve(HmsScanResultMapper.toJson(scans))
-    } catch (e: Throwable) {
-      promise.reject(E_DECODE_FAILED, e.message ?: "Failed to decode image", e)
-    } finally {
-      if (!bitmap.isRecycled) {
-        bitmap.recycle()
+      try {
+        // use closes the bitmap before the promise settles and the caller releases its file.
+        val json =
+          HmsScanImage.read(uri).use { image ->
+            val types = HmsScanResultMapper.parseFormatsCsv(formatsCsv)
+            val creator = HmsScanAnalyzerOptions.Creator().setPhotoMode(true)
+            if (types != null && types.isNotEmpty()) {
+              creator.setHmsScanTypes(types.first(), *types.drop(1).toIntArray())
+            } else {
+              creator.setHmsScanTypes(HmsScan.ALL_SCAN_TYPE)
+            }
+            val scans = ScanUtil.decodeWithBitmap(reactApplicationContext, image.bitmap, creator.create())
+            HmsScanResultMapper.toJson(scans, image.scaleX, image.scaleY)
+          }
+        promise.resolve(json)
+      } catch (error: ScanImageFailure) {
+        promise.reject(error.code, error.message, error)
+      } catch (error: InvalidScanResponse) {
+        promise.reject("E_INVALID_RESPONSE", error.message, error)
+      } catch (error: Exception) {
+        promise.reject("E_DECODE_FAILED", error.message ?: "图片识别失败", error)
+      } catch (error: OutOfMemoryError) {
+        promise.reject("E_DECODE_FAILED", "图片识别内存不足", error)
       }
     }
   }
 
-  /** Resolve a uri/path to a decoded [Bitmap], or null on any failure. */
-  private fun loadBitmap(uri: String): Bitmap? =
+  /** Android does not distinguish never asked from blocked in a read-only query. */
+  override fun getCameraPermissionStatus(promise: Promise) {
     try {
-      val parsed = Uri.parse(uri)
-      val scheme = parsed.scheme?.lowercase()
-      when (scheme) {
-        "content", "file", "android.resource" -> {
-          val resolver = reactApplicationContext.contentResolver
-          var stream: InputStream? = null
-          try {
-            stream = resolver.openInputStream(parsed)
-            if (stream == null) null else BitmapFactory.decodeStream(stream)
-          } finally {
-            stream?.close()
-          }
-        }
+      promise.resolve(if (hasCameraPermission()) GRANTED else DENIED)
+    } catch (error: Exception) {
+      promise.reject("E_UNAVAILABLE", "读取相机权限失败", error)
+    }
+  }
 
-        null -> {
-          // No scheme -> treat as an absolute filesystem path.
-          val path = parsed.path ?: uri
-          decodeFile(path)
+  override fun requestCameraPermission(promise: Promise) {
+    UiThreadUtil.runOnUiThread {
+      if (invalidated) {
+        promise.reject("E_UNAVAILABLE", "扫码模块已释放")
+        return@runOnUiThread
+      }
+      try {
+        if (hasCameraPermission()) {
+          promise.resolve(GRANTED)
+          return@runOnUiThread
         }
-
-        else -> {
-          // Unsupported scheme (e.g. http/https): JS contract forbids remote URLs.
-          null
+        val activity = reactApplicationContext.currentActivity
+        if (activity !is PermissionAwareActivity) {
+          promise.reject("E_NO_ACTIVITY", "没有可申请相机权限的界面")
+          return@runOnUiThread
+        }
+        permissionBatch?.let { pending ->
+          if (pending.activity === activity) {
+            pending.promises.add(promise)
+            return@runOnUiThread
+          }
+          rejectPermissions(pending, "E_NO_ACTIVITY", "相机权限所属界面已结束")
+        }
+        val batch = PermissionBatch(activity, mutableListOf(promise))
+        permissionBatch = batch
+        reactApplicationContext.addLifecycleEventListener(this)
+        val listener =
+          PermissionListener { requestCode, _, grantResults ->
+            if (requestCode != CAMERA_PERMISSION_REQUEST_CODE) {
+              return@PermissionListener false
+            }
+            if (permissionBatch !== batch) return@PermissionListener true
+            if (grantResults.isEmpty()) {
+              rejectPermissions(batch, "E_UNAVAILABLE", "相机权限申请未完成")
+            } else {
+              val status =
+                when {
+                  grantResults[0] == PackageManager.PERMISSION_GRANTED -> GRANTED
+                  ActivityCompat.shouldShowRequestPermissionRationale(activity, Manifest.permission.CAMERA) -> DENIED
+                  else -> BLOCKED
+                }
+              finishPermissions(batch).forEach { it.resolve(status) }
+            }
+            true
+          }
+        try {
+          activity.requestPermissions(arrayOf(Manifest.permission.CAMERA), CAMERA_PERMISSION_REQUEST_CODE, listener)
+        } catch (error: Exception) {
+          rejectPermissions(batch, "E_UNAVAILABLE", error.message ?: "申请相机权限失败")
         }
+      } catch (error: Exception) {
+        promise.reject("E_UNAVAILABLE", "申请相机权限失败", error)
       }
-    } catch (e: Throwable) {
-      null
     }
+  }
 
-  private fun decodeFile(path: String): Bitmap? {
-    val file = File(path)
-    if (!file.exists() || !file.canRead()) return null
-    return BitmapFactory.decodeFile(file.absolutePath)
+  private fun finishPermissions(batch: PermissionBatch): List<Promise> {
+    if (permissionBatch !== batch) return emptyList()
+    permissionBatch = null
+    reactApplicationContext.removeLifecycleEventListener(this)
+    return batch.promises.toList().also { batch.promises.clear() }
   }
 
-  // ── Camera permission ────────────────────────────────────────────────────
-
-  /**
-   * Current camera permission without prompting.
-   *
-   * Note: at query time Android exposes no reliable signal to distinguish
-   * "blocked" / "undetermined" from a plain denial (shouldShowRequestPermissionRationale
-   * is false for both the never-asked and permanently-denied states), so a
-   * not-granted result is reported as "denied". The blocked/undetermined nuance is
-   * resolved by requestCameraPermission() via the post-request rationale check.
-   */
-  override fun getCameraPermissionStatus(promise: Promise) {
-    promise.resolve(if (hasCameraPermission()) GRANTED else DENIED)
+  private fun rejectPermissions(
+    batch: PermissionBatch,
+    code: String,
+    message: String,
+  ) {
+    finishPermissions(batch).forEach { it.reject(code, message) }
   }
 
-  /**
-   * Request the camera permission (system dialog if needed) and resolve the
-   * resulting status:
-   *   - granted: permission held.
-   *   - denied: rejected but the app may ask again (rationale should be shown).
-   *   - blocked: rejected with "don't ask again" (rationale will not be shown).
-   */
-  override fun requestCameraPermission(promise: Promise) {
-    if (hasCameraPermission()) {
-      promise.resolve(GRANTED)
-      return
-    }
+  override fun onHostResume() = Unit
 
-    val activity = currentActivity
-    if (activity == null || activity !is PermissionAwareActivity) {
-      // Can't surface a system dialog without a PermissionAwareActivity; report the
-      // current (not-granted) state rather than hanging the promise.
-      promise.reject(
-        E_NO_ACTIVITY,
-        "Cannot request camera permission: no current PermissionAwareActivity",
-      )
-      return
-    }
+  override fun onHostPause() = Unit
 
-    val permissionAwareActivity = activity as PermissionAwareActivity
-    val listener =
-      PermissionListener { requestCode, _, grantResults ->
-        if (requestCode != CAMERA_PERMISSION_REQUEST_CODE) {
-          return@PermissionListener false
-        }
-        val granted =
-          grantResults.isNotEmpty() &&
-            grantResults[0] == PackageManager.PERMISSION_GRANTED
-        val status =
-          when {
-            granted -> GRANTED
-
-            // After a denial: rationale==true means the user can be asked again;
-            // rationale==false means "don't ask again" (blocked).
-            ActivityCompat.shouldShowRequestPermissionRationale(
-              activity,
-              Manifest.permission.CAMERA,
-            ) -> DENIED
-
-            else -> BLOCKED
-          }
-        promise.resolve(status)
-        true
-      }
+  override fun onHostDestroy() {
+    permissionBatch?.let { rejectPermissions(it, "E_NO_ACTIVITY", "相机权限所属界面已结束") }
+  }
 
-    permissionAwareActivity.requestPermissions(
-      arrayOf(Manifest.permission.CAMERA),
-      CAMERA_PERMISSION_REQUEST_CODE,
-      listener,
-    )
+  override fun invalidate() {
+    val waiting = mutableListOf<Runnable>()
+    synchronized(imageQueue) {
+      invalidated = true
+      imageQueue.queue.drainTo(waiting)
+      // Do not interrupt an active vendor read or return its file before it finishes.
+      imageQueue.shutdown()
+    }
+    waiting.forEach { (it as ImageWork).rejectUnavailable() }
+    UiThreadUtil.runOnUiThread {
+      permissionBatch?.let { rejectPermissions(it, "E_UNAVAILABLE", "扫码模块已释放") }
+    }
+    super.invalidate()
   }
 
   private fun hasCameraPermission(): Boolean =
-    ContextCompat.checkSelfPermission(
-      reactApplicationContext,
-      Manifest.permission.CAMERA,
-    ) == PackageManager.PERMISSION_GRANTED
+    ContextCompat.checkSelfPermission(reactApplicationContext, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED
 
   companion object {
     const val NAME = NativeHmsScanSpec.NAME
-
     private const val GRANTED = "granted"
     private const val DENIED = "denied"
     private const val BLOCKED = "blocked"
-
-    private const val E_IMAGE_LOAD_FAILED = "E_IMAGE_LOAD_FAILED"
-    private const val E_DECODE_FAILED = "E_DECODE_FAILED"
-    private const val E_NO_ACTIVITY = "E_NO_ACTIVITY"
-
-    private const val CAMERA_PERMISSION_REQUEST_CODE = 0x48_4D // "HM"
+    private const val CAMERA_PERMISSION_REQUEST_CODE = 0x48_4D
   }
 }

package/android/src/main/java/com/unif/reactnativehmsscan/HmsScanResultMapper.kt

@@ -15,22 +15,28 @@ import org.json.JSONObject
  *   "cornerPoints":[{"x":10,"y":20}]}]
  * ```
  */
+internal class InvalidScanResponse(
+  message: String,
+) : IllegalArgumentException(message)
+
 internal object HmsScanResultMapper {
   /**
    * Serialize an array of [HmsScan] into the ScanResult[] JSON string. The element
    * type is nullable because the HMS APIs (decodeWithBitmap / OnResultCallback)
    * hand back a Java array that can contain nulls.
    */
-  fun toJson(scans: Array<out HmsScan?>?): String {
+  fun toJson(
+    scans: Array<out HmsScan?>?,
+    scaleX: Double = 1.0,
+    scaleY: Double = 1.0,
+  ): String {
     val array = JSONArray()
     if (scans != null) {
       for (scan in scans) {
         if (scan == null) continue
         val value = scan.getOriginalValue()
-        // A hit with no value is meaningless to the JS layer (it would be dropped
-        // by coerceResult anyway); skip it to keep the payload clean.
-        if (value.isNullOrEmpty()) continue
-        array.put(toJsonObject(scan, value))
+        if (value == null) throw InvalidScanResponse("ScanKit returned a result without text")
+        array.put(toJsonObject(scan, value, scaleX, scaleY))
       }
     }
     return array.toString()
@@ -39,6 +45,8 @@ internal object HmsScanResultMapper {
   private fun toJsonObject(
     scan: HmsScan,
     value: String,
+    scaleX: Double,
+    scaleY: Double,
   ): JSONObject {
     val obj = JSONObject()
     obj.put("value", value)
@@ -53,8 +61,8 @@ internal object HmsScanResultMapper {
         if (point == null) continue
         points.put(
           JSONObject().apply {
-            put("x", point.x)
-            put("y", point.y)
+            put("x", point.x * scaleX)
+            put("y", point.y * scaleY)
           },
         )
       }
@@ -66,7 +74,7 @@ internal object HmsScanResultMapper {
     return obj
   }
 
-  /** HmsScan.getScanType() (barcode symbology) -> unified BarcodeFormat string. */
+  /** HmsScan.getScanType() (barcode symbology) -> unified ScanFormat string. */
   fun mapScanType(scanType: Int): String =
     when (scanType) {
       HmsScan.QRCODE_SCAN_TYPE -> "QR_CODE"
@@ -105,7 +113,7 @@ internal object HmsScanResultMapper {
     return if (types.isEmpty()) null else types.toIntArray()
   }
 
-  /** Unified BarcodeFormat string -> HmsScan.*_SCAN_TYPE (null when unknown). */
+  /** Unified ScanFormat string -> HmsScan.*_SCAN_TYPE (null when unknown). */
   private fun mapFormatString(format: String): Int? =
     when (format) {
       "QR_CODE" -> HmsScan.QRCODE_SCAN_TYPE