Compartilhar dadosShare data

Este artigo explica como dar suporte ao contrato de Compartilhamento em um aplicativo da Plataforma Universal do Windows (UWP).This article explains how to support the Share contract in a Universal Windows Platform (UWP) app. O contrato de Compartilhamento é uma maneira fácil de compartilhar dados como texto, links, fotos e vídeos entre aplicativos rapidamente.The Share contract is an easy way to quickly share data, such as text, links, photos, and videos, between apps. Por exemplo, um usuário pode querer compartilhar uma página da Web com seus amigos usando um aplicativo de rede social ou salvar um link em um aplicativo de anotações para consultar mais tarde.For example, a user might want to share a webpage with their friends using a social networking app, or save a link in a notes app to refer to later.

Observação

Os exemplos de código neste artigo são escritos para aplicativos UWP.The code examples in this article are written for UWP apps. Os aplicativos de área de trabalho do WPF, Windows Forms e C++/Win32 devem usar a interface IDataTransferManagerInterop para obter o objeto datatransfermanager para uma janela específica.WPF, Windows Forms, and C++/Win32 desktop apps must use the IDataTransferManagerInterop interface to get the DataTransferManager object for a specific window. Para obter mais informações, consulte o exemplo de ShareName .For more information, see the ShareSource sample.

Configurar um manipulador de eventosSet up an event handler

Adicione um manipulador de eventos DataRequested para ser chamado sempre que um usuário invocar o compartilhamento.Add a DataRequested event handler to be called whenever a user invokes share. Isso pode ocorrer quando o usuário toca em um controle no aplicativo (por exemplo, um botão ou um comando da barra de aplicativos) ou automaticamente em um cenário específico (se o usuário terminar um nível e obtiver uma pontuação alta, por exemplo).This can occur either when the user taps a control in your app (such as a button or app bar command) or automatically in a specific scenario (if the user finishes a level and gets a high score, for example).

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

Quando ocorre um evento DataRequested, o app recebe um objeto DataRequest.When a DataRequested event occurs, your app receives a DataRequest object. Este contém um DataPackage que você pode usar para fornecer o conteúdo que o usuário quer compartilhar.This contains a DataPackage that you can use to provide the content that the user wants to share. Você deve fornecer um título e os dados a serem compartilhados.You must provide a title and data to share. Uma descrição é opcional, mas recomendada.A description is optional, but recommended.

DataRequest request = args.Request;

Escolher dadosChoose data

Você pode compartilhar vários tipos de dados, incluindo:You can share various types of data, including:

  • Texto sem formataçãoPlain text
  • URIs (Uniform Resource Identifiers)Uniform Resource Identifiers (URIs)
  • HTMLHTML
  • Texto formatadoFormatted text
  • BitmapsBitmaps
  • ArquivosFiles
  • Dados personalizados definidos pelo desenvolvedorCustom developer-defined data

O objeto DataPackage pode conter um ou mais desses formatos, em qualquer combinação.The DataPackage object can contain one or more of these formats, in any combination. O exemplo a seguir demonstra o compartilhamento de texto.The following example demonstrates sharing text.

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

Definir propriedadesSet properties

Ao empacotar dados para compartilhamento, você pode fornecer uma variedade de propriedades que dão informações adicionais sobre o conteúdo compartilhado.When you package data for sharing, you can supply a variety of properties that provide additional information about the content being shared. Essas propriedades podem ajudar os aplicativos de destino a melhorar a experiência do usuário.These properties help target apps improve the user experience. Por exemplo, uma descrição ajuda quando o usuário está compartilhando conteúdo com mais de um aplicativo.For example, a description helps when the user is sharing content with more than one app. A adição de uma miniatura ao compartilhar uma imagem ou um link para uma página da Web fornece uma referência visual ao usuário.Adding a thumbnail when sharing an image or a link to a web page provides a visual reference to the user. Para obter mais informações, consulte DataPackagePropertySet.For more information, see DataPackagePropertySet.

Todas as propriedades, exceto o título, são opcionais.All properties except the title are optional. A propriedade de título é obrigatória e deve ser definida.The title property is mandatory and must be set.

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

Iniciar a interface do usuário de compartilhamentoLaunch the share UI

Uma interface do usuário para compartilhamento é fornecida pelo sistema.A UI for sharing is provided by the system. Para iniciá-la, chame o método ShowShareUI.To launch it, call the ShowShareUI method.

DataTransferManager.ShowShareUI();

Tratar errosHandle errors

Na maioria dos casos, o compartilhamento de conteúdo é um processo simples e direto.In most cases, sharing content is a straightforward process. Contudo, há sempre a chance de algo inesperado acontecer.However, there's always a chance that something unexpected could happen. Por exemplo, o aplicativo pode exigir que o usuário selecione conteúdo para compartilhamento, mas o usuário não faz essa seleção.For example, the app might require the user to select content for sharing but the user didn't select any. Para lidar com essas situações, use o método FailWithDisplayText, que exibirá uma mensagem ao usuário se algo der errado.To handle these situations, use the FailWithDisplayText method, which will display a message to the user if something goes wrong.

Atrasar o compartilhamento com delegadosDelay share with delegates

Às vezes, pode não fazer sentido preparar imediatamente os dados que o usuário deseja compartilhar.Sometimes, it might not make sense to prepare the data that the user wants to share right away. Por exemplo, se o seu aplicativo oferece suporte ao envio de um arquivo de imagem grande em diversos formatos possíveis, é ineficiente criar todas essas imagens antes de o usuário fazer sua seleção.For example, if your app supports sending a large image file in several different possible formats, it's inefficient to create all those images before the user makes their selection.

Para resolver o problema, um DataPackage pode conter um delegado - uma função que é chamada quando o aplicativo de recebimento solicita dados.To solve this problem, a DataPackage can contain a delegate — a function that is called when the receiving app requests data. Recomendamos o uso de um delegado sempre que os dados que um usuário deseja compartilhar usarem muitos recursos.We recommend using a delegate any time that the data a user wants to share is resource-intensive.

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();
    }
}

Confira tambémSee also