如何共享 HTML (HTML)
[ 本文适用于编写 Windows 运行时应用的 Windows 8.x 和 Windows Phone 8.x 开发人员。如果你要针对 Windows 10 进行开发,请参阅 最新文档 ]
共享 HTML 内容不同于共享其他基本格式(如文本或链接)。遇到的主要挑战是,用户选择的内容可能会包含对其他元素的引用。支持 HTML 共享的应用需要考虑如何处理这些引用以确保用户能够共享他们要共享的内容。
演示共享 HTML 的挑战的典型情形是同时包含文本和图像的内容。当用户选择此内容并点击“共享”超级按钮之后,他们期望同时共享文本和图像。但是,HTML 不包含图像,而只包含指向图像所在位置的一个 img 标记。如果图像参考对于某个目标应用(如某个本地存储的图像)不是可访问的,那么你需要设置一个资源映射。
若要帮助确保你可以按用户期望的方式共享 HTML,则 Windows.ApplicationModel.DataTransfer 命名空间包含一些函数,这些函数可帮助捕获引用的元素,如图像。我们将向你展示具体做法。
你需要了解的内容
技术
先决条件
- 你应当熟悉 Visual Studio 及其关联模板。
- 你应当熟悉 JavaScript。
- 你应当了解如何使用 JavaScript 来标识用户已选择的 HTML,并找到该选择范围内子元素(如 Img 标记)的实例。
说明
步骤 1: 将你的应用设置为共享源
DataTransferManager 对象是任何共享操作的主起点。当用户想要调用“共享”时,添加要引发的 DataRequested 事件处理程序。在 Windows 应用商店应用中,当用户调用“共享”超级按钮时,将自动执行此操作。如果你面向 Windows Phone 进行开发,则没有内置的“共享”超级按钮,因此你将需要为用户添加一个控件,以便点击和触发该处理程序。
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareHtmlHandler);
剩下的步骤用于实现 shareHtmlHandler
函数。
步骤 2: 获取 DataRequest 对象
当发生 datarequested 事件时,你的应用会收到 DataRequest 对象。该对象包含的 DataPackage 可用来提供用户要共享的内容。
var request = e.request;
步骤 3: 设置标题和描述属性。
request.data.properties.title = "Share Html Example";
request.data.properties.description =
"Demonstrates how to share an HTML fragment with a local image.";
步骤 4: 使用 createHtmlFormat 方法可设置片段的格式
createHtmlFormat 函数使用标头和系统共享内容所需的其他信息覆盖 HTML 格式。
var localImage = "ms-appx:///images/logo.png";
var htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
var htmlFormat =
Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.createHtmlFormat(htmlExample);
步骤 5: 向 DataPackage 中添加 HTML
若要添加 HTML,请使用 setHtmlFormat 函数。
request.data.setHtmlFormat(htmlFormat);
步骤 6: 创建本地图像的 RandomAccessStreamReference
var streamRef =
Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(new Windows.Foundation.Uri(localImage));
步骤 7: 向资源映射中添加 RandomAccessStreamReference
若要添加图像文件,请使用 resourceMap 属性。
request.data.resourceMap[localImage] = streamRef;
如果被共享的 HTML 片段中包含多个本地图像,则你需要对每个本地图像都重复执行此步骤。
完整示例
下面是用来设置可供用户共享的一些 HTML 的函数的示例。有关更完整的示例,请查阅我们的代码库示例。
function shareHtmlHandler(e) {
var localImage = "ms-appx:///images/logo.png";
var htmlExample = "<p>Here is a local image: <img src=\"" + localImage + "\">.</p>";
var request = e.request;
request.data.properties.title = "Share Html Example";
request.data.properties.description = "Demonstrates how to share an HTML fragment with a local image.";
var htmlFormat = Windows.ApplicationModel.DataTransfer.HtmlFormatHelper.createHtmlFormat(htmlExample);
request.data.setHtmlFormat(htmlFormat);
var streamRef = Windows.Storage.Streams.RandomAccessStreamReference.createFromUri(new Windows.Foundation.Uri(localImage));
request.data.resourceMap[localImage] = streamRef;
}
app.onactivated = function (args) {
if (args.detail.kind === activation.ActivationKind.launch) {
if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
// This app is newly launched; register the app as a share source.
var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
dataTransferManager.addEventListener("datarequested", shareHtmlHandler);
} else {
// TODO: This app was reactivated from suspension.
// Restore the app state here.
}
args.setPromise(WinJS.UI.processAll());
}
};