快速入門：接收分享的內容 (HTML)

發行項
12/11/2015

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

這個快速入門會逐步引導您執行從另一個應用程式接收分享內容的必要步驟。

目標: 了解如何接收分享內容。

先決條件

若要使用本節所述的程式碼：

您應該熟悉 Visual Studio 以及相關範本。
您應該熟悉 JavaScript。

指示

1. 支援分享協定。

您的應用程式可以接收分享的內容之前，必須先宣告它支援分享協定。這個協定會讓系統知道您的應用程式能夠接收內容。如果您使用 Visual Studio 範本建立應用程式，以下是支援分享協定的方法：

開啟資訊清單檔案。檔案名稱應該是 package.appxmanifest。
開啟 [宣告] 索引標籤。
從 [可用宣告]**** 清單中選擇 [共用目標]。

若要深入了解，請參閱共用目標合約項目範本。

2. 指定您支援的檔案類型和資料格式

身為目標應用程式開發人員，您需要決定想要支援的檔案類型和資料格式。如果要指定您支援的檔案類型：

開啟資訊清單檔案。
在 [宣告]**** 頁面的 [支援的檔案類型] 區段中，按一下 [加入新的]****。
輸入想要支援的副檔名。例如，.docx。您必須加上句點 (.)。

如果想要支援所有檔案類型，請選取 [SupportsAnyFileType] 方塊。

如果要指定您支援的資料格式：

開啟資訊清單檔案。
在 [資料格式]**** 區段中，按一下 [加入新的]。
輸入支援的資料格式名稱。例如，"文字"。

分享 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.");

您通常會依照上述順序呼叫這些方法，而且您不可以呼叫它們一次以上。不過，有時目標應用程式可能會先呼叫 reportDataRetrieved，之後才呼叫 reportStarted。例如，應用程式可能會在啟用處理常式的工作期間抓取資料，但直到使用者按一下 [分享] 按鈕後才會呼叫 reportStarted。

若要查看這種分享類型的使用方式，請參閱我們的分享內容目標應用程式範例。

5. 報告分享已經完成

最後，當您的應用程式順利處理完分享內容時，應該呼叫 reportCompleted。

shareOperation.reportCompleted();

當應用程式報告分享完成後，就會關閉您的應用程式。

6. 如果分享成功，則傳回 QuickLink 物件

注意

Windows Phone 8.1 不支援 QuickLinks。Windows Phone 市集應用程式可以接收 QuickLink 做為分享作業的一部分，但是它們會自動被忽略。

當使用者選取您的應用程式來接收分享內容時，強烈建議您建立一個 QuickLink。QuickLink 就像捷徑，可讓使用者方便與您的應用程式分享資訊。例如，您的應用程式可以建立一個 QuickLink，以開啟已預先設定朋友電子郵件地址的新電子郵件訊息。

當使用者選取您的應用程式來接收分享內容時，強烈建議您建立一個 QuickLink。QuickLink 是一個捷徑，可讓使用者方便與您的應用程式分享資訊。例如，您的應用程式可以建立一個 QuickLink，以開啟已預先設定朋友電子郵件地址的新電子郵件訊息。

QuickLink 必須包含標題、圖示以及識別碼。當使用者點選分享常用鍵時，就會出現標題 (如「Email Mom」) 和圖示。識別碼可讓應用程式識別所選的 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 的識別碼及對應的使用者資料。當使用者點選 QuickLink 時，您可以透過 ShareOperation.quickLinkId 屬性取得它的 ID。順利分享到 QuickLink 時，呼叫 reportCompleted 應該會傳回相同的 QuickLink。

摘要與後續步驟

現在您應該清楚知道如何接收分享內容，以及如何建立 QuickLink，以協助使用者與您的應用程式分享內容。

如果要深入了解如何將分享新增到應用程式，或需要更多相關特定範例，您可以參考：

注意對共用目標應用程式偵錯不同於對其他種類的應用程式偵錯。若要深入了解，請參閱對目標應用程式偵錯的指導方針。