如何接收文件 (HTML)

项目
12/11/2015

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

共享文件比共享更简单的数据类型（如文本）需要稍微多做一些准备。共享文件时，你需要考虑处理文件可能会花费多长时间。

如果你认为你的应用需要时间来处理用户希望共享的文件，请确保在开始处理这些文件之前调用 reportStarted。此方法确保系统使你的应用保持活动状态，直到你的应用完成处理为止。在你的应用完成其处理之后，请调用 reportCompleted 来完成共享操作。要了解详细信息，请参阅快速入门：接收共享内容中的"报告扩展共享状态"。

你需要了解的内容

技术

Windows.ApplicationModel.DataTransfer

先决条件

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

说明

步骤 1: 支持“共享”合约。

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

打开清单文件 (package.appxmanifest)。
打开“声明”选项卡。
从“可用声明”列表中，选择“共享目标”。****
单击“添加”****以在应用中添加到对共享目标协定的支持。

步骤 2: 指定你的应用支持的文件类型。

你可以通过在应用清单中指定你的应用的扩展来指定你的应用支持的文件类型：

打开清单文件。
在“数据格式”部分中，单击“新增”****。
键入文件名扩展名，如“.txt”（不包含引号）。
对于任何其他文件类型，请重复上一步骤。

前面的步骤将以下部分添加到清单中：

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

注意你不需要在“数据格式”部分中指定存储项。对存储项的支持是从清单中的 SupportedFileTypes 部分推断出来的。如果你的应用支持任何文件类型，那么你可以通过选中支持任何文件类型在清单中指定它们。

注意当为共享目标协定激活你的应用时，你可以指定一个不同的输入点。若要完成此操作，请在程序包清单中的“共享目标”声明的“应用设置”部分中修改“起始页”条目。****强烈建议你还使用一个单独的 JavaScript 文件来处理此页面的激活。例如，检查共享内容目标应用示例。

步骤 3: 添加要用来检测应用在何时激活的事件处理程序。

当用户选择你的应用来共享内容时，系统会激活你的应用。由于可通过许多方式实现该操作，因此你需要添加用来检测激活原因的代码。这可通过检查 kind 属性的值来完成。

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

步骤 4: 获取 ShareOperation 对象。

ShareOperation 对象包含你的应用为了获取用户要共享的内容而所需的全部数据。

shareOperation = args.detail.shareOperation;

步骤 5: 快速从已激活的事件处理程序返回。

activated 事件处理程序必须快速返回。将 activated 事件处理程序中的某个异步事件排入队列，这样共享数据处理会在已激活事件返回后发生。

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

剩下的步骤将实现 shareReady 函数。

步骤 6: 查明 DataPackageView 是否包含存储项。

ShareOperation 对象包含一个 DataPackageView 对象。DataPackageView 对象是源应用在创建数据时所使用的 DataPackage 对象的只读版本。使用此对象来查明正在共享的内容是否包含存储项。

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

检查 DataPackage 是否包含你感兴趣的数据格式是很好的做法，即使你的应用仅支持一种格式也是如此。这更便于在以后支持其他数据格式。

步骤 7: 处理文件。

要获取文件，请调用 DataPackageView.GetStorageItemsAsync 方法。

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

注意

处理文件可能会需要时间。重要的是，你不要强制用户等待你的应用完成加载和处理数据。在 Windows 8.1 上，你可以调用 reportStarted 方法以通知系统应用已开始处理正在共享的内容。即使用户关闭你的应用以返回到源应用，系统也会使你的应用保持活动状态，直到你调用 reportCompleted— 为止。要了解详细信息，请参阅快速入门：接收共享内容中的“报告扩展共享状态”。

步骤 8: 调用 reportCompleted。

在你的应用成功完成共享内容之后，请调用 reportCompleted。在你调用此方法之后，系统会关闭你的应用。

shareOperation.reportCompleted();

备注

检查我们的共享内容目标应用示例代码示例以了解应用作为共享的一部分接收文本的整个端对端体验。

完整示例

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