SAPUI5: Mobiles QR- und Barcode-Scannen mit sap.ndc.BarcodeScanner

Eine Anleitung zur Verwaltung von nativen Barcode-/QR-Code-Scanprozessen, API-Statusmodellen und asynchronen Fehlerschleifen durch Auslösen der Gerätekamera in Fiori-Mobil- und Handheld-Terminalanwendungen.

Eine der kritischsten Anforderungen für Fiori-Anwendungen, die für Außendienstoperationen wie Logistik, Lagerverwaltung (WM/EWM) und Produktionsverfolgung (PP) entwickelt wurden, ist die Barcode- oder QR-Code-Scanfunktion. SAPUI5 bietet in seiner Architektur ein fertiges, optimiertes Steuerelement für den Zugriff auf hybride oder native mobile Gerätehardware: sap.ndc.BarcodeScanner. In diesem Leitfaden behandeln wir die Standards für das Auslösen der Gerätehardware, die Überprüfung des Scan-Status und die Ausnahmebehandlung, ohne Abhängigkeiten von externen Bibliotheken zu schaffen.

💡 Regeln für Hardware- und Scan-Management

Stiller Abbruch (Silent UX) Ansatz: Wenn ein Benutzer den Scan-Bildschirm manuell schließt (Abbrechen), ist dies kein technischer Fehler oder eine Situation, die eine Benachrichtigung erfordert. Für eine reibungslose Benutzererfahrung ist es ein gängiger UX-Standard, die Funktion stillschweigend zu verlassen (return), ohne dem Benutzer eine zusätzliche Toast-Nachricht anzuzeigen, wenn das Flag cancelled erfasst wird.
Browser- und Infrastrukturstandards: Die Bibliothek sap.ndc wählt dynamisch den geeigneten Scan-Anbieter (Scanning Provider) basierend auf der Umgebung aus, in der die Anwendung ausgeführt wird (SAP Fiori Client, nativer Container oder moderne mobile Browser). Aufgrund von Sicherheitsrichtlinien erfordert der Kamerazugriff, dass die Anwendung unter dem HTTPS-Protokoll oder, als Ausnahme während der Entwicklung, auf localhost ausgeführt wird.
Vorabprüfung und Statusmodell: Vor dem Starten des Scanvorgangs kann die BarcodeScanner.getStatusModel() API verwendet werden, um zu überprüfen, ob eine nutzbare Kamerainfrastruktur auf dem Gerät verfügbar ist. Der Aktivitätsstatus des Scanners kann über dieses Modell dynamisch überwacht werden.

💻 Controller & XML View Hardware-Integrationsreferenz

0. JavaScript-Scan- und Integrationslogik (Scanner.controller.js)

Asynchrones Auslösen der Kamerainfrastruktur, Verfolgung des Statusmodells, Unterscheidung von industriellen Barcode-Formaten (CODE_128, QR_CODE usw.) und Callback-Management.

sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "sap/m/MessageToast",
    "sap/m/MessageBox",
    "sap/ndc/BarcodeScanner"
], function (Controller, MessageToast, MessageBox, BarcodeScanner) {
    "use strict";

    return Controller.extend("ui5.app.controller.Scanner", {

        onInit: function () {
            this.oViewModel = this.getView().getModel("localViewModel");
            
            // Optional: Access the structural feature status model provided by UI5 framework
            // Contains status flags: available, enabled, dialogVisible
            this.oScannerStatusModel = BarcodeScanner.getStatusModel();
            this.getView().setModel(this.oScannerStatusModel, "scannerStatus");
        },

        onTriggerScan: function () {
            // Best Practice: Check feature availability before invoking hardware layers
            if (!this.oScannerStatusModel.getProperty("/available")) {
                MessageBox.error("No supportive scanning provider or camera hardware detected on this device.");
                return;
            }

            // Fire asynchronous hardware invocation
            BarcodeScanner.scan(
                function (mResult) {
                    // Success callback execution context
                    // Silent UX approach: exit quietly if user aborts scanning explicitly via dismiss button
                    if (mResult.cancelled) {
                        return;
                    }

                    // Extract scanned raw alphanumeric string and format tokens
                    var sScannedCode = mResult.text;
                    var sFormat = mResult.format; // Supported formats: QR_CODE, CODE_128, CODE_39, EAN_13

                    console.log("Scan execution approved. Code: " + sScannedCode + " Format: " + sFormat);

                    // Sync state controller with the retrieved token
                    this.getView().getModel("localViewModel").setProperty("/scannedId", sScannedCode);
                    MessageToast.show("Token captured successfully.");

                    // Trigger downstream enterprise pipeline operations
                    this._fetchScannedObjectDetails(sScannedCode);

                }.bind(this),

                function (oError) {
                    // Error callback execution - triggered on missing permissions or media capture blockages
                    MessageBox.error("Hardware acquisition or media stream fault: " + oError);
                }
            );
        },

        _fetchScannedObjectDetails: function (sBarcodeKey) {
            console.log("Initiating backend verification pipeline for identifier: " + sBarcodeKey);
        }
    });
});

1. Ansichtsstruktur und Auslöse-Button (Scanner.view.xml)

Eine UI-Struktur, die für den Benutzer zum Starten der Kamera konzipiert ist und den flexiblen Layout-Regeln und Framework-Standards entspricht.

<mvc:View 
    controllerName="ui5.app.controller.Scanner"
    xmlns:mvc="sap.ui.core.mvc" 
    xmlns="sap.m">

    <Page id="scannerPage" title="Mobile Barcode & QR Integration" titleAlignment="Center">
        
        <VBox class="sapUiMediumMargin" width="100%" alignItems="Center" justifyContainer="Center">
            
            <Image src="images/barcode-placeholder.png" width="180px" class="sapUiMediumMarginBottom" />
            
            <!-- Custom layout configuration without using non-standard control properties -->
            <HBox width="350px" alignItems="Center" class="sapUiContentPadding">
                <Input value="{localViewModel>/scannedId}" 
                       placeholder="Scanned data will appear here" 
                       editable="false" 
                       width="100%" 
                       class="sapUiSmallMarginEnd" />
                       
                <Button id="btnScan"
                        icon="sap-icon://qr-code" 
                        type="Emphasized" 
                        tooltip="Trigger Camera Scanner"
                        enabled="{scannerStatus>/enabled}"
                        press="onTriggerScan" />
            </HBox>

        </VBox>
        
    </Page>
</mvc:View>

Verpassen Sie nicht den neuen Code in der Bibliothek!

Abonnieren Sie den Newsletter, um sofort über wöchentlich aktualisierte unternehmensweite SAPUI5/Fiori-Komponenten, Leistungstipps und Architekturentwürfe informiert zu werden.