快速入门:共享内容 (HTML)

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

成功的应用应该能够让用户轻松地与其家人和朋友即时共享他们的活动。能够让用户轻松共享内容的应用往往会获得更多的关注,从而鼓励用户更频繁地使用这些应用。

若要了解如何这些 API 的信息,请继续阅读。如果你更希望了解如何让你的应用接收共享的内容,请参阅快速入门:接收共享内容

目标: 阅读此快速入门后,你应当了解了如何共享内容。

先决条件

  • 你应当熟悉 Visual Studio 及其模板。
  • 你应当熟悉在 HTML 和 JavaScript 中开发。

说明

选择数据格式

所有共享操作的核心均为 DataPackage 对象。此对象包含用户想要共享的数据。DataPackage 可以包含的内容类型包括:

  • 纯文本
  • 统一资源标识符 (URI)
  • HTML
  • 格式化的文本
  • 位图
  • 文件
  • 开发人员定义的数据

DataPackage 对象可以包含其中一种或多种格式(可任意组合)。此外,DataPackage 可以包含委托 — 一种在接收应用请求数据时调用的函数。我们建议你在用户想要共享的数据很消耗资源时使用委托,因为它可帮助你的应用更高效地共享数据。

选择属性

当你打包数据进行共享时,可以给出各种可提供与共享内容相关的其他信息的属性。利用好这些属性可帮助目标应用改善用户体验。例如,用户与多个应用共享内容时,提供表达用户共享内容的标题和说明会很有帮助。共享图像或指向网页的链接时,添加一个缩略图可为用户提供直观的参考。有关提供哪些属性可使用的详细信息,请查看有关 DataPackage.DataPackagePropertySet 的文档。

设置共享源

若要将你的应用程序设置为共享源应用,首先需要获取已分配给当前窗口的 DataTransferManager 类的实例。

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();

该类支持 DataRequested 事件,当用户想要调用“共享”超级按钮时会触发该事件。在 Windows 应用商店应用中,当用户调用“共享”超级按钮时,将自动执行此操作。如果你面向 Windows Phone 进行开发,则没有内置的“共享”超级按钮,因此你将需要为用户添加一个控件,以便点击和触发该处理程序。

dataTransferManager.addEventListener("datarequested", function (e) {
    // Code to handle event goes here.
});

上面的示例会注册一个事件处理程序,无论何时引发 datarequested 事件时都会调用该事件处理程序。该处理程序会接收 DataRequest 对象,你的应用使用此对象设置用户要在你的共享源应用中共享的数据。

你共享的任何内容必须包含两个属性:标题和内容本身。 此外,为了更加清晰,我们还建议你包含一个描述属性。

下列代码以之前的示例为基础,并显示如何与目标应用共享纯文本。

function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareTextHandler);
}

function shareTextHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Text Example";
    request.data.properties.description = "Demonstrates how to share text.";
    request.data.setText("Hello World!");
}

共享和委托

有时,当用户调用共享时,立即准备数据是不可取的。例如,如果你的应用支持若干种不同的数据格式,则立即创建所有这些格式会降低效率。最好是等待目标应用指定它需要的格式,然后再生成数据。要实现此目的,你可通过在收到请求时进行委托调用来配置 DataPackage 对象仅填充需要的数据。

request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);

要了解关于此类型共享的详细信息,请查看如何共享文件

以编程方式调用共享窗格

为共享设置你的内容后,就可以开始了。用户只需选择用来接收内容的应用即可。在某些情况下,如共享游戏中的高分时,使用超级按钮并非最佳选择。你也可以以编程方式启动“共享”超级按钮。

注意  

Windows Phone 8.1 上不存在 Charms bar,因此你必须通过编程方式包括共享选项。它在任何情况下均可作为应用栏的一部分而被访问,也可与特定页面上的指定控件相关联。

function showShareUI() {
    Windows.ApplicationModel.DataTransfer.DataTransferManager.showShareUI();
}

处理错误及其他问题

大多数情况下,提供内容是一个简单直接的过程。但是,会存在你的应用可能无法共享的情形。为了帮助你处理这些情况,在 Windows 上 8.1,DataRequest 对象支持 FailWithDisplayText 方法。如果用户无法从某个特定视图共享,或者需要在共享之前执行其他步骤,请使用此方法向用户显示一条文本消息。例如,应用可能需要用户选择用于共享的内容,但用户未选择任何内容。

摘要和后续步骤

你现在应当了解共享如何工作了。

要了解更多,或获取有关如何向应用添加共享的更具体示例,请查阅:

相关主题

选择用于共享的数据格式

内容共享指南和清单

快速入门:接收共享内容