快速入门：接收共享内容 (HTML)

项目
12/11/2015

[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发，请参阅最新文档 ]

此快速入门将带你完成从另一个应用接收共享内容所需的步骤。

目标: 了解如何接收共享内容

先决条件

要使用本部分所述的代码：

你应当熟悉 Visual Studio 及其关联模板。
你应当熟悉 JavaScript。

说明

1. 支持“共享”合约。

你必须首先声明你的应用支持“共享”合约，然后你的应用才能接收共享内容。此合约让系统知道你的应用可用于接收内容。如果你使用 Visual Studio 模板创建应用，以下是支持“共享”合约的方法：

打开清单文件。该文件的名称应为 package.appxmanifest。
打开“声明”选项卡。
从“可用声明”列表中，选择“共享目标”。****

要了解详细信息，请参阅共享目标协定项模板。

2. 指定你支持的文件类型和数据格式

作为目标应用开发人员，你需要决定你希望支持哪些文件类型和数据格式。若要指定你支持的文件类型，请执行以下操作：

打开清单文件。
在“声明”页的“支持的文件类型”部分，单击“新增”。
键入要支持的文件扩展名。例如，.docx。你需要包括句点 (.)。

如果希望支持所有文件类型，请选中“支持所有文件类型”框。

若要指定你支持的数据格式，请执行以下操作：

打开清单文件。
在“数据格式”****部分中，单击“新增”。
键入支持的数据格式的名称。例如，"文本"。

共享 API 支持多种标准格式，如文本、HTML 和位图。你还可以指定自定义文件类型和数据格式。指定时，请记住源应用必须知道这些类型和格式是什么；否则这些应用无法共享该类型的数据。

3. 处理共享激活

当用户选择你的应用时，会触发应用程序 activated 事件。你的应用需要处理此事件来处理用户要共享的数据。由于可能触发 activated 事件的原因有很多，你需要做的第一件事情是检查事件的原因是否为共享数据。

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

用户要共享的数据包含在一个 ShareOperation 对象中。你可以使用该对象来检查所包含数据的格式。以下是处理纯文本格式的共享内容的事件处理程序的一个示例：

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. 报告扩展共享状态（针对耗时操作）

注意

以下步骤仅适用于 Windows 应用商店应用。你可以在下面调用来自 Windows Phone 8.1 的报告方法，但不会返回任何数据。

在某些情况下，你的应用可能需要花费一定时间来处理用户要共享的数据。我们将这些共享实例称为扩展共享。扩展共享的示例包括用户共享文件或图像的集合。这些项目比简单的文本字符串大，因此处理时间较长。

注意如果你的应用仅可以接收简单的文本或超链接，则可以跳过本部分。

作为目标应用，你的应用不应只是因为它需要更多时间来处理数据，就迫使用户查看你的应用的 UI。你应当使用 ShareOperation 对象让系统获知你的应用仍在工作。那样，用户可以关闭你的应用的 UI 并返回到他们正在进行的事项。同时，你的应用继续在后台处理数据。

shareOperation.reportStarted();

在调用 reportStarted 之后，将不再有任何与你的应用所进行的用户交互。因此，你不应该调用它，除非你的应用处于可以由用户关闭的位置。

使用扩展共享时，用户有可能会在你的应用获得来自 DataPackage 对象的所有数据之前关闭源应用。因此，我们建议你让系统知道你的应用何时已获得它所需的数据。这样，系统可以根据需要暂停或终止源应用。

shareOperation.reportDataRetreived();

如果发生错误，你还可以调用 reportError 向系统发送一条错误消息。用户在检查共享的状态时将看到该消息。只要你调用 reportError，你的应用就会关闭并且结束共享—用户将需要重新开始才能将同一内容共享给你的应用。根据你的方案，你可能确定某个特殊错误并不严重，不足以结束共享操作。在这种情况下，你可以选择不调用 reportError 并且继续此共享。

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

通常在使用这些方法时，请确保按照所述的顺序来进行调用，并且你无法多次调用它们。然而在某些时候，目标应用可能会在调用 reportStarted 之前调用 reportDataRetrieved。例如，应用可能在激活处理程序中执行任务时检索数据，但不调用 reportStarted，直到用户单击“共享”按钮之后才调用。

要了解此类型共享的实际应用，请查看我们的共享内容目标应用示例。

5. 报告共享已完成

最后，当你的应用成功处理好共享内容之后，你应当调用 reportCompleted。

shareOperation.reportCompleted();

在你的应用报告共享完成之后，你的应用会被关闭。

6. 如果共享成功，则返回 QuickLink 对象

注意

QuickLink 在 Windows Phone 8.1 中不受支持。Windows Phone 应用商店应用可以将 QuickLink 接收为共享操作的一部分，但这些 QuickLink 会被自动忽略。

当用户选择你的应用来接收共享内容时，我们强烈建议你创建一个 QuickLink。QuickLink 类似于快捷方式，可让用户更轻松地使用你的应用共享信息。例如，你的应用可以创建一个 QuickLink，用来打开预配置了好友电子邮件地址的新邮件。

当用户选择你的应用来接收共享内容时，我们强烈建议你创建一个 QuickLink。QuickLink 是一个快捷方式，可让用户更轻松地使用你的应用共享信息。例如，你的应用可以创建一个 QuickLink，用来打开预配置了好友电子邮件地址的新邮件。

QuickLink 必须包含标题、图标和 ID。当用户点击“共享”超级按钮时，会显示标题（如“Email Mom”）和图标。ID 是你的应用用于标识所选择的 QuickLink 的标识符。当你的应用创建 QuickLink 时，该应用会通过调用 ShareOperation 对象的 reportCompleted 方法，将 QuickLink 返回到系统。下面是一个示例：

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);
    });
}

请记住，你的应用负责存储 QuickLink 的 ID 及相应的用户数据。当用户点击 QuickLink 时，你可以通过 ShareOperation.quickLinkId 属性获取其 ID。当到 QuickLink 的共享成功之后，你应该在调用 reportCompleted 时返回相同的 QuickLink。

摘要和后续步骤

现在，对于如何接收共享内容，以及如何创建 QuickLink 来帮助用户使用你的应用共享内容，你应该有了一个清晰的了解。

要了解更多，或获取有关如何向应用添加共享的更具体示例，则需要查阅：

注意调试共享目标应用与调试其他种类的应用不同。要了解详细信息，请参阅调试目标应用指南。

通过