Receba dados partilhados na sua aplicação Windows

O contrato Windows Share permite que a sua aplicação apareça na Folha de Partilha do Windows como uma aplicação alvo — permitindo que os utilizadores partilhem conteúdos de outras aplicações diretamente para a sua. Este artigo explica como gerir o conteúdo partilhado assim que a sua aplicação é ativada como alvo de partilha.

Antes de seguir os passos aqui, registe a sua aplicação como share target:

Observação

O modelo de ativação para aplicações de desktop WinUI 3 difere do UWP. No WinUI 3, a ativação de partilhas é feita através AppInstance.GetActivatedEventArgs() do código de arranque da sua aplicação — não via Application.OnShareTargetActivated(). As ShareOperation APIs e DataPackageView descritas neste artigo funcionam da mesma forma depois de obter o ShareTargetActivatedEventArgs. Consulte Integrar aplicações empacotadas com o Windows Share para obter o modelo de ativação do SDK de Aplicações Windows.

Escolha formatos de dados para suportar

Quando declara a sua aplicação como alvo de partilha no seu manifesto de pacote, especifica que tipos de ficheiros e formatos de dados a sua aplicação pode receber. Apenas as aplicações que suportam os formatos partilhados aparecem na Folha de Partilha.

Pode configurar os tipos suportados de duas formas:

Usando o editor de manifestos do Visual Studio:

  1. Abra package.appxmanifest no Visual Studio.
  2. Selecione o separador Declarações .
  3. Escolhe Share Target na lista de Declarações Disponíveis , depois seleciona Adicionar.
  4. Em Tipos de Ficheiro Suportados, adicione as extensões de ficheiro que a sua aplicação gere (por exemplo, .jpg, .png). Selecione SupportsAnyFileType para aceitar todos os tipos de ficheiros.
  5. Em Formatos de Dados, adicione os nomes dos formatos que a sua aplicação gere (por exemplo, Text, Uri, Bitmap).

Diretamente no XML do manifesto:

<Extensions>
  <uap:Extension Category="windows.shareTarget">
    <uap:ShareTarget>
      <uap:SupportedFileTypes>
        <uap:SupportsAnyFileType />
      </uap:SupportedFileTypes>
      <uap:DataFormat>Text</uap:DataFormat>
      <uap:DataFormat>Uri</uap:DataFormat>
      <uap:DataFormat>Bitmap</uap:DataFormat>
      <uap:DataFormat>StorageItems</uap:DataFormat>
    </uap:ShareTarget>
  </uap:Extension>
</Extensions>

Registre-se apenas para formatos que seu aplicativo pode manipular. Se declarar um formato mas não conseguir processá-lo, a experiência do utilizador sofre.

Ler dados partilhados

Quando a sua aplicação é ativada como destino de partilha, recebe um objeto ShareOperation através de ShareTargetActivatedEventArgs. A sua Data propriedade é um DataPackageView que expõe o conteúdo partilhado.

Use Contains para verificar quais os formatos disponíveis, depois chame o método assíncrono apropriado para recuperar os dados:

ShareOperation shareOperation = args.ShareOperation;

if (shareOperation.Data.Contains(StandardDataFormats.Text))
{
    string text = await shareOperation.Data.GetTextAsync();
    // Process the shared text.
}

if (shareOperation.Data.Contains(StandardDataFormats.WebLink))
{
    Uri webLink = await shareOperation.Data.GetWebLinkAsync();
    // Process the shared link.
}

if (shareOperation.Data.Contains(StandardDataFormats.StorageItems))
{
    IReadOnlyList<IStorageItem> items = await shareOperation.Data.GetStorageItemsAsync();
    // Process the shared files or folders.
}

Status de compartilhamento de relatório

Se o processamento dos dados partilhados demorar — por exemplo, carregar ficheiros para um servidor — reporte o progresso ao sistema usando os métodos de estado ShareOperation . Isto permite ao sistema gerir adequadamente o ciclo de vida da aplicação de origem.

Chame estes métodos pela ordem indicada à medida que a sua operação de partilha progride:

Method Quando ligar
RelatórioIniciado Assim que a sua aplicação começar a processar a partilha. Depois deste ponto, não esperes mais interação do utilizador com a interface de partilha.
ReportDataRecuperado Depois de a sua aplicação ter obtido todos os dados necessários do DataPackageView. Isto permite ao sistema suspender ou terminar a aplicação de origem.
RelatórioSubmetidoTarefa de Antecedentes Se a tua aplicação continuar a processar em segundo plano depois de a interface de partilha ser encerrada.
Relatório Concluído Quando a sua aplicação terminar de processar com sucesso o conteúdo partilhado.
ReportError Se ocorrer um erro grave. O utilizador vê a mensagem e a operação de partilha termina. 
shareOperation.ReportStarted();

try
{
    string text = await shareOperation.Data.GetTextAsync();
    shareOperation.ReportDataRetrieved();

    // Perform any additional processing here...
    await ProcessSharedDataAsync(text);

    shareOperation.ReportCompleted();
}
catch (Exception)
{
    shareOperation.ReportError("Something went wrong. Please try again.");
}

Observação

Chame ReportError apenas em caso de erros graves o suficiente para encerrar a operação de partilha. Para erros recuperáveis, pode continuar a processar sem chamar ReportError.

Observação

Existem casos em que uma aplicação de destino pode invocar ReportDataRetrieved antes de ReportStarted — por exemplo, se a sua aplicação recuperar dados como parte do processamento da ativação, mas só invocar ReportStarted mais tarde, quando o utilizador seleciona explicitamente um botão Partilhar.

Quando um utilizador partilha conteúdo na sua aplicação, pode devolver um QuickLink para tornar a partilha futura mais rápida. A QuickLink aparece como um atalho na Folha de Partilha — por exemplo, um atalho de contacto que permite ao utilizador partilhar rapidamente com esse contacto novamente sem ter de navegar pela interface da sua aplicação.

A QuickLink tem um título, um ícone e um ID. O ID é o identificador interno da sua aplicação para o atalho — como um ID de contacto ou nome da conta. Quando o utilizador seleciona posteriormente um QuickLink, o sistema ativa a sua aplicação e devolve o ID de QuickLink através de ShareOperation.QuickLinkId.

Retorne a QuickLink passando para ReportCompleted:

private async Task ReportCompletedWithQuickLink(
    ShareOperation shareOperation, string quickLinkId, string quickLinkTitle)
{
    QuickLink quickLinkInfo = new QuickLink
    {
        Id = quickLinkId,
        Title = quickLinkTitle,

        // QuickLink supported types are configured independently from the manifest.
        SupportedFileTypes = { "*" },
        SupportedDataFormats =
        {
            StandardDataFormats.Text,
            StandardDataFormats.WebLink,
            StandardDataFormats.Bitmap,
            StandardDataFormats.StorageItems
        }
    };

    StorageFile iconFile = await Windows.ApplicationModel.Package.Current
        .InstalledLocation.CreateFileAsync(
            "assets\\contact.png", CreationCollisionOption.OpenIfExists);
    quickLinkInfo.Thumbnail = RandomAccessStreamReference.CreateFromFile(iconFile);

    shareOperation.ReportCompleted(quickLinkInfo);
}

Observação

A QuickLink armazena apenas o ID — não os dados associados. A sua aplicação é responsável por persistir quaisquer dados do utilizador (como dados de contacto) e recuperá-los quando este QuickLink for ativado via ShareOperation.QuickLinkId.

Consulte também

  • Last updated on