Receber dados

Este artigo explica como receber conteúdo em seu aplicativo da Plataforma Universal do Windows (UWP) compartilhado de outro aplicativo usando o contrato de Compartilhamento. Este contrato de Partilha permite que a sua aplicação seja apresentada como uma opção quando o utilizador invoca Partilhar.

Declarar seu aplicativo como um destino de compartilhamento

O sistema exibe uma lista de possíveis aplicativos de destino quando um usuário invoca Compartilhar. Para aparecer na lista, seu aplicativo precisa declarar que suporta o 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. Ele deve ser chamado de algo como package.appxmanifest.
2. Abra o separador Declarações.
3. Escolha Destino de Partilha 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 oferecem 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 o fizer, lembre-se de que as aplicações de origem têm de 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. Apenas as aplicações de destino que suportam os dados que estão a ser partilhados aparecem quando o utilizador invoca Partilhar.

Para definir tipos de ficheiro:

1. Abra o arquivo de manifesto. Ele deve ser chamado de algo como package.appxmanifest.
2. Na seção Tipos de Arquivo Suportados 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 período. Se você quiser oferecer 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 secção Formatos de Dados da página Declarações e, em seguida, selecioneAdicionar Novo .
3. Digite o nome do formato de dados suportado, por exemplo, "Texto".

Manipular a ativação de compartilhamento

Quando um utilizador seleciona a sua aplicação (geralmente ao selecioná-la numa lista de aplicações de destino disponíveis na interface de partilha do utilizador), um evento OnShareTargetActivated é gerado. Seu aplicativo precisa manipular 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 utilizador 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ório

Em alguns casos, pode levar 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 simples cadeia de texto, por isso levam mais tempo 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 dispense 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 adquiriu os dados necessários. Desta forma, o sistema pode suspender ou encerrar o aplicativo de origem, conforme necessário.

shareOperation.ReportSubmittedBackgroundTask(); 

Se algo correr mal, chame ReportError para enviar uma mensagem de erro para o 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 em seu aplicativo. Dependendo do 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."); 

Finalmente, 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 uma aplicação alvo pode chamar ReportDataRetrieved antes de ReportStarted. Por exemplo, a aplicação pode recuperar os dados como parte de uma tarefa no manipulador de ativação, mas não chamar ReportStarted até que o utilizador selecione um botão Compartilhar.

Retornar um QuickLink se a partilha tiver sido bem-sucedida

Quando um usuário seleciona seu aplicativo para receber conteúdo, recomendamos que você crie um QuickLink. Um QuickLink é como um atalho que facilita aos utilizadores partilhar informações com o seu aplicativo. Por exemplo, você pode criar um QuickLink que abra uma nova mensagem de email 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. O ID é o que seu aplicativo usa para acessar qualquer informação personalizada, como um endereço de e-mail ou credenciais de login. Quando a sua aplicação cria um QuickLink, a aplicação devolve o QuickLink ao sistema ao chamar ReportCompleted.

Na verdade, um QuickLink não armazena dados. Em vez disso, ele contém um identificador que, quando selecionado, é enviado para seu aplicativo. Seu aplicativo é responsável por armazenar a ID do QuickLink e os dados de usuário correspondentes. Quando o utilizador toca no QuickLink , pode-se obter o seu 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);
}

Ver também

• Comunicação entre aplicações
• Partilhar dados
• OnShareTargetActivated
• RelatórioIniciado
• ReportError
• Relatório Concluído
• ReportDataRecuperado
• RelatórioIniciado
• QuickLink
• QuickLinkId