Architektura CameraBarcodeReaderView

Kontrolka CameraBarcodeReaderView jest centralnym komponentem ZXing.Net.MAUI. Została zadeklarowana w XAML i skonfigurowana poprzez wiązanie BarcodeReaderOptions. Każda strona, która jej używa, musi implementować OnAppearing i nadpisania OnDisappearing do zarządzania stanem IsDetecting:

<ContentPage xmlns:zxing="clr-namespace:ZXing.Net.Maui.Controls;assembly=ZXing.Net.MAUI.Controls">
    <zxing:CameraBarcodeReaderView
        x:Name="CameraView"
        Options="{Binding ReaderOptions}"
        BarcodesDetected="OnBarcodesDetected" />
</ContentPage>

<ContentPage xmlns:zxing="clr-namespace:ZXing.Net.Maui.Controls;assembly=ZXing.Net.MAUI.Controls">
    <zxing:CameraBarcodeReaderView
        x:Name="CameraView"
        Options="{Binding ReaderOptions}"
        BarcodesDetected="OnBarcodesDetected" />
</ContentPage>

// Toggling IsDetecting in lifecycle overrides is the documented pattern
protected override void OnDisappearing()
{
    base.OnDisappearing();
    if (CameraView != null)
        CameraView.IsDetecting = false;  // Nie IDisposable on the control
}

protected override void OnAppearing()
{
    base.OnAppearing();
    if (CameraView != null)
        CameraView.IsDetecting = true;
}

// Toggling IsDetecting in lifecycle overrides is the documented pattern
protected override void OnDisappearing()
{
    base.OnDisappearing();
    if (CameraView != null)
        CameraView.IsDetecting = false;  // Nie IDisposable on the control
}

protected override void OnAppearing()
{
    base.OnAppearing();
    if (CameraView != null)
        CameraView.IsDetecting = true;
}

' Toggling IsDetecting in lifecycle overrides is the documented pattern
Protected Overrides Sub OnDisappearing()
    MyBase.OnDisappearing()
    If CameraView IsNot Nothing Then
        CameraView.IsDetecting = False ' Nie IDisposable on the control
    End If
End Sub

Protected Overrides Sub OnAppearing()
    MyBase.OnAppearing()
    If CameraView IsNot Nothing Then
        CameraView.IsDetecting = True
    End If
End Sub

Każda strona skanowania w aplikacji ZXing.Net.MAUI zawiera ten standardowy fragment dotyczący cyklu życia. Brak IDisposable oznacza, że stan aparatu musi być zarządzany ręcznie przez flagę IsDetecting zamiast standardowego wzorca Dispose.

Szczegółowe porównanie funkcji

Podejście ZXing.Net.MAUI

ZXing.Net.MAUI jest zaprojektowany wokół platformowych API kamery dla iOS i Android.Windows MAUIobsługuje tylko generowanie kodów kreskowych — skanowanie kamery nie zostało zaimplementowane i nie jest na publicznej mapie drogowej. Odzwierciedla to architektoniczny wybór, aby zbudować bibliotekę wokół kontroli celownika kamery na żywo, których implementacje platformowe zostały napisane tylko dla mobilnych systemów operacyjnych.

Projekt MAUI celujący w net8.0-windows10.0.19041.0 nie uzyska funkcjonalności skanowania kodu kreskowego z ZXing.Net.MAUI. Mac Catalyst jest obecny na liście docelowych frameworków, ale skanowanie na tym docelowym nie jest oficjalnie udokumentowane. Zespoły, które rozpoczynają projekt z celami tylko mobilnymi i później dodają wymaganie dla Windows lub macOS, odkryją, że ZXing.Net.MAUI nie może pokryć skanowania na tych docelowych. Wsparcie dla iOS samo w sobie niesie zastrzeżenie: GitHub issue #260 dokumentuje, że urządzenia iPhone 15 Pro i Pro Max są dotknięte problemem z autofokusem, który uniemożliwia niezawodne wykrywanie.

Podejście IronBarcode

IronBarcode obsługuje wszystkie docelowe frameworki MAUI — iOS, Android, Windows i macOS — z tego samego pakietu i przy użyciu tego samego wzorca kodu. Podejście MediaPicker + BarcodeReader.Read() w naturalny sposób mapuje się na każdą platformę: na urządzeniach mobilnych MediaPicker.CapturePhotoAsync() wywołuje aparata w urządzeniu; W systemie Windows odpowiada to okienku wyboru plików, co jest właściwym zachowaniem w środowisku desktopowym. Nie jest wymagany żaden kod specyficzny dla platformy, kompilacja warunkowa ani rejestracja usług platformy.

Wzór kodu BARCODE MAUI na komputery stacjonarne z systemem Windows i macOS jest obsługiwany przez ten sam pakiet, który obsługuje skanowanie mobilne. To samo wywołanie BarcodeReader.Read(), które działa na urządzeniu z Androidem, działa również w punkcie końcowym ASP.NET Core, aplikacji desktopowej WinForms lub funkcji Azure — cel wdrożenia nie wpływa na API.

Podejście ZXing.Net.MAUI

CameraBarcodeReaderView to uporczywa kontrolka aparatu osadzona na stronie XAML. Zaczyna przetwarzać klatki kamery, gdy IsDetecting jest ustawione na true i zatrzymuje się, gdy jest ustawione na false. Brak implementacji Dispose() oznacza, że zasoby aparatu nie są zwalniane przez standardowy wzorzec IDisposable, gdy użytkownik opuszcza stronę. Dokumentowane obejście polega na ustawieniu IsDetecting = false w OnDisappearing() i przywróceniu go w OnAppearing():

// ZXing.Net.MAUI: toggle IsDetecting in page lifecycle overrides
protected override void OnDisappearing()
{
    base.OnDisappearing();
    CameraView.IsDetecting = false;
}

protected override void OnAppearing()
{
    base.OnAppearing();
    CameraView.IsDetecting = true;
}

// ZXing.Net.MAUI: toggle IsDetecting in page lifecycle overrides
protected override void OnDisappearing()
{
    base.OnDisappearing();
    CameraView.IsDetecting = false;
}

protected override void OnAppearing()
{
    base.OnAppearing();
    CameraView.IsDetecting = true;
}

' ZXing.Net.MAUI: toggle IsDetecting in page lifecycle overrides
Protected Overrides Sub OnDisappearing()
    MyBase.OnDisappearing()
    CameraView.IsDetecting = False
End Sub

Protected Overrides Sub OnAppearing()
    MyBase.OnAppearing()
    CameraView.IsDetecting = True
End Sub

Ten wzór musi być powtórzony na każdej stronie, na której znajduje się skaner. Aplikacje, które często nawigują do strony skanowania i z powrotem, mogą akumulować zasoby kamery, które nie zostały w pełni zwolnione, co jest śledzone w GitHub issue #164 obok raportów o wzroście pamięci i przerywanym inicjowaniu kamery przy powrocie. Problem z automatycznym ostrzeniem iPhone 15 Pro (problem GitHub nr 260) to osobna kwestia w warstwie integracji aparatu: podgląd aparatu renderuje kod kreskowy wyraźnie, ale system autofokusa nie blokuje wystarczająco ostro, aby wykrywanie na sprzęcie iPhone16,1 i iPhone16,2 było możliwe. Udokumentowane obejście polega na poinstruowaniu użytkownika, aby ręcznie dostosował odległość między urządzeniem a kodem kreskowym.

Podejście IronBarcode

IronBarcode nie osadza elementu sterującego kamerą w układzie XAML. Zamiast tego, wywołanie MediaPicker.CapturePhotoAsync() otwiera interfejs użytkownika aparatu systemowego, gdy użytkownik naciska przycisk. Aparat systemowy samodzielnie zarządza ostrością, ekspozycją i autofokusem. Gdy użytkownik potwierdza przechwycenie, wynikowy obraz jest przekazywany do BarcodeReader.Read() jako tablica bajtów:

// NuGet: dotnet add package IronBarcode
using IronBarCode;

private async void ScanButton_Clicked(object sender, EventArgs e)
{
    var photo = await MediaPicker.CapturePhotoAsync();
    if (photo == null) return;

    using var stream = await photo.OpenReadAsync();
    using var ms = new MemoryStream();
    await stream.CopyToAsync(ms);

    var results = BarcodeReader.Read(ms.ToArray());
    foreach (var barcode in results)
        Console.WriteLine($"{barcode.Format}: {barcode.Value}");
}

// Nie OnAppearing or OnDisappearing needed — no camera state to manage

// NuGet: dotnet add package IronBarcode
using IronBarCode;

private async void ScanButton_Clicked(object sender, EventArgs e)
{
    var photo = await MediaPicker.CapturePhotoAsync();
    if (photo == null) return;

    using var stream = await photo.OpenReadAsync();
    using var ms = new MemoryStream();
    await stream.CopyToAsync(ms);

    var results = BarcodeReader.Read(ms.ToArray());
    foreach (var barcode in results)
        Console.WriteLine($"{barcode.Format}: {barcode.Value}");
}

// Nie OnAppearing or OnDisappearing needed — no camera state to manage

Imports IronBarCode
Imports System.IO

Private Async Sub ScanButton_Clicked(sender As Object, e As EventArgs)
    Dim photo = Await MediaPicker.CapturePhotoAsync()
    If photo Is Nothing Then Return

    Using stream = Await photo.OpenReadAsync()
        Using ms As New MemoryStream()
            Await stream.CopyToAsync(ms)

            Dim results = BarcodeReader.Read(ms.ToArray())
            For Each barcode In results
                Console.WriteLine($"{barcode.Format}: {barcode.Value}")
            Next
        End Using
    End Using
End Sub

' Nie OnAppearing or OnDisappearing needed — no camera state to manage

Samouczek dotyczący skanera BARCODE .NET MAUI obejmuje pełną konfigurację projektu dla tego wzorca, w tym konfigurację uprawnień zarówno dla systemu iOS, jak i Android. Ponieważ nie ma stałego widoku kamery, nie ma zasobów do zwolnienia, stanu do przełączania ani szablonu cyklu życia do utrzymania na różnych stronach.

Podejście ZXing.Net.MAUI

ZXing.Net.MAUI dziedziczy wymagania specyfikacji formatu ZXing.Net. Przed rozpoczęciem skanowania, programista musi wypełnić BarcodeReaderOptions.Formats maską bitową wartości enum BarcodeFormats, które powinny zostać wykryte. Formaty nieujęte w tej liście nie będą wykrywane — w sposób cichy, bez błędów ani ostrzeżeń:

// ZXing.Net.MAUI: formats must be declared explicitly
// Formats not listed here are not detected
ReaderOptions = new BarcodeReaderOptions
{
    Formats = BarcodeFormats.QRCode |
              BarcodeFormats.Code128 |
              BarcodeFormats.Ean13 |
              BarcodeFormats.UpcA,
    TryHarder = true,
    AutoRotate = true
};

// ZXing.Net.MAUI: formats must be declared explicitly
// Formats not listed here are not detected
ReaderOptions = new BarcodeReaderOptions
{
    Formats = BarcodeFormats.QRCode |
              BarcodeFormats.Code128 |
              BarcodeFormats.Ean13 |
              BarcodeFormats.UpcA,
    TryHarder = true,
    AutoRotate = true
};

' ZXing.Net.MAUI: formats must be declared explicitly
' Formats not listed here are not detected
ReaderOptions = New BarcodeReaderOptions With {
    .Formats = BarcodeFormats.QRCode Or
               BarcodeFormats.Code128 Or
               BarcodeFormats.Ean13 Or
               BarcodeFormats.UpcA,
    .TryHarder = True,
    .AutoRotate = True
}

Jeśli użytkownik skieruje kamerę na GS1 DataBar, kod Aztec, MaxiCode lub dowolny format, który nie został zadeklarowany w opcjach, skanowanie nie zwróci wyniku bez podniesienia błędu. Kamera wyświetla kod kreskowy, a aplikacja nie otrzymuje wyniku. W kontrolowanym środowisku — magazynie, w którym każdy produkt ma etykietę Code128 — jest to wykonalne. W wdrożeniach, w których formaty kodów kreskowych są określane przez zewnętrznych dostawców, klientów lub systemy zewnętrzne, brak ścieżki alternatywnej staje się nawracającym problemem wsparcia.

Podejście IronBarcode

IronBarcode automatycznie wykrywa format we wszystkich obsługiwanych formatach bez konieczności wcześniejszej konfiguracji. BarcodeReader.Read() analizuje obraz i zwraca wyniki dla każdego zidentyfikowanego kodu kreskowego, niezależnie od formatu. Nie jest wymagana lista BarcodeReaderOptions:

// IronBarcode: no format specification needed
// All 50+ formats detected automatically
var results = BarcodeReader.Read(imageBytes);
foreach (var barcode in results)
    Console.WriteLine($"{barcode.Format}: {barcode.Value}");

// IronBarcode: no format specification needed
// All 50+ formats detected automatically
var results = BarcodeReader.Read(imageBytes);
foreach (var barcode in results)
    Console.WriteLine($"{barcode.Format}: {barcode.Value}");

Imports IronBarcode

' IronBarcode: no format specification needed
' All 50+ formats detected automatically
Dim results = BarcodeReader.Read(imageBytes)
For Each barcode In results
    Console.WriteLine($"{barcode.Format}: {barcode.Value}")
Next

Jeśli konieczne jest dostrojenie wydajności w kontrolowanym scenariuszu, w którym oczekiwany jest tylko jeden format, wskazówki dotyczące formatu mogą być przekazywane opcjonalnie — ale nigdy nie są one wymagane do prawidłowego wykrywania. BarCode w formacie, którego programista nie przewidział, nadal zostanie wykryty i zwrócony.

Podejście ZXing.Net.MAUI

ZXing.Net.MAUI to biblioteka do sterowania kamerą. Nie posiada API do odczytu kodów kreskowych ze ścieżek plików, tablic bajtów przekazywanych bezpośrednio z pamięci lub dokumentów PDF. Kontrolka CameraBarcodeReaderView wymaga żywego strumienia z aparatu; Nie ma metody statycznej, która przyjmuje ścieżkę do pliku i zwraca wyniki BARCODE. Zespoły, które muszą odczytywać BARCODES z przesłanych plików PDF, systemów zarządzania dokumentami lub kolejek przetwarzania obrazów w trybie wsadowym, nie mogą używać ZXing.Net.MAUI w tych scenariuszach i muszą wprowadzić oddzielną bibliotekę.

Podejście IronBarcode

IronBarcode odczytuje kody kreskowe z dowolnego źródła poprzez tę samą metodę BarcodeReader.Read(). Obsługuje ścieżki plików, tablice bajtów, strumienie i dokumenty PDF. Analiza plików PDF odbywa się natywnie —IronBarcode przetwarza strony PDF bezpośrednio, bez pośredniego etapu rasteryzacji:

// NuGet: dotnet add package IronBarcode
using IronBarCode;

// Read barcodes from a PDF file
var results = BarcodeReader.Read("invoice.pdf");
foreach (var barcode in results)
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Format} — {barcode.Value}");

// Read from a user-selected file using MAUI FilePicker
var file = await FilePicker.PickAsync();
if (file != null)
{
    var fileResults = BarcodeReader.Read(file.FullPath);
    foreach (var result in fileResults)
        ResultLabel.Text += $"\n{result.Format}: {result.Value}";
}

// NuGet: dotnet add package IronBarcode
using IronBarCode;

// Read barcodes from a PDF file
var results = BarcodeReader.Read("invoice.pdf");
foreach (var barcode in results)
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Format} — {barcode.Value}");

// Read from a user-selected file using MAUI FilePicker
var file = await FilePicker.PickAsync();
if (file != null)
{
    var fileResults = BarcodeReader.Read(file.FullPath);
    foreach (var result in fileResults)
        ResultLabel.Text += $"\n{result.Format}: {result.Value}";
}

Imports IronBarCode
Imports Microsoft.Maui.Storage

' Read barcodes from a PDF file
Dim results = BarcodeReader.Read("invoice.pdf")
For Each barcode In results
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Format} — {barcode.Value}")
Next

' Read from a user-selected file using MAUI FilePicker
Dim file = Await FilePicker.PickAsync()
If file IsNot Nothing Then
    Dim fileResults = BarcodeReader.Read(file.FullPath)
    For Each result In fileResults
        ResultLabel.Text &= $"\n{result.Format}: {result.Value}"
    Next
End If

Pełny proces odczytu kodów kreskowych z plików PDF, w tym dokumentów wielostronicowych i mieszanych formatów kodów kreskowych na różnych stronach, został opisany w przewodniku odczytu kodów kreskowych z plików PDF. Obejmuje to faktury wysyłkowe, bilety cyfrowe, przepływy pracy związane z zarządzaniem dokumentami oraz scenariusze przetwarzania wsadowego, których nie jest w stanie obsłużyć architektura oparta wyłącznie na kamerze, jaką jest ZXing.Net.MAUI.

Wymagania dotyczące Windows MAUI

Najczęstszym powodem ponownej oceny jest dodanie środowiska docelowegoWindows MAUIdo projektu, który początkowo był przeznaczony wyłącznie dla systemów iOS i Android. Zespoły MAUI często zaczynają od tworzenia aplikacji z priorytetem na urządzenia mobilne, a wraz z ewolucją wymagań rozszerzają się na platformy stacjonarne. Gdy dojdzie do tego rozszerzenia, ZXing.Net.MAUI nie zapewni dalszego rozwoju — platforma Windows nie jest zaimplementowana i nie znajduje się w publicznym planie rozwoju. Zespół musi albo zaakceptować fakt, że skanowanie BarCode nie będzie dostępne w systemie Windows, albo zastąpić bibliotekę. Ponieważ wymiana wiąże się z zmianą struktury wzorca skanowania, zespoły zazwyczaj wprowadzają tę zmianę jednocześnie na wszystkich platformach.

Kompatybilność ze sprzętem obecnej generacji

Problem z autofokusem iPhone 15 Pro (GitHub issue #260) to realne rozważenie dla każdego zespołu dostarczającego produkcyjny skaner kodów kreskowych dla użytkowników iOS. iPhone 15 Pro i Pro Max są powszechne w segmencie konsumenckim, który oczekuje wyrafinowanego doświadczenia aplikacji, a obejście, które wymaga od użytkowników dostosowanie ich odległości od kodu kreskowego, to zauważalny regres w UX w porównaniu z starszym sprzętem iPhone. Zespoły, które napotykają ten problem w QA lub otrzymują raporty wsparcia od użytkowników iPhone 15 Pro, stoją przed dylematem między pozostaniem przy bibliotece, gdzie nie ma obecnie dostępnego rozwiązania, a migracją do podejścia, które nie jest dotknięte modelem skupienia widoku kamery.

Przetwarzanie plików i dokumentów

Wymagania dotyczące skanowania BarCODE rzadko ograniczają się do przechwytywania obrazu na żywo z kamery. Aplikacje, które zaczynają jako skanery zapasów, często rozszerzają się o odczytywanie BARCODE-ów z przesłanych plików PDF, przetwarzanie faktur wysyłkowych lub obsługę biletów cyfrowych z załączników e-mailowych. ZXing.Net.MAUI nie posiada API dla żadnego z tych scenariuszy. Gdy w backlogu pojawia się wymaganie dotyczące odczytu BARCODE z pliku lub dokumentu, zespoły korzystające z ZXing.Net.MAUI muszą wprowadzić oddzielną bibliotekę, aby sobie z tym poradzić. Jeśli zespół już korzysta z IronBarcode w którymkolwiek z tych scenariuszy opartych na plikach, naturalnym kolejnym krokiem będzie konsolidacja skanowania kamerą MAUI w tej samej bibliotece IronBarcode.

Wymagania dotyczące stabilności produkcji

Oznaczenie przed wersją 1.0 w v0.7.4 - podczas gdy sam pakiet jest stabilnym wydaniem NuGet - niesie konsekwencje dla zespołów podlegających analizie kompozycji oprogramowania, audytom zależności lub wewnętrznym procesom zatwierdzania. Niektóre środowiska przedsiębiorstw wymagają, aby zależności produkcyjne miały stabilne wydanie 1.0+, komercyjną umowę wsparcia lub oba. ZXing.Net.MAUI jest utrzymywany przez społeczność i przed wersją 1.0, co pasuje do wewnętrznych narzędzi i prototypów, ale dodaje kroki przeglądu w aplikacjach skierowanych do klienta, gdzie skaner kodów kreskowych jest podstawowym przepływem pracy. Brak płatnego poziomu wsparcia oznacza, że każdy krytyczny błąd zależy od dostępności utrzymywacza społeczności.

Wzorzec CameraBarcodeReaderView do MediaPicker

Kontrolka XAML CameraBarcodeReaderView i jej deklaracja przestrzeni nazw xmlns:zxing są całkowicie usunięte. W każdym pliku XAML zawierającym widok skanera zastąpieniem jest kontrolka Button, która wywołuje MediaPicker.CapturePhotoAsync() w swoim obsłudze Clicked. Model oparty na zdarzeniach — gdzie wyniki trafiają przez BarcodesDetected — zostaje zastąpiony przez bezpośrednie odczytanie wartości zwracanej BarcodeReader.Read() w obsłudze async.

Wykrywanie usunięcia z cyklu życia

Każde nadpisanie OnAppearing i OnDisappearing służące wyłącznie do przełączania CameraView.IsDetecting można usunąć. Jeśli tamte nadpisania zawierają inną logikę cyklu życia strony, linie IsDetecting są usunięte, a pozostała logika jest zachowana. Nie ma ekwiwalentu IronBarcode do IsDetecting, ponieważ nie ma trwałego stanu aparatu do zarządzania między nawigacjami stroną.

Usunięcie rejestracji UseBarcodeReader()

ZXing.Net.MAUI wymaga jednokrotnego wywołania builder.UseBarcodeReader() w MauiProgram.cs, aby zarejestrować swoje usługi aparatów platformowych.IronBarcode nie wymaga żadnej rejestracji MauiProgram.cs. Linia UseBarcodeReader() jest usunięta, a import przestrzeni nazw using ZXing.Net.Maui;, który ją wspiera, jest usunięty wraz z odinstalowaniem pakietu.