共用方式為

共用資料

  • 發行項

本文介紹如何在桌面或通用 Windows 平台 (UWP) 應用程式中支援共用合約。 「共用」合約是在應用程式之間快速共用資料 (如文字、連結、相片和影片) 的簡單方法。 例如，使用者可能會想要使用社交網路應用程式與他們的朋友共用網頁，或將連結儲存在筆記應用程式中以供稍後參考。

注意

本文中的程式碼範例來自 UWP 應用程式。 傳統型應用程式應該使用 IDataTransferManagerInterop。 有關詳細資訊和代碼示例，請參閱 顯示依賴於 CoreWindow 的 WinRT UI 物件。 另請參閱 WPF 共用內容來源應用程式範例。

設定事件處理常式

新增一個 DataRequested 事件處理常式，以便在使用者叫用共用時呼叫。 當使用者點選您應用程式中的控制項 (例如按鈕或應用程式列命令) 或在特定案例中自動點選控制項時，就會發生這種情況 (例如，如果使用者完成一層級並取得高分)。

DataTransferManager dataTransferManager = DataTransferManager.GetForCurrentView();
dataTransferManager.DataRequested += DataTransferManager_DataRequested;

當 DataRequested 事件發生時，您的應用程式會收到一個 DataRequest 物件。 這包含一個 DataPackage，可用來提供使用者想要共用的內容。 您必須提供要共用的標題和資料。 描述是選擇性的，但建議使用。

DataRequest request = args.Request;

選擇資料

您可以共用各種類型的資料，包括：

  • 純文字
  • 統一資源識別碼 (URI)
  • HTML
  • 格式化文字
  • 點陣圖
  • 檔案
  • 自訂開發人員定義的資料

DataPackage 物件可以採取任何組合，包含一或多個這些格式。 以下範例示範如何共用文字。

request.Data.SetText("Hello world!");

設定屬性

當您封裝資料以供共用時，您可以提供各種屬性，以提供共用內容的其他資訊。 這些屬性可協助目標應用程式改善使用者體驗。 例如，描述可協助使用者在與多個應用程式共用內容時。 在共用影像或網頁的連結時新增縮圖，可提供使用者的視覺參考。 如需詳細資訊，請參閱 DataPackagePropertySet。

警告

除了標題以外的所有屬性都是選擇性的。 標題屬性是必要屬性，而且必須設定。

request.Data.Properties.Title = "Share Example";
request.Data.Properties.Description = "A demonstration on how to share";

啟動共用 UI

系統會提供共用的 UI。 若要啟動它，請呼叫 ShowShareUI 方法。

DataTransferManager.ShowShareUI();

處理錯誤

在大部分情況下，共用內容是一個直接的程序。 不過，總有可能發生意外的情況。 例如，應用程式可能需要使用者選取內容以供共用，但使用者未選取任何內容。 若要處理這些情況，請使用 FailWithDisplayText 方法，這會在發生錯誤時向使用者顯示訊息。

延遲與委派共用

有時候，準備使用者想要立即共用的資料可能沒有意義。 例如，如果您的應用程式支援以數種不同的格式傳送大型影像檔，則使用者在選取這些影像之前，建立所有這些影像效率不佳。

若要解決此問題，DataPackage 可以包含委派，這是接收應用程式要求資料時所呼叫的函式。 每當使用者想要共用的資料需要大量資源時，建議使用委派。

async void OnDeferredImageRequestedHandler(DataProviderRequest request)
{
    // Provide updated bitmap data using delayed rendering
    if (this.imageStream != null)
    {
        DataProviderDeferral deferral = request.GetDeferral();
        InMemoryRandomAccessStream inMemoryStream = new InMemoryRandomAccessStream();

        // Decode the image.
        BitmapDecoder imageDecoder = await BitmapDecoder.CreateAsync(this.imageStream);

        // Re-encode the image at 50% width and height.
        BitmapEncoder imageEncoder = await BitmapEncoder.CreateForTranscodingAsync(inMemoryStream, imageDecoder);
        imageEncoder.BitmapTransform.ScaledWidth = (uint)(imageDecoder.OrientedPixelWidth * 0.5);
        imageEncoder.BitmapTransform.ScaledHeight = (uint)(imageDecoder.OrientedPixelHeight * 0.5);
        await imageEncoder.FlushAsync();

        request.SetData(RandomAccessStreamReference.CreateFromStream(inMemoryStream));
        deferral.Complete();
    }
}

另請參閱