So wird’s gemacht: Empfangen von Dateien (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]

Zum Freigeben von Dateien ist kaum mehr Vorbereitung nötig als für einfachere Datentypen (wie Text). Wenn Sie Dateien freigeben, müssen Sie berücksichtigen, wie lange das Verarbeiten der Dateien dauern könnte.

Wenn Sie vermuten, dass die App etwas Zeit für die Verarbeitung der Dateien beansprucht, die ein Benutzer freigeben möchte, rufen Sie zuerst reportStarted auf. Erst danach sollte die Verarbeitung erfolgen. Auf diese Weise stellen Sie sicher, dass das System Ihre App aktiv hält, bis die Verarbeitung abgeschlossen ist. Rufen Sie nach dem Abschluss der Verarbeitung reportCompleted auf, um die Freigabe zu beenden. Weitere Informationen erhalten Sie in "Berichten über den Status bei verlängertem Teilen" in Schnellstart: Empfangen von geteilten Inhalten.

Wissenswertes

Technologien

Windows.ApplicationModel.DataTransfer

Voraussetzungen

Sie sollten mit Visual Studio und den zugehörigen Vorlagen vertraut sein.
Sie sollten mit JavaScript vertraut sein.

Anweisungen

Schritt 1: Unterstützen Sie den Freigabe-Vertrag.

Bevor die App freigegebene Inhalte empfangen kann, müssen Sie deklarieren, dass sie den Freigabe-Vertrag unterstützt. Dieser Vertrag informiert das System darüber, dass Ihre App für das Empfangen von Inhalten zur Verfügung steht. Wenn Sie die App mithilfe einer Microsoft Visual Studio-Vorlage erstellen, gehen Sie wie folgt vor, um den Zielfreigabe-Vertrag zu unterstützen:

Öffnen Sie die Manifestdatei (package.appxmanifest).
Öffnen Sie die Registerkarte Deklarationen.
Wählen Sie in der Liste Verfügbare Deklarationen die Option Zielfreigabe aus.
Klicken Sie auf Hinzufügen, um die Unterstützung für den Zielfreigabe-Vertrag in Ihrer App hinzuzufügen.

Schritt 2: Geben Sie die Dateitypen an, die Ihre App unterstützt.

Sie können die Dateitypen angeben, die Ihre App unterstützt, indem Sie die jeweiligen Erweiterungen im App-Manifest angeben:

Öffnen Sie die Manifestdatei.
Klicken Sie im Abschnitt Datenformate auf Neu hinzufügen.
Geben Sie die Dateinamenerweiterung an, etwa ".txt" (ohne Anführungszeichen).
Wiederholen Sie den vorherigen Schritt für jeden weiteren Dateityp.

Die vorhergehenden Schritte fügen dem Manifest den folgenden Abschnitt hinzu:

<Extensions>
  <Extension Category="windows.shareTarget">
    <ShareTarget>
      <SupportedFileTypes>
        <FileType>.txt</FileType>
    </ShareTarget>
  </Extension>
</Extensions>

Hinweis "StorageItems" müssen im Abschnitt mit den Datenformaten nicht angegeben werden. Die Unterstützung hierfür wird aus dem Abschnitt "SupportedFileTypes" im Manifest abgeleitet. Wenn Ihre App bestimmte Dateitypen unterstützt, können Sie sie im Manifest angeben, indem Sie Unterstützt alle Dateitypen aktivieren.

Hinweis Sie können einen anderen Einstiegspunkt angeben, wenn die App für den Zielfreigabe-Vertrag aktiviert ist. Ändern Sie dazu im Paketmanifest unter der Deklaration Zielfreigabe im Einstellungsabschnitt App den Seiteneintrag Start. Wir raten dringend dazu, außerdem eine gesonderte JavaScript-Datei zu verwenden, die die Aktivierung für diese Seite behandelt. Sehen Sie sich dazu das Beispiel zur Ziel-App für die Inhaltsfreigabe an.

Schritt 3: Hinzufügen eines Ereignishandlers zum Erkennen der App-Aktivierung

Wenn ein Benutzer Ihre App zum Freigeben von Inhalten verwendet, aktiviert das System die App. Da dies auf viele unterschiedliche Arten geschehen kann, müssen Sie Code hinzufügen, der erkennt, weshalb die Aktivierung stattgefunden hat. Überprüfen Sie dazu den Wert der kind-Eigenschaft.

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The application has been launched. Initialize as appropriate.
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        ...
    }
};

Schritt 4: Abrufen des ShareOperation-Objekts

Das ShareOperation-Objekt enthält alle Daten, die die App zum Abrufen der Inhalte benötigt, die der Benutzer freigeben möchte.

shareOperation = args.detail.shareOperation;

Schritt 5: Schnelle Rückgabe für aktivierten Ereignishandler

Der activated-Ereignishandler muss schnell zurückgegeben werden. Fügen Sie ein asynchrones Ereignis für den activated-Ereignishandler in die Warteschlange ein, damit die Freigabedaten nach Rückgabe des aktivierten Ereignisses verarbeitet werden.

WinJS.Application.addEventListener("shareready", shareReady, false);
WinJS.Application.queueEvent({ type: "shareready" });

Die verbleibenden Schritte implementieren die shareReady-Funktion.

Schritt 6: Überprüfen, ob die "DataPackageView" "StorageItems" enthält

Das ShareOperation-Objekt enthält ein DataPackageView-Objekt. Dieses Objekt ist eine schreibgeschützte Version des DataPackage-Objekts, das von der Quell-App zum Erstellen der Daten verwendet wurde. Stellen Sie mit diesem Objekt fest, ob der freigegebene Inhalt "StorageItems" enthält.

if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
    // Data being shared contains one or more StorageItem. Code to process the StorageItems goes here.
}

Es ist empfehlenswert, zu überprüfen, ob das DataPackage das Datenformat enthält, das Sie interessiert, selbst wenn Ihre App nur ein Format unterstützt. Dies erleichtert Ihnen die Arbeit, falls später andere Datenformate unterstützt werden sollen.

Schritt 7: Verarbeiten der Dateien

Rufen Sie zum Abrufen der Dateien die DataPackageView.GetStorageItemsAsync-Methode auf.

shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
    var fileList = "";
    for (var i = 0; i < storageItems.size; i++) {
        fileList += storageItems.getAt(i).name;
        if (i < storageItems.size - 1) {
            fileList += ", ";
        }
    }
    // In this example, we only display the file names. To do this, you need 
    // a <div> element with an id of "output" in your HTML page.

    // In your app, replace this with whatever is appropriate for your scenario.
    document.getElementById("output").innerText = "Files: " + fileList;
});

Hinweis

Das Verarbeiten von Dateien kann etwas Zeit beanspruchen. Zwingen Sie den Benutzer keinesfalls dazu zu warten, bis die App vollständig geladen und die Verarbeitung der Daten abgeschlossen ist. In Windows 8.1 können Sie die reportStarted-Methode aufrufen, um dem System mitzuteilen, dass die App mit der Verarbeitung der geteilten Inhalte begonnen hat. Das System hält die App aktiv, bis Sie reportCompleted— aufrufen, auch wenn der Benutzer die App schließt und zur Quell-App zurückkehrt. Weitere Informationen erhalten Sie in "Berichten über den Status bei verlängertem Teilen" in Schnellstart: Empfangen von geteilten Inhalten.

Schritt 8: Aufrufen von "reportCompleted"

Rufen Sie reportCompleted auf, wenn die App die Inhalte freigegebenen hat. Nachdem Sie diese Methode aufgerufen haben, schließt das System Ihre App.

shareOperation.reportCompleted();

Anmerkungen

Das Beispiel zur Ziel-App für die Inhaltsfreigabe veranschaulicht Code für den gesamten End-to-End-Vorgang für eine App, die bei einer Freigabe Text empfängt.

Vollständiges Beispiel

var shareOperation = null;

function shareReady(args) {
    if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.storageItems)) {
        shareOperation.data.getStorageItemsAsync().then(function (storageItems) {
            var fileList = "";
            for (var i = 0; i < storageItems.size; i++) {
                fileList += storageItems.getAt(i).name;
                if (i < storageItems.size - 1) {
                    fileList += ", ";
                }
            }
            // In this example, we only display the file names. To do this, you need 
            // a <div> element with an id of "output" in your HTML page.

            // In your app, replace this with whatever is appropriate for your scenario.
            document.getElementById("output").innerText = "Files: " + fileList;
        });
    }
}

app.onactivated = function (args) {
    if (args.detail.kind === activation.ActivationKind.launch) {
        // The app has been launched.
        args.setPromise(WinJS.UI.processAll());
    } else if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
        // This app was activated for the Share contract.
        args.setPromise(WinJS.UI.processAll());

        // We receive the ShareOperation object as part of the eventArgs.
        shareOperation = args.detail.shareOperation;

        // We queue an asychronous event so that working with the ShareOperation 
        // object does not block or delay the return of the activation handler.
        WinJS.Application.addEventListener("shareready", shareReady, false);
        WinJS.Application.queueEvent({ type: "shareready" });
    }
};