So wird’s gemacht: Herunterladen einer Datei mit WinJS.xhr (HTML)

Artikel
12/12/2015

[ Dieser Artikel richtet sich an Windows 8.x- und Windows Phone 8.x-Entwickler, die Windows-Runtime-Apps schreiben. Wenn Sie für Windows 10 entwickeln, finden Sie weitere Informationen unter neueste Dokumentation]

WinJS.xhr bietet eine einfache Möglichkeit zum Herunterladen von Webinhalten in Ihre App. In diesem Thema werden das Herunterladen einer Datei mit WinJS.xhr, das Behandeln von Fehlern und das Erstellen von Berichten zum Downloadstatus erläutert. Zudem wird gezeigt, wie Sie verschiedene Inhaltstypen herunterladen.

Die WinJS.xhr-Funktion gibt ein WinJS.Promise-Objekt zurück. Weitere Informationen über asynchrone Methoden im Allgemeinen und JavaScript-Zusagen im Besonderen finden Sie unter Asynchrone Programmierung in JavaScript.

Warnung Es ist jetzt möglich, XMLHttpRequest zu verwenden, um sehr große Objekte, wie Blob- und FormData-Objekte, zu übertragen, deren Upload sehr viel Zeit in Anspruch nehmen kann. Da Apps jederzeit beendet werden können, sollten Sie für diese Vorgänge ggf. die Dateiupload-APIs in der Windows-Runtime-API nutzen. Weitere Informationen zum Hochladen von Inhalten finden Sie unter So wird's gemacht: Hochladen einer Datei.

Voraussetzungen

Dieses Verfahren setzt voraus, dass Sie eine einfache App erstellen können, für die Vorlage "Windows-Bibliothek für JavaScript" verwendet wird. Informationen zum Erstellen der ersten App finden Sie unter Erstellen Ihrer ersten Windows-Runtime-App mit JavaScript.

Einrichten der App für den Zugriff auf das Web

Bestimmte Funktionen müssen Apps explizit hinzugefügt werden, z. B. der Zugriff auf das Netzwerk. Weitere Informationen zu Funktionen finden Sie unter Deklaration der App-Funktionen und So wird's gemacht: Konfigurieren von Netzwerkfunktionen.

Erstellen Sie in Visual Studio eine leere JavaScript-App.
Öffnen Sie die Datei "package.appxmanifest", und wählen Sie die Registerkarte Funktionen aus.
Für die Windows-Version des Beispiels sollte die Funktion Internet (Client) bereits ausgewählt sein. Wenn dies nicht der Fall ist, wählen Sie sie jetzt aus. Falls die App als Client eine Verbindung mit Webdiensten in einem Heim- oder Arbeitsplatznetzwerk herstellen können muss, ist außerdem die Funktion Private Netzwerke (Client und Server) erforderlich.

Wählen Sie für die Windows Phone-Version des Beispiels die Funktion Internet (Client und Server) aus.

Hinweis Unter Windows Phone gibt es nur eine Netzwerkfunktion – Internet (Client und Server) –, die den Netzwerkzugriff komplett für die App aktiviert.

Einfaches Herunterladen

In diesem Schritt laden Sie eine Webseite herunter und melden den Abschluss des Downloads.

Erstellen Sie eine leere App, und geben Sie ihr den Namen XhrExample.
Fügen Sie im HTML-Text in der Datei "default.html" ein DIV-Element hinzu, das die Benachrichtigung zum Abschluss des Vorgangs, den Status und Fehlerberichte enthält.
```
<div id="xhrReport"></div>
```
Fügen Sie dem HTML-Text in der Datei "default.html" außerdem ein SCRIPT-Element hinzu, das den WinJS.xhr-Code enthält.
```
var xhrDiv = document.getElementById("xhrReport");
xhrDiv.style.color = "#000000";

WinJS.xhr({ url: "https://www.microsoft.com" })
    .done(function complete(result) {
        // Report download.
        xhrDiv.innerText = "Downloaded the page";
        xhrDiv.style.backgroundColor = "#00FF00";
});
```
Im vorangehenden Codebeispiel schreibt die complete-Funktion in das DIV-Element, dass der Download abgeschlossen ist.

Beachten Sie die Syntax von WinJS.xhr. Diese Funktionen akzeptiert einen einzelnen Parameter, in dem die Optionen angegeben werden. url ist die einzige erforderliche Option. Informationen zu weiteren Optionen finden Sie in der Referenzdokumentation.

Jede Zusage verfügt über zwei Funktionen, mit denen Sie das Ergebnis eines asynchronen Vorgangs behandeln können: then und done. Beide Funktionen akzeptieren drei Parameter: Eine Funktion, die aufgerufen wird, wenn der Download abgeschlossen ist (d. h., wenn readyState gleich 4 ist), eine Funktion, die aufgerufen wird, wenn ein Fehler vorliegt, und eine Funktion, die aufgerufen wird, während der Download ausgeführt wird (d. h., wenn readyState gleich 2 oder 3 ist). Nur die done-Funktion löst eine Ausnahme aus, wenn ein Fehler nicht behandelt wird. Sie sollten die done-Funktion verwenden, wenn Sie keine Fehlerfunktion bereitstellen möchten.
Erstellen Sie anschließend die App, und führen Sie sie im Debugmodus aus. Daraufhin sollte ein grünes Feld mit der Meldung "Downloaded the page" (Seite wurde vollständig heruntergeladen) angezeigt werden.
Versuchen Sie nun, einen Fehler zu erzeugen, um zu sehen, was passiert. Ersetzen Sie die URL https://www.microsoft.com im Code durch http://www.nosuchsite.example. Wenn Sie die App im Debugmodus ausführen, sollte die debugger-Anweisung in der terminateAppHandler-Funktion in der WinJS-Datei "base.js" angezeigt werden.

Behandeln von Fehlern

In diesem Schritt fügen Sie einen Fehlerhandler hinzu, der beim Auftreten eines Fehler in DIV schreibt.

Fügen Sie dem Code, den Sie oben in Schritt 3 hinzugefügt haben, einen Fehlerhandler hinzu. In WinJS.xhr verfügt die Fehlerfunktion über einen Parameter zur Darstellung der Anforderung.

var xhrDiv = document.getElementById("xhrReport");

WinJS.xhr({ url: "http://www.nosuchsite.example" })
    .done(function complete(result) {
        // Report download.
        xhrDiv.innerText = "Downloaded the page";
        xhrDiv.style.backgroundColor = "#00FF00"; 
        },
        function error(result){
            xhrDiv.innerHTML = "Got error: " + result.statusText;
            xhrDiv.style.backgroundColor = "#FF0000";
     });

Wenn Sie die App ausführen, sollte ein rotes Feld angezeigt werden, das den Fehler meldet.

Melden des Status

In diesem Schritt melden Sie den Status des Downloads, indem Sie eine Fortschrittsfunktion für die done-Funktion bereitstellen.

Fügen Sie dem Code, den Sie im vorhergehenden Schritt 3 hinzugefügt haben, einen Statushandler hinzu. In WinJS.xhr verfügt die Fortschrittsfunktion über einen Parameter zur Darstellung der Anforderung.

var xhrDiv = document.getElementById("xhrReport");

WinJS.xhr({ url: "https://www.microsoft.com" })
    .done(function complete(result) {
        // Report download.
            xhrDiv.innerText = "Downloaded the page";
            xhrDiv.style.backgroundColor = "#00FF00"; 
        },
        function error(error){
            xhrDiv.innerHTML = "Got error: " + error.statusText;
            xhrDiv.style.backgroundColor = "#FF0000";
        }, 
        function progress(result) {
            xhrDiv.innerText = "Ready state is " + result.readyState;
            xhrDiv.style.backgroundColor = "#0000FF";
    });

Wenn Sie den Code ausführen, sollte ein blaues Feld mit der Meldung "Ready state is 2" oder "Ready state is 3" und anschließend ein grüner Bereich mit der Meldung "Downloaded the page" angezeigt werden. (Vielleicht müssen Sie den Vorgang durch einen Haltepunkt verlangsamen, damit das blaue Feld angezeigt wird.)

Herunterladen unterschiedlicher Arten von Inhalt

Mit WinJS.xhr können Sie verschiedene Inhaltstypen herunterladen. Der Inhaltstyp wird in der responseType-Option von WinJS.xhr angegeben.

Die folgenden Typen werden unterstützt:

arraybuffer: Der Typ von response ist ein ArrayBuffer-Objekt. Mit diesem Typ werden binäre Inhalte als Array vom Typ Int8, Int64 oder anderer ganzahliger oder Gleitkommatypen dargestellt. (Weitere Informationen zu den unterschiedlichen zurzeit in JavaScript unterstützten typisierten Arrays finden Sie unter Typisierte Arrays.) Die responseText- und responseXML-Eigenschaften sind undefined.

Im folgenden Code wird das Behandeln einer arraybuffer-Antwort dargestellt:
```
<div id="xhrDiv"></div>
<script type="text/javascript">
    WinJS.xhr({ url: "https://www.microsoft.com", responseType: "arraybuffer" })
        .done(function complete(result) {
            var arrayResponse = result.response;
            var ints = new Uint32Array(arrayResponse.byteLength / 4);

            xhrDiv.style.backgroundColor = "#00FF00";
            xhrDiv.innerText = "Array is " + ints.length + "uints long";
        });
</script> 
```

blob: Der Typ von response ist ein Blob-Objekt. Damit werden binärer Inhalt als einzelne binäre Entität dargestellt. Die responseText- und responseXML-Eigenschaften sind undefined.

Im folgenden Code wird die blob-Behandlung veranschaulicht:

WinJS.xhr({ url: "https://www.microsoft.com/windows/Framework/images/win_logo.png", responseType: "blob" })
    .done(
        function (request) {
            var imageBlob = URL.createObjectURL(request.response);
            var imageTag = xhrDiv.appendChild(document.createElement("image"));
            imageTag.src = imageBlob;
        });

document: Der Typ von response ist ein XML-DOM-Objekt (Document Object Model). Damit werden XML-Inhalte dargestellt, also Inhalte mit dem MIME-Typ "text/xml". (Wenn der MIME-Typ nicht "text/xml" ist, ist responseXML von demselben Typ, während responseTextundefined ist.
json: Der Typ von response ist ein String-Objekt. Damit werden JSON-Zeichenfolgen dargestellt. responseText ist ebenfalls vom Typ String, während responseXMLundefined ist.
ms-stream: Der Typ von response ist msStream, und responseText und responseXML sind undefined. Dieser Antworttyp ist in der W3C-Spezifikation nicht enthalten. Er wird aber unterstützt, um das Streamen von Daten zu vereinfachen. Weitere Informationen finden Sie unter XMLHttpRequest-Erweiterungen.

text (Standard): Der Typ von response und responseText ist String.

Im folgenden Beispiel wird das Behandeln einer text -Antwort dargestellt:

WinJS.xhr({ url: "http://www.msdn.microsoft.com/library", responseType: "text" 
    .done(
        function (request) {
            var text = request.responseText;
            var subText = text.substring(text.indexOf("Welcome"), text.indexOf("services.") + 9);
            xhrDiv.innerHTML = subText;
    });

Zusammenfassung

Weitere Informationen zu WinJS.xhr und XMLHttpRequest finden Sie in den folgenden Themen: