|
| 1 | +# ai_barcode_scanner |
| 2 | + |
| 3 | +[](https://pub.dev/packages/ai_barcode_scanner) |
| 4 | + |
| 5 | +A universal barcode and QR code scanner for Flutter based on MLKit. Uses CameraX on Android, AVFoundation on iOS and Apple Vision & AVFoundation on macOS. |
| 6 | + |
| 7 | +## Platform Support |
| 8 | + |
| 9 | +| Android | iOS | MacOS | Web | Linux | Windows | |
| 10 | +| :-----: | :-: | :---: | :-: | :---: | :-----: | |
| 11 | +| ✔️ | ✔️ | ✔️ | ✔️ | | | |
| 12 | + |
| 13 | +### Android |
| 14 | +SDK 21 and newer. Reason: CameraX requires at least SDK 21. |
| 15 | +Also, make sure you upgrade kotlin to the latest version in your project. |
| 16 | + |
| 17 | +This packages uses the **bundled version** of MLKit Barcode-scanning for Android. This version is more accurate and immediately available to devices. However, this version will increas the size of the app with approximately 3 to 10 MB. The alternative for this is to use the **unbundled version** of MLKit Barcode-scanning for Android. This version is older than the bundled version however this only increases the size by around 600KB. |
| 18 | + |
| 19 | +To use this version you must alter the ai_barcode_scanner gradle file to replace `com.google.mlkit:barcode-scanning:17.0.2` with `com.google.android.gms:play-services-mlkit-barcode-scanning:18.0.0`. Keep in mind that if you alter the gradle files directly in your project it can be overriden when you update your pubspec.yaml. I am still searching for a way to properly replace the module in gradle but have yet to find one. |
| 20 | + |
| 21 | +[You can read more about the difference between the two versions here.](https://developers.google.com/ml-kit/vision/barcode-scanning/android) |
| 22 | + |
| 23 | +### iOS |
| 24 | +iOS 11 and newer. Reason: MLKit for iOS requires at least iOS 10 and a [64bit device](https://developers.google.com/ml-kit/migration/ios). |
| 25 | + |
| 26 | +**Add the following keys to your Info.plist file, located in <project root>/ios/Runner/Info.plist:** |
| 27 | + |
| 28 | +NSCameraUsageDescription - describe why your app needs access to the camera. This is called Privacy - Camera Usage Description in the visual editor. |
| 29 | + |
| 30 | +**If you want to use the local gallery feature from [image_picker](https://pub.dev/packages/image_picker)** |
| 31 | + |
| 32 | +NSPhotoLibraryUsageDescription - describe why your app needs permission for the photo library. This is called Privacy - Photo Library Usage Description in the visual editor. |
| 33 | + |
| 34 | +### macOS |
| 35 | +macOS 10.13 or newer. Reason: Apple Vision library. |
| 36 | + |
| 37 | +### Web |
| 38 | +Add this to `web/index.html`: |
| 39 | + |
| 40 | +```html |
| 41 | +< script src= "https://cdn.jsdelivr.net/npm/[email protected]/dist/jsQR.min.js"></ script> |
| 42 | +``` |
| 43 | + |
| 44 | +Web only supports QR codes for now. |
| 45 | +Do you have experience with Flutter Web development? [Help me with migrating from jsQR to qr-scanner for full barcode support!](https://github.com/juliansteenbakker/ai_barcode_scanner/issues/54) |
| 46 | + |
| 47 | +## Usage |
| 48 | + |
| 49 | +Import `package:ai_barcode_scanner/ai_barcode_scanner.dart`, and use the widget with or without the controller. |
| 50 | + |
| 51 | +If you don't provide a controller, you can't control functions like the torch(flash) or switching camera. |
| 52 | + |
| 53 | +If you don't set allowDuplicates to false, you can get multiple scans in a very short time, causing things like pop() to fire lots of times. |
| 54 | + |
| 55 | +```dart |
| 56 | +import 'package:ai_barcode_scanner/ai_barcode_scanner.dart'; |
| 57 | +
|
| 58 | +/// Simple example of using the barcode scanner. |
| 59 | +BarcodeScanner( |
| 60 | + onScan: (String value) { |
| 61 | + debugPrint(value); |
| 62 | + }, |
| 63 | + ), |
| 64 | +
|
| 65 | +/// Example of using the barcode scanner with a controller. |
| 66 | +BarcodeScanner( |
| 67 | + controller: BarcodeScannerController(), |
| 68 | + onScan: (String value) { |
| 69 | + debugPrint(value); |
| 70 | + }, |
| 71 | + ), |
| 72 | +
|
| 73 | +/// Example of using the barcode scanner with validation. |
| 74 | +/// Validator works on the raw string, not the decoded value. |
| 75 | +/// If you want to validate the scanner, use the [validateText] and [validateType] parameters. |
| 76 | +BarcodeScanner( |
| 77 | + validateText: 'https://', |
| 78 | + validateType: ValidateType.startsWith, |
| 79 | + controller: BarcodeScannerController(), |
| 80 | + onScan: (String value) { |
| 81 | + debugPrint(value); |
| 82 | + }, |
| 83 | + ), |
| 84 | +``` |
| 85 | + |
| 86 | +### Parameters of the widget |
| 87 | + |
| 88 | +```dart |
| 89 | + /// Function that gets Called when barcode is scanned successfully |
| 90 | + final void Function(String) onScan; |
| 91 | +
|
| 92 | + /// Function that gets called when a Barcode is detected. |
| 93 | + /// |
| 94 | + /// [barcode] The barcode object with all information about the scanned code. |
| 95 | + /// [args] Information about the state of the MobileScanner widget |
| 96 | + final Function(Barcode barcode, MobileScannerArguments? args)? onDetect; |
| 97 | +
|
| 98 | + /// Validate barcode text with [ValidateType] |
| 99 | + /// [validateText] and [validateType] must be set together. |
| 100 | + final String? validateText; |
| 101 | +
|
| 102 | + /// Validate type [ValidateType] |
| 103 | + /// Validator working with single string value only. |
| 104 | + final ValidateType? validateType; |
| 105 | +
|
| 106 | + /// Set to false if you don't want duplicate barcode to be detected |
| 107 | + final bool allowDuplicates; |
| 108 | +
|
| 109 | + /// Fit to screen |
| 110 | + final BoxFit fit; |
| 111 | +
|
| 112 | + /// Barcode controller (optional) |
| 113 | + final MobileScannerController? controller; |
| 114 | +
|
| 115 | + /// Show overlay or not (default: true) |
| 116 | + final bool showOverlay; |
| 117 | +
|
| 118 | + /// Overlay border color (default: white) |
| 119 | + final Color borderColor; |
| 120 | +
|
| 121 | + /// Overlay border width (default: 10) |
| 122 | + final double borderWidth; |
| 123 | +
|
| 124 | + /// Overlay color |
| 125 | + final Color overlayColor; |
| 126 | +
|
| 127 | + /// Overlay border radius (default: 10) |
| 128 | + final double borderRadius; |
| 129 | +
|
| 130 | + /// Overlay border length (default: 30) |
| 131 | + final double borderLength; |
| 132 | +
|
| 133 | + /// Overlay cut out width (optional) |
| 134 | + final double? cutOutWidth; |
| 135 | +
|
| 136 | + /// Overlay cut out height (optional) |
| 137 | + final double? cutOutHeight; |
| 138 | +
|
| 139 | + /// Overlay cut out offset (default: 0) |
| 140 | + final double cutOutBottomOffset; |
| 141 | +
|
| 142 | + /// Overlay cut out size (default: 300) |
| 143 | + final double cutOutSize; |
| 144 | +
|
| 145 | + /// Show hint or not (default: true) |
| 146 | + final bool showHint; |
| 147 | +
|
| 148 | + /// Hint text (default: 'Scan QR Code') |
| 149 | + final String hintText; |
| 150 | +
|
| 151 | + /// Hint margin |
| 152 | + final EdgeInsetsGeometry hintMargin; |
| 153 | +
|
| 154 | + /// Hint padding |
| 155 | + final EdgeInsetsGeometry hintPadding; |
| 156 | +
|
| 157 | + /// Hint background color (optional) |
| 158 | + final Color? hintBackgroundColor; |
| 159 | +
|
| 160 | + /// Hint text style |
| 161 | + final TextStyle hintTextStyle; |
| 162 | +
|
| 163 | + /// Show error or not (default: true) |
| 164 | + final bool showError; |
| 165 | +
|
| 166 | + /// Error color (default: red) |
| 167 | + final Color errorColor; |
| 168 | +
|
| 169 | + /// Error text (default: 'Invalid BarCode') |
| 170 | + final String errorText; |
| 171 | +
|
| 172 | + /// Show success or not (default: true) |
| 173 | + final bool showSuccess; |
| 174 | +
|
| 175 | + /// Success color (default: green) |
| 176 | + final Color successColor; |
| 177 | +
|
| 178 | + /// Success text (default: 'BarCode Found') |
| 179 | + final String successText; |
| 180 | +
|
| 181 | + /// Can auto back to previous page when barcode is successfully scanned (default: true) |
| 182 | + final bool canPop; |
| 183 | +``` |
| 184 | + |
| 185 | +## Thanks to |
| 186 | +This plugin is based on the [mobile_scanner](https://pub.dev/packages/mobile_scanner) plugin by [steenbakker.dev](https://pub.dev/publishers/steenbakker.dev/packages). |
| 187 | + |
| 188 | +I recommend you to read the [mobile_scanner](https://pub.dev/packages/mobile_scanner) plugin's documentation. |
0 commit comments