Guida introduttiva: Concetti di base degli Appunti (HTML)

Articolo
12/11/2015

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

Le migliori app sono quelle che offrono agli utenti il maggior controllo possibile sui dati. Le operazioni degli Appunti sono uno dei metodi di controllo che gli utenti si aspettano di trovare in un'applicazione. Queste operazioni consentono agli utenti di tagliare, copiare e incollare i dati. Le operazioni degli Appunti possono essere eseguite all'interno della stessa app o tra due app diverse nello stesso computer. Gli Appunti consentono agli utenti di posizionare le informazioni nel punto desiderato con la massima semplicità.

Più modi di condividere i dati

Prima di esaminare come si aggiungono le operazioni degli Appunti in un'app, tieni presente che Windows 8 supporta diversi modi per lo spostamento dei dati. Per una panoramica di questi metodi, vedi Condivisione e scambio di dati. Uno di questi metodi, la condivisione, presenta molti aspetti in comune con gli Appunti. Dal punto di vista dello sviluppatore, la condivisione e le operazioni degli Appunti usano lo stesso spazio dei nomi Windows, Windows.ApplicationModel.DataTransfer. Entrambi i metodi richiedono che l'app raccolga i dati selezionati da un utente. (Spesso questa operazione è definita "creazione di pacchetti" perché per eseguirla si deve usare la classe DataPackage). Dal punto di vista dell'utente, gli Appunti rappresentano il modo "classico" per spostare i dati.

In qualità di sviluppatore, tieni presente che sebbene le operazioni di condivisione e quelle degli Appunti siano molto simili, presentano differenze importanti. Nella condivisione, l'attenzione è concentrata sulla destinazione: l'app o il servizio selezionato dall'utente. Negli Appunti, l'attenzione è concentrata principalmente sui dati. Inoltre, le operazioni degli Appunti sono l'unico modo per poter scambiare i dati tra un'app desktop e un'app di Windows Store.

Per ulteriori informazioni sulle differenze tra le operazioni di condivisione e quelle degli Appunti, vedi Condivisione e scambio di dati.

Supporto degli Appunti incorporato

Nella maggior parte dei casi, non dovrai scrivere alcuna riga di codice per integrare il supporto delle operazioni degli Appunti. Molti dei controlli che puoi usare per creare l'app di Windows Store supportano già le operazioni degli Appunti. Per ulteriori informazioni sui controlli disponibili, vedi Aggiunta di controlli e contenuto.

Prima di iniziare

Aggiungere il supporto per le operazioni degli Appunti all'app è un'operazione molto semplice. Ti consigliamo innanzitutto di leggere l'argomento Linee guida ed elenco di controllo per i comandi relativi agli Appunti. In questo documento troverai molte informazioni che possono aiutarti a creare l'esperienza utente ottimale per le operazioni degli Appunti, oltre ad alcuni suggerimenti per sfruttare al meglio il tuo codice.

Successivamente, devi valutare quali sono i tipi di formati di dati che desideri supportare. In Windows 8 sono disponibili due categorie di formati: standard e personalizzati. Attualmente, tra i formati standard sono inclusi:

Text
HTML
URI
Bitmap
StorageItems
RTF

Per visualizzare un esempio di operazioni degli Appunti che utilizzano questi formati di dati, vedi il nostro esempio di codice. Ti consigliamo di leggere anche l'argomento di riferimento StandardDataFormats, che puoi usare per specificare i tipi di formati supportati dalla tua app.

I formati di dati personalizzati, come indicato dal nome, fanno riferimento a formati relativi a dati che non rientrano in uno dei formati standard. Spesso, tali formati rappresentano raccolte logiche di dati, ad esempio un indirizzo o un evento. Per il supporto dei formati personalizzati, ti consigliamo di usare uno dei numerosi schemi disponibili in http://schema.org/docs/full.htm. L'uso di formati di dati comuni, come questi schemi, garantisce che l'app che riceve i dati degli Appunti sappia cosa farne.

Introduzione

In genere, il supporto delle operazioni degli Appunti prevede due azioni: copiare (o tagliare) e incollare. Esaminiamo innanzitutto come gestire le operazioni di copia e di taglio. Per prima cosa, verifica che l'app includa i riferimenti appropriati. Se stai usando un modello di Microsoft Visual Studio, questi riferimenti vengono aggiunti non appena crei un nuovo progetto. Se non stai usando Visual Studio, verifica che l'app abbia accesso allo spazio dei nomi Windows.ApplicationModel.DataTransfer.

Dopo aver configurato il progetto, devi aggiungere un'istanza dell'oggetto DataPackage. Questo oggetto contiene sia i dati che l'utente desidera copiare, sia le proprietà, ad esempio una descrizione, che desideri includere.

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

Copia e Taglia

A questo punto, sei pronto per specificare l'operazione degli Appunti da eseguire. Tali operazioni sono disponibili usando l'enumerazione DataPackageOperation. Ecco cosa fare per le operazioni di copia:

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

ed ecco cosa devi fare per le operazioni di taglio (chiamate anche operazioni di spostamento):

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

A questo punto, puoi aggiungere i dati selezionati dall'utente all'oggetto DataPackage. Se questi dati sono supportati dalla classe DataPackage, puoi usare uno dei metodi corrispondenti nell'oggetto DataPackage.

Per aggiungere testo:

dataPackage.setText("Hello World!");

Per visualizzare esempi relativi all'aggiunta di altri formati a un DataPackage, vedi esempio di Appunti nella Code Gallery. Tieni anche presente che puoi aggiungere più di un formato a un oggetto DataPackage.

L'ultima operazione da fare è aggiungere l'oggetto DataPackage agli Appunti. A questo scopo, puoi chiamare il metodo Clipboard.setContent statico.

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

Incolla

Per recuperare il contenuto degli Appunti, chiama il metodo Clipboard.getContent statico. Questo metodo restituisce un oggetto DataPackageView che contiene il contenuto. Questo oggetto è quasi identico all'oggetto DataPackage, ad eccezione del fatto che il relativo contenuto è di sola lettura. Con questo oggetto, puoi usare i metodi AvailableFormats o contains per identificare i formati disponibili. Successivamente, puoi chiamare il metodo DataPackageView corrispondente per recuperare i dati. Ecco, ad esempio, come fare per recuperare il testo archiviato negli Appunti:

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

Revisione delle modifiche negli Appunti

Oltre ai comandi copia e incolla, puoi anche aggiungere un gestore di eventi in modo che l'app riceva una notifica ogni volta che il contenuto degli Appunti subisce modifiche. Puoi ottenere questo risultato gestendo l'evento ContentChanged degli Appunti.

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

Grazie a questo gestore, l'app riceve una notifica ogni volta che cambia il contenuto degli Appunti.

Passaggi successivi

Hai acquisito le conoscenze di base per aggiungere il supporto degli Appunti alla tua app. Se non lo hai già fatto, ti consigliamo di leggere le nostre Linee guida ed elenco di controllo per i comandi relativi agli appunti, per creare un'esperienza utente ottimale. Per visualizzare un'ampia gamma di esempi su come usare gli Appunti, puoi anche scaricare il nostro esempio dalla Code Gallery.