@capgo/camera-preview 8.3.6 → 8.3.8-beta.pr356.31.1

package/dist/docs.json

@@ -128,6 +128,52 @@
         ],
         "slug": "capturesample"
       },
+      {
+        "name": "startBarcodeScanner",
+        "signature": "(options?: BarcodeScannerOptions | undefined) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "BarcodeScannerOptions | undefined"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.8.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios, web"
+          }
+        ],
+        "docs": "Starts barcode scanning on the active camera preview.\n\nThe scanner reuses the current camera session and emits `barcodeScanned` events.\nCall `stopBarcodeScanner()` when scanning is no longer needed.\n\nAndroid uses the lightweight Google Play Services ML Kit model. If the model is not installed yet,\nfirst scans may return no result until Google Play Services finishes downloading it.",
+        "complexTypes": [
+          "BarcodeScannerOptions"
+        ],
+        "slug": "startbarcodescanner"
+      },
+      {
+        "name": "stopBarcodeScanner",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.8.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios, web"
+          }
+        ],
+        "docs": "Stops barcode scanning while keeping the camera preview running.",
+        "complexTypes": [],
+        "slug": "stopbarcodescanner"
+      },
       {
         "name": "getSupportedFlashModes",
         "signature": "() => Promise<{ result: CameraPreviewFlashMode[]; }>",
@@ -151,19 +197,19 @@
       },
       {
         "name": "setAspectRatio",
-        "signature": "(options: { aspectRatio: '4:3' | '16:9'; x?: number; y?: number; }) => Promise<{ width: number; height: number; x: number; y: number; }>",
+        "signature": "(options: { aspectRatio: CameraPreviewAspectRatio; x?: number; y?: number; }) => Promise<{ width: number; height: number; x: number; y: number; }>",
         "parameters": [
           {
             "name": "options",
-            "docs": "- The desired aspect ratio and optional position.\n- aspectRatio: The desired aspect ratio ('4:3' or '16:9')\n- x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.\n- y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.",
-            "type": "{ aspectRatio: '4:3' | '16:9'; x?: number | undefined; y?: number | undefined; }"
+            "docs": "- The desired aspect ratio and optional position.\n- aspectRatio: The desired aspect ratio ('4:3', '16:9', or 'fill')\n- x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.\n- y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.",
+            "type": "{ aspectRatio: CameraPreviewAspectRatio; x?: number | undefined; y?: number | undefined; }"
           }
         ],
         "returns": "Promise<{ width: number; height: number; x: number; y: number; }>",
         "tags": [
           {
             "name": "param",
-            "text": "options - The desired aspect ratio and optional position.\n- aspectRatio: The desired aspect ratio ('4:3' or '16:9')\n- x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.\n- y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically."
+            "text": "options - The desired aspect ratio and optional position.\n- aspectRatio: The desired aspect ratio ('4:3', '16:9', or 'fill')\n- x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.\n- y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically."
           },
           {
             "name": "returns",
@@ -179,14 +225,16 @@
           }
         ],
         "docs": "Set the aspect ratio of the camera preview.",
-        "complexTypes": [],
+        "complexTypes": [
+          "CameraPreviewAspectRatio"
+        ],
         "slug": "setaspectratio"
       },
       {
         "name": "getAspectRatio",
-        "signature": "() => Promise<{ aspectRatio: '4:3' | '16:9'; }>",
+        "signature": "() => Promise<{ aspectRatio: CameraPreviewAspectRatio; }>",
         "parameters": [],
-        "returns": "Promise<{ aspectRatio: '4:3' | '16:9'; }>",
+        "returns": "Promise<{ aspectRatio: CameraPreviewAspectRatio; }>",
         "tags": [
           {
             "name": "returns",
@@ -202,7 +250,9 @@
           }
         ],
         "docs": "Gets the current aspect ratio of the camera preview.",
-        "complexTypes": [],
+        "complexTypes": [
+          "CameraPreviewAspectRatio"
+        ],
         "slug": "getaspectratio"
       },
       {
@@ -895,6 +945,72 @@
         ],
         "slug": "addlistenerorientationchange-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'barcodeScanned', listenerFunc: (data: BarcodeScannedEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'barcodeScanned'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(data: BarcodeScannedEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.8.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios, web"
+          }
+        ],
+        "docs": "Adds a listener for barcode scan results.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "BarcodeScannedEvent"
+        ],
+        "slug": "addlistenerbarcodescanned-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'barcodeScanError', listenerFunc: (data: BarcodeScanErrorEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'barcodeScanError'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(data: BarcodeScanErrorEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.8.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, web"
+          }
+        ],
+        "docs": "Adds a listener for non-fatal barcode scanner errors.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "BarcodeScanErrorEvent"
+        ],
+        "slug": "addlistenerbarcodescanerror-"
+      },
       {
         "name": "deleteFile",
         "signature": "(options: { path: string; }) => Promise<{ success: boolean; }>",
@@ -1177,8 +1293,10 @@
             }
           ],
           "docs": "The aspect ratio of the camera preview, '4:3' or '16:9' or 'fill'.\nCannot be set if width or height is provided, otherwise the call will be rejected.\nUse setPreviewSize to adjust size after starting.",
-          "complexTypes": [],
-          "type": "'4:3' | '16:9' | undefined"
+          "complexTypes": [
+            "CameraPreviewAspectRatio"
+          ],
+          "type": "CameraPreviewAspectRatio"
         },
         {
           "name": "aspectMode",
@@ -1218,7 +1336,7 @@
           "name": "includeSafeAreaInsets",
           "tags": [
             {
-              "text": "ios",
+              "text": "android, ios",
               "name": "platform"
             },
             {
@@ -1505,6 +1623,54 @@
           "docs": "Sets the quality of video for recording.\nOptions: 'low', 'medium', 'high'",
           "complexTypes": [],
           "type": "'low' | 'medium' | 'high' | undefined"
+        },
+        {
+          "name": "barcodeScanner",
+          "tags": [
+            {
+              "text": "android, ios, web",
+              "name": "platform"
+            },
+            {
+              "text": "8.8.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Starts barcode scanning together with the camera preview.\nSet to `true` or pass options to scan all supported formats.\nOmit this option to keep barcode scanning disabled at startup.",
+          "complexTypes": [
+            "BarcodeScannerOptions"
+          ],
+          "type": "boolean | BarcodeScannerOptions | undefined"
+        }
+      ]
+    },
+    {
+      "name": "BarcodeScannerOptions",
+      "slug": "barcodescanneroptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "formats",
+          "tags": [],
+          "docs": "Restricts detection to the given formats. Leaving this empty scans all supported formats.\nRestricting formats can improve scanning speed.",
+          "complexTypes": [
+            "BarcodeScannerFormat"
+          ],
+          "type": "BarcodeScannerFormat[] | undefined"
+        },
+        {
+          "name": "detectionInterval",
+          "tags": [
+            {
+              "text": "500",
+              "name": "default"
+            }
+          ],
+          "docs": "Minimum delay between native scan attempts in milliseconds.\nLower values scan more often but use more CPU.",
+          "complexTypes": [],
+          "type": "number | undefined"
         }
       ]
     },
@@ -1987,6 +2153,79 @@
         }
       ]
     },
+    {
+      "name": "BarcodeScannedEvent",
+      "slug": "barcodescannedevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "barcodes",
+          "tags": [],
+          "docs": "Barcodes decoded from the current frame.",
+          "complexTypes": [
+            "BarcodeScanResult"
+          ],
+          "type": "BarcodeScanResult[]"
+        }
+      ]
+    },
+    {
+      "name": "BarcodeScanResult",
+      "slug": "barcodescanresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "value",
+          "tags": [],
+          "docs": "Decoded barcode value.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "format",
+          "tags": [],
+          "docs": "Barcode format.",
+          "complexTypes": [
+            "BarcodeFormat"
+          ],
+          "type": "BarcodeFormat"
+        },
+        {
+          "name": "displayValue",
+          "tags": [],
+          "docs": "Human-readable value when the platform exposes one.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "rawBytes",
+          "tags": [],
+          "docs": "Base64-encoded raw bytes when the platform exposes them.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "BarcodeScanErrorEvent",
+      "slug": "barcodescanerrorevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "message",
+          "tags": [],
+          "docs": "Native scanner error message.",
+          "complexTypes": [],
+          "type": "string"
+        }
+      ]
+    },
     {
       "name": "SafeAreaInsets",
       "slug": "safeareainsets",
@@ -2062,6 +2301,25 @@
     }
   ],
   "typeAliases": [
+    {
+      "name": "CameraPreviewAspectRatio",
+      "slug": "camerapreviewaspectratio",
+      "docs": "",
+      "types": [
+        {
+          "text": "'4:3'",
+          "complexTypes": []
+        },
+        {
+          "text": "'16:9'",
+          "complexTypes": []
+        },
+        {
+          "text": "'fill'",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "GridMode",
       "slug": "gridmode",
@@ -2115,6 +2373,65 @@
         }
       ]
     },
+    {
+      "name": "BarcodeScannerFormat",
+      "slug": "barcodescannerformat",
+      "docs": "",
+      "types": [
+        {
+          "text": "'aztec'",
+          "complexTypes": []
+        },
+        {
+          "text": "'codabar'",
+          "complexTypes": []
+        },
+        {
+          "text": "'code_39'",
+          "complexTypes": []
+        },
+        {
+          "text": "'code_93'",
+          "complexTypes": []
+        },
+        {
+          "text": "'code_128'",
+          "complexTypes": []
+        },
+        {
+          "text": "'data_matrix'",
+          "complexTypes": []
+        },
+        {
+          "text": "'ean_8'",
+          "complexTypes": []
+        },
+        {
+          "text": "'ean_13'",
+          "complexTypes": []
+        },
+        {
+          "text": "'itf'",
+          "complexTypes": []
+        },
+        {
+          "text": "'pdf417'",
+          "complexTypes": []
+        },
+        {
+          "text": "'qr_code'",
+          "complexTypes": []
+        },
+        {
+          "text": "'upc_a'",
+          "complexTypes": []
+        },
+        {
+          "text": "'upc_e'",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "PictureFormat",
       "slug": "pictureformat",
@@ -2231,6 +2548,23 @@
         }
       ]
     },
+    {
+      "name": "BarcodeFormat",
+      "slug": "barcodeformat",
+      "docs": "",
+      "types": [
+        {
+          "text": "BarcodeScannerFormat",
+          "complexTypes": [
+            "BarcodeScannerFormat"
+          ]
+        },
+        {
+          "text": "'unknown'",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "ExposureMode",
       "slug": "exposuremode",

package/dist/esm/definitions.d.ts

@@ -3,6 +3,40 @@ export type CameraPosition = 'rear' | 'front';
 export type FlashMode = CameraPreviewFlashMode;
 export type GridMode = 'none' | '3x3' | '4x4';
 export type CameraPositioning = 'center' | 'top' | 'bottom';
+export type CameraPreviewAspectRatio = '4:3' | '16:9' | 'fill';
+export type BarcodeScannerFormat = 'aztec' | 'codabar' | 'code_39' | 'code_93' | 'code_128' | 'data_matrix' | 'ean_8' | 'ean_13' | 'itf' | 'pdf417' | 'qr_code' | 'upc_a' | 'upc_e';
+export type BarcodeFormat = BarcodeScannerFormat | 'unknown';
+export interface BarcodeScannerOptions {
+    /**
+     * Restricts detection to the given formats. Leaving this empty scans all supported formats.
+     * Restricting formats can improve scanning speed.
+     */
+    formats?: BarcodeScannerFormat[];
+    /**
+     * Minimum delay between native scan attempts in milliseconds.
+     * Lower values scan more often but use more CPU.
+     * @default 500
+     */
+    detectionInterval?: number;
+}
+export interface BarcodeScanResult {
+    /** Decoded barcode value. */
+    value: string;
+    /** Barcode format. */
+    format: BarcodeFormat;
+    /** Human-readable value when the platform exposes one. */
+    displayValue?: string;
+    /** Base64-encoded raw bytes when the platform exposes them. */
+    rawBytes?: string;
+}
+export interface BarcodeScannedEvent {
+    /** Barcodes decoded from the current frame. */
+    barcodes: BarcodeScanResult[];
+}
+export interface BarcodeScanErrorEvent {
+    /** Native scanner error message. */
+    message: string;
+}
 export interface CameraPermissionStatus {
     camera: PermissionState;
     microphone?: PermissionState;
@@ -114,7 +148,7 @@ export interface CameraPreviewOptions {
      *
      * @since 2.0.0
      */
-    aspectRatio?: '4:3' | '16:9';
+    aspectRatio?: CameraPreviewAspectRatio;
     /**
      * Controls how the camera preview fills the available space.
      * - 'contain': Fits the entire preview within the space, may show letterboxing (default).
@@ -131,7 +165,7 @@ export interface CameraPreviewOptions {
     gridMode?: GridMode;
     /**
      * Adjusts the y-position to account for safe areas (e.g., notches).
-     * @platform ios
+     * @platform android, ios
      * @default false
      */
     includeSafeAreaInsets?: boolean;
@@ -242,6 +276,14 @@ export interface CameraPreviewOptions {
      * @default "high"
      */
     videoQuality?: 'low' | 'medium' | 'high';
+    /**
+     * Starts barcode scanning together with the camera preview.
+     * Set to `true` or pass options to scan all supported formats.
+     * Omit this option to keep barcode scanning disabled at startup.
+     * @platform android, ios, web
+     * @since 8.8.0
+     */
+    barcodeScanner?: boolean | BarcodeScannerOptions;
 }
 /**
  * Defines the options for capturing a picture.
@@ -431,6 +473,26 @@ export interface CameraPreviewPlugin {
     captureSample(options: CameraSampleOptions): Promise<{
         value: string;
     }>;
+    /**
+     * Starts barcode scanning on the active camera preview.
+     *
+     * The scanner reuses the current camera session and emits `barcodeScanned` events.
+     * Call `stopBarcodeScanner()` when scanning is no longer needed.
+     *
+     * Android uses the lightweight Google Play Services ML Kit model. If the model is not installed yet,
+     * first scans may return no result until Google Play Services finishes downloading it.
+     *
+     * @since 8.8.0
+     * @platform android, ios, web
+     */
+    startBarcodeScanner(options?: BarcodeScannerOptions): Promise<void>;
+    /**
+     * Stops barcode scanning while keeping the camera preview running.
+     *
+     * @since 8.8.0
+     * @platform android, ios, web
+     */
+    stopBarcodeScanner(): Promise<void>;
     /**
      * Gets the flash modes supported by the active camera.
      *
@@ -443,8 +505,8 @@ export interface CameraPreviewPlugin {
     /**
      * Set the aspect ratio of the camera preview.
      *
-     * @param {{ aspectRatio: '4:3' | '16:9'; x?: number; y?: number }} options - The desired aspect ratio and optional position.
-     *   - aspectRatio: The desired aspect ratio ('4:3' or '16:9')
+     * @param {{ aspectRatio: CameraPreviewAspectRatio; x?: number; y?: number }} options - The desired aspect ratio and optional position.
+     *   - aspectRatio: The desired aspect ratio ('4:3', '16:9', or 'fill')
      *   - x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.
      *   - y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.
      * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.
@@ -452,7 +514,7 @@ export interface CameraPreviewPlugin {
      * @platform android, ios
      */
     setAspectRatio(options: {
-        aspectRatio: '4:3' | '16:9';
+        aspectRatio: CameraPreviewAspectRatio;
         x?: number;
         y?: number;
     }): Promise<{
@@ -464,12 +526,12 @@ export interface CameraPreviewPlugin {
     /**
      * Gets the current aspect ratio of the camera preview.
      *
-     * @returns {Promise<{ aspectRatio: '4:3' | '16:9' }>} A promise that resolves with the current aspect ratio.
+     * @returns {Promise<{ aspectRatio: CameraPreviewAspectRatio }>} A promise that resolves with the current aspect ratio.
      * @since 7.5.0
      * @platform android, ios
      */
     getAspectRatio(): Promise<{
-        aspectRatio: '4:3' | '16:9';
+        aspectRatio: CameraPreviewAspectRatio;
     }>;
     /**
      * Sets the grid mode of the camera preview overlay.
@@ -736,6 +798,20 @@ export interface CameraPreviewPlugin {
     addListener(eventName: 'orientationChange', listenerFunc: (data: {
         orientation: DeviceOrientation;
     }) => void): Promise<PluginListenerHandle>;
+    /**
+     * Adds a listener for barcode scan results.
+     *
+     * @since 8.8.0
+     * @platform android, ios, web
+     */
+    addListener(eventName: 'barcodeScanned', listenerFunc: (data: BarcodeScannedEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Adds a listener for non-fatal barcode scanner errors.
+     *
+     * @since 8.8.0
+     * @platform android, web
+     */
+    addListener(eventName: 'barcodeScanError', listenerFunc: (data: BarcodeScanErrorEvent) => void): Promise<PluginListenerHandle>;
     /**
      * Deletes a file at the given absolute path on the device.
      * Use this to quickly clean up temporary images created with `storeToFile`.