plugin_scanner_qr 0.3.0

Plugin Flutter para leitura de QR Code no Android usando ML Kit e CameraX. Oferece leitura única em tela cheia e leitura contínua com preview embutido na árvore de widgets (PlatformView), com debounce [...]

0.3.0

Calibração de câmera no preview embutido

Pensada para kiosk/totem (ex.: relógio de ponto) em ambiente de muita luz e aparelhos com autofoco lento (ex.: Galaxy A03s). Tudo é opcional e com degradação segura — quem não configurar nada mantém o comportamento anterior, com uma única exceção deliberada: a resolução da análise.

• Resolução da análise configurável — novo padrão 1280x720. O default do CameraX (640x480) entrega poucos pixels por módulo do QR, e qualquer desfoque leve inviabiliza a leitura. QrScannerController(analysisResolution: ...) aceita QrAnalysisResolution.sd (640x480, comportamento antigo), .hd (novo padrão), .fullHd ou um valor customizado. O CameraX negocia a resolução suportada mais próxima; a negociada aparece em getCameraCapabilities().
• Modos de foco (QrFocusMode) via focusMode: no construtor ou setFocusMode() em runtime:
  • continuous — autofoco contínuo do CameraX (padrão, igual a antes);
  • periodic — dispara um foco no centro do frame a cada intervalo (autoFocusInterval, padrão 3 s) — para aparelhos cujo AF por contraste "caça" e trava num plano errado;
  • fixed — desliga o AF e trava a lente numa distância fixa em dioptrias (focusDistance; 25 cm ≈ 4.0) via Camera2 Interop — ideal para totem, onde a distância de leitura é sempre a mesma. Se o aparelho não expõe foco manual, cai silenciosamente em continuous e setFocusMode() retorna false.
• Compensação de exposição — setExposureCompensation(index), com clamp automático ao range do aparelho. Índices negativos escurecem a cena (útil contra reflexo de QR em tela de celular).
• Zoom linear — setLinearZoom(0.0–1.0); um valor pequeno faz o QR ocupar mais pixels na distância típica do totem.
• getCameraCapabilities() — snapshot do que o hardware suporta: foco manual (e range em dioptrias), calibração da escala de foco, range/passo da exposição, range de zoom, flash e resolução de análise negociada. Feito para validar em campo o que o aparelho do totem aceita.
• Example — novo painel "Calibração da câmera" no preview embutido: capabilities ao vivo, seletor de modo de foco, sliders de distância/exposição/ zoom e seletor de resolução SD/HD/FullHD (recria o preview, preservando câmera e lanterna).

Sem breaking changes.

0.2.0

Preview embutido (PlatformView)

• QrScannerPreview + QrScannerController — a leitura contínua agora usa uma PlatformView embutida na árvore de widgets, em vez de uma Activity de tela cheia. Isso permite desenhar UI Flutter por cima do preview: overlay de status, botões, drawer e showDialog.
• Renderização com PreviewView.ImplementationMode.COMPATIBLE (TextureView) e Texture Layer Hybrid Composition (initSurfaceAndroidView). hybridComposition: true disponível como alternativa.
• Canais por instância (preview_$viewId), eliminando o EventSink estático. Eventos agora são Map com discriminador type (barcode/cameraOpened/error), em vez de String crua.
• PreviewLifecycleOwner — cada preview tem seu próprio LifecycleRegistry, combinando intenção do Dart + foreground da Activity + view anexada. pauseScanning/resumeScanning não recriam mais as use cases do CameraX.

Correções

• Permissão de câmera não mente mais. requestCameraPermission() respondia true antes de o usuário decidir, e a Activity pedia permissão sem tratar onRequestPermissionsResult — resultado: tela preta permanente na primeira execução. Agora há RequestPermissionsResultListener e o Future só completa após a resposta real.
• Novo hasCameraPermission() — consulta pura. O plugin não solicita permissão no caminho do preview, evitando Can request only one set of permissions at a time quando o app usa permission_handler.
• Vazamentos corrigidos: cliente do ML Kit era criado a cada switchCamera() e nunca fechado; cameraExecutor só era desligado no modo contínuo (sair pelo botão voltar vazava); scanEventSink estático e singleton MlKitScannerActivity.current removidos; listeners de Activity agora são desregistrados no detach.
• unbind(preview, analysis) em vez de unbindAll() — ProcessCameraProvider é singleton de processo e unbindAll() derrubaria outros consumidores de câmera.
• uses-feature android:required passou a false — como true, era mesclado no app consumidor e o removia da Play Store para aparelhos sem câmera.
• Removido o atributo package do manifest da lib (obsoleto no AGP 8) e o bloco dependencies {} que estava aninhado dentro de android {}.
• Removidas ~200 linhas de pipeline CameraX morto (startCamera, bindCameraUseCases, stopScanner, QRCodeAnalyzer) que nunca eram alcançadas.
• Corrigido o teste de widget do example, que procurava um texto inexistente.

Breaking changes

• startContinuousScan responde UNSUPPORTED. Use QrScannerPreview com QrScannerController. ContinuousQrScanner e os métodos globais do modo contínuo seguem disponíveis, marcados @Deprecated; os globais delegam para a última QrScannerPreview criada.
• requestCameraPermission() marcado @Deprecated — prefira gerenciar a permissão no app.
• CameraX 1.3.1 → 1.3.4. Requer ndkVersion = "27.0.12077973" no app consumidor.

0.1.0

• Leitura contínua oficializada — API pública completa com startContinuousScan, pauseScanning, resumeScanning e stopContinuousScan.
• Novos modelos Dart — ContinuousScanOptions (debounce, cooldown, câmera, orientação, torch) e QrScanResult (valor + timestamp).
• ContinuousQrScanner — helper de alto nível que encapsula permissão, abertura da câmera e ciclo de vida do stream.
• Debounce nativo — o Android suprime reemissões do mesmo QR dentro do intervalo duplicateDebounce (padrão 1500 ms), sem round-trip para o Flutter.
• Cooldown nativo — após cada leitura, o scanner pausa automaticamente pelo tempo configurado em cooldown (padrão Duration.zero = sem pausa).
• Toasts removidos por padrão — feedback visual de "Leitura pausada/retomada" agora só é exibido quando showNativeFeedback: true.
• PluginScannerQr refatorada como fachada fina; toda lógica de canal delegada à PluginScannerQrPlatform.
• onBarcodeScanned — stream oficial tipado como Stream<QrScanResult> na platform interface e no method channel.
• Example atualizado para usar ContinuousQrScanner com slider de cooldown configurável.

0.0.1

• Versão inicial com leitura única (scanQRCode, scanQRCodeWithOptions).