Schnellstart: Empfangen von geteilten Inhalten (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]

Diese Schnellstartanleitung führt Sie durch die Schritte zum Teilen von Inhalten mit einer anderen App.

Ziel: Sie erfahren, wie Sie geteilte Inhalte empfangen.

Voraussetzungen

Folgendes ist für die Verwendung des in diesem Abschnitt beschriebenen Codes erforderlich:

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

Anweisungen

1. Unterstützung des Freigabe-Vertrags

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 Visual Studio-Vorlage erstellen, gehen Sie wie folgt vor, um den Freigabe-Vertrag zu unterstützen:

Öffnen Sie die Manifestdatei. Ihr Name sollte package.appxmanifest lauten.
Öffnen Sie die Registerkarte Deklarationen.
Wählen Sie in der Liste Verfügbare Deklarationen die Option Zielfreigabe aus.

Weitere Informationen erhalten Sie in Elementvorlage "Zielfreigabe-Vertrag".

2. Angeben der unterstützten Dateitypen und Datenformate

Als Entwickler einer Ziel-App müssen Sie entscheiden, welche Dateitypen und Datenformate Sie unterstützen möchten. Gehen Sie wie folgt vor, um die unterstützten Dateitypen anzugeben:

Öffnen Sie die Manifestdatei.
Klicken Sie im Abschnitt Unterstützte Dateitypen der Seite Deklarationen auf Neue Hinzufügen.
Geben Sie die zu unterstützenden Dateinamenerweiterungen ein. Beispiel: .docx Sie müssen den Punkt (.) angeben.

Wenn Sie alle Dateitypen unterstützen möchten, aktivieren Sie das Feld SupportsAnyFileType.

Gehen Sie wie folgt vor, um die unterstützten Datenformate anzugeben:

Öffnen Sie die Manifestdatei.
Klicken Sie im Abschnitt Datenformate auf Neue hinzufügen.
Geben Sie den Namen des zu unterstützenden Datenformats ein. Beispiel: "Text".

Die Freigabe-APIs unterstützen verschiedene Standardformate wie Text, HTML und Bitmaps. Sie können auch benutzerdefinierte Dateitypen und Datenformate angeben. Denken Sie in solchen Fällen jedoch daran, dass die Quell-Apps wissen müssen, welcher Art diese Typen und Formate sind, da sie diese andernfalls nicht teilen.

3. Handhabung der Freigabeaktivierung

Wenn ein Benutzer Ihre App auswählt, wird ein activated-Anwendungsereignis ausgelöst. Ihre App muss dieses Ereignis handhaben, damit die Daten, die der Benutzer teilen möchte, verarbeitet werden können. Da ein activated-Ereignis aus verschiedenen Gründen ausgelöst werden kann, müssen Sie zunächst prüfen, ob der Grund für das Auslösen des Ereignisses die Freigabe von Daten ist.

if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
    // Code to handle activation goes here.
}

Die Daten, die ein Benutzer teilen möchte, sind in einem ShareOperation-Objekt enthalten. Mithilfe dieses Objekts können Sie das Format der enthaltenen Daten ermitteln. Im Folgenden finden Sie ein Beispiel für einen Ereignishandler, der geteilte Inhalte im Nur-Text-Format behandelt:

var shareOperation = eventObject.detail.shareOperation;
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
    shareOperation.data.getTextAsync().done(function (text) {
            // To output the text using this example, 
            // you need a div tag with an id of "output" in your HTML file.
            document.getElementById("output").innerText = text;
        }, function (e) {
            displayError("Error retrieving Text format: " + e);
        }
    });
}

4. Berichten über den Status bei verlängertem Teilen (bei längeren Vorgängen)

Hinweis

Die folgenden Schritte gelten nur für Windows Store-Apps. Sie können die folgenden Berichtsmethoden zwar auch unter Windows Phone 8.1 aufrufen, in diesem Fall werden jedoch keine Daten zurückgegeben.

In einigen Fällen kann es eine Weile dauern, bis Ihre App die Daten verarbeitet hat, die der Benutzer teilen möchte. Dies wird als verlängertes Teilen bezeichnet. Verlängertes Teilen tritt z. B. beim Austausch von Datei- oder Bildsammlungen auf. Diese Elemente sind größer als einfache Textzeichenfolgen, sodass auch ihre Verarbeitung länger dauert.

Hinweis Wenn Ihre App nur einfache Dinge wie Texte oder Hyperlinks empfangen kann, können Sie diesen Abschnitt überspringen.

Als Ziel-App sollte Ihre App Benutzer nicht dazu zwingen, sich mit der UI Ihrer App auseinanderzusetzen, nur weil sie mehr Zeit für die Handhabung von Daten benötigt. Verwenden Sie stattdessen das ShareOperation-Objekt, um das System darüber zu informieren, dass Ihre App noch ausgeführt wird. Auf diese Weise können Benutzer die UI der App verlassen und mit ihrer vorherigen Tätigkeit fortfahren. Währenddessen fährt Ihre App im Hintergrund mit der Datenverarbeitung fort.

shareOperation.reportStarted();

Nach dem Aufruf von reportStarted sollte Ihre App keine Benutzerinteraktion mehr verlangen. Sie sollten den Aufruf daher nur durchführen, wenn Ihre App vom Benutzer verlassen werden kann.

Beim verlängerten Teilen ist es möglich, dass der Benutzer die Quell-App beendet, bevor Ihre App alle Daten aus dem DataPackage-Objekt abgerufen hat. Es wird daher empfohlen, dass Sie das System informieren, wenn Ihre App die erforderlichen Daten erhalten hat. So kann das System die Quell-App ggf. anhalten oder beenden.

shareOperation.reportDataRetreived();

Falls ein Fehler auftritt, können Sie auch reportError aufrufen, um eine Fehlermeldung an das System zu senden. Den Benutzern wird die Meldung angezeigt, wenn sie den Status des Teilens überprüfen. Sobald Sie reportError aufrufen, wird Ihre App geschlossen und die Freigabe beendet. Der Benutzer muss von vorne beginnen und Ihrer App denselben Inhalt erneut freigeben. In Abhängigkeit vom Szenario können Sie entscheiden, dass ein bestimmter Fehler nicht schwerwiegend genug ist, um den Freigabevorgang zu beenden. In diesem Fall können Sie auswählen, dass reportError nicht aufgerufen und die Freigabe fortgesetzt wird.

shareOperation.reportError("Could not reach the server! Try again later.");

Wenn Sie diese Methoden verwenden, rufen Sie sie in der Regel in der angegebene Reihenfolge auf. Zudem können Sie die Methoden jeweils nur einmal aufrufen. Unter bestimmten Umständen kann reportDataRetrieved von einer Ziel-App jedoch vor reportStarted aufgerufen werden. Beispielweise können die Daten von der App im Rahmen einer Aufgabe des Aktivierungshandlers aufgerufen werden. reportStarted wird jedoch erst aufgerufen, wenn der Benutzer auf eine Schaltfläche zum Teilen klickt.

Zum Testen dieser Art der Freigabe verwenden Sie das Beispiel zur Ziel-App für die Inhaltsfreigabe.

5. Berichten über den Abschluss des Teilens

Zum Abschluss der erfolgreichen Verarbeitung der freigegebenen Daten durch Ihre App sollten Sie reportCompleted aufrufen.

shareOperation.reportCompleted();

Wenn Ihre App meldet, dass das Teilen abgeschlossen ist, wird sie beendet.

6. Zurückgeben eines QuickLink-Objekts nach erfolgreicher Freigabe

Hinweis

QuickLinks werden unter Windows Phone 8.1 nicht unterstützt. Windows Phone Store-Apps können QuickLinks zwar im Rahmen eines Vorgangs zum Teilen empfangen, sie werden jedoch automatisch ignoriert.

Wählt ein Benutzer Ihre App aus, um freigegebene Inhalte zu empfangen, sollten Sie einen QuickLink erstellen. Ein QuickLink ähnelt einer Verknüpfung, über die Benutzer leichter Informationen mit Ihrer App austauschen können. Ihre App könnte beispielsweise einen QuickLink erstellen, der eine neue E-Mail erstellt, die bereits die E-Mail-Adresse eines Freundes enthält.

Wählt ein Benutzer Ihre App aus, um freigegebene Inhalte zu empfangen, sollten Sie einen QuickLink erstellen. Ein QuickLink ist eine Verknüpfung, über die Benutzer leichter Informationen mit Ihrer App austauschen können. Ihre App könnte beispielsweise einen QuickLink erstellen, der eine neue E-Mail erstellt, die bereits die E-Mail-Adresse eines Freundes enthält.

Ein QuickLink muss über einen Titel, ein Symbol und eine ID verfügen. Der Titel (etwa "E-Mail an Mutter") und das Symbol werden angezeigt, wenn der Benutzer auf den Charm "Teilen" tippt. Die ID wird von Ihrer App dazu genutzt, herauszufinden, welcher QuickLink ausgewählt wurde. Wenn Ihre App einen QuickLink erstellt, gibt sie den QuickLink an das System zurück, indem sie die ShareOperation-Methode des reportCompleted-Objekts aufruft. Hier ist ein Beispiel:

function reportCompleted() {
    var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink();
    quickLink.id = "123456789";
    quickLink.title = id("quickLinkTitle").value;

    // For quicklinks, the supported FileTypes and DataFormats are set independently from the manifest.
    var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
    quickLink.supportedFileTypes.replaceAll(["*"]);
    quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, dataFormats.bitmap, 
        dataFormats.storageItems, dataFormats.html, customFormatName]);

    Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
        quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
        shareOperation.reportCompleted(quickLink);
    });
}

Vergessen Sie nicht, dass Ihre App selbst für das Speichern der ID für den QuickLink und die damit zusammenhängenden Benutzerdaten verantwortlich ist. Wenn der Benutzer auf den QuickLink tippt, können Sie seine ID über die ShareOperation.quickLinkId-Eigenschaft abrufen Falls eine Freigabe an einen QuickLink erfolgreich ist, sollten Sie denselben QuickLink beim Aufruf von reportCompleted zurückgeben.

Zusammenfassung und nächste Schritte

Sie sollten nun wissen, wie Sie geteilte Inhalte empfangen und einen QuickLink erstellen, mit dem Benutzer Inhalte über Ihre App teilen können.

Weitere Informationen oder spezifische Beispiele zum Hinzufügen der Funktion zum Teilen zur App finden Sie in folgenden Themen:

Hinweis Das Debuggen von Ziel-Apps zum Teilen unterscheidet sich vom Debuggen anderer Arten von Apps. Weitere Informationen erhalten Sie in Richtlinien zum Debuggen von Ziel-Apps.

Freigeben über