Guida introduttiva: Aggiunta della funzionalità di ricerca a un'app (HTML)
[ 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 ]
La maggior parte degli utenti si affida alla ricerca per trovare ciò di cui ha bisogno. Se la tua app riproduce file multimediali, ad esempio, gli utenti si aspetteranno di poter cercare un brano o un video specifico, così come vorranno cercare ricette o ingredienti in un'app per la cucina.
Con un po' di pianificazione, non è particolarmente difficile aggiungere funzionalità di ricerca alla tua app. Ecco cosa serve:
- Un'origine dati in cui eseguire la ricerca. Dovrai predisporre qualcosa di simile a un catalogo o un inventario di elementi che gli utenti potrebbero voler cercare. Quanto più descrittivo sarà l'inventario che riesci a creare, tanto migliori saranno i risultati della ricerca.
- Un controllo per l'immissione delle query di ricerca. Windows offre il controllo SearchBox che puoi usare nella tua app. Il controllo SearchBox include un'area di input per l'immissione delle query, un pulsante per l'esecuzione della ricerca ed eventi per la gestione delle query di ricerca. Fornisce inoltre automaticamente alcuni suggerimenti per la ricerca.
- Una pagina per la visualizzazione dei risultati di ricerca. Microsoft Visual Studio include il modello Pagina risultati ricerca che consente di creare automaticamente molto del codice necessario per gestire le query di ricerca e visualizzare i risultati.
Questa guida introduttiva descrive come usare questi elementi per aggiungere funzionalità di ricerca alla tua app.
Vedi questa funzionalità in azione nell'ambito della serie di argomenti su funzionalità delle app dall'inizio alla fine: Interfaccia utente delle app di Windows Store dall'inizio alla fine
Prerequisiti
- In questo articolo si presume che tu sappia come aggiungere controlli in un'app di Windows Store di base con JavaScript. Per istruzioni sull'aggiunta di controlli, vedi Guida introduttiva: Aggiunta di controlli e gestione di eventi e Guida introduttiva: Aggiunta di controlli e stili WinJS.
- Dovresti avere familiarità con l'uso delle origini dati e del data binding. Per istruzioni, vedi Come personalizzare i dati dei modelli di Visual Studio.
Impostare i dati
Quando l'utente immette una query di ricerca, la tua app cerca gli elementi che potrebbero corrispondere a quelli cercati dall'utente. I dati in cui l'app esegue la ricerca possono essere in varie forme, come un file XML, dati JSON (JavaScript Object Notation), un database, un servizio Web o file nel file system.
Gli esempi in questa guida introduttiva usano i dati di esempio forniti al momento della creazione di un nuovo progetto in Microsoft Visual Studio.
Quando usi Visual Studio per creare una nuova applicazione Griglia, Hub o Divisa, nella cartella js dell'app viene creato un file denominato data.js. Questo file include dati statici che puoi sostituire con dati personalizzati. Se ad esempio la tua app effettua una singola richiesta xhr per ottenere dati RSS o JSON, devi in genere includere questo codice in data.js. In questo modo potrai usare facilmente i tuoi dati senza cambiare il modello di dati usato in Pagina risultati ricerca.
I dati di esempio avranno un aspetto simile al seguente:
function generateSampleData() {
// . . .
var sampleGroups = [
{ key: "group1", title: "Group Title: 1", // . . .
// . . .
];
var sampleItems = [
{ group: sampleGroups[0], title: "Item Title: 1", // . . .
// . . .
];
return sampleItems;
}
Per rendere questi dati accessibili ai tuoi file, il file data.js definisce uno spazio dei nomi Data che espone i membri seguenti:
items: un elemento WinJS.Binding.List che contiene gli elementi dati. Si tratta di un elemento Listraggruppato.groups: un elemento WinJS.Binding.List che contiene i gruppi ai quali gli elementi dati appartengono. Puoi ottenere i gruppi anche chiamando items.groups.- getItemReference: recupera un oggetto che contiene la chiave di gruppo e il titolo dell'elemento specificato.
- getItemsFromGroup: recupera un elemento FilteredListProjection contenente gli elementi che appartengono al gruppo con la chiave specificata.
- resolveGroupReference: recupera un oggetto che rappresenta il gruppo con la chiave specificata.
- resolveItemReference: questo metodo usa una matrice che contiene due stringhe, una chiave di gruppo e un titolo, e recupera l'elemento con la chiave di gruppo e il titolo specificati.
Non devi necessariamente usare questo spazio dei nomi o questi membri per i tuoi dati, ma se li usi, sarà più semplice utilizzare il modello Pagina risultati ricerca.
Per altre info sull'uso dei dati generati da un modello, vedi Come personalizzare dati di modelli di Visual Studio.
Aggiungere una pagina dei risultati della ricerca
Nell'elemento Pagina risultati ricerca vengono elaborate le query di ricerca e vengono visualizzati i risultati. Aggiungiamone una al tuo progetto. In queste istruzioni si suppone che il tuo progetto sia stato creato da un modello Hub, Grid o Split .
.gif "Hh465238.wedge(it-it,WIN.10).gif")
Aggiungere l'elemento Pagina risultati di ricerca
Nella cartella di progetto pages di Esplora soluzioni aggiungi una nuova cartella denominata search.
Apri il menu di scelta rapida per la cartella search e quindi scegli Aggiungi > Nuovo elemento.
Nel riquadro centrale della finestra di dialogo Aggiungi nuovo elemento scegli Pagina risultati di ricerca. Per questo esempio mantieni il nome predefinito, searchResults.html, che viene visualizzato nella casella Nome.
Scegli Aggiungi.
Visual Studio aggiunge searchResults.html, searchResults.css e searchResults.js al progetto nella nuova cartella search.
Aggiungere un controllo SearchBox
Dobbiamo ancora lavorare alla pagina dei risultati di ricerca, ma prima di tutto aggiungiamo un controllo SearchBox all'app. La disponibilità di un controllo SearchBox renderà più semplice il testing della pagina dei risultati di ricerca durante l'implementazione.
Un controllo SearchBox consente agli utenti di immettere le query e può anche visualizzare suggerimenti. Per aggiungere un controllo SearchBox alla tua app, è sufficiente aggiungere questo markup a una pagina XAML:
<div class="searchBox"
data-win-control="WinJS.UI.SearchBox"
data-win-options="{placeholderText: 'Search'}">
</div>
Dovrai anche eseguire la registrazione per l'evento onquerysubmitted, ma lo farai in un passaggio successivo.
Qual è la posizione consigliata per la casella di ricerca? Consigliamo di aggiungere una casella di ricerca in ogni pagina della tua app, in modo che gli utenti possano eseguire facilmente ricerche quando preferiscono. Se lo spazio è un problema, puoi aggiungere la casella di ricerca in una barra dell'app superiore.
Aggiungere un controllo SearchBox a una pagina
Aggiungi un controllo SearchBox a una delle pagine della tua app. Queste istruzioni funzionano per qualsiasi pagina basata su un controllo Page.
In genere, la posizione migliore per il controllo SearchBox è nell'angolo superiore destro della pagina. La maggior parte delle pagine create da un modello di Visual Studio (come il modello Controllo pagina) include un controllo header che contiene il titolo della pagina e un pulsante Indietro:
<header aria-label="Header content" role="banner"> <button data-win-control="WinJS.UI.BackButton"></button> <h1 class="titlearea win-type-ellipsis"> <span class="pagetitle"></span> </h1> </header>È sufficiente che tu aggiunga SearchBox dopo l'elemento h1:
<header aria-label="Header content" role="banner"> <button data-win-control="WinJS.UI.BackButton"></button> <h1 class="titlearea win-type-ellipsis"> <span class="pagetitle">Welcome to basicPage</span> </h1> <div class="searchBox" data-win-control="WinJS.UI.SearchBox" data-win-options="{placeholderText: 'Search'}"> </div> </header>È consigliabile offrire agli utenti la possibilità di cercare contenuto nell'app semplicemente digitando tramite la tastiera.
Molti utenti usano la tastiera per interagire con Windows 8. In questo modo gli utenti possono usare in modo efficiente l'interazione della tastiera e l'esperienza di ricerca dell'app diventa coerente con la schermata Start.
Imposta la proprietà focusOnKeyboardInput del controllo SearchBox su true in modo che la casella di ricerca riceva l'input quando un utente inizia a digitare.
<div class="searchBox" data-win-control="WinJS.UI.SearchBox" data-win-options="{placeholderText: 'Search', focusOnKeyboardInput: true }"> </div>Il foglio di stile default.css che Visual Studio crea automaticamente attribuisce agli elementi header un layout -ms-grid. Per posizionare l'elemento SearchBox nell'angolo superiore destro della pagina, è sufficiente che tu aggiunga questo stile al file CSS (Cascading Style Sheets) per la tua pagina:
.searchBox { -ms-grid-column: 4; margin-top: 57px; margin-right: 29px; }
Gestire l'evento onquerysubmitted
La tua app avrà probabilmente più controlli SearchBox. Definisci quindi un singolo gestore eventi onquerysubmitted che possa essere usato da tutti i controlli.
Apri il file default.js dell'app.
Crea un gestore eventi onquerysubmitted denominato "querySubmittedHandler" con un singolo argomento denominato "args". Puoi inserire questa definizione di metodo in un punto qualsiasi all'interno della funziona anonima che esegue il wrapping del codice di default.js esistente.
function querySubmittedHandler(args) { }Usa il gestore eventi per passare alla nuova pagina dei risultati di ricerca chiamando WinJS.Navigation.navigate. Poiché la proprietà
args.detailscontiene un oggetto che fornisce info sull'evento necessarie per la pagina dei risultati di ricerca, quando chiami WinJS.Navigation.navigate, dovrai passare questo oggetto.function querySubmittedHandler(args) { WinJS.Navigation.navigate('/pages/search/searchResults.html', args.detail); }Avviso Se hai creato l'app con il modello Applicazione vuota, dovrai aggiungere all'app anche il supporto per la navigazione se vuoi che la funzionalità di ricerca funzioni. Puoi fare in modo che la tua app supporti la navigazione esattamente come i modelli Applicazione griglia, Applicazione divisa e Applicazione di navigazione aggiungendo all'app un controllo personalizzato denominato
PageControlNavigator. In Guida introduttiva: Uso della navigazione a pagina singola viene spiegato in che modo il controllo personalizzato supporta la navigazione. Se preferisci aggiungere il supporto per la navigazione senza ricorrere a un controllo personalizzato, dovrai scrivere personalmente codice in grado di ascoltare e rispondere agli eventi di navigazione come WinJS.Navigation.navigated. Un esempio di supporto della navigazione senza l'uso di un controllo personalizzato comePageControlNavigatorè disponibile in Esempio di navigazione e cronologia di navigazione.È ora necessario esporre pubblicamente questo gestore eventi definendo uno spazio dei nomi e rendendone il gestore un membro. Chiama lo spazio dei nomi "SearchUtils". Devi inoltre utilizzare il metodo WinJS.UI.eventHandler in modo che sia possibile impostare il gestore eventi in modo dichiarativo. Per altre info su questa operazione, vedi Come impostare gestori eventi in modo dichiarativo).
WinJS.Namespace.define("SearchUtils", { querySubmittedHandler: WinJS.UI.eventHandler(querySubmittedHandler) } );Apri la pagina HTML contenente SearchBox. Usa la proprietà data-win-options per impostare l'evento onquerysubmitted su
SampleUtils.querySubmittedHandler.<div class="searchBox" data-win-control="WinJS.UI.SearchBox" data-win-options="{placeholderText: 'Search', focusOnKeyboardInput: true, onquerysubmitted: SearchUtils.querySubmittedHandler}"> </div>
Proviamola. Esegui l'app, digita una query di prova in SearchBox e premi INVIO. Se usi i dati di esempio di Visual Studio, prova ad utilizzare "1" come query di prova.
.png "Query di prova")
Il gestore dell'evento onquerysubmitted scritto attiva lo spostamento alla pagina dei risultati di ricerca passando la query immessa.
.png "Risultati della query di prova")
Se hai usato i dati di esempio, vengono restituiti i risultati che corrispondono alla query di prova. Se hai usato dati personalizzati, è possibile che non venga restituito alcun risultato perché prima è necessario aggiornare la pagina dei risultati di ricerca. L'operazione verrà eseguita in un passaggio successivo.
Eseguire una ricerca nei dati
Torniamo ora alla pagina dei risultati della ricerca. Quando la tua app passa alla pagina dei risultati della ricerca, uno dei primi metodi che chiama è _handleQuery . Il metodo _handleQuery chiama diversi metodi che dovrai modificare:
_generateFiltersGenera l'elenco dei filtri che possono essere usati dagli utenti per filtrare i risultati.
_searchDataCerca elementi corrispondenti nei dati e li archivia in un elemento List denominato
originalResults._populateFilterBarVisualizza i filtri nell'elenco dei filtri.
Aggiorna quindi questi metodi per personalizzarli in base ai tuoi dati.
Aggiornare i filtri
Il metodo _generateFilters genera l'elenco dei filtri che l'utente può selezionare per filtrare i risultati. Il metodo generato dal modello crea tre filtri, ovvero un filtro per visualizzare tutti i risultati, un filtro per visualizzare gli elementi del gruppo 1 e un filtro per visualizzare tutto il resto. Sostituisci il codice generato dal modello con un codice che generi l'elenco dei filtri in modo dinamico. In questo modo, se modifichi i dati di esempio, i nuovi filtri verranno visualizzati nella pagina. In seguito dovrai aggiornare il codice _generateFilters e creare due metodi helper. Prima però devi aggiornare il file data.js in modo che sia possibile accedere all'elenco dei gruppi e usare tali gruppi per definire i filtri.
Aggiornare il metodo _generateFilters
In searchResults.js individua il metodo
_generateFiltersed elimina il codice che contiene.Inizializza la matrice
_filters. La matrice_filtersè una variabile membro definita dalla pagina dei risultati di ricerca._generateFilters: function () { this._filters = [];Crea ora un filtro. Un filtro è un oggetto che ha tre proprietà:
results: un elemento List che contiene gli elementi da visualizzare. Per il momento puoi impostarlo su null.text: il testo visualizzato per il filtro.predicate: una funzione che prende un elemento. Se l'elemento corrisponde ai criteri del filtro, ovvero se deve essere visualizzato quando si seleziona il filtro, la funzione restituisce true. In caso contrario, restituisce false.
Crea innanzitutto il filtro per visualizzare tutti gli elementi. Poiché tale filtro visualizza sempre elementi, il suo elemento
predicaterestituisce sempre true.this._filters.push({ results: null, text: "All", predicate: function (item) { return true; } });Crea quindi un filtro per ogni gruppo nei dati. I gruppi sono archiviati come un elemento List denominato
Data.groups. Usa il metodo forEach per eseguire un'iterazione attraverso ogni gruppo nell'elemento List. Il metodo forEach usa una funzione come suo parametro. Tale funzione viene chiamata per ogni elemento nell'elenco. Passa al metodo una funzione membro denominata_createFiltersForGroups. Creerai la funzione nel passaggio seguente.if (window.Data) { Data.groups.forEach(this._createFiltersForGroups.bind(this)); } },Ora creiamo la funzione
_createFiltersForGroups.Crea una funzione membro denominata
_createFiltersForGroupsche accetta tre parametri: element, index e array._createFiltersForGroups: function (element, index, array){Il parametro element contiene il nostro oggetto gruppo. Crea un nuovo oggetto filtro e usa il metodo push per aggiungerlo alla matrice
_filters. Imposta la proprietàresultsdel filtro su null, la proprietàtextsu element.titlee la proprietàpredicatesu una funzione denominata_filterPredicate. Definirai il metodo_filterPredicatenel prossimo passaggio.this._filters.push( { results: null, text: element.title, predicate: this._filterPredicate.bind(element)} ); },Crea una funzione membro denominata
_filterPredicateche accetta un solo parametro denominato item. Restituisci true se la proprietàgroupdel parametro item è uguale all'oggetto gruppo corrente._filterPredicate: function (item) { return item.group === this; },
Ecco il codice completo per i tre metodi appena creati:
_generateFilters: function () {
this._filters = [];
this._filters.push({ results: null, text: "All", predicate: function (item) { return true; } });
if (window.Data) {
Data.groups.forEach(this._createFiltersForGroups.bind(this));
}
},
_createFiltersForGroups: function (element, index, array){
this._filters.push(
{ results: null, text: element.title, predicate: this._filterPredicate.bind(element)}
);
},
_filterPredicate: function (item) {
return item.group === this;
},
Esegui una ricerca nell'app. Nella barra dei filtri dovrebbero essere disponibili i nuovi filtri.
.png "Elenco dei filtri aggiornato")
Se utilizzi i dati di esempio generati dal modello, è possibile che alcuni dei gruppi siano troncati. Puoi risolvere il problema apportando alcune modifiche nel file CSS per la pagina dei risultati di ricerca.
Aggiornare il file CSS per la pagina dei risultati di ricerca
Apri searchResults.css.
Individua lo stile
.searchResults section[role=main]e modifica il valore della proprietà -ms-grid-rows impostandolo su "auto 1fr"..searchResults section[role=main] { /* Define a grid with rows for the filters and results */ -ms-grid-columns: 1fr; -ms-grid-rows: auto 1fr; -ms-grid-row: 1; -ms-grid-row-span: 2; display: -ms-grid; }Individua lo stile
.searchResults section[role=main] .filterbar, modifica il valore della proprietà word-wrap impostandolo su "normal" e imposta margin-bottom su "20px"..searchResults section[role=main] .filterbar { -ms-font-feature-settings: "case" 1; -ms-grid-row: 1; list-style-type: none; margin-left: 60px; margin-right: 60px; margin-top: 133px; max-width: calc(100% - 120px); position: relative; white-space: normal; z-index: 1; margin-bottom: 20px; }Individua lo stile
.searchResults section[role=main] .filterbar lie modifica il valore della proprietà display impostandolo su "inline-block"..searchResults section[role=main] .filterbar li { display: inline-block; margin-left: 20px; margin-right: 20px; margin-top: 5px; opacity: 0.6; }Individua lo stile
.searchResults section[role=main] .resultslist, modifica il valore della proprietà -ms-grid-row impostandolo su "2" e imposta -ms-grid-row-span su "1"..searchResults section[role=main] .resultslist { -ms-grid-row: 2; -ms-grid-row-span: 1; height: 100%; position: relative; width: 100%; z-index: 0; }
Esegui un'altra ricerca nell'app. Questa volta tutti i filtri dovrebbero essere visibili.
.png "Elenco dei filtri aggiornato")
Aggiornare l'algoritmo di ricerca
Il metodo _searchData cerca gli elementi che corrispondono alla query di ricerca. Il codice generato dal modello cerca il titolo, il sottotitolo e la descrizione di ogni elemento. Scrivi ora un codice di ricerca che classifichi i risultati in base alla pertinenza.
Aggiornare il metodo _searchData
Apri searchResults.js, individua il metodo
_searchDataed elimina il codice che contiene.Crea una variabile denominata
originalResults. Questo sarà il valore restituito.// This function populates a WinJS.Binding.List with search results for the // provided query. _searchData: function (queryText) { // Create a variable for the results list. var originalResults;Fai in modo che nella tua ricerca non venga fatta distinzione tra maiuscole e minuscole convertendo il testo della query e il testo che cerchi in lettere minuscole. Inizia convertendo la query in lettere minuscole e archiviandola come variabile denominata
lowercaseQueryText.// Convert the query to lowercase. var lowercaseQueryText = queryText.toLocaleLowerCase();Prima di tentare di accedere ai dati, è opportuno verificare che i dati esistano.
if (window.Data) {Se usi i dati di esempio forniti in data.js, gli elementi sono archiviati in
Data.items, un oggetto WinJS.Binding.List. Usa il metodo createFiltered per filtrare gli elementi che non soddisfano la query di ricerca.Il metodo createFiltered usa come parametro una funzione di filtro che utilizza un parametro singolo, ovvero item. List chiama questa funzione in ogni elemento dell'elenco per determinare se deve essere incluso nell'elenco filtrato. La funzione restituisce true se l'elemento deve essere incluso e false se deve essere omesso.
originalResults = Data.items.createFiltered( function (item) {In JavaScript puoi associare nuove proprietà a oggetti esistenti. Aggiungi una proprietà
rankinga item e impostane il valore su "-1".// A ranking < 0 means that a match wasn't found. item.ranking = -1;Verifica innanzitutto se il titolo dell'elemento contiene il testo della query. In caso affermativo, attribuisci all'elemento 10 punti.
if (item.title.toLocaleLowerCase().indexOf(lowercaseQueryText) >= 0) { item.ranking += 10; }Verifica quindi l'eventuale presenza di occorrenze nel campo del sottotitolo. Attribuisci 5 punti ad ogni elemento corrispondente trovato.
if (item.subtitle.toLocaleLowerCase().indexOf(lowercaseQueryText) >= 0) { item.ranking += 5; }Controlla infine il campo della descrizione. Attribuisci 1 punto ad ogni elemento corrispondente trovato.
if (item.description.toLocaleLowerCase().indexOf(lowercaseQueryText) >= 0) { item.ranking += 1; }Se la classificazione di un elemento è -1, significa che non soddisfa la query di ricerca. Per quanto riguarda il valore restituito, fai in modo che restituisca true se la classificazione dell'elemento è maggiore o uguale a 0.
return (item.ranking >= 0); } );Finora hai filtrato l'elenco solo in base agli elementi che soddisfano la query di ricerca e hai aggiunto info sulla classificazione. Utilizza ora il metodo createSorted per ordinare l'elenco dei risultati in modo che gli elementi con il maggior numero di punti vengano visualizzati per primi.
// Sort the results by the ranking info we added. originalResults = originalResults.createSorted(function (firstItem, secondItem){ if (firstItem.ranking == secondItem.ranking) { return 0; } else if (firstItem.ranking < secondItem.ranking) return 1; else return -1; }); }Se mancano i dati, crea un elenco vuoto.
else { // For some reason, the Data namespace is null, so we // create an empty list to return. originalResults = new WinJS.Binding.List(); }Infine, fai in modo che vengano restituiti i risultati.
return originalResults; }
Ecco il codice completo per il metodo _searchDataaggiornato.
_searchData: function (queryText) {
// Create a variable for the results list.
var originalResults;
// Convert the query to lowercase.
var lowercaseQueryText = queryText.toLocaleLowerCase();
if (window.Data)
{
originalResults = Data.items.createFiltered(
function (item) {
// A ranking < 0 means that a match wasn't found.
item.ranking = -1;
if (item.title.toLocaleLowerCase().indexOf(lowercaseQueryText) >= 0) {
item.ranking += 10;
}
if (item.subtitle.toLocaleLowerCase().indexOf(lowercaseQueryText) >= 0) {
item.ranking += 5;
}
if (item.description.toLocaleLowerCase().indexOf(lowercaseQueryText) >= 0) {
item.ranking += 1;
}
return (item.ranking >= 0);
}
);
// Sort the results by the ranking info we added.
originalResults = originalResults.createSorted(function (firstItem, secondItem){
if (firstItem.ranking == secondItem.ranking) {
return 0;
}
else if (firstItem.ranking < secondItem.ranking)
return 1;
else
return -1;
});
}
else {
// For some reason, the Data namespace is null, so we
// create an empty list to return.
originalResults = new WinJS.Binding.List();
}
return originalResults;
}
Consentire il passaggio agli elementi restituiti dalla ricerca
Quando esegui una ricerca nell'app, nella pagina dei risultati di ricerca i risultati vengono visualizzati in un controllo ListView. Se adesso fai clic su uno dei risultati della ricerca, non viene eseguita alcuna operazione. Puoi però aggiungere codice in modo che l'elemento venga visualizzato quando si fa clic su di esso.
Quando l'utente fa clic su un elemento in ListView, ListView genera l'evento oniteminvoked. Il codice generato dal modello per la pagina di risultati di ricerca definisce un gestore eventi oniteminvoked denominato _itemInvoked. Aggiorna il codice in modo che consenta di passare all'elemento richiamato.
Per consentire il passaggio agli elementi
Aprire searchResults.js e aggiungere codice alla funzione
_itemInvokedper passare alla pagina corretta. Attenzione L'URI illustrato è relativo al modello Hub. Per il modello Grid, l'URI deve essere: /pages/itemDetail/itemDetail.html. Per il modello Split, l'URI deve essere: /pages/items/items.html._itemInvoked: function (args) { args.detail.itemPromise.done(function itemInvoked(item) { // TODO: Navigate to the item that was invoked. var itemData = [item.groupKey, item.data.title]; WinJS.Navigation.navigate("/pages/item/item.html", { item: itemData }); }); },
(Facoltativo) Aggiornare la proprietà itemTemplate del controllo ListView
La pagina dei risultati di ricerca generata dal modello definisce un elemento itemTemplate progettato per interagire con l'origine dati di esempio creata automaticamente da Visual Studio e presuppone per ogni elemento di dati l'esistenza dei campi "image", "title", "subtitle" e "description".
Se i tuoi dati includono campi diversi, dovrai modificare la proprietà itemTemplate. Per istruzioni, vedi Guida introduttiva: Aggiunta di un controllo ListView.
(Facoltativo) Aggiungere suggerimenti per la ricerca
I suggerimenti di ricerca vengono visualizzati nella casella del riquadro di ricerca. I suggerimenti sono importanti perché consentono agli utenti di risparmiare tempo e fornisce consigli utili su cosa cercare nell'app.
Puoi ottenere suggerimenti da varie risorse:
- Puoi definirli personalmente. Ad esempio, puoi creare un elenco di case automobilistiche.
- Puoi ottenerli da Windows se l'app consente la ricerca nei file locali.
- Puoi ottenerli da un servizio Web o da un server.
Per informazioni sulla visualizzazione dei suggerimenti, vedi Linee guida ed elenco di controllo per la ricerca.
Puoi usare LocalContentSuggestionSettings per aggiungere con poche righe di codice suggerimenti basati su file locali di Windows. In alternativa, puoi registrare l'evento onsuggestionsrequested del controllo casella di ricerca e creare un elenco di suggerimenti personale composto da suggerimenti recuperati da un'altra origine (come un elenco definito localmente o un servizio Web). Questo guida introduttiva mostra come gestire l'evento onsuggestionsrequested.
Per altri esempi di codice che illustrano come aggiungere suggerimenti per la ricerca, scarica l'esempio del controllo SearchBox. L'esempio mostra come aggiungere suggerimenti per la ricerca usando tutte le tre possibili origini e come aggiungere suggerimenti per le lingue asiatiche orientali tramite forme alternative del testo di query generate da un IME (Input Method Editor). (Consigliamo di usare alternative per il testo di query se l'app verrà usata da utenti giapponesi o cinesi.)
Gestire l'evento SuggestionsRequested
È probabile che la tua app includa più controlli SearchBox. Definisci un singolo gestore eventi nel file default.js utilizzabile da tutti i controlli. Aggiungi questo codice dopo il metodo
querySubmittedHandlercreato in un passaggio precedente.function suggestionsRequestedHandler(args) {Converti il testo della query SearchBox in lettere minuscole.
var query = args.detail.queryText.toLocaleLowerCase();Il sistema fornisce automaticamente alcuni suggerimenti, come le ricerche precedenti eseguite dall'utente. Aggiungiamo i nostri suggerimenti per la ricerca a quelli forniti dal sistema.
// Retrieve the system-supplied suggestions. var suggestionCollection = args.detail.searchSuggestionCollection;Verifica che la query contenga almeno un carattere e che sia possibile accedere ai dati.
if (query.length > 0 && window.Data) {Eseguiamo un'iterazione di ogni elemento dei dati per individuare eventuali corrispondenze. Quando troviamo una corrispondenza, aggiungiamo il titolo dell'elemento alla raccolta dei suggerimenti per la ricerca.
Data.items.forEach( function (element, index, array) { if (element.title.substr(0, query.length).toLocaleLowerCase() === query) { suggestionCollection.appendQuerySuggestion(element.title); } });La proprietà
args.detail.linguisticDetails.queryTextAlternativesfornisce ulteriori suggerimenti per gli utenti che immettono il testo in un IME. L'uso di questi suggerimenti migliora l'esperienza di ricerca per gli utenti delle lingue dell'Asia orientale. Controlliamo le alternative al testo di query per le stringhe che contengono la query originale e le aggiungiamo all'elenco dei suggerimenti.args.detail.linguisticDetails.queryTextAlternatives.forEach( function (element, index, array) { if (element.substr(0, query.length).toLocaleLowerCase() === query) { suggestionCollection.appendQuerySuggestion(element); } }); } }Ecco tutto il codice che ci serve per il gestore eventi per i suggerimenti per la ricerca. Ecco il metodo
suggestionsRequestedHandlercompleto:function suggestionsRequestedHandler(args) { var query = args.detail.queryText.toLocaleLowerCase(); // Retrieve the system-supplied suggestions. var suggestionCollection = args.detail.searchSuggestionCollection; if (query.length > 0 && window.Data) { Data.items.forEach( function (element, index, array) { if (element.title.substr(0, query.length).toLocaleLowerCase() === query) { suggestionCollection.appendQuerySuggestion(element.title); } }); args.detail.linguisticDetails.queryTextAlternatives.forEach( function (element, index, array) { if (element.substr(0, query.length).toLocaleLowerCase() === query) { suggestionCollection.appendQuerySuggestion(element); } }); } }Nota Se l'origine dati è asincrona, devi eseguire il wrapping degli aggiornamenti alla raccolta dei suggerimenti per la ricerca in Promise. Il codice di esempio usa un elemento List, che è un'origine dati sincrona. Di seguito viene invece illustrato l'aspetto del metodo se List fosse un'origine dati asincrona.
function suggestionsRequestedHandler(args) { var query = args.detail.queryText.toLocaleLowerCase(); // Retrieve the system-supplied suggestions. var suggestionCollection = args.detail.searchSuggestionCollection; if (query.length > 0 && window.Data) { args.detail.setPromise(WinJS.Promise.then(null, function () { Data.items.forEach( function (element, index, array) { if (element.title.substr(0, query.length).toLocaleLowerCase() === query) { suggestionCollection.appendQuerySuggestion(element.title); } }); args.detail.linguisticDetails.queryTextAlternatives.forEach( function (element, index, array) { if (element.substr(0, query.length).toLocaleLowerCase() === query) { suggestionCollection.appendQuerySuggestion(element); } }); }) ); } }Ecco tutto il codice che ci serve per il gestore eventi per i suggerimenti per la ricerca. Rendilo pubblicamente accessibile esponendolo mediante lo spazio dei nomi
SearchUtilsdefinito in un passaggio precedente:WinJS.Namespace.define("SearchUtils", { querySubmittedHandler: WinJS.UI.eventHandler(querySubmittedHandler), suggestionsRequestedHandler: WinJS.UI.eventHandler(suggestionsRequestedHandler) } );Registriamo ora l'evento nel nostro controlloSearchBox. Apri la pagina HTML che contiene SearchBox e imposta l'evento onsuggestionsrequested su
SearchUtils.suggestionsRequestedHandler.<div class="searchBox" data-win-control="WinJS.UI.SearchBox" data-win-options="{placeholderText: 'Search', focusOnKeyboardInput: true, onquerysubmitted: SearchUtils.querySubmittedHandler, onsuggestionsrequested: SearchUtils.suggestionsRequestedHandler}"> </div>
Implementazione del contratto Ricerca (per le versioni precedenti di Windows)
Prima di Windows 8.1, le app usavano l'accesso alla ricerca per rendere disponibili funzionalità di ricerca in-app. Gli sviluppatori dovevano implementare il contratto Ricerca e usare l'API SearchPane per gestire le query e ottenere suggerimenti e risultati.
Anche se continuiamo a offrire supporto completo per il contratto Ricerca di Windows 8 e l'API SearchPane, a partire da Windows 8.1 consigliamo di usare il controllo SearchBox invece di SearchPane. Le app che usano il controllo SearchBox non devono implementare il contratto Ricerca.
Esistono casi in cui un'app deve usare il controllo SearchPane e il contratto Ricerca? Se prevedi che gli utenti non debbano eseguire ricerche frequenti nella tua app, puoi usare il controllo SearchPane e il contratto Ricerca. Ti consigliamo di usare un pulsante con il glifo di ricerca (Segoe UI Symbol 0xE0094, 15 pt) nella tua app su cui gli utenti possono fare clic per attivare il riquadro di ricerca. Per visualizzare il codice di implementazione del controllo SearchPane e del contratto Ricerca, vedi l'esempio di contratto Ricerca.
Riepilogo e passaggi successivi
Hai scoperto come usare il controllo SearchBox e la Pagina risultati ricerca per aggiungere funzionalità di ricerca nella tua app.
Per le linee guida che ti consentono di progettare e creare una buona esperienza di ricerca per gli utenti, vedi Linee guida ed elenco di controllo per la ricerca.