更新CameraX至v1.2.1

2023-03-04 20:54:37 +08:00
parent b2fa6aaec0
commit a85d793149
53 changed files with 1566 additions and 884 deletions
--- a/README.md
+++ b/README.md
@@ -24,35 +24,44 @@ ZXingLite for Android 是ZXing的精简极速版，基于ZXing库优化扫码和


 ## ViewfinderView属性说明
-| 属性 | 值类型 | 默认值 | 说明 |
-| :------| :------ | :------ | :------ |
-| maskColor | color |<font color=#000000>#60000000</font>| 扫描区外遮罩的颜色 |
-| frameColor | color |<font color=#1FB3E2>#7F1FB3E2</font>| 扫描区边框的颜色 |
-| cornerColor | color |<font color=#1FB3E2>#FF1FB3E2</font>| 扫描区边角的颜色 |
-| laserColor | color |<font color=#1FB3E2>#FF1FB3E2</font>| 扫描区激光线的颜色 |
-| labelText | string |  | 扫描提示文本信息 |
-| labelTextColor | color |<font color=#C0C0C0>#FFC0C0C0</font>| 提示文本字体颜色 |
+
+| 属性 | 属性类型      | 默认值 | 属性说明  |
+| :------|:----------| :------ | :------ |
+| maskColor | color     |<font color=#000000>#60000000</font>| 扫描区外遮罩的颜色 |
+| frameColor | color     |<font color=#1FB3E2>#7F1FB3E2</font>| 扫描区边框的颜色 |
+| cornerColor | color     |<font color=#1FB3E2>#FF1FB3E2</font>| 扫描区边角的颜色 |
+| laserColor | color     |<font color=#1FB3E2>#FF1FB3E2</font>| 扫描区激光线的颜色 |
+| labelText | string    |  | 扫描提示文本信息 |
+| labelTextColor | color     |<font color=#C0C0C0>#FFC0C0C0</font>| 提示文本字体颜色 |
 | labelTextSize | dimension |14sp| 提示文本字体大小 |
 | labelTextPadding | dimension |24dp| 提示文本距离扫描区的间距 |
 | labelTextWidth | dimension | | 提示文本的宽度，默认为View的宽度 |
-| labelTextLocation | enum |bottom| 提示文本显示位置 |
+| labelTextLocation | enum      |bottom| 提示文本显示位置 |
 | frameWidth | dimension |  | 扫码框宽度 |
 | frameHeight | dimension |  | 扫码框高度 |
-| laserStyle | enum | line | 扫描激光的样式 |
-| gridColumn | integer | 20 | 网格扫描激光列数 |
-| gridHeight | integer | 40dp | 网格扫描激光高度，为0dp时，表示动态铺满 |
+| laserStyle | enum      | line | 扫描激光的样式 |
+| gridColumn | integer   | 20 | 网格扫描激光列数 |
+| gridHeight | integer   | 40dp | 网格扫描激光高度，为0dp时，表示动态铺满 |
 | cornerRectWidth | dimension | 4dp | 扫描区边角的宽 |
 | cornerRectHeight | dimension | 16dp | 扫描区边角的高 |
 | scannerLineMoveDistance | dimension | 2dp | 扫描线每次移动距离 |
 | scannerLineHeight | dimension | 5dp | 扫描线高度 |
 | frameLineWidth | dimension | 1dp | 边框线宽度 |
-| scannerAnimationDelay | integer | 20 | 扫描动画延迟间隔时间，单位：毫秒 |
-| frameRatio | float | 0.625f | 扫码框与屏幕占比 |
+| scannerAnimationDelay | integer   | 20 | 扫描动画延迟间隔时间，单位：毫秒 |
+| frameRatio | float     | 0.625f | 扫码框与屏幕占比 |
 | framePaddingLeft | dimension | 0 | 扫码框左边的内间距 |
 | framePaddingTop | dimension | 0 | 扫码框上边的内间距 |
 | framePaddingRight | dimension | 0 | 扫码框右边的内间距 |
 | framePaddingBottom | dimension | 0 | 扫码框下边的内间距 |
-| frameGravity | enum | center | 扫码框对齐方式 |
+| frameGravity | enum      | center | 扫码框对齐方式 |
+| pointColor | color     | <font color=#1FB3E2>#FF1FB3E2</font> | 结果点的颜色 |
+| pointStrokeColor | color     | <font color=#FFFFFF>#FFFFFFFF</font> | 结果点描边的颜色 |
+| pointRadius | dimension | 15dp | 结果点的半径 |
+| pointStrokeRatio | float     | 1.2 | 结果点描边半径与结果点半径的比例 |
+| pointDrawable | reference |  | 结果点自定义图片 |
+| showPointAnim | boolean   | true | 是否显示结果点的动画 |
+| laserDrawable | reference | | 扫描激光自定义图片 |
+| viewfinderStyle | enum      | classic | 取景框样式；支持：classic：经典样式（带扫码框那种）、popular：流行样式（不带扫码框） |


 ## 引入
@@ -73,8 +82,8 @@ allprojects {
 2. 在Module的 **build.gradle** 里面添加引入依赖项

 ```gradle
-//AndroidX 版本
-implementation 'com.github.jenly1314:zxing-lite:2.3.0'
+// AndroidX 版本
+implementation 'com.github.jenly1314:zxing-lite:2.3.1'

 ```

@@ -89,81 +98,75 @@ implementation 'com.github.jenly1314:zxing-lite:2.3.0'

 **v1.x** 旧版本 [v1.1.9](https://github.com/jenly1314/ZXingLite/tree/androidx)
 ```gradle
-//AndroidX 版本
+// AndroidX 版本
 implementation 'com.king.zxing:zxing-lite:1.1.9-androidx'

-//Android Support 版本
+// Android Support 版本
 implementation 'com.king.zxing:zxing-lite:1.1.9'
 ```

+## 使用说明

-### 快速实现扫码有以下几种方式：
+### 快速实现扫码识别有以下几种方式：

-> 1、直接使用CaptureActivity或者CaptureFragment。(纯洁的扫码，无任何添加剂)
+> 1、直接使用CaptureActivity或者CaptureFragment。(默认的扫码实现)

 > 2、通过继承CaptureActivity或者CaptureFragment并自定义布局。（适用于大多场景，并无需关心扫码相关逻辑，自定义布局时需覆写getLayoutId方法）实现示例：[CustomCaptureActivity](app/src/main/java/com/king/zxing/app/CustomCaptureActivity.java) 和 [QRCodeActivity](app/src/main/java/com/king/zxing/app/QRCodeActivity.java)

-> 3、在你项目的Activity或者Fragment中实例化一个CameraScan即可。（适用于想在扫码界面写交互逻辑，又因为项目架构或其它原因，无法直接或间接继承CaptureActivity或CaptureFragment时使用）实现示例：[CustomActivity](app/src/main/java/com/king/zxing/app/CustomActivity.java)
+> 3、在你项目的Activity或者Fragment中实例化一个CameraScan即可。（适用于想在扫码界面写交互逻辑，又因为项目架构或其它原因，无法直接或间接继承CaptureActivity或CaptureFragment时使用）实现示例：[CustomFullScanActivity](app/src/main/java/com/king/zxing/app/CustomFullScanActivity.java)

 > 4、继承CameraScan自己实现一个，可参照默认实现类DefaultCameraScan，其它步骤同方式3。（扩展高级用法，谨慎使用）

+### 关于 CameraScan

-## 示例
+**CameraScan** 作为相机扫描的（核心）基类；所有与相机扫描相关的都是基于此类来直接或间接进行控制的。

-布局示例
->  可自定义布局（覆写getLayoutId方法），布局内至少要保证有PreviewView。
+### 关于 CameraConfig

-> PreviewView 用来预览，布局内至少要保证有PreviewView，如果是继承CaptureActivity或CaptureFragment，控件id可覆写getPreviewViewId方法自定义
+主要是相机相关的配置；如：摄像头的前置后置、相机预览相关、图像分析相关等配置。

-> ViewfinderView 用来渲染扫码视图，给用户起到一个视觉效果，本身扫码识别本身没有关系，如果是继承CaptureActivity或CaptureFragment，控件id可复写getViewfinderViewId方法自定义，默认为previewView，返回0表示无需ViewfinderView
+> 你可以直接库中内置实现的相机配置： **CameraConfig** 、**AspectRatioCameraConfig** 和 **ResolutionCameraConfig**。

-> ivFlashlight 用来内置手电筒，如果是继承CaptureActivity或CaptureFragment，控件id可复写getFlashlightId方法自定义，默认为ivFlashlight。返回0表示无需内置手电筒。您也可以自己去定义
+#### 这里简单说下各自的特点：

+* **CameraConfig**：默认的相机配置。
+* **AspectRatioCameraConfig**：根据纵横比配置相机，使输出分析的图像尽可能的接近屏幕的比例
+* **ResolutionCameraConfig**：根据尺寸配置相机的目标图像大小，使输出分析的图像的分辨率尽可能的接近屏幕尺寸

-```Xml
-<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
-    android:layout_width="match_parent"
-    android:layout_height="match_parent">
-    <androidx.camera.view.PreviewView
-        android:id="@+id/previewView"
-        android:layout_width="match_parent"
-        android:layout_height="match_parent"/>
-    <com.king.zxing.ViewfinderView
-        android:id="@+id/viewfinderView"
-        android:layout_width="match_parent"
-        android:layout_height="match_parent"/>
-    <ImageView
-        android:id="@+id/ivFlashlight"
-        android:layout_width="wrap_content"
-        android:layout_height="wrap_content"
-        android:layout_gravity="center"
-        android:src="@drawable/zxl_flashlight_selector"
-        android:layout_marginTop="@dimen/zxl_flashlight_margin_top" />
-</FrameLayout>
-```
+> 你也可以自定义或覆写 **CameraConfig** 中的 **options** 方法，根据需要定制配置。

-或在你的布局中添加
+这里特别温馨提示：默认配置在未配置相机的目标分析图像大小时，会优先使用：横屏：640 * 480 竖屏：480 * 640；

-```Xml
-    <include layout="@layout/zxl_capture"/>
-```
+根据这个图像质量顺便说下默认配置的优缺点：

-代码示例 （二维码/条形码）
-```Java
-    //跳转的默认扫码界面
-    startActivityForResult(new Intent(context,CaptureActivity.class),requestCode);
+* 优点：因为图像质量不高，所以在低配置的设备上使用也能hold住，这样就能尽可能的适应各种设备；
+* 缺点：正是由于图像质量不高，从而可能会对检测识别率略有影响，比如在某些机型上体验欠佳。
+* 结论：在适配、性能与体验之间得有所取舍，找到平衡点。

-    //生成二维码
-    CodeUtils.createQRCode(content,600,logo);
-    //生成条形码
-    CodeUtils.createBarCode(content, BarcodeFormat.CODE_128,800,200);
-    //解析条形码/二维码
-    CodeUtils.parseCode(bitmap);
-    //解析二维码
-    CodeUtils.parseQRCode(bitmap);
-```
+> 当使用默认的 **CameraConfig** 在某些机型上体验欠佳时，你可以尝试使用 **AspectRatioCameraConfig** 或
+**ResolutionCameraConfig** 会有意想不到奇效。
+
+### 关于 **Analyzer**
+
+**Analyzer** 为定义的分析器接口；主要用于分析相机预览的帧数据；通过实现 **Analyzer** 可以自定义分析过程。
+
+### 关于 **CaptureActivity** 和 **CaptureFragment**
+
+**CaptureActivity** 和 **CaptureFragment** 作为扫描预览界面的基类，主要目的是便于快速实现扫码识别。
+
+> 扫描预览界面内部持有 **CameraScan**，并处理了 **CameraScan** 的初始化（如：相机权限、相机预览、生命周期等细节）
+
+## 使用示例
+
+### CameraScan配置示例
+
+**CameraScan** 里面包含部分支持链式调用的方法，即调用返回是 **CameraScan** 本身的一些配置建议在调用 **startCamera()** 方法之前调用。
+
+> 如果是通过继承 **CaptureActivity** 或者 **CaptureFragment** 或其子类实现的相机扫描，可以在
+**initCameraScan()** 方法中获取 **CameraScan** ，然后根据需要修改相关配置。
+
+示例1：

-CameraScan配置示例
 ```java
    //获取CameraScan，扫码相关的配置设置。CameraScan里面包含部分支持链式调用的方法，即调用返回是CameraScan本身的一些配置建议在startCamera之前调用。
    getCameraScan().setPlayBeep(true)//设置是否播放音效，默认为false
@@ -176,16 +179,17 @@ CameraScan配置示例
            .bindFlashlightView(ivFlashlight)//绑定手电筒，绑定后可根据光线传感器，动态显示或隐藏手电筒按钮
            .setOnScanResultCallback(this)//设置扫码结果回调，需要自己处理或者需要连扫时，可设置回调，自己去处理相关逻辑
            .setAnalyzer(new MultiFormatAnalyzer(new DecodeConfig()))//设置分析器,DecodeConfig可以配置一些解码时的配置信息，如果内置的不满足您的需求，你也可以自定义实现，
-            .setAnalyzeImage(true)//设置是否分析图片，默认为true。如果设置为false，相当于关闭了扫码识别功能
-            .startCamera();//启动预览（如果是通过继承CaptureActivity或CaptureFragment实现扫码无需调用这句startCamera）
+            .setAnalyzeImage(true);//设置是否分析图片，默认为true。如果设置为false，相当于关闭了扫码识别功能
+            
+    // 启动预览（如果是通过继承CaptureActivity或CaptureFragment实现的则无需调用startCamera）
+    getCameraScan().startCamera();

-
-    //设置闪光灯（手电筒）是否开启,需在startCamera之后调用才有效
+    // 设置闪光灯（手电筒）是否开启,需在startCamera之后调用才有效
    getCameraScan().enableTorch(torch);

 ```

-CameraScan配置示例（只需识别二维码的配置示例）
+示例2：（只需识别二维码的配置示例）
 ```java
        //初始化解码配置
        DecodeConfig decodeConfig = new DecodeConfig();
@@ -201,7 +205,65 @@ CameraScan配置示例（只需识别二维码的配置示例）
                .setAnalyzer(new MultiFormatAnalyzer(decodeConfig));//设置分析器,如果内置实现的一些分析器不满足您的需求，你也可以自定义去实现
 ```

-通过继承CaptureActivity实现扫二维码完整示例
+### 布局示例
+
+**PreviewView** 用来预览，布局内至少要保证有 **PreviewView**，如果是继承 **CaptureActivity** 或 **CaptureFragment**，控件id可覆写`getPreviewViewId`方法自定义
+
+**ViewfinderView** 用来渲染扫码视图，给用户起到一个视觉效果，本身扫码识别本身没有关系，如果是继承 **CaptureActivity** 或 **CaptureFragment**，控件ID可复写`getViewfinderViewId`方法自定义，默认为 **previewView**，返回0表示无需 **ViewfinderView**
+
+**ivFlashlight** 是布局内置的手电筒，如果是继承 **CaptureActivity** 或 **CaptureFragment**，控件id可复写`getFlashlightId`方法自定义，默认为 **ivFlashlight**。返回0表示无需内置手电筒。您也可以自己去定义
+
+>  可自定义布局（覆写`getLayoutId方法`），布局内至少要保证有 **PreviewView**。
+
+```Xml
+<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent">
+
+    <androidx.camera.view.PreviewView
+        android:id="@+id/previewView"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent" />
+
+    <com.king.zxing.ViewfinderView
+        android:id="@+id/viewfinderView"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent" />
+
+    <ImageView
+        android:id="@+id/ivFlashlight"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:layout_gravity="center"
+        android:layout_marginTop="@dimen/zxl_flashlight_margin_top"
+        android:contentDescription="@null"
+        android:src="@drawable/zxl_flashlight_selector" />
+</FrameLayout>
+```
+
+或在你的布局中添加
+
+```Xml
+    <include layout="@layout/zxl_capture"/>
+```
+
+### 代码示例
+
+**工具类CodeUtils的使用示例（二维码/条形码）**
+```Java
+
+    // 生成二维码
+    CodeUtils.createQRCode(content,600,logo);
+    // 生成条形码
+    CodeUtils.createBarCode(content, BarcodeFormat.CODE_128,800,200);
+    // 解析条形码/二维码
+    CodeUtils.parseCode(bitmap);
+    // 解析二维码
+    CodeUtils.parseQRCode(bitmap);
+```
+
+**通过继承CaptureActivity实现扫二维码完整示例**
+
 ```java
 public class QRCodeActivity extends CaptureActivity {

@@ -259,16 +321,19 @@ public class QRCodeActivity extends CaptureActivity {

 ```

-如果直接使用CaptureActivity需在您项目的AndroidManifest中添加如下配置
+
+### 其他
+
+#### AndroidManifest
+
+如果你直接使用了默认 **CaptureActivity** ，则需在你项目的AndroidManifest中注册 **CaptureActivity**，配置如下
 ```Xml
    <activity
        android:name="com.king.zxing.CaptureActivity"
        android:screenOrientation="portrait"
        android:theme="@style/CaptureTheme"/>
 ```
-
-
-### 其他
+#### JDK版本

 需使用JDK8+编译，在你项目中的build.gradle的android{}中添加配置：

@@ -290,7 +355,7 @@ compileOptions {

 ## 版本说明

-### v2.x 基于CameraX重构震撼发布
+### v2.x 基于CameraX进行了重构

 #### v2.x 相对于 v1.x 的优势

@@ -304,7 +369,7 @@ compileOptions {

 #### v1.x 说明

-[【v1.1.9】](https://github.com/jenly1314/ZXingLite/tree/androidx) 如果您正在使用 **1.x** 版本请点击下面的链接查看分支版本，当前 **2.x** 版本已经基于 **CameraX** 进行重构，不支持升级，请在新项目中使用。
+[【v1.1.9】](https://github.com/jenly1314/ZXingLite/tree/androidx) 如果您正在使用 **1.x** 版本请点击下面的链接查看分支版本，当前 **2.x** 版本已经基于 **CameraX** 进行重构，API变化较大，谨慎升级。

 查看AndroidX版 **1.x** 分支 [请戳此处](https://github.com/jenly1314/ZXingLite/tree/androidx)

@@ -314,6 +379,11 @@ compileOptions {

 ## 版本记录

+#### v2.3.1：2023-3-4
+* 更新CameraX至v1.2.1
+* 更新Gradle至v7.5
+* 优化细节
+
 #### v2.3.0：2022-12-11
 * 更新CameraX至v1.2.0
 * 更新zxing至v3.5.1