重新想象 Windows 8 Store Apps (39) - 契约: Share Contract
作者:webabcd
介绍
重新想象 Windows 8 Store Apps 之 契约
- Share Contract - 右侧边栏称之为 Charm,其中的“共享”称之为 Share Contract
示例
1、演示如何开发共享源
Contracts/ShareContract/ShareSource.xaml
<Page x:Class="XamlDemo.Contracts.ShareContract.ShareSource" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:local="using:XamlDemo.Contracts.ShareContract" xmlns:d="http://schemas.microsoft.com/expression/blend/2008" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="d"> <Grid Background="Transparent"> <StackPanel Margin="120 0 0 0"> <TextBlock Name="lblMsg" FontSize="14.667" /> <Button Content="Share Text" Click="Button_Click_1" Margin="0 10 0 0" /> <Button Content="Share Link" Click="Button_Click_1" Margin="0 10 0 0" /> <Button Content="Share Image" Click="Button_Click_1" Margin="0 10 0 0" /> <Button Content="Share File" Click="Button_Click_1" Margin="0 10 0 0" /> <Button Content="Share Html" Click="Button_Click_1" Margin="0 10 0 0" /> <Button Content="Share Custom Data" Click="Button_Click_1" Margin="0 10 0 0" /> <Button Content="Share With Deferral" Click="Button_Click_1" Margin="0 10 0 0" /> </StackPanel> </Grid> </Page>
Contracts/ShareContract/ShareSource.xaml.cs
/* * Share Contract - 右侧边栏称之为 Charm,其中的“共享”称之为 Share Contract * * 本例演示如何开发共享源 * 共享源 - 提供共享数据的 app * 共享目标 - 接收并处理共享数据的 app * 共享面板 - 点击“共享”后出来的,包含了一堆共享目标的面板 * * DataTransferManager - 共享数据管理器 * GetForCurrentView() - 返回当前窗口关联的 DataTransferManager 对象 * ShowShareUI() - 弹出共享面板,以开始共享操作 * DataRequested - 共享操作开始时(即弹出共享面板后)所触发的事件,事件参数为 DataTransferManager 和 DataRequestedEventArgs * TargetApplicationChosen - 选中了共享面板上的某个共享目标时所触发的事件,事件参数为 DataTransferManager 和 TargetApplicationChosenEventArgs * * TargetApplicationChosenEventArgs - TargetApplicationChosen 的事件参数 * ApplicationName - 选中的共享目标的名称 * * DataRequestedEventArgs - DataRequested 的事件参数 * Request - 返回 DataRequest 类型的数据 * * DataRequest - 一个对象,其包括了共享的内容和错误提示 * FailWithDisplayText() - 指定当共享操作失败时,需要在共享面板上显示的提示信息 * Data - 需要共享的内容,返回 DataPackage 对象 * * DataPackage - 共享内容(注:复制到剪切板的内容也是通过此对象来封装) * Properties - 返回 DataPackagePropertySetView 对象 * Properties.Title - 共享数据的标题 * Properties.Description - 共享数据的描述 * Properties.Thumbnail - 共享数据的缩略图 * Properties.FileTypes - 获取共享数据中包含的文件类型 * SetText(), SetUri(), SetHtmlFormat(), SetRtf(), SetBitmap(), SetStorageItems(), SetData(), SetDataProvider() - 设置需要共享的各种格式的数据,详细用法见下面的相关 demo(注:一个 DataPackage 可以有多种不同格式的数据) * ResourceMap - IDictionary<string, RandomAccessStreamReference> 类型,共享 html 时如果其中包含了本地资源的引用(如引用了本地图片),则需要通过 ResourceMap 传递 * GetView() - 返回 DataPackageView 对象,其相当于 DataPackage 的一个只读副本,详细说明见 ShareTarget.xaml.cs * 另:WebView.DataTransferPackage 会返回用户选中的内容的 DataPackage 对象,以便分享浏览器内的 html 内容 * * 异步共享: * 1、DataPackage 通过 SetDataProvider() 传递数据,其对应的委托的参数为一个 DataProviderRequest 类型的数据 * 2、DataProviderRequest.GetDeferral() 用于获取 DataProviderDeferral 对象以开始异步处理,然后通过 DataProviderDeferral.Complete() 通知 DataPackage 已经完成了异步操作 */ using System; using System.Collections.Generic; using System.Threading.Tasks; using Windows.ApplicationModel.DataTransfer; using Windows.Storage; using Windows.Storage.Pickers; using Windows.Storage.Streams; using Windows.UI.ViewManagement; using Windows.UI.Xaml; using Windows.UI.Xaml.Controls; using Windows.UI.Xaml.Navigation; using System.Linq; using Windows.Graphics.Imaging; namespace XamlDemo.Contracts.ShareContract { public sealed partial class ShareSource : Page { // 当前需要分享的内容的类型 private string _shareType = "Share Text"; // 需要分享的文件集合 private IReadOnlyList<StorageFile> _selectedFiles; public ShareSource() { this.InitializeComponent(); } protected override void OnNavigatedTo(NavigationEventArgs e) { // 初始化 DataTransferManager DataTransferManager dataTransferManager = DataTransferManager.GetForCurrentView(); dataTransferManager.DataRequested += dataTransferManager_DataRequested; dataTransferManager.TargetApplicationChosen += dataTransferManager_TargetApplicationChosen; } void dataTransferManager_DataRequested(DataTransferManager sender, DataRequestedEventArgs args) { // 共享操作开始时(即弹出共享面板后),根据需要分享的内容的类型执行指定的方法 switch (_shareType) { case "Share Text": ShareText(sender, args); break; case "Share Link": ShareLink(sender, args); break; case "Share Image": ShareImage(sender, args); break; case "Share File": ShareFile(sender, args); break; case "Share With Deferral": ShareWithDeferral(sender, args); break; case "Share Html": ShareHtml(sender, args); break; case "Share Custom Data": ShareCustomData(sender, args); break; default: break; } // 共享操作失败时,在共享面板上显示的提示信息 // args.Request.FailWithDisplayText("共享操作失败"); } void dataTransferManager_TargetApplicationChosen(DataTransferManager sender, TargetApplicationChosenEventArgs args) { // 显示用户需要与其共享内容的应用程序的名称 lblMsg.Text = "共享给:" + args.ApplicationName; } private async void Button_Click_1(object sender, RoutedEventArgs e) { _shareType = (sender as Button).Content.ToString(); // 如果需要共享文件,则提示用户选择文件 if (_shareType == "Share Image" || _shareType == "Share File" || _shareType == "Share With Deferral") { bool unsnapped = ((ApplicationView.Value != ApplicationViewState.Snapped) || ApplicationView.TryUnsnap()); if (unsnapped) { FileOpenPicker filePicker = new FileOpenPicker { ViewMode = PickerViewMode.List, SuggestedStartLocation = PickerLocationId.PicturesLibrary, FileTypeFilter = { "*" } // FileTypeFilter = { ".jpg", ".png", ".bmp", ".gif", ".tif" } }; _selectedFiles = await filePicker.PickMultipleFilesAsync(); if (_selectedFiles.Count > 0) { // 弹出共享面板,以开始共享操作 DataTransferManager.ShowShareUI(); } } } else { // 弹出共享面板,以开始共享操作 DataTransferManager.ShowShareUI(); } } // 共享文本的 Demo private void ShareText(DataTransferManager dtm, DataRequestedEventArgs args) { DataPackage dataPackage = args.Request.Data; dataPackage.Properties.Title = "Title"; dataPackage.Properties.Description = "Description"; dataPackage.SetText("需要分享的详细内容"); } // 共享超链的 Demo private void ShareLink(DataTransferManager dtm, DataRequestedEventArgs args) { DataPackage dataPackage = args.Request.Data; dataPackage.Properties.Title = "Title"; dataPackage.Properties.Description = "Description"; dataPackage.SetUri(new Uri("http://webabcd.cnblogs.com")); } // 共享图片的 Demo(关于如何为分享的图片减肥请参见本例的“异步共享的 Demo”) private void ShareImage(DataTransferManager dtm, DataRequestedEventArgs args) { DataPackage dataPackage = args.Request.Data; dataPackage.Properties.Title = "Title"; dataPackage.Properties.Description = "Description"; // 分享选中的所有文件中的第一个文件(假设其是图片) RandomAccessStreamReference imageStreamRef = RandomAccessStreamReference.CreateFromFile(_selectedFiles.First()); dataPackage.Properties.Thumbnail = imageStreamRef; dataPackage.SetBitmap(imageStreamRef); } // 共享文件的 Demo private void ShareFile(DataTransferManager dtm, DataRequestedEventArgs args) { DataPackage dataPackage = args.Request.Data; dataPackage.Properties.Title = "Title"; dataPackage.Properties.Description = "Description"; dataPackage.SetStorageItems(_selectedFiles); } // 共享 html 的 Demo private void ShareHtml(DataTransferManager dtm, DataRequestedEventArgs args) { string localImage = "ms-appx:///Assets/Logo.png"; string htmlExample = "<p><b>webabcd</b><img src=\"" + localImage + "\" /></p>"; // 为 html 添加共享所需的必要的标头,以保证可以正常进行 html 的共享操作 string htmlFormat = HtmlFormatHelper.CreateHtmlFormat(htmlExample); DataPackage dataPackage = args.Request.Data; dataPackage.Properties.Title = "Title"; dataPackage.Properties.Description = "Description"; dataPackage.SetHtmlFormat(htmlFormat); // 设置本地图像数据(如果需要共享的 html 包含本地图像,则只能通过这种方法共享之) RandomAccessStreamReference streamRef = RandomAccessStreamReference.CreateFromUri(new Uri(localImage)); dataPackage.ResourceMap[localImage] = streamRef; /* * 以下演示如何共享 WebView 中的被用户选中的 html * 具体可参见:Controls/WebView/Share.xaml * DataPackage dataPackage = WebView.DataTransferPackage; DataPackageView dataPackageView = dataPackage.GetView(); if ((dataPackageView != null) && (dataPackageView.AvailableFormats.Count > 0)) { dataPackage.Properties.Title = "Title"; dataPackage.Properties.Description = "Description"; args.Request.Data = dataPackage; } */ } // 共享自定义数据的 Demo private void ShareCustomData(DataTransferManager dtm, DataRequestedEventArgs args) { DataPackage dataPackage = args.Request.Data; dataPackage.Properties.Title = "Title"; dataPackage.Properties.Description = "Description"; // 指定需要分享的自定义数据,第一个参数是自定义数据的格式 id(注:标准格式 id 在 Windows.ApplicationModel.DataTransfer.StandardDataFormats 枚举) // 要让自定义数据可以正常分享,需要在 Package.appxmanifest 中的“共享目标”声明中对自定义格式 id 做相应的配置,以及在 SourceTarget 对自定义格式 id 做相应的处理 dataPackage.SetData("http://webabcd/sharedemo", "自定义数据"); } // 异步共享的 Demo(在共享内容需要较长时间才能计算出来的场景下,应该使用异步共享) private void ShareWithDeferral(DataTransferManager dtm, DataRequestedEventArgs args) { DataPackage dataPackage = args.Request.Data; dataPackage.Properties.Title = "Title"; dataPackage.Properties.Description = "Description"; dataPackage.Properties.Thumbnail = RandomAccessStreamReference.CreateFromFile(_selectedFiles.First()); // 通过委托来提供共享数据,当用户点击了共享目标后会调用此委托,即不马上提供共享数据,而是等到用户点击了共享目标后再异步准备数据 dataPackage.SetDataProvider(StandardDataFormats.Bitmap, providerRequest => this.OnDeferredImageRequestedHandler(providerRequest, _selectedFiles.First())); } // 用户点击了共享目标后会调用此方法 private async void OnDeferredImageRequestedHandler(DataProviderRequest providerRequest, StorageFile imageFile) { // 获取 DataProviderDeferral,以开始异步处理,即在此之后允许调用 await 方法 DataProviderDeferral deferral = providerRequest.GetDeferral(); InMemoryRandomAccessStream inMemoryStream = new InMemoryRandomAccessStream(); try { // 将用户选中的图片缩小一倍,然后再共享 IRandomAccessStream imageStream = await imageFile.OpenAsync(FileAccessMode.Read); BitmapDecoder imageDecoder = await BitmapDecoder.CreateAsync(imageStream); 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(); // 停 3 秒,以模拟长时间任务 await Task.Delay(3000); providerRequest.SetData(RandomAccessStreamReference.CreateFromStream(inMemoryStream)); } finally { // 通知 DataPackage 已经完成了共享数据的准备 deferral.Complete(); } } } }
2、演示如何开发共享目标
Contracts/ShareContract/ShareTarget.xaml
<Page x:Class="XamlDemo.Contracts.ShareContract.ShareTarget" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:local="using:XamlDemo.Contracts.ShareContract" xmlns:d="http://schemas.microsoft.com/expression/blend/2008" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="d"> <Grid Background="#438bdf"> <ScrollViewer Name="scrollView" Margin="120 0 0 0"> <StackPanel> <TextBlock Name="lblMsg" FontSize="14.667" /> <Image Name="imgThumbnail" Margin="0 10 0 0" /> <Image Name="imgBitmap" Margin="0 10 0 0" /> <Button Content="新增一个 QuickLink,并完成共享操作" Click="Button_Click_1" Margin="0 10 0 0" /> </StackPanel> </ScrollViewer> </Grid> </Page>
Contracts/ShareContract/ShareTarget.xaml.cs
/* * Share Contract - 右侧边栏称之为 Charm,其中的“共享”称之为 Share Contract * * 本例演示如何开发共享目标 * 1、在 Package.appxmanifest 中新增一个“共享目标”声明,并做相关配置 * 2、在 App.xaml.cs 中 override void OnShareTargetActivated(ShareTargetActivatedEventArgs args),以获取相关的共享信息 * * ShareTargetActivatedEventArgs - 当 app 由共享激活时的事件参数 * ShareOperation - 返回一个 ShareOperation 类型的对象 * PreviousExecutionState - 此 app 被共享激活前的执行状态(ApplicationExecutionState 枚举:NotRunning, Running, Suspended, Terminated, ClosedByUser) * SplashScreen - 启动画面对象 * * ShareOperation - 共享操作的相关信息 * Data - 返回 DataPackageView 对象,其相当于 DataPackage 的一个只读副本 * QuickLinkId - 如果是 QuickLink 激活的,此属性可获取此 QuickLink 的 Id * RemoveThisQuickLink() - 如果是 QuickLink 激活的,此方法可删除此 QuickLink * ReportCompleted() - 通知系统共享操作已经完成(会自动关闭共享面板),需要的话可以指定一个需要增加的 QuickLink 对象 * ReportStarted(), ReportDataRetrieved(), ReportError(), ReportSubmittedBackgroundTask() - 顾名思义的一些方法,用不用皆可,它们的作用是可以帮助系统优化资源的使用 * * DataPackage 对象的只读版本,从剪切板获取数据或者共享目标接收数据均通过此对象来获取 DataPackage 对象的数据 * AvailableFormats - DataPackage 中数据所包含的所有格式 * Contains() - 是否包含指定格式的数据 * Properties - 返回 DataPackagePropertySetView 对象,就是由共享源所设置的一些信息,参见 ShareSource.xaml.cs * GetTextAsync(), GetUriAsync(), GetRtfAsync(), GetHtmlFormatAsync(), GetBitmapAsync(), GetStorageItemsAsync(), GetDataAsync(), GetResourceMapAsync() - 获取共享过来的各种格式的数据,详细用法见下面的相关 demo(注:一个 DataPackage 可以有多种不同格式的数据) * * QuickLink - 预定义了一些数据,指向相应共享目标的一个快捷方式,其会出现在共享面板的上部 * Id - 预定义数据 * Title - QuickLink 出现在共享面板上的时候所显示的名称 * Thumbnail - QuickLink 出现在共享面板上的时候所显示的图标 * SupportedDataFormats - 共享数据中所包含的数据格式与 SupportedDataFormats 定义的相匹配(两个集合中的元素有一个匹配即可),QuickLink 才会出现在共享面板上 * SupportedFileTypes - 共享数据中所包含的文件的扩展名与 SupportedDataFormats 定义的相匹配(两个集合中的元素有一个匹配即可),QuickLink 才会出现在共享面板上 * * QuickLink 的适用场景举例 * 1、当用户总是共享信息到某一个邮件地址时,便可以此邮件地址为 QuickLinkId 生成一个 QuickLink * 2、下回用户再想共享信息到此邮件地址时,就可点此 QuickLink 来启动共享操作 * 3、共享目标被 QuickLink 激活后便可以解析 QuickLink 中的 Id,即用户需要共享到的邮件地址,从而避免用户输入此邮件地址,从而方便用户的共享操作 */ using System; using System.Collections.Generic; using System.Threading.Tasks; using Windows.ApplicationModel; using Windows.ApplicationModel.Activation; using Windows.ApplicationModel.DataTransfer; using Windows.ApplicationModel.DataTransfer.ShareTarget; using Windows.Storage; using Windows.Storage.Streams; using Windows.UI.Core; using Windows.UI.Popups; using Windows.UI.Xaml.Controls; using Windows.UI.Xaml.Media.Imaging; using Windows.UI.Xaml.Navigation; namespace XamlDemo.Contracts.ShareContract { public sealed partial class ShareTarget : Page { private ShareOperation _shareOperation; public ShareTarget() { this.InitializeComponent(); } protected async override void OnNavigatedTo(NavigationEventArgs e) { // 获取 ShareOperation 对象 ShareTargetActivatedEventArgs shareTargetActivated = (ShareTargetActivatedEventArgs)e.Parameter; if (shareTargetActivated == null) { lblMsg.Text = "为了演示共享目标,请从共享源激活本页面"; return; } _shareOperation = shareTargetActivated.ShareOperation; // 异步获取共享数据 await Task.Factory.StartNew(async () => { // 显示共享数据中相关信息 OutputMessage("QuickLinkId: " + _shareOperation.QuickLinkId); OutputMessage("Title: " + _shareOperation.Data.Properties.Title); OutputMessage("Description: " + _shareOperation.Data.Properties.Description); ShowThumbnail(_shareOperation.Data.Properties.Thumbnail); // 如果共享数据中包含 Text 格式数据,则显示之 if (_shareOperation.Data.Contains(StandardDataFormats.Text)) { try { var text = await _shareOperation.Data.GetTextAsync(); OutputMessage("Text: " + text); } catch (Exception ex) { OutputMessage(ex.ToString()); } } // 如果共享数据中包含 Uri 格式数据,则显示之 if (_shareOperation.Data.Contains(StandardDataFormats.Uri)) { try { var uri = await _shareOperation.Data.GetUriAsync(); OutputMessage("Uri: " + uri.AbsoluteUri); } catch (Exception ex) { OutputMessage(ex.ToString()); } } // 如果共享数据中包含 Bitmap 格式数据,则显示之 if (_shareOperation.Data.Contains(StandardDataFormats.Bitmap)) { try { IRandomAccessStreamReference stream = await _shareOperation.Data.GetBitmapAsync(); ShowBitmap(stream); } catch (Exception ex) { OutputMessage(ex.ToString()); } } // 如果共享数据中包含 Html 格式数据,则显示之 if (_shareOperation.Data.Contains(StandardDataFormats.Html)) { try { // 获取 html 数据 var html = await _shareOperation.Data.GetHtmlFormatAsync(); OutputMessage("Html: " + html); // 获取 html 中包含的本地资源的引用(如引用的本地图片等),其数据在分享源的 DataPackage.ResourceMap 中设置 IReadOnlyDictionary<string, RandomAccessStreamReference> sharedResourceMap = await _shareOperation.Data.GetResourceMapAsync(); } catch (Exception ex) { OutputMessage(ex.ToString()); } } // 如果共享数据中包含 StorageItems 格式数据,则显示之 if (_shareOperation.Data.Contains(StandardDataFormats.StorageItems)) { try { var storageItems = await _shareOperation.Data.GetStorageItemsAsync(); foreach (var storageItem in storageItems) { OutputMessage("storageItem: " + storageItem.Path); } } catch (Exception ex) { OutputMessage(ex.ToString()); } } // 如果共享数据中包含“http://webabcd/sharedemo”格式数据,则显示之 if (_shareOperation.Data.Contains("http://webabcd/sharedemo")) { try { var customData = await _shareOperation.Data.GetTextAsync("http://webabcd/sharedemo"); OutputMessage("Custom Data: " + customData); } catch (Exception ex) { OutputMessage(ex.ToString()); } } }); } // 在 UI 上输出指定的信息 async private void OutputMessage(string message) { await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () => { lblMsg.Text += message; lblMsg.Text += Environment.NewLine; }); } // 显示图片 async private void ShowThumbnail(IRandomAccessStreamReference thumbnail) { await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, async () => { if (thumbnail != null) { IRandomAccessStreamWithContentType thumbnailStream = await thumbnail.OpenReadAsync(); BitmapImage bitmapImage = new BitmapImage(); bitmapImage.SetSource(thumbnailStream); imgThumbnail.Source = bitmapImage; } }); } // 显示图片 async private void ShowBitmap(IRandomAccessStreamReference bitmap) { await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, async () => { if (bitmap != null) { IRandomAccessStreamWithContentType bitmapStream = await bitmap.OpenReadAsync(); BitmapImage bitmapImage = new BitmapImage(); bitmapImage.SetSource(bitmapStream); imgBitmap.Source = bitmapImage; } }); } // 演示如何增加一个 QuickLink private async void Button_Click_1(object sender, Windows.UI.Xaml.RoutedEventArgs e) { QuickLink quickLink = new QuickLink { Id = "我是预定义数据,避免用户再次输入", Title = "QuickLink Title", SupportedFileTypes = { "*" }, SupportedDataFormats = { StandardDataFormats.Text, StandardDataFormats.Uri, StandardDataFormats.Bitmap, StandardDataFormats.StorageItems, StandardDataFormats.Html, "http://webabcd/sharedemo" } }; try { // 设置 QuickLink 的图标 StorageFile iconFile = await Package.Current.InstalledLocation.CreateFileAsync("Assets\\Logo.png", CreationCollisionOption.OpenIfExists); quickLink.Thumbnail = RandomAccessStreamReference.CreateFromFile(iconFile); // 完成共享操作,同时增加一个指定的 QuickLink _shareOperation.ReportCompleted(quickLink); } catch (Exception ex) { OutputMessage(ex.ToString()); } } } }
3、通过共享激活应用程序
App.xaml.cs
// 通过共享激活应用程序时所调用的方法 protected override void OnShareTargetActivated(ShareTargetActivatedEventArgs args) { var rootFrame = new Frame(); rootFrame.Navigate(typeof(MainPage), args); Window.Current.Content = rootFrame; Window.Current.Activate(); }
OK
[源码下载]