共用方式為

接收資料

  • 發行項

本文介紹如何使用「共用」合約接收從其他應用共用的通用 Windows 平台 (UWP) 應用程式中的內容。 此分享協定可讓使用者叫用 [分享] 時，將應用程式顯示為選項。

將您的應用程式宣告為共用目標

當使用者叫用 Share 時，系統會顯示可能的目標應用程式清單。 若要出現在清單上，您的應用程式必須宣告其支援共用合約。 這可讓系統知道您的應用程式可用來接收內容。

  1. 開啟資訊清單檔案。 它應該稱為 package.appxmanifest 之類的專案。
  2. 開啟宣告索引標籤。
  3. 從可用宣告清單中選擇共用目標，然後選取新增。

選擇檔案類型和格式

接下來，決定您支援的檔案類型和資料格式。 共用 API 支援數種標準格式，例如 Text、HTML 和 Bitmap。 您也可以指定自訂檔案類型和資料格式。 如果您這麼做，請記住來源應用程式必須知道這些類型和格式為何；否則，這些應用程式無法使用格式來共用資料。

只註冊您的應用程式可以處理的格式。 只有在使用者叫用 Share 時，才會顯示支援共用資料的目標應用程式。

若要設定檔案類型：

  1. 開啟資訊清單檔案。 它應該稱為 package.appxmanifest 之類的專案。
  2. 在宣告頁面的支援的檔案類型區段中，選取新增新的。
  3. 輸入您想要支持的副檔名，例如「.docx」。需要包含期間。 如果您想要支援所有檔案類型，請選取 SupportsAnyFileType 核取方塊。

若要設定資料格式：

  1. 開啟資訊清單檔案。
  2. 開啟宣告頁面的資料格式區段，然後選取新增新的。
  3. 輸入您支持的資料格式名稱，例如「Text」。

處理共用啟用

當使用者選取您的應用程式時 (通常是從共用 UI 中的可用目標應用程式清單中選取它)，就會引發 OnShareTargetActivated 事件。 您的應用程式必須處理此事件，才能處理使用者想要共用的資料。

protected override async void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
{
    // Code to handle activation goes here. 
}

使用者想要共用的資料會包含在 ShareOperation 物件中 您可以使用這個物件來檢查它所包含的資料格式。

ShareOperation shareOperation = args.ShareOperation;
if (shareOperation.Data.Contains(StandardDataFormats.Text))
{
    string text = await shareOperation.Data.GetTextAsync();

    // To output the text from this example, you need a TextBlock control
    // with a name of "sharedContent".
    sharedContent.Text = "Text: " + text;
}

報告共用狀態

在某些情況下，您的應用程式可能需要時間來處理想要共用的資料。 範例包括共用檔案或影像集合的使用者。 這些項目大於簡單的文字字串，因此需要較長的時間來處理。

shareOperation.ReportStarted();

呼叫 ReportStarted 之後，請勿預期會再與您的應用程式互動。 因此，除非您的應用程式位於使用者可關閉的某個時間點，否則您不應該呼叫它。

使用擴充共用時，使用者可能會在應用程式擁有 DataPackage 物件中的所有資料之前關閉來源應用程式。 因此，我們建議您讓系統知道應用程式何時取得所需的資料。 如此一來，系統就可以視需要暫停或終止來源應用程式。

shareOperation.ReportSubmittedBackgroundTask();

如果發生錯誤，請呼叫 ReportError 將錯誤訊息傳送至系統。 使用者會在檢查共用的狀態時看到訊息。 此時，您的應用程式已關閉，且共用已結束。 共用必須再次啟動，才能將內容共用至您的應用程式。 視您的案例而定，您可能會決定特定錯誤不夠嚴重，無法結束共用作業。 在此情況下，您可以選擇不要呼叫 ReportError，並繼續共用。

shareOperation.ReportError("Could not reach the server! Try again later.");

最後，當您的應用程式成功處理共用內容時，您應該呼叫 ReportCompleted 讓系統知道。

shareOperation.ReportCompleted();

當您使用這些方法時，通常會依照剛才描述的順序呼叫它們，而且您不會多次呼叫它們。 不過，有時候目標應用程式可以在 ReportStarted 之前呼叫 ReportDataRetrieved。 例如，應用程式可能會擷取資料做為啟用處理常式中工作的一部分，但直到使用者選取 Sharee 按鈕，才會呼叫 ReportStarted。

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

QuickLink 必須有標題、圖示和識別碼。當使用者點選共用魅力時，會出現標題 (例如「電子郵件媽媽」) 和圖示。 識別碼是您應用程式用來存取任何自訂資訊的內容，例如電子郵件地址或登入認證。 當您的應用程式建立 QuickLink 時，應用程式會透過呼叫 ReportCompleted 將 QuickLink 傳回系統。

QuickLink 實際上不會儲存資料。 相反地，它會包含識別碼，當選取時，會傳送至您的應用程式。 您的應用程式負責儲存 QuickLink 的識別碼和對應的使用者資料。 當使用者點選 QuickLink 時，您可以透過 QuickLinkId 屬性來取得其 Id。

async void ReportCompleted(ShareOperation shareOperation, string quickLinkId, string quickLinkTitle)
{
    QuickLink quickLinkInfo = new QuickLink
    {
        Id = quickLinkId,
        Title = quickLinkTitle,

        // For quicklinks, the supported FileTypes and DataFormats are set 
        // independently from the manifest
        SupportedFileTypes = { "*" },
        SupportedDataFormats = { StandardDataFormats.Text, StandardDataFormats.Uri, 
                StandardDataFormats.Bitmap, StandardDataFormats.StorageItems }
    };

    StorageFile iconFile = await Windows.ApplicationModel.Package.Current.InstalledLocation.CreateFileAsync(
            "assets\\user.png", CreationCollisionOption.OpenIfExists);
    quickLinkInfo.Thumbnail = RandomAccessStreamReference.CreateFromFile(iconFile);
    shareOperation.ReportCompleted(quickLinkInfo);
}

另請參閱