Receber dados

  • Artigo

Este artigo explica como receber conteúdo em seu aplicativo UWP (Plataforma Universal do Windows) compartilhado de outro aplicativo usando o contrato de compartilhamento. Este contrato de Compartilhamento permite que seu aplicativo seja apresentado como uma opção quando o usuário invoca o compartilhamento.

Declarar seu aplicativo como um destino de compartilhamento

O sistema exibe uma lista de possíveis aplicativos de destino quando um usuário invoca Share. Para aparecer na lista, seu aplicativo precisa declarar que dá suporte ao contrato de compartilhamento. Isso permite que o sistema saiba que seu aplicativo está disponível para receber conteúdo.

  1. Abra o arquivo de manifesto. Deve ser chamado de algo como package.appxmanifest.
  2. Abra a guia Declarações .
  3. Escolha Compartilhar Destino na lista Declarações Disponíveis e selecione Adicionar.

Escolha tipos e formatos de arquivo

Em seguida, decida quais tipos de arquivo e formatos de dados você suporta. As APIs de compartilhamento dão suporte a vários formatos padrão, como texto, HTML e bitmap. Você também pode especificar tipos de arquivo e formatos de dados personalizados. Se você fizer isso, lembre-se de que os aplicativos de origem precisam saber quais são esses tipos e formatos; caso contrário, esses aplicativos não poderão usar os formatos para compartilhar dados.

Registre-se apenas para formatos que seu aplicativo pode manipular. Somente os aplicativos de destino que dão suporte aos dados que estão sendo compartilhados aparecem quando o usuário invoca Compartilhar.

Para definir tipos de arquivo:

  1. Abra o arquivo de manifesto. Deve ser chamado de algo como package.appxmanifest.
  2. Na seção Tipos de Arquivo com Suporte da página Declarações, selecione Adicionar Novo.
  3. Digite a extensão de nome de arquivo que você deseja suportar, por exemplo, ".docx". Você precisa incluir o ponto. Se você quiser dar suporte a todos os tipos de arquivo, marque a caixa de seleção SupportsAnyFileType .

Para definir formatos de dados:

  1. Abra o arquivo de manifesto.
  2. Abra a seção Formatos de Dados da página Declarações e selecione Adicionar Novo.
  3. Digite o nome do formato de dados compatível, por exemplo, "Texto".

Manipular a ativação de compartilhamento

Quando um usuário seleciona seu aplicativo (geralmente selecionando-o em uma lista de aplicativos de destino disponíveis na interface do usuário de compartilhamento), um evento OnShareTargetActivated é gerado. Seu aplicativo precisa lidar com esse evento para processar os dados que o usuário deseja compartilhar.

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

Os dados que o usuário deseja compartilhar estão contidos em um objeto ShareOperation . Você pode usar esse objeto para verificar o formato dos dados que ele contém.

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

Status de compartilhamento de relatórios

Em alguns casos, pode levar algum tempo para que seu aplicativo processe os dados que deseja compartilhar. Os exemplos incluem usuários compartilhando coleções de arquivos ou imagens. Esses itens são maiores do que uma cadeia de caracteres de texto simples, portanto, demoram mais para serem processados.

shareOperation.ReportStarted();

Depois de chamar ReportStarted, não espere mais interação do usuário com seu aplicativo. Como resultado, você não deve chamá-lo, a menos que seu aplicativo esteja em um ponto em que possa ser descartado pelo usuário.

Com um compartilhamento estendido, é possível que o usuário ignore o aplicativo de origem antes que seu aplicativo tenha todos os dados do objeto DataPackage. Como resultado, recomendamos que você informe ao sistema quando seu aplicativo tiver adquirido os dados necessários. Dessa forma, o sistema pode suspender ou encerrar o aplicativo de origem conforme necessário.

shareOperation.ReportSubmittedBackgroundTask();

Se algo der errado, chame ReportError para enviar uma mensagem de erro ao sistema. O usuário verá a mensagem quando verificar o status do compartilhamento. Nesse ponto, seu aplicativo é desligado e o compartilhamento é encerrado. O usuário precisará começar novamente para compartilhar o conteúdo com seu aplicativo. Dependendo do seu cenário, você pode decidir que um erro específico não é grave o suficiente para encerrar a operação de compartilhamento. Nesse caso, você pode optar por não chamar ReportError e continuar com o compartilhamento.

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

Por fim, quando seu aplicativo tiver processado com êxito o conteúdo compartilhado, você deverá chamar ReportCompleted para informar o sistema.

shareOperation.ReportCompleted();

Quando você usa esses métodos, geralmente os chama na ordem descrita e não os chama mais de uma vez. No entanto, há momentos em que um aplicativo de destino pode chamar ReportDataRetrieved antes de ReportStarted. Por exemplo, o aplicativo pode recuperar os dados como parte de uma tarefa no manipulador de ativação, mas não chamar ReportStarted até que o usuário selecione um botão Compartilhar .

Quando um usuário seleciona seu aplicativo para receber conteúdo, recomendamos que você crie um QuickLink. Um QuickLink é como um atalho que facilita o compartilhamento de informações com seu aplicativo pelos usuários. Por exemplo, você pode criar um QuickLink que abre uma nova mensagem de e-mail pré-configurada com o endereço de e-mail de um amigo.

Um QuickLink deve ter um título, um ícone e um Id. O título (como "Enviar e-mail para a mãe") e o ícone aparecem quando o usuário toca no botão Compartilhar. A ID é o que seu aplicativo usa para acessar qualquer informação personalizada, como um endereço de email ou credenciais de login. Quando seu aplicativo cria um QuickLink, o aplicativo retorna o QuickLink para o sistema chamando ReportCompleted.

Um QuickLink não armazena dados. Em vez disso, ele contém um identificador que, quando selecionado, é enviado ao seu aplicativo. Seu aplicativo é responsável por armazenar o ID do QuickLink e os dados do usuário correspondentes. Quando o usuário toca no QuickLink, você pode obter sua ID por meio da propriedade QuickLinkId.

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

Confira também