Guia de início rápido: noções básicas sobre área de transferência (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Os melhores aplicativos dão aos usuários o máximo possível de controle sobre dados. Um método de controle que os usuários esperam é operações com a área de transferência. Estas operações permitem que os usuários cortem, copiem e colem dados. As operações na área de transferência podem ocorrer no mesmo aplicativo ou entre dois aplicativos diferentes no mesmo computador. Com a área de transferência, os usuários podem colocar facilmente informações que precisam onde precisam.

Mais de uma forma de compartilhar dados

Antes de discutirmos como adicionar operações de área de transferência ao seu aplicativo, lembre-se de que o Windows 8 dá suporte a várias maneiras de mover dados. Fornecemos uma visão geral desses métodos em Compartilhando e trocando dados. Uma destas formas, compartilhamento, tem muito em comum com a área de transferência. Da perspectiva de um desenvolvedor, o compartilhamento e as operações da área de transferência usam o mesmo espaço de nome do Windows, Windows.ApplicationModel.DataTransfer. Ambas também exigem que o seu aplicativo colete os dados que um usuário seleciona. (Frequentemente chamamos isso de empacotamento, porque você usa a classe DataPackage para fazer isso.) Da perspectiva de um usuário, a área de transferência representa a forma "clássica" de mover dados.

Como desenvolvedor, você deve estar ciente de que, embora o compartilhamento e as operações da área de transferência sejam muito semelhantes, eles possuem diferenças importantes. Ao compartilhar, o foco está no destino: o aplicativo ou serviço que o usuário seleciona. Já na área de transferência, o foco está mais nos dados. Mais importante, as operações da área de transferência são a única forma de trocar dados entre um aplicativo da área de trabalho e um aplicativo da Windows Store.

Para obter mais informações sobre as diferenças entre o compartilhamento e as operações da área de transferência, consulte Compartilhar e trocar dados.

Suporte interno da área de transferência

Em muitos casos, você pode não precisar escrever nenhum código para suportar operações da área da transferência. Muitos dos controles que você pode usar para criar o seu aplicativo da Windows Store já permitem operações na área da transferência. Para obter mais informações sobre quais controles estão disponíveis, consulte Adicionando controles e conteúdo.

Antes de iniciar

Adicionando suporte ao seu aplicativo para operações da área da transferência é bem simples. Em primeiro lugar, consulte Diretrizes e lista de verificação para comandos da área de transferência. Você encontrará ali muitas informações que podem ajudá-lo a criar a melhor experiência do usuário para operações na área de transferência, assim como algumas ideias que podem ajudá-lo a tirar o máximo de seu código.

Em seguida, você precisa considerar quais tipos de formatos de dados quer suportar. No Windows 8, há duas categorias de formatos: padrão e personalizado. Atualmente, os formatos padrão incluem:

Texto
HTML
URI
Bitmaps
StorageItems
RTF

Para ver um exemplo das operações da área de transferência que usam estes formatos de dados, consulte nosso exemplo de código. Você também pode desejar consultar o tópico de referência, StandardDataFormats, que usa para especificar os tipos de formatos que o seu aplicativo suporta.

Os formatos de dados personalizados, conforme o nome implica, dizem respeito aos formatos de dados que não são padronizados. Frequentemente, estes formatos representam conexões lógicas de dados—como um endereço ou um evento. Para suportar formatos personalizados, sugerimos com veemência que você use um dos principais esquemas especificados em http://schema.org/docs/full.htm. Usar formatos de dados conhecidos, como estes esquemas, ajuda a assegurar que o aplicativo que recebe os dados da área de transferência saiba o que fazer com eles.

Introdução

Suportar as operações da área de transferência normalmente tem duas partes: cópia (ou corte) e cola. Vamos ver como lidar com as operações de cópia e corte primeiramente. Em primeiro lugar, certifique-se que o seu aplicativo tenha as referências apropriadas. Se estiver usando um modelo do Microsoft Visual Studio, estas referências são adicionadas assim que você cria um novo projeto. Se você não estiver usando o Visual Studio, certifique-se que o seu aplicativo acesse o namespace Windows.ApplicationModel.DataTransfer.

Após configurar o seu projeto, você precisa de uma instância do objeto DataPackage. Este objeto é que contém os dados que o usuário quer copiar e quaisquer propriedades (como uma descrição) que você quer incluir.

var dataPackage = new Windows.ApplicationModel.DataTransfer.DataPackage();

Copiar e cortar

Neste ponto, você está pronto para especificar a operação da área da transferência que você quer realizar. Estas operações estão disponíveis usando a enumeração DataPackageOperation. Isso é o que você faz para copiar operações:

var dataPackage = new Windows.ApplicationModel.DataTransfer.DataPackage();
dataPackage.requestedOperation = Windows.ApplicationModel.DataTransfer.DataPackageOperation.copy;

E isso é o que você faz para cortar operações (também chamado de operações de mudança):

var dataPackage = new Windows.ApplicationModel.DataTransfer.DataPackage();
dataPackage.requestedOperation = Windows.ApplicationModel.DataTransfer.DataPackageOperation.move;

Neste ponto, você pode adicionar os dados que um usuário selecionou para o objeto DataPackage. Se estes dados são suportados pela classe DataPackage, você pode usar um dos métodos correspondentes no objeto DataPackage.

Para adicionar texto:

dataPackage.setText("Hello World!");

Para ver exemplos sobre como adicionar outros formatos ao DataPackage, veja o exemplo da área de transferência na galeria de código. E lembre-se, você pode adicionar mais de um formato a um DataPackage.

A última coisa que você precisa fazer é adicionar o DataPackage à área de transferência. Você pode fazer isso chamando o método estático Clipboard.setContent.

Windows.ApplicationModel.DataTransfer.Clipboard.setContent(dataPackage);

Colar

Para obter o conteúdo da área de transferência, chame o método estático Clipboard.getContent. Este método retorna um DataPackageView que contém o conteúdo. Este objeto é quase idêntico a um objeto DataPackage, exceto que o seu conteúdo é somente leitura. Com este objeto, você pode usar o método AvailableFormats ou contains para identificar quais formatos estão disponíveis. Em seguida, você pode chamar o método correspondente DataPackageView para obter os dados. Por exemplo, isso é como você pode obter o texto armazenado na área de transferência:

var dataPackageView = Windows.ApplicationModel.DataTransfer.Clipboard.getContent();
if (dataPackageView.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
    dataPackageView.getTextAsync().then(function (text) {
        // To output the text from this example, you need an HTML element
        // with an id of "output".
        document.getElementById("output").innerText = "Clipboard now contains: " + text;
    });
}

Acompanhando mudanças na área de transferência

Além dos comandos de copiar e colar, você também pode considerar útil adicionar um manipulador de eventos para que o seu aplicativo saiba quando o conteúdo da área de transferência muda. Você pode fazer isso manipulando o evento ContentChanged da área da transferência.

Windows.ApplicationModel.DataTransfer.Clipboard.addEventListener("contentchanged", function (event) {
    var dataPackageView = Windows.ApplicationModel.DataTransfer.Clipboard.getContent();
    if (dataPackageView.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
        dataPackageView.getTextAsync().then(function (text) {
            // To output the text from this example, you need an HTML element
            // with an id of "output".
            document.getElementById("output").innerText = "Clipboard now contains: " + text;
        });
    }
});

Com este manipulador, o seu aplicativo é avisado sempre que o conteúdo da área de transferência muda.

Próximas etapas

Agora, você deve ter um entendimento básico de como adicionar suporte da área de transferência ao seu aplicativo. Se ainda não tiver feito isso, recomendamos que você consulte as nossas Diretrizes e lista de verificação para comandos da área de transferência, para que você possa criar a melhor experiência do usuário possível. Além disso, baixe o nosso exemplo da galeria do código para ver uma variedade de exemplos sobre como usar a área de transferência.