Oktatóanyag: Automatikus kiegészítés és javaslatok hozzáadása a .NET SDK használatával

Megtudhatja, hogyan implementálhatja az automatikus kiegészítést (gépelési lekérdezések és javasolt eredmények), amikor a felhasználó elkezd begépelni egy keresőmezőbe. Ebben az oktatóanyagban az automatikusan kitöltött lekérdezéseket és a javasolt eredményeket külön-külön, majd együtt jelenítjük meg. Előfordulhat, hogy egy felhasználónak csak két vagy három karaktert kell beírnia az összes elérhető eredmény megkereséséhez.

Ebben az oktatóanyagban a következőket sajátíthatja el:

  • Javaslatok hozzáadása
  • Kiemelés hozzáadása a javaslatokhoz
  • Automatikus kiegészítés hozzáadása
  • Automatikus kiegészítés és javaslatok kombinálása

Áttekintés

Ez az oktatóanyag automatikus kiegészítést és javasolt eredményeket ad az előző "Lapozás hozzáadása a keresési eredményekhez" című oktatóanyaghoz.

Az oktatóanyagban szereplő kód egy kész verziója a következő projektben található:

Előfeltételek

  • 2a-add-paging (GitHub) megoldás. Ez a projekt lehet az előző oktatóanyagból készült saját verzió, vagy a GitHub egy példánya.

Javaslatok hozzáadása

Kezdjük a legegyszerűbb esettel, amikor alternatív megoldásokat kínálunk a felhasználónak: a javasolt eredmények legördülő listáját.

  1. Az index.cshtml fájlban cserélje le a @id a TextBoxFor utasításban azureautosuggestre.

     @Html.TextBoxFor(m => m.searchText, new { @class = "searchBox", @id = "azureautosuggest" }) <input value="" class="searchBoxSubmit" type="submit">
    
  2. Ezt az utasítást követve a záró </div> után írja be ezt a szkriptet. Ez a szkript a nyílt forráskódú jQuery felhasználói felületi kódtár automatikus kiegészítési widgetét használja a javasolt eredmények legördülő listájának megjelenítéséhez.

    <script>
        $("#azureautosuggest").autocomplete({
            source: "/Home/SuggestAsync?highlights=false&fuzzy=false",
            minLength: 2,
            position: {
                my: "left top",
                at: "left-23 bottom+10"
            }
        });
    </script>
    

    Az azonosító "azureautosuggest" a fenti szkriptet a keresőmezőhöz csatlakoztatja. A widget forrásbeállítása egy Javaslat metódusra van állítva, amely meghívja a Suggest API-t két lekérdezési paraméterrel: kiemelések és homályos, mindkettő hamisra van állítva ebben a példányban. A keresés indításához legalább két karakter szükséges.

Adja hozzá a hivatkozásokat a jQuery-szkriptekhez a nézetben

  1. A jQuery-kódtár eléréséhez módosítsa a <nézetfájl> szakaszát a következő kódra:

    <head>
        <meta charset="utf-8">
        <title>Typeahead</title>
        <link href="https://code.jquery.com/ui/1.12.1/themes/start/jquery-ui.css"
              rel="stylesheet">
        <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
        <script src="https://code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
    
        <link rel="stylesheet" href="~/css/hotels.css" />
    </head>
    
  2. Mivel új jQuery-referenciát vezetünk be, el kell távolítanunk vagy megjegyzést kell fűznünk az alapértelmezett jQuery-hivatkozáshoz a _Layout.cshtml fájlban (a Nézetek/Megosztott mappában). Keresse meg a következő sorokat, és fűzzön megjegyzést az első szkriptsorhoz az ábrán látható módon. Ez a módosítás elkerüli a jQueryre mutató hivatkozások összeütközését.

    <environment include="Development">
        <!-- <script src="~/lib/jquery/dist/jquery.js"></script> -->
        <script src="~/lib/bootstrap/dist/js/bootstrap.js"></script>
        <script src="~/js/site.js" asp-append-version="true"></script>
    </environment>
    

    Most már használhatjuk az előre definiált automatikus kiegészítés jQuery függvényeket.

A Javaslat művelet hozzáadása a vezérlőhöz

  1. A kezdőlap vezérlőjében adja hozzá a SuggestAsync műveletet (a PageAsync művelet után).

    public async Task<ActionResult> SuggestAsync(bool highlights, bool fuzzy, string term)
    {
        InitSearch();
    
        // Setup the suggest parameters.
        var options = new SuggestOptions()
        {
            UseFuzzyMatching = fuzzy,
            Size = 8,
        };
    
        if (highlights)
        {
            options.HighlightPreTag = "<b>";
            options.HighlightPostTag = "</b>";
        }
    
        // Only one suggester can be specified per index. It is defined in the index schema.
        // The name of the suggester is set when the suggester is specified by other API calls.
        // The suggester for the hotel database is called "sg", and simply searches the hotel name.
        var suggestResult = await _searchClient.SuggestAsync<Hotel>(term, "sg", options).ConfigureAwait(false);
    
        // Convert the suggested query results to a list that can be displayed in the client.
        List<string> suggestions = suggestResult.Value.Results.Select(x => x.Text).ToList();
    
        // Return the list of suggestions.
        return new JsonResult(suggestions);
    }
    

    A Méret paraméter megadja, hogy hány eredményt ad vissza (ha nincs meghatározva, az alapértelmezett érték 5). Az index létrehozásakor egy javaslattevő van megadva a keresési indexben. A Microsoft által üzemeltetett mintahotel-indexben a javaslattevő neve "sg", és kizárólag a HotelName mezőben keres javasolt találatokat.

    A fuzzy matching lehetővé teszi, hogy a kimenetben "közeli egyezések" szerepeljenek, akár egy szerkesztési távolságnyi eltérésig. Ha a highlights paraméter értéke igaz, akkor félkövér HTML-címkék jelennek meg a kimenetben. A következő szakaszban mindkét paramétert igaz értékre állítjuk.

  2. Szintaxishibák léphetnek fel. Ha igen, adja hozzá a következő két using utasítást a fájl tetejére.

    using System.Collections.Generic;
    using System.Linq;
    
  3. Indítsa el az alkalmazást. Számos lehetőséget kap-e például, amikor beírja a "po"-t? Most próbálja ki a "pa" elemet.

    A *po* beírása két javaslatot jelenít meg

    Figyeljen arra, hogy a beírt betűknek egy szót kell kezdeniük, és nem szabad egyszerűen szerepelniük a szóban.

  4. A nézetszkriptben állítsa a >fuzzy értéket igazra, majd futtassa újra az alkalmazást. Most írja be a "po" szót. Figyelje meg, hogy a keresés feltételezi, hogy egy betű hibás.

    *pa* beírása igazra állított fuzzy beállítással

    Ha érdekli, az Azure Cognitive Search Lucene lekérdezési szintaxisa részletesen leírja a homályos keresésekben használt logikát.

Kiemelés hozzáadása a javaslatokhoz

A kiemelési paraméter igaz értékre állításával javíthatjuk a javaslatok megjelenését a felhasználó számára. Először azonban fel kell adnunk néhány kódot a nézethez a félkövér szöveg megjelenítéséhez.

  1. A nézetben (index.cshtml) adja hozzá a következő szkriptet a korábban ismertetett "azureautosuggest" szkript után.

    <script>
        var updateTextbox = function (event, ui) {
            var result = ui.item.value.replace(/<\/?[^>]+(>|$)/g, "");
            $("#azuresuggesthighlights").val(result);
            return false;
        };
    
        $("#azuresuggesthighlights").autocomplete({
            html: true,
            source: "/home/suggest?highlights=true&fuzzy=false&",
            minLength: 2,
            position: {
                my: "left top",
                at: "left-23 bottom+10"
            },
            select: updateTextbox,
            focus: updateTextbox
        }).data("ui-autocomplete")._renderItem = function (ul, item) {
            return $("<li></li>")
                .data("item.autocomplete", item)
                .append("<a>" + item.label + "</a>")
                .appendTo(ul);
        };
    </script>
    
  2. Most módosítsa a szövegdoboz azonosítóját, hogy az a következőképpen legyen olvasható.

    @Html.TextBoxFor(m => m.searchText, new { @class = "searchBox", @id = "azuresuggesthighlights" }) <input value="" class="searchBoxSubmit" type="submit">
    
  3. Futtassa újra az alkalmazást, és a javaslatokban félkövérre kell látnia a beírt szöveget. Próbálja meg beírni a "pa" szöveget.

    *pa* beírása kiemeléssel

    A kiemeléshez használt szkriptben lévő logika nem teljesen megbízható. Ha olyan kifejezést ad meg, amely kétszer jelenik meg ugyanabban a névben, a félkövér találatok nem teljesen a kívántak. Próbálkozzon a "mo" gépeléssel.

    Az egyik kérdés, amelyre a fejlesztőnek válaszolnia kell, az, hogy mikor működik "elég jól" egy szkript, és mikor kell foglalkoznia a furcsaságaival. Ebben az oktatóanyagban nem emeljük ki tovább a kiemelést, de egy pontos algoritmus megkeresése megfontolandó, ha a kiemelés nem hatékony az adatok esetében. További információ: Találatok kiemelése.

Automatikus kiegészítés hozzáadása

A javaslatoktól kissé eltérő másik változat az automatikus kiegészítés (más néven "type-ahead"), amely befejez egy lekérdezési kifejezést. A felhasználói élmény javítása előtt ismét a legegyszerűbb implementációval kezdjük.

  1. Írja be a következő szkriptet a nézetbe a korábbi szkriptek követésével.

    <script>
        $("#azureautocompletebasic").autocomplete({
            source: "/Home/Autocomplete",
            minLength: 2,
            position: {
                my: "left top",
                at: "left-23 bottom+10"
            }
        });
    </script>
    
  2. Most módosítsa a szövegdoboz azonosítóját, így az a következőképpen hangzik el.

    @Html.TextBoxFor(m => m.searchText, new { @class = "searchBox", @id = "azureautocompletebasic" }) <input value="" class="searchBoxSubmit" type="submit">
    
  3. A kezdővezérlőben adja meg az AutocompleteAsync műveletet a SuggestAsync művelet után.

    public async Task<ActionResult> AutoCompleteAsync(string term)
    {
        InitSearch();
    
        // Setup the autocomplete parameters.
        var ap = new AutocompleteOptions()
        {
            Mode = AutocompleteMode.OneTermWithContext,
            Size = 6
        };
        var autocompleteResult = await _searchClient.AutocompleteAsync(term, "sg", ap).ConfigureAwait(false);
    
        // Convert the autocompleteResult results to a list that can be displayed in the client.
        List<string> autocomplete = autocompleteResult.Value.Results.Select(x => x.Text).ToList();
    
        return new JsonResult(autocomplete);
    }
    

    Figyelje meg, hogy ugyanazt az "sg" nevű javaslattevő függvényt használjuk az automatikus kiegészítési keresésben, mint a javaslatok esetében (tehát csak a szállodanevek automatikus kiegészítését próbáljuk meg).

    Az Automatikus kiegészítésMode beállítások számos skáláját használjuk, és a OneTermWithContextet használjuk. További lehetőségek leírásáért tekintse meg az Automatikus kiegészítés API-t .

  4. Indítsa el az alkalmazást. Figyelje meg, hogy a legördülő listában megjelenő lehetőségek tartománya egyetlen szó. Próbálkozzon az "re" betűvel kezdődő szavak beírásával. Figyelje meg, hogyan csökken a lehetőségek száma a további betűk beírásával.

    Gépelés alapszintű automatikus kiegészítéssel

    Jelenleg a korábban futtatott javaslatszkript valószínűleg hasznosabb, mint ez az automatikus kiegészítési szkript. Az automatikus kiegészítés felhasználóbarátabbá tétele érdekében fontolja meg a javasolt eredmények használatát.

Automatikus kiegészítés és javaslatok kombinálása

Az automatikus kiegészítés és a javaslatok kombinálása a legösszetettebb lehetőség, és valószínűleg a legjobb felhasználói élményt nyújtja. Azt szeretnénk, hogy a beírt szöveggel beágyazott módon jelenjen meg az Azure Cognitive Search első választása a szöveg automatikus kiegészítéséhez. Emellett több javaslatot is szeretnénk legördülő listaként.

Vannak olyan kódtárak, amelyek ezt a funkciót kínálják – ezt gyakran "beágyazott automatikus kiegészítésnek" vagy hasonló névnek is nevezik. Ezt a funkciót azonban natív módon fogjuk implementálni, hogy megismerhesse az API-kat. Ebben a példában először a vezérlőn fogunk dolgozni.

  1. Adjon hozzá egy műveletet a vezérlőhöz, amely csak egy automatikus kiegészítési eredményt ad vissza egy megadott számú javaslattal együtt. Ezt a műveletet autocompleteAndSuggestAsync-nek hívjuk. Az otthoni vezérlő központban adja hozzá a következő műveletet a többi új művelet után.

    public async Task<ActionResult> AutoCompleteAndSuggestAsync(string term)
    {
        InitSearch();
    
        // Setup the type-ahead search parameters.
        var ap = new AutocompleteOptions()
        {
            Mode = AutocompleteMode.OneTermWithContext,
            Size = 1,
        };
        var autocompleteResult = await _searchClient.AutocompleteAsync(term, "sg", ap);
    
        // Setup the suggest search parameters.
        var sp = new SuggestOptions()
        {
            Size = 8,
        };
    
        // Only one suggester can be specified per index. The name of the suggester is set when the suggester is specified by other API calls.
        // The suggester for the hotel database is called "sg" and simply searches the hotel name.
        var suggestResult = await _searchClient.SuggestAsync<Hotel>(term, "sg", sp).ConfigureAwait(false);
    
        // Create an empty list.
        var results = new List<string>();
    
        if (autocompleteResult.Value.Results.Count > 0)
        {
            // Add the top result for type-ahead.
            results.Add(autocompleteResult.Value.Results[0].Text);
        }
        else
        {
            // There were no type-ahead suggestions, so add an empty string.
            results.Add("");
        }
    
        for (int n = 0; n < suggestResult.Value.Results.Count; n++)
        {
            // Now add the suggestions.
            results.Add(suggestResult.Value.Results[n].Text);
        }
    
        // Return the list.
        return new JsonResult(results);
    }
    

    Az eredménylista tetején egy automatikus kiegészítési lehetőség lesz visszaadva, amelyet az összes javaslat követ.

  2. Ebben a nézetben először implementálunk egy trükköt, hogy egy világosszürke automatikus kiegészítési szót közvetlenül a felhasználó által beírt félkövérebb szöveg alatt jelenítsünk meg. A HTML a relatív elhelyezést is tartalmazza erre a célra. Módosítsa a TextBoxFor utasítást (és annak környező <div> utasításait) a következőkre, figyelembe adva, hogy egy második, alatta azonosított keresőmező közvetlenül a normál keresőmezőnk alatt található, és húzza le ezt a keresőmezőt 39 képponttal az alapértelmezett helyéről!

    <div id="underneath" class="searchBox" style="position: relative; left: 0; top: 0">
    </div>
    
    <div id="searchinput" class="searchBoxForm" style="position: relative; left: 0; top: -39px">
        @Html.TextBoxFor(m => m.searchText, new { @class = "searchBox", @id = "azureautocomplete" }) <input value="" class="searchBoxSubmit" type="submit">
    </div>
    

    Figyelje meg, hogy ebben az esetben ismét módosítjuk az azonosítót azureautocomplete-re .

  3. A nézetben is írja be a következő szkriptet az eddig beírt szkriptek után. A szkript hosszadalmas és összetett, mivel számos bemeneti viselkedést kezel.

    <script>
        $('#azureautocomplete').autocomplete({
            delay: 500,
            minLength: 2,
            position: {
                my: "left top",
                at: "left-23 bottom+10"
            },
    
            // Use Ajax to set up a "success" function.
            source: function (request, response) {
                var controllerUrl = "/Home/AutoCompleteAndSuggestAsync?term=" + $("#azureautocomplete").val();
                $.ajax({
                    url: controllerUrl,
                    dataType: "json",
                    success: function (data) {
                        if (data && data.length > 0) {
    
                            // Show the autocomplete suggestion.
                            document.getElementById("underneath").innerHTML = data[0];
    
                            // Remove the top suggestion as it is used for inline autocomplete.
                            var array = new Array();
                            for (var n = 1; n < data.length; n++) {
                                array[n - 1] = data[n];
                            }
    
                            // Show the drop-down list of suggestions.
                            response(array);
                        } else {
    
                            // Nothing is returned, so clear the autocomplete suggestion.
                            document.getElementById("underneath").innerHTML = "";
                        }
                    }
                });
            }
        });
    
        // Complete on TAB.
        // Clear on ESC.
        // Clear if backspace to less than 2 characters.
        // Clear if any arrow key hit as user is navigating the suggestions.
        $("#azureautocomplete").keydown(function (evt) {
    
            var suggestedText = document.getElementById("underneath").innerHTML;
            if (evt.keyCode === 9 /* TAB */ && suggestedText.length > 0) {
                $("#azureautocomplete").val(suggestedText);
                return false;
            } else if (evt.keyCode === 27 /* ESC */) {
                document.getElementById("underneath").innerHTML = "";
                $("#azureautocomplete").val("");
            } else if (evt.keyCode === 8 /* Backspace */) {
                if ($("#azureautocomplete").val().length < 2) {
                    document.getElementById("underneath").innerHTML = "";
                }
            } else if (evt.keyCode >= 37 && evt.keyCode <= 40 /* Any arrow key */) {
                document.getElementById("underneath").innerHTML = "";
            }
        });
    
        // Character replace function.
        function setCharAt(str, index, chr) {
            if (index > str.length - 1) return str;
            return str.substr(0, index) + chr + str.substr(index + 1);
        }
    
        // This function is needed to clear the "underneath" text when the user clicks on a suggestion, and to
        // correct the case of the autocomplete option when it does not match the case of the user input.
        // The interval function is activated with the input, blur, change, or focus events.
        $("#azureautocomplete").on("input blur change focus", function (e) {
    
            // Set a 2 second interval duration.
            var intervalDuration = 2000, 
                interval = setInterval(function () {
    
                    // Compare the autocorrect suggestion with the actual typed string.
                    var inputText = document.getElementById("azureautocomplete").value;
                    var autoText = document.getElementById("underneath").innerHTML;
    
                    // If the typed string is longer than the suggestion, then clear the suggestion.
                    if (inputText.length > autoText.length) {
                        document.getElementById("underneath").innerHTML = "";
                    } else {
    
                        // If the strings match, change the case of the suggestion to match the case of the typed input.
                        if (autoText.toLowerCase().startsWith(inputText.toLowerCase())) {
                            for (var n = 0; n < inputText.length; n++) {
                                autoText = setCharAt(autoText, n, inputText[n]);
                            }
                            document.getElementById("underneath").innerHTML = autoText;
    
                        } else {
                            // The strings do not match, so clear the suggestion.
                            document.getElementById("underneath").innerHTML = "";
                        }
                    }
    
                    // If the element loses focus, stop the interval checking.
                    if (!$input.is(':focus')) clearInterval(interval);
    
                }, intervalDuration);
        });
    </script>
    

    Figyelje meg, hogy az intervallumfüggvényt arra használják, hogy törölje a mögöttes szöveget, ha az már nem egyezik meg a felhasználó által gépelttel, és beállítsa a megfelelő kis- vagy nagybetűt, ahogyan a felhasználó gépeli (mivel a "pa" megegyezik a "PA", "pA", "Pa" változatokkal a keresés során), hogy a megjelenített szöveg rendezett legyen.

    Olvassa el a szkript megjegyzéseit a teljesebb megértés érdekében.

  4. Végül egy kisebb módosítást kell elvégeznünk két HTML-osztályon, hogy transzparensek legyenek. Adja hozzá a következő sort a searchBoxForm és a searchBox osztályokhoz a hotels.css fájlban.

    background: rgba(0,0,0,0);
    
  5. Most futtassa az alkalmazást. Írja be a "pa" kifejezést a keresőmezőbe. Kapod a "palotát" az automatikus kiegészítési javaslatként, valamint két hotelt, amelyekben a "pa" szerepel?

    Gépelés soros automatikus kiegészítéssel és javaslatokkal

  6. Próbáljon meg lapozással elfogadni az automatikus kiegészítési javaslatot, majd a nyílbillentyűkkel és a tabulátorbillentyűvel jelöljön ki javaslatokat, majd próbálkozzon újra az egérrel és egyetlen kattintással. Ellenőrizze, hogy a szkript megfelelően kezeli-e ezeket a helyzeteket.

    Dönthet úgy, hogy egyszerűbb betölteni egy olyan tárat, amely ezt a funkciót kínálja Önnek, de most már legalább egy módszert ismer a beágyazott automatikus kiegészítés működéséhez.

Összefoglalás

Vegye figyelembe a projekt alábbi tanulságait:

  • Az automatikus kiegészítés (más néven "type-ahead") és a javaslatok lehetővé teszik, hogy a felhasználó csak néhány kulcsot írjon be, hogy pontosan azt keresse meg, amit szeretne.
  • Az automatikus kiegészítés és a közösen végzett javaslatok gazdag felhasználói élményt nyújtanak.
  • Mindig tesztelje az automatikus kiegészítési függvényeket a bemenet minden formájával.
  • A setInterval függvény használata hasznos lehet a felhasználói felület elemeinek ellenőrzésében és javításában.

Következő lépések

A következő oktatóanyagban a felhasználói élmény javításának egy másik módját vizsgáljuk meg, amellyel egyetlen kattintással szűkítheti a kereséseket.