AndroidQrCode to gotowy komponent html, który po osadzeniu w dowolnym formularzu StudioSystem uruchamia aparat urządzenia mobilnego w trybie skanowania kodów QR i wstawia odczytaną wartość do wskazanego pola. Konfiguracja sprowadza się do jednego wymaganego parametru - ssElementId - oraz kilku opcjonalnych, sterujących wyglądem przycisku i wyborem kamery.
Komponent AndroidQrCode
Dodanie skanera kodów QR do formularza w StudioSystem nie wymaga pisania własnej integracji z aparatem urządzenia. Wystarczy umieścić w kodzie html pojedynczy element z klasą AndroidQrCode, a resztę - obsługę kamery, podgląd i dekodowanie obrazu - przejmuje gotowa biblioteka.
<div class="AndroidQrCode" ssWidh="100px" ssText="QR SCAN" ssClass="art-buttonSiberia" ssElementId="QR_CODE_VALUE"></div>Ten sam element można wstawić dynamicznie z poziomu skryptu transakcji jqs, co w praktyce jest częstszym scenariuszem niż zapisanie go na stałe w pliku html:
$("#formularz").append('<div class="AndroidQrCode" ssWidh="100px" ssText="QR SCAN" ssClass="art-buttonSiberia" ssElementId="QR_CODE_VALUE"></div>');Sam element w tym momencie jest jeszcze bierny - dopiero po uruchomieniu funkcji konfigurującej, opisanej w sekcji o aktywacji skanera, zamienia się w działający przycisk.
Parametry konfiguracyjne
Zachowanie komponentu ustawia się atrybutami umieszczonymi bezpośrednio na elemencie div. Jeden z nich jest wymagany, pozostałe mają rozsądne wartości domyślne.
| Parametr | Wymagany | Znaczenie |
|---|---|---|
ssElementId | Tak | Id elementu html, do którego trafi zeskanowana wartość. |
ssText | Nie | Podpis przycisku. Domyślnie „Skanuj kod QR” z ikoną z /images_k/24x24/dodaj.png. |
ssWidh | Nie | Szerokość przycisku (px, % lub calc). Domyślnie 200px. Tak, nazwa parametru to rzeczywiście „ssWidh”, nie „ssWidth”. |
ssClass | Nie | Dodatkowa klasa CSS dołączana obok domyślnej klasy art-button. |
ssCameraId | Nie | Numer kamery urządzenia, od 0 do liczby kamer minus jeden. |
ssFunction | Nie | Nazwa funkcji użytkownika wykonywanej po zakończeniu skanowania. |
Parametr ssText pozwala też dodać własną ikonę zamiast domyślnej grafiki, na przykład:
ssText="Skanuj kod QR<img src='/images_k/24x24/android.png' style='margin-left: 5px;' title='android qr scaner'/>"Parametr ssClass nie zastępuje domyślnego stylu, tylko go uzupełnia - element otrzymuje jednocześnie klasy art-button i wskazaną w ssClass. Wartość art-buttonSiberia zmienia na przykład intensywny, ciemny niebieski na jaśniejszy odcień z palety Siberia, bez potrzeby pisania osobnego arkusza stylów dla każdego przycisku skanera.
Aktywacja skanera
Sam znacznik div nie uruchamia jeszcze niczego - to wyłącznie punkt zaczepienia dla skryptu. Aktywacja wymaga dwóch kroków: pobrania biblioteki skanera i wywołania na elemencie funkcji konfigurującej.
$.getScript('/Scripts/html5-qrcode.min.js', function () {
$(".AndroidQrCode").each(function (index) {
new KonfigurujAndroidQrCode($(this));
});
});Funkcja KonfigurujAndroidQrCode znajduje się w pliku studiosystemIS.js i jako parametr przyjmuje obiekt jQuery wskazujący na skonfigurowany element. Do poprawnego działania funkcjonalności u klienta potrzebne są więc dwa pliki:
- /Scripts/html5-qrcode.min.js - biblioteka odpowiedzialna za obsługę kamery i dekodowanie obrazu.
- /Scripts/studiosystemIS.js - plik z klasą
KonfigurujAndroidQrCode, spinającą bibliotekę z elementem html.
Wzorzec „najpierw pobierz skrypt, potem skonfiguruj każdy pasujący element” pozwala dodać skaner do formularza zbudowanego dynamicznie, bez znajomości liczby przycisków w chwili pisania kodu strony - each() obsłuży tyle elementów AndroidQrCode, ile akurat znajdzie się na stronie.
Gdzie trafia zeskanowana wartość
Parametr ssElementId nie tylko wskazuje cel, ale też decyduje pośrednio o sposobie wstawienia wartości - skrypt sam sprawdza rodzaj wskazanego elementu i dobiera odpowiednią metodę jQuery.
- input i textarea - wartość wstawiana jest metodą
val(), czyli tak, jakby użytkownik wpisał ją ręcznie z klawiatury. - div, span, p i pozostałe elementy html - wartość wstawiana jest metodą
html(), nadpisując dotychczasową zawartość elementu.
Dzięki temu ten sam komponent obsłuży zarówno pole formularza, do którego trafi numer seryjny gotowy do zapisania w bazie danych, jak i zwykły znacznik podglądu, w którym wynik ma się po prostu wyświetlić operatorowi bez dalszej edycji.
Opcjonalny parametr ssFunction pozwala pójść o krok dalej - zamiast (albo obok) wstawienia wartości do elementu, po zeskanowaniu kodu wykonana zostaje wskazana funkcja użytkownika, co otwiera drogę do bardziej złożonych scenariuszy, na przykład automatycznego wysłania formularza od razu po odczycie kodu.
Ograniczenia i wymagania
Zanim skaner trafi do produkcyjnego formularza, warto znać jego praktyczne ograniczenia - część z nich wynika z natury skanowania obrazem, a nie z samej implementacji.
- Uprawnienia do aparatu - aplikacja musi mieć zgodę systemu Android na dostęp do aparatu, inaczej skanowanie się nie uruchomi.
- Kod musi być wydrukowany - skaner nie radzi sobie dobrze z odczytem kodów wyświetlanych na ekranach laptopów, monitorów, telefonów czy telewizorów. Skanowany kod QR powinien znajdować się na papierze.
- Jakość aparatu i autofocus - szybszy autofocus przekłada się wprost na szybszy odczyt, szczególnie przy kodach mniejszych rozmiarów.
- Ilość światła - przy słabym oświetleniu czas i skuteczność odczytu wyraźnie spadają.
- Stan skanowanego kodu - zabrudzony, wygnieciony lub uszkodzony wydruk może utrudnić albo całkowicie uniemożliwić odczyt.
Żadne z tych ograniczeń nie jest specyficzne wyłącznie dla StudioSystem - to naturalne cechy skanowania obrazem kamerą telefonu, wspólne dla większości bibliotek tego typu. Warto jednak uwzględnić je już na etapie projektowania procesu, na przykład zakładając drukowanie etykiet z kodem QR w rozmiarze większym niż absolutne minimum.
Realne zastosowania w transakcjach
Komponent nie jest wyłącznie przykładem z dokumentacji - pracuje na produkcji w kilku miejscach platformy. W transakcji wyszukiwania roli YMS skaner kodów QR oparty właśnie na bibliotece html5-qrcode.min.js można włączyć lub wyłączyć parametrem konfiguracyjnym, w zależności od tego, czy operator na placu ma pod ręką kody QR czy wpisuje dane ręcznie.
Drugim miejscem jest transakcja przyjęcia wewnętrznego w module WMS, gdzie sekcja wyszukiwania wykorzystuje już nowszy wariant biblioteki i dodatkowo konfiguruje przycisk tak, aby po odczycie kodu symulował naciśnięcie klawisza Enter - operator nie musi wykonywać żadnej dodatkowej czynności poza samym zeskanowaniem. Oba przykłady pokazują tę samą zasadę: skaner nie zastępuje pola tekstowego, tylko przyspiesza jego wypełnienie, co ma znaczenie przy większej skali pracy opisanej w materiale o aplikacji Android WMS.
Warto zwrócić uwagę, że w obu przypadkach skaner jest funkcją opcjonalną, a nie jedyną drogą wprowadzenia danych - operator zawsze może wpisać wartość ręcznie, jeśli akurat nie ma przy sobie wydrukowanego kodu albo urządzenie chwilowo nie ma dostępu do aparatu. Pełny wykaz transakcji, w których taki wybór ma znaczenie, zebrano w materiale o transakcjach YMS, obejmującym zarówno rejestrację awizacji, jak i obsługę placu z poziomu urządzenia mobilnego.
Wartość gotowa od razu po odczycie
Operator nie przepisuje niczego ręcznie - zeskanowana wartość trafia do formularza w ułamku sekundy po rozpoznaniu kodu przez kamerę.
Nowszy skaner EAN i QR
Opisany komponent obsługuje wyłącznie kody QR. Tam, gdzie w jednym procesie trzeba odczytywać zarówno kody QR, jak i klasyczne kody kreskowe EAN, powstała nowsza, połączona wersja skanera. Zamiast html5-qrcode.min.js i funkcji KonfigurujAndroidQrCode, korzysta ona z biblioteki html5-qrcode_21.min.js oraz funkcji KonfigurujAndroidQrAndBarCode, opisanej dokładnie w materiale o skanowaniu kodów EAN i QR przy pomocy aparatu.
Wybór między wersjami zależy wyłącznie od zakresu kodów występujących w danym procesie. Jeśli formularz ma do czynienia tylko z kodami QR, prostszy i lżejszy komponent AndroidQrCode w zupełności wystarczy - nie ma powodu, aby sięgać po połączony skaner tam, gdzie druga obsługiwana przez niego funkcja nigdy nie zostanie wykorzystana.
Warto pamiętać, że skanowanie aparatem to tylko jedna strona obsługi kodów w StudioSystem. Drugą jest ich generowanie i drukowanie na dokumentach, opisane w materiale o kodach kreskowych w StudioSystem - tam kod trafia na wydruk zamiast być z niego odczytywany, ale konfiguracja opiera się na tym samym skorowidzu definicji.
Podsumowanie
Komponent AndroidQrCode pozwala dodać skanowanie kodów QR do dowolnego formularza StudioSystem jednym znacznikiem html i kilkoma liniami kodu aktywującego. Jedynym wymaganym parametrem jest ssElementId, a o sposób wstawienia wartości - do pola formularza czy do zwykłego elementu podglądu - dba sam skrypt.
W praktyce komponent działa już w transakcjach modułu YMS i WMS, przyspieszając wprowadzanie danych tam, gdzie operator ma pod ręką wydrukowany kod. Tam, gdzie potrzebna jest dodatkowo obsługa kodów EAN, naturalnym krokiem jest przejście na nowszy, połączony wariant skanera.