如何分享 HTML (HTML)

發行項
12/11/2015

[ 本文的目標對象是撰寫 Windows 執行階段 App 的 Windows 8.x 和 Windows Phone 8.x 開發人員。如果您正在開發適用於 Windows 10 的 App，請參閱最新文件 ]

分享 HTML 內容不同於其他基本格式，例如文字或連結。主要的難題是使用者選取的內容可能包含對其他元素的參照。支援分享 HTML 的應用程式需要考慮如何處理這些參照，以確保使用者分享想要的內容。

最能充分說明分享 HTML 難題的典型情況就是同時包含文字和影像的內容。當使用者選取這類內容並點選分享常用鍵時，他們預期會同時分享文字和影像。但是，HTML 並沒有包含影像，它包含的是指向影像位置的 img 標記。如果目標應用程式無法存取影像參考 (例如儲存在本機的影像)，您需要設定資源對應。

為了確保您可以使用者預期的方式來分享 HTML，Windows.ApplicationModel.DataTransfer 命名空間包含了一些函式，可協助擷取參照的元素 (如影像)。我們將為您示範如何進行。

您必須知道的事

技術

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: 將 HTML 新增到 DataPackage

若要新增 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());
    }
};