PhoneGap von Grund auf neu: Geräte-APIs

German (Deutsch) translation by Nikol Angelowa (you can also view the original English article)

Sie möchten lernen, wie Sie PhoneGap verwenden, wissen aber nicht, wo Sie anfangen sollen? Machen Sie mit, wenn wir "Sculder" zusammenstellen, nicht nur eine Hommage an eine exzellente Science-Fiction-TV-Serie, sondern auch eine vollwertige native mobile Anwendung für den Gläubigen an Sie!

In unserem ersten Teil haben wir uns mit der Einrichtung unserer Entwicklungsumgebung und der Einrichtung von PhoneGap für iOS- und Android-SDKs befasst. In diesem zweiten Teil unserer PhoneGap-Reihe werden wir uns einige der Geräte-APIs ansehen, auf die PhoneGap uns Zugriff gewährt, und diskutieren, wie wir sie verwenden könnten.

Einrichten unseres Projekts

In diesem Teil der Serie werden wir uns nur einige der Funktionen von PhoneGap ansehen, daher werden wir vorerst nur einen Test einrichten.

Richten Sie Ihr Projekt in einer beliebigen Umgebung ein: Xcode für iOS oder Eclipse für Android. Ich werde auf Unterschiede zwischen den beiden hinweisen, wenn es notwendig wird.

Wir beginnen mit grundlegendem HTML und fügen die Datei Phongap.js hinzu. Wenn Sie Ihr Projekt mit Xcode erstellt haben, ist dies so ziemlich das grundlegende HTML, das erstellt wird.

<!DOCTYPE html>
<html>
  <head>
    <title>Acceleration</title>

    <script type="text/javascript" charset="utf-8" src="PhoneGap.js"></script>

  </head>
  <body>
    
  </body>
</html>

Bereitstellung auf einem Testgerät

In diesem Teil der Serie möchten wir in der Lage sein, mindestens ein tatsächliches Gerät zu testen, da der Simulator Einschränkungen hinsichtlich Gerätesensoren wie Beschleunigungsmesser und Kamera aufweist. Um ein iOS-Gerät als Testgerät zum Laufen zu bringen, benötigen Sie ein kostenpflichtiges Entwicklerkonto. Wenn Sie Ihr Gerät an Ihren Computer anschließen und Xcode ausführen, können Sie dieses Telefon zu einem Entwicklungstelefon machen. Gehen Sie das Setup durch und jetzt, wenn Sie Ihre App erstellen und ausführen möchten, können Sie Ihr Gerät aus dem Dropdown-Menü auswählen.

Für Android ist es ziemlich dasselbe, außer dass Sie dies in Eclipse tun. Schließen Sie Ihr Telefon an und stellen Sie sicher, dass es sich im Debug-Modus über USB befindet (in den Telefoneinstellungen). Wenn Sie Ihre App ausführen möchten, wählen Sie Als Android-App ausführen.

Werfen wir einen Blick auf einige Grundlagen des Gerätesensors.

Die Beschleunigungsmesser-API

Der Beschleunigungsmesser gibt eine Rückmeldung für die Bewegung des Geräts über alle drei Achsen. Wir haben einige Methoden für den Beschleunigungsmesser in PhoneGap: getCurrentAcceleration, watchAcceleration und clearWatch

Es gibt auch einige Argumente für die Beschleunigungsmessermethode. accelerometerSuccess, accelerometerError und accelerometerOptions.

Wir verwenden unsere erste Methode, accelerometer.getCurrentAcceleration, wie folgt.

	navigator.accelerometer.getCurrentAcceleration(accelerometerSuccess, accelerometerError);

Die aktuelle Beschleunigung wird mit der Funktion AccelerometerSuccess zurückgegeben. Alle benötigten Daten befinden sich im acceleration objekt, das wir an unsere Erfolgsfunktion zurückgeben. Lassen Sie uns ein Beispiel zum Laufen bringen. Nehmen Sie unser Grundlayout, das wir am Anfang dieses Teils eingerichtet haben, und fügen Sie es hinzu.

<!DOCTYPE html>
<html>
  <head>
    <title>Acceleration</title>

    <script type="text/javascript" charset="utf-8" src="PhoneGap.js"></script>
    <script>
    	//first we want to wait for PhoneGap to load
    	document.addEventListener("deviceready", loaded, false)
    	//PhoneGap is loaded
    	function loaded(){
    		navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);
    	}

    	//Get the current Acceleration data if Successful
    	function onSuccess(acceleration){
    		alert('Acceleration X: ' + acceleration.x + '\n' +
              'Acceleration Y: ' + acceleration.y + '\n' +
              'Acceleration Z: ' + acceleration.z + '\n' +
              'Timestamp: '      + acceleration.timestamp + '\n');
    	}

    	// alert if there is an error
    	function onError(){
    		alert("Error");
    	}

    </script>

  </head>
  <body>
    
  </body>
</html>

Wenn Sie dies in einem Simulator oder Gerät ausführen, werden Sie beim Laden mit einer einzelnen Warnung begrüßt. Was wir tun müssen, ist die Beschleunigung in Intervallen zu beobachten und dann die Daten auszugeben. Wir können dies mit der watchAcceleration-Methode tun. Wir verwenden es mit folgenden:

var watchID = navigator.accelerometer.watchAcceleration(Success, Error, [Options]);

Die watchID ist eine Referenz, an die wir unsere Optionen anhängen können, und auch eine Möglichkeit, die wir bei Verwendung der clearWatch-Methode verwenden können.

Lassen Sie uns fortfahren und unser älteres JavaScript durch Folgendes ersetzen:

	//wait for PhoneGap to load
	document.addEventListener("deviceready", loaded, false);

    // PhoneGap is ready
    function loaded() {
        startWatch();
    }

    // Start watching the acceleration

    function startWatch() {

        // Update acceleration every 3 seconds
        var options = { frequency: 3000 };

        watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);
    }

    // Stop watching the acceleration
    function stopWatch() {
        if (watchID) {
            navigator.accelerometer.clearWatch(watchID);
            watchID = null;
        }
    }

    // Success
    function onSuccess(acceleration) {
        var element = document.getElementById('accelerometer');
        element.innerHTML = 'Acceleration X: ' + acceleration.x + '<br />' +
                            'Acceleration Y: ' + acceleration.y + '<br />' +
                            'Acceleration Z: ' + acceleration.z + '<br />' +
                            'Timestamp: '      + acceleration.timestamp + '<br />';
    }

     // Error
    function onError() {
        alert('onError!');
    }

Wie Sie sehen können, übergeben wir eine frequency option an die Überwachungsmethode. Dies ist in Millisekunden angegeben, daher wird diese Methode alle 3 Sekunden erneut ausgelöst. Bei Erfolg wird der HTML-Code eines Elements mit der ID des accelerometer aktualisiert. Wir müssen dieses Element nur in unseren aktuellen HTML-Code aufnehmen.

<body>
    <div id="accelerometer">Waiting for accelerometer...</div>
</body>

Wenn Sie nun die App laden, werden sich die Daten des Beschleunigungsmessers ändern.

Wenn Sie die Simulatoren anstelle der tatsächlichen Geräte verwenden, werden Sie keine Änderung der Beschleunigungsmesserausgabe feststellen.

Das war's also für den Zugriff auf die Beschleunigungsmesser-Geräte-API. Schauen wir uns nun an, wie Sie damit ein Verwackeln in PhoneGap erkennen.

Ereignisse schütteln

Um ein Verwackeln mit PhoneGap zu erkennen, werden wir unsere onSuccess-Funktion entfernen und unsere startWatch-Funktion neu schreiben. Um zu wissen, ob das Gerät geschüttelt wurde, müssen wir die vorherige Ausrichtung kennen, um diese mit der aktuellen Ausrichtung zu vergleichen. Dazu setzen wir eine Variable am Anfang der startWatch-Funktion.

var previousReading = {
	x: null,
    y: null,
    z: null
}

Als nächstes starten wir die watchAcceleration-Funktion.

navigator.accelerometer.watchAcceleration();

Wenn die Beschleunigung erfolgreich ist, werden wir einige Variablen festlegen, die uns helfen, ein Verwackeln zu erkennen.

var changes = {},
bound = 0.2;

Jetzt können wir die vorherige Beschleunigung mit der aktuellen Beschleunigung vergleichen. Wenn sie über das hinausgeht, was wir auch für unsere bound Variable festgelegt haben, können wir unsere erschütterte Funktion auslösen.

if (previousReading.x !== null) {
	changes.x = Math.abs(previousReading.x, acceleration.x);
	changes.y = Math.abs(previousReading.y, acceleration.y);
	changes.z = Math.abs(previousReading.z, acceleration.z);
}

if (changes.x > bound && changes.y > bound && changes.z > bound) {
	shaken();
}

Wir können dann den vorherigen Messwert für das nächste Mal auf den aktuellen Messwert setzen.

 previousReading = {
  x: acceleration.x,
  y: acceleration.y,
  z: acceleration.z
 }

Vergessen wir zum Schluss nicht, eine "Shaken" -Funktion zu schreiben, um das Shake tatsächlich zu handhaben. Im Moment wird nur eine Nachricht alarmiert.

function shaken(){
	alert("Shaken");
}

Sie müssen daran denken, Ihren Fehlerbehandler und Ihre Häufigkeit am Ende der watchAcceleration-Methode am Ende hinzuzufügen.

Ihr endgültiger Code sollte jetzt ungefähr so aussehen:

<!DOCTYPE html>
<html>
    <head>
        <title>Acceleration</title>
        
        <script type="text/javascript" charset="utf-8" src="PhoneGap.js"></script>
        <script type="text/javascript" charset="utf-8">
            
            // The watch id references the current `watchAcceleration`
            var watchID = null;
            
            //wait for PhoneGap to load
            document.addEventListener("deviceready", loaded, false);
            
            // PhoneGap is ready
            function loaded() {
                startWatch();
            }
            
            // Start watching the acceleration
            
            function startWatch() {
                
                var previousReading = {
                    x: null,
                    y: null,
                    z: null
                }
                
                navigator.accelerometer.watchAcceleration(function (acceleration) {
                  var changes = {},
                  bound = 0.2;
                  if (previousReading.x !== null) {
                      changes.x = Math.abs(previousReading.x, acceleration.x);
                      changes.y = Math.abs(previousReading.y, acceleration.y);
                      changes.z = Math.abs(previousReading.z, acceleration.z);
                  }
                  
                  if (changes.x > bound && changes.y > bound && changes.z > bound) {
                  	shaken();
                  }
                  
                  previousReading = {
                  x: reading.x,
                  y: reading.y,
                  z: reading.z
                  }
                  
                  }, onError, { frequency: 2000 });
            }
            
            function shaken(){
                alert("Shaken");
            }
            
            // Error
            function onError() {
                alert('onError!');
            }
            
            </script>
    </head>
    <body>
    </body>
</html>

Ich fand, dass die Grenze von 0,2 ziemlich gut war, aber Sie sollten versuchen, sie nach dem Testen zu erhöhen. Wir haben jetzt erläutert, was mit den Beschleunigungsmesserdaten erreicht werden kann und wie sie erfasst werden. Schauen wir uns also die Kamera an.

Die Kamera-API

Die Kamera ist heute wahrscheinlich eine der am häufigsten verwendeten Funktionen auf Smartphones, insbesondere da die Kameraauflösung auf den meisten Handys schnell zu Standard-Point-and-Shoot-Versionen führt. Zum Glück bietet uns PhoneGap eine ziemlich einfache Möglichkeit, Bilder von der Kamera des Geräts aufzunehmen und diese Bilder schnell in unsere Anwendung zu integrieren.

Die Methode, die wir verwenden werden, ist camera.getPicture() und genau wie der Beschleunigungsmesser wird er auf die gleiche Weise aufgerufen und verwendet drei Parameter. Die Methodensignaturen sehen ungefähr so aus: navigator.camera.getPicture( cameraSuccess, cameraError, [ cameraOptions ] ). Wie Sie sehen werden, müssen beim Umgang mit der Gerätekamera viel mehr Optionen berücksichtigt werden als beim Umgang mit dem Beschleunigungsmesser.

Folgende optionale Parameter können Sie durchlaufen:

Qualität
Zieltyp
Quelle Typ
allowEdit
encodingType
targetWidth
targetHeight

Wie Sie vielleicht erraten haben, ist quality die Qualität, mit der das Bild gespeichert wird. Dies ist eine Zahl von 0 bis 100. Die Variable destinationType ist das Format des zurückgegebenen Bildes. DATA_URL ist eine Base64-codierte Zeichenfolge und FILE_URI ist eine tatsächliche Bild-URI (jpeg/png). Mit dem Parameter sourceType möchten Sie das Quellbild abrufen, das aus PHOTOLIBRARY, CAMERA oder SAVEDPHOTOALBUM stammen kann. Mit der Option allowEdit kann das Bild vor dem Speichern bearbeitet werden. EncodingType definiert die Codierung des zurückgegebenen Bildes bei Verwendung von FILE_URI, aus der Sie entweder JPEG oder PNG verwenden können. Mit targetWidth und targetHeight wird das Bild skaliert, wobei das Seitenverhältnis beibehalten wird. Schließlich gibt es MediaType, das nur bei Auswahl von SAVEDPHOTOALBUM funktioniert und bei dem Sie möglicherweise definieren möchten, was der Benutzer aus PICTURE, VIDEO oder ALLMEDIA auswählen kann.

Lassen Sie uns also unsere Kamera starten. Zuerst haben wir eine Schaltfläche, die beim Klicken unsere Kamera startet. Wenn das Foto aufgenommen wurde, geben wir die als Miniaturansicht codierte Bildbasis64 zurück. Der Quellcode sieht folgendermaßen aus:

<!DOCTYPE html>
<html>
    <head>
        <title>Capture Photo</title>
        
        <script type="text/javascript" charset="utf-8" src="PhoneGap.js"></script>
        <script type="text/javascript" charset="utf-8">

        	var pictureSource,
        		destinationType
            
            document.addEventListener("deviceready",loaded,false);
            
            function loaded() {
                pictureSource=navigator.camera.PictureSourceType;
                destinationType=navigator.camera.DestinationType;
            }
            
            function getPhoto(imageData) {
                var smallImage = document.getElementById('smallImage');
                
                
                smallImage.style.display = 'block';
                
                
                smallImage.src = "data:image/jpeg;base64," + imageData;
            }
            
            function capturePhoto() {
                navigator.camera.getPicture(getPhoto, onFail, { quality: 50 });
            }
           
            
            function onFail(message) {
                alert('Failed because: ' + message);
            }
            
            </script>
    </head>
    <body>
        <button onclick="capturePhoto();">Capture Photo</button> <br>
        <img style="display:none;width:60px;height:60px;" id="smallImage" src="" />
    </body>
</html>

Nach wie vor warten wir auf das Laden von PhoneGap. Wenn der Ladevorgang abgeschlossen ist, können wir die Optionen für den destinationType und den sourceType festlegen. Standardmäßig sind diese auf CAMERA und DATA_URL festgelegt. Wenn Sie auf die Schaltfläche klicken, wird die Funktion capturePhoto ausgelöst. Bei Erfolg startet capturePhoto unsere getPhoto-Funktion. Unsere Funktion empfängt die Bilddaten in dem von uns angegebenen Format, und wir können damit machen, was wir wollen. Alles, was wir wirklich tun, ist, ein HTML-Element anzugeben und unsere Daten in den src dieses Elements zu stellen.

Führen Sie Ihren Code auf Ihrem Gerät aus und testen Sie ihn. Nachdem Sie ein Bild aufgenommen und getestet haben, sollten Sie Folgendes haben:

Es ist auch möglich, das Foto nach der Aufnahme zu bearbeiten. Alles, was wir tun müssen, ist, den Parameter allowEdit: true in den Optionen zu durchlaufen, nachdem das Foto aufgenommen wurde. Es wird in den Bearbeitungsbildschirm verschoben, in dem Sie das Foto zoomen und zuschneiden können. Wir können den folgenden Code verwenden, wenn wir das Bild erfassen:

navigator.camera.getPicture(getPhoto, onFail, { allowEdit: true });

Die Option allowEdit weist einige bemerkenswerte allowEdit auf. Derzeit funktioniert dies nur unter iOS und wird in Blackberry, Android, Palm und Windows 7 ignoriert.

Wenn wir ein Foto aus dem Fotoalbum oder einem anderen Speicher (z. B. localstorage) abrufen möchten, verwenden wir pictureSource.PHOTOLIBRARY.

Das sind so ziemlich die Grundlagen, die wir brauchen, um mit der Kamera in PhoneGap einsatzbereit zu sein. Probieren Sie es aus und probieren Sie einige Dinge mit unterschiedlichen Bildqualitäten, -typen und -größen aus.

Speicher-APIs

Möglicherweise möchten wir das aufgenommene Foto an einem anderen Ort als dem Fotoalbum auf dem Gerät speichern. In der Tat ist dies sehr wahrscheinlich der Fall. Wir werden wahrscheinlich auch andere Informationen speichern wollen. Es gibt einige Möglichkeiten, um den Gerätespeicher zu verwenden. Eine davon ist die Verwendung von WebSQL, die andere die Verwendung von WebStorage - beide wie vom W3C definiert. Sie können die Daten auch an einen Remote-Server senden, wenn Sie sie in einer Cloud-App(Instagr.am) bereitstellen möchten, oder Sie können noch einen Schritt weiter gehen und Lawnchair oder PersistenceJS verwenden

Ich persönlich bevorzuge die WebStorage-Methode und für dieses Projekt ist sie perfekt.

Wir können WebStorage mit der folgenden Syntax verwenden:

	//Store the data
	window.localStorage.setItem("key", "value");
	//retrieve the data
	var value = window.localStorage.getItem("key");
	// value is now equal to "value"

	// remove the value
	window.localStorage.removeItem("key");

Mit dieser grundlegenden Syntax können wir das Base64-codierte Image im lokalen Speicher speichern und bei Bedarf abrufen.

Die Geolocation-API

Geolocation liefert Standortinformationen des Geräts. Viele Geräte können bereits die Browserfunktion verwenden, um die Geolocation-API zu verwenden. Wenn Sie die Implementierung von PhoneGap verwenden, wird diese verwendet, sofern verfügbar.

Die Geolocation von PhoneGap verfügt über drei Methoden: getCurrentPosition, watchPosition und clearWatch. Die Methode getCurrentPosition gibt den aktuellen Standort des Geräts mit einem Positionsobjekt zurück, das die Eigenschaften für Folgendes enthält:

Breite
Längengrad
Höhe
Richtigkeit
Höhengenauigkeit
Überschrift
Geschwindigkeit

Die grundlegende Verwendung der Geolocation-Funktionalität sollte mittlerweile ziemlich vertraut sein:

	navigator.geolocation.getCurrentPosition(success, error);

Und dann können wir so etwas tun:

function onSuccess(position) {
	var el = document.getElementById('location');
    	el.innerHTML = 
    	'Latitude: ' 		   + position.coords.latitude              + '<br />' +
        'Longitude: '          + position.coords.longitude             + '<br />' +
        'Altitude: '           + position.coords.altitude              + '<br />' +
        'Accuracy: '           + position.coords.accuracy              + '<br />' +
        'Altitude Accuracy: '  + position.coords.altitudeAccuracy      + '<br />' +
        'Heading: '            + position.coords.heading               + '<br />' +
        'Speed: '              + position.coords.speed                 + '<br />' +
        'Timestamp: '          + new Date(position.timestamp)          + '<br />';
}

Ihr vollständiger Code sollte ungefähr so aussehen:

<!DOCTYPE html>
<html>
    <head>
        <title>Geolocation</title>
        
        <script type="text/javascript" charset="utf-8" src="PhoneGap.js"></script>
        <script type="text/javascript" charset="utf-8">
            
            document.addEventListener("deviceready", loaded, false);
            
            function loaded() {
                navigator.geolocation.getCurrentPosition(success, error);
            }
            
            function success(position) {
                var element = document.getElementById('geolocation');
                element.innerHTML = 'Latitude: ' + position.coords.latitude     + '<br />' +
                'Longitude: '			+ position.coords.longitude             + '<br />' +
                'Altitude: '           	+ position.coords.altitude              + '<br />' +
                'Accuracy: '           	+ position.coords.accuracy              + '<br />' +
                'Altitude Accuracy: '  	+ position.coords.altitudeAccuracy      + '<br />' +
                'Heading: '            	+ position.coords.heading               + '<br />' +
                'Speed: '              	+ position.coords.speed                 + '<br />' +
                'Timestamp: '          	+ new Date(position.timestamp)          + '<br />';
            }
            
            function error(error) {
                alert(error.message);
            }
            
            </script>
    </head>
    <body>
        <p id="geolocation">Finding geolocation...</p>
    </body>
</html>

Dies gibt Ihnen die Positionsinformationen in dem Moment, in dem die success funktion ausgelöst wird. Wenn wir die Geolokalisierung des Geräts ständig beobachten möchten, verwenden wir anstelle von navigator.geolocation.getCurrentPosition die Methode navigator.geolocation.watchPosition und übergeben ihr die Häufigkeit, auf der wir aktualisieren möchten. Unser Code sollte jetzt ungefähr so aussehen:

<!DOCTYPE html>
<html>
    <head>
        <title>Geolocation</title>
        
        <script type="text/javascript" charset="utf-8" src="PhoneGap.js"></script>
        <script type="text/javascript" charset="utf-8">
            
            document.addEventListener("deviceready", loaded, false);
            
            var watchID = null;
            
            function loaded() {
                watchID = navigator.geolocation.watchPosition(success, error, { frequency: 3000 });
            }
            
            
            function success(position) {
                var element = document.getElementById('geolocation');
                element.innerHTML = 'Latitude: ' + position.coords.latitude     + '<br />' +
                'Longitude: '			+ position.coords.longitude             + '<br />' +
                'Altitude: '           	+ position.coords.altitude              + '<br />' +
                'Accuracy: '           	+ position.coords.accuracy              + '<br />' +
                'Altitude Accuracy: '  	+ position.coords.altitudeAccuracy      + '<br />' +
                'Heading: '            	+ position.coords.heading               + '<br />' +
                'Speed: '              	+ position.coords.speed                 + '<br />' +
                'Timestamp: '          	+ new Date(position.timestamp)          + '<br />' +
                '<hr>' + element.innerHTML;
            }
            
            function error(error) {
                alert(error.message);
            }
            
            </script>
    </head>
    <body>
        <p id="geolocation">Finding geolocation...</p>
    </body>
</html>

Wenn Sie Ihre App jetzt ausführen, sollten Sie eine App erhalten, die folgendermaßen aussieht:

Wie der Beschleunigungsmesser verfügt auch die Geolokalisierung über eine clearWatch-Methode, mit der Sie nicht mehr nach Änderungen suchen können, die Sie mit dem folgenden Code verwenden können:

	navigator.geolocation.clearWatch(watchID);

Damit haben wir jetzt das Wissen, die Geolocation-API in PhoneGap für unsere Anwendung zu verwenden. Möglicherweise möchten wir unseren Standort nur zu einem bestimmten Zeitpunkt aufzeichnen und lokal oder remote speichern. Möglicherweise möchten wir auch unsere Bewegung im Laufe der Zeit aufzeichnen und speichern. Was auch immer wir damit machen wollen, wir wissen jetzt, wie wir diese Informationen erhalten können.

PhoneGap Plugins

Zusätzlich zu den Funktionen, die PhoneGap standardmäßig bietet, steht für PhoneGap eine Vielzahl von Plugins zur Verfügung, mit denen Sie beispielsweise eine Datumsauswahl, einen Datei-Uploader und Paypal durchführen können. Da wir in dieser App keine Plugins verwenden, würde die Verwendung und Installation der Plugins den Rahmen dieser Serie sprengen. Sie sollten jedoch wissen, welche Optionen Sie haben, wenn Sie mit PhoneGap arbeiten. Schauen Sie sich also unbedingt den GitHub an Projekt für Plugins und das Wiki für Informationen darüber, wie Sie mit ihnen arbeiten können. Wenn Sie ein separates Tutorial zur Verwendung von PhoneGap-Plugins und sogar zum Schreiben eigener Plugins sehen möchten, teilen Sie uns dies bitte in den Kommentaren mit!

Abschluss

Obwohl wir noch nicht mit der Entwicklung einer Anwendung begonnen haben, können wir jetzt mit PhoneGap arbeiten, auf einem Gerät und einem Simulator testen, einen guten Überblick über die Funktionsweise der APIs von PhoneGap und die Verwendung der API in einer App erhalten. Im nächsten Teil werden wir mit dem Bau von Sculder beginnen, unserer Beispielanwendung!