typeahead standalone
v5.4.0
Eine schnelle, voll funktionsfähige, eigenständige Autovervollständigungsbibliothek
? Höhepunkte?
Hier finden Sie detaillierte Dokumente mit Live-Demos für typeahead-standalone.js .
Vorschau eines einfachen Beispiels:
# you can install typeahead with npm
$ npm install --save typeahead-standalone
# Alternatively you can use Yarn
$ yarn add typeahead-standaloneFügen Sie dann die Bibliothek in Ihre App/Seite ein.
Als Modul
// using ES6 modules
import typeahead from 'typeahead-standalone' ; // imports library (js)
import 'typeahead-standalone/dist/basic.css' ; // imports basic styles (css)
// using CommonJS modules
const typeahead = require ( 'typeahead-standalone' ) ;
require ( 'typeahead-standalone/dist/basic.css' ) ;Im Browserkontext
<!-- Include the basic styles & the library -->
< link rel =" stylesheet " href =" ./node_modules/typeahead-standalone/dist/basic.css " />
< script src =" ./node_modules/typeahead-standalone/dist/typeahead-standalone.umd.js " > </ script >
<!-- Alternatively, you can use a CDN. For example, use jsdelivr to get the latest version -->
< link rel =" stylesheet " href =" https://cdn.jsdelivr.net/npm/typeahead-standalone/dist/basic.css " />
< script src =" https://cdn.jsdelivr.net/npm/typeahead-standalone " > </ script >
<!-- or use unpkg.com to get a specific version -->
< link rel =" stylesheet " href =" https://unpkg.com/[email protected]/dist/basic.css " />
< script src =" https://unpkg.com/[email protected]/dist/typeahead-standalone.umd.js " > </ script > Die Bibliothek wird als globales Objekt unter window.typeahead verfügbar sein
Typeahead erfordert ein input , an das es sich anhängen kann, und eine Data source (lokal/remote), um Vorschläge anzuzeigen.
Hier ist ein sehr einfaches Beispiel (siehe Demo für fortgeschrittene Beispiele)
<!-- include the library -->
< script src =" ... " async > </ script >
<!-- Html markup -->
< input type =" search " id =" searchInput " autocomplete =" off " placeholder =" Search... " > // local Data
const colors = [ 'Grey' , 'Brown' , 'Black' , 'Blue' ] ;
// input element to attach to
const inputElement = document . getElementById ( "searchInput" ) ;
typeahead ( {
input : inputElement ,
source : {
local : colors ,
// prefetch: {...}
// remote: {...}
}
} ) ; Sie können die folgenden Konfigurationsoptionen an typeahead-standalone übergeben:
| Parameter | Beschreibung | Standard |
|---|---|---|
input | Das DOM-Eingabeelement muss mit diesem Parameter übergeben werden und Typeahead hängt sich an dieses Feld an. | - (Erforderlich) |
source | Dies ist die Datenquelle, aus der Vorschläge berechnet werden. Die Quelle kann lokal sein, vorab abgerufen oder von einem Remote-Endpunkt abgerufen werden. Einzelheiten | - (Erforderlich) |
minLength | Geben Sie die Mindestlänge an, ab der Vorschläge auf dem Bildschirm angezeigt werden sollen. | 1 |
limit | Geben Sie die maximale Anzahl der Vorschläge an, die angezeigt werden sollen. | 5 |
highlight | Die passenden Buchstaben aus der Suchanfrage werden in der Vorschlagsliste hervorgehoben. Um das Styling zu erleichtern, wird eine Klasse tt-highlight hinzugefügt | true |
autoSelect | Wenn auf „true“ gesetzt, wird der erste angezeigte Vorschlag vorab ausgewählt | false |
hint | Aktualisiert den Eingabeplatzhalter so, dass er dem ersten übereinstimmenden Vorschlag entspricht. Zur Vereinfachung des Stylings wird ein Klassen tt-hint hinzugefügt | true |
diacritics | Flag zum Aktivieren/Deaktivieren der von sprachdiakritischen Zeichen unterstützten Suche (d. h. Suche durch Konvertieren von akzentuierten Zeichen in ihre nicht akzentuierten Gegenstücke) | undefined |
classNames: Object | Das classNames-Objekt kann verwendet werden, um benutzerdefinierte Klassen für jedes HTML-Element festzulegen, das in das DOM eingefügt wird. Einzelheiten | undefined |
templates | Ein Objekt, das Vorlagen für Kopfzeile, Fußzeile, Vorschlag, Gruppe und NotFound-Status enthält. Weitere Informationen finden Sie im Abschnitt „Vorlagen“. | undefined |
preventSubmit | Wenn Ihr Eingabeelement innerhalb eines Formularelements verwendet wird, ermöglicht dieses Flag, die standardmäßige Absendeaktion zu verhindern, wenn die EINGABETASTE gedrückt wird. | false |
onSubmit(event, selectedItem?) | Wenn Sie Typeahead außerhalb eines Formularelements verwenden möchten, kann dieser Handler zum Verarbeiten/Übermitteln des Eingabewerts verwendet werden. Wird durch Drücken der ENTER-Taste ausgelöst. Der erste Parameter ist das Tastaturereignis und der zweite Parameter ist das ausgewählte Element oder undefiniert, wenn kein Element ausgewählt wurde | undefined |
display(selectedItem, event?) => string | Dieser Rückruf wird ausgeführt, wenn der Benutzer ein Element aus den Vorschlägen auswählt. Der aktuelle Vorschlag/das aktuelle Element wird als Parameter übergeben und muss eine Zeichenfolge zurückgeben , die als Eingabewert festgelegt wird. Das zweite optionale event ist ein Maus-/Tastaturereignis, das zur Verfolgung der Benutzerinteraktion oder für Analysen verwendet werden kann. Der Standardwert ist null . | Gibt die Zeichenfolgendarstellung des ausgewählten Elements zurück |
tokenizer?: (words: string) => string[] | Die Tokenizer-Funktion wird verwendet, um die Suchabfrage und die Suchdaten nach einem oder mehreren bestimmten Zeichen aufzuteilen. Diese Funktion ist nützlich, wenn Sie nach Bindestrichen oder Wörtern mit einem bestimmten Präfix/Suffix suchen möchten | Wörter werden durch Leerzeichen getrennt (Neue Zeile, Tab, Leerzeichen) |
listScrollOptions?: ScrollIntoViewOptions | Ermöglicht eine genaue Steuerung des Scrollverhaltens für eine große Liste von Vorschlägen, die gescrollt werden müssen. Diese Optionen werden an die Funktion scrollIntoView() übergeben. MDN-Ref | { block: "nearest", inline: "nearest", behaviour: "auto"} |
retainFocus | Dieser Parameter ist nützlich, um den Fokus beim Drücken der „Tab“-Taste zu steuern, wenn die Liste der Vorschläge geöffnet ist. Wenn diese Option aktiviert ist, wird die hervorgehobene Option ausgewählt und der Fokus dann wieder auf die Sucheingabe zurückgesetzt. Wenn diese Option deaktiviert ist, wird durch Drücken der Tabulatortaste die hervorgehobene Option ausgewählt und der Fokus auf das nächste fokussierbare Element in Ihrem Formular verschoben | true |
hooks | Die Hooks-Konfigurationsoption ist nützlich, um beliebigen Code zu bestimmten Zeitpunkten im Lebenszyklus von Typeahead auszuführen. Einzelheiten | undefiniert |
Dies ist die Datenquelle, aus der Vorschläge bereitgestellt werden. Dies ist das erwartete Format des Quellobjekts.
source: {
local: [],
remote: {
url: 'https://remoteapi.com/%QUERY', // OR "url: (inputQuery: string) => `https://remoteapi.com/${inputQuery}`"
wildcard: '%QUERY',
debounce: 300 // optional, default => 200ms
requestOptions: {} // optional, default => undefined
},
prefetch: {
url: 'https://remoteapi.com/load-suggestions', // OR `url: () => string`
when: 'onFocus', // optional, default => 'onInit'
done: false, // optional, default => false
process: (items) => void, // optional, default => undefined
requestOptions: {} // optional, default => undefined
},
keys: ['...'], // optional (required when source => Object[])
groupKey: '...', // optional, default => undefined
identity: (item) => string, // optional (determines uniqueness of each suggestion)
transform: function (data) {
// modify source data if needed & return it
return data;
}
}
local Datenquelle wird verwendet, wenn Sie Vorschläge aus einer lokalen Quelle wie einer Variablen bereitstellen möchten.prefetch Datenquelle wird verwendet, wenn Sie Vorschläge vorab von einem Remote-Endpunkt laden möchten. Sie müssen den url -Parameter angeben, der auf den Endpunkt verweist, der Vorschläge zurückgibt. Sie können einen optionalen Parameter when angeben, der definiert, wann die Vorabrufanforderung erfolgen soll. Der Standardwert ist onInit was bedeutet, dass Vorschläge vorgeladen werden, sobald Typeahead initialisiert wird. Sie können es auf onFocus setzen, wodurch Vorschläge nur dann vorab geladen werden, wenn der Benutzer das Sucheingabefeld fokussiert. Das done -Flag ist optional und kann verwendet werden, um die Prefetch-Anfrage programmgesteuert zu deaktivieren. Der Standardwert ist false . Es wird automatisch auf true gesetzt, wenn Daten zum ersten Mal vorab abgerufen werden (um mehrere Netzwerkanfragen zu verhindern). Durch die Einstellung done: true wird die Vorabrufanforderung nicht ausgeführt. Ein Beispiel für einen Anwendungsfall hierfür ist, wenn Sie localStorage zum Speichern von Vorschlägen verwenden, der localStorage jedoch bereits zuvor Vorschläge gespeichert hatte, wodurch die Notwendigkeit entfällt, die Daten erneut vorab abzurufen. Der process(suggestions) ist optional. Es wird ausgeführt, nachdem die Prefetch-Anfrage erfolgt ist. Es empfängt die transformierten Vorschläge als Parameter und kann beispielsweise zum Speichern der empfangenen Vorschläge in localStorage zur späteren Verwendung verwendet werden.remote -Datenquelle wird verwendet, wenn Sie einen Remote-Endpunkt abfragen möchten, um Daten abzurufen.remote Datenquelle verwenden, müssen Sie die url und die wildcard festlegen. wildcard wird beim Ausführen der Anfrage durch die Suchzeichenfolge ersetzt.debounce -Option wird verwendet, um die Ausführung von http-Anfragen zu verzögern (in Millisekunden). Dies ist optional und der Standardwert beträgt 200 ms.GET .transform() Funktion bereitstellen, die sofort aufgerufen wird, nachdem der Prefetch-/Remote-Endpunkt eine Antwort zurückgegeben hat. Sie können die Antwort ändern, bevor sie von Typeahead verarbeitet wird.keys ist erforderlich, wenn die Datenquelle ein Array von Objekten ist. Der erste Schlüssel wird verwendet, um zu identifizieren, welche Eigenschaft des Objekts als Text für die Anzeige der Vorschläge verwendet werden soll. Nehmen wir zum Beispiel an, die Datenquelle sieht etwa so aus: /* Example Data source */
[
{ id : 1 , color : "Yellow" , meta : { colorCode : "YW" } } ,
{ id : 2 , color : "Green" , meta : { colorCode : "GN" } , shade : "Greenish" } ,
{ id : 3 , color : "Olive" , meta : { colorCode : "OV" } , shade : "Greenish" } ,
...
] Wenn wir nun den in der Eigenschaft color definierten Text als Vorschläge verwenden möchten, müssen die Schlüssel „Farbe“ als ersten Schlüssel enthalten. (dh keys: ["color"] ).
Wenn Sie dem Suchindex weitere Eigenschaften hinzufügen möchten, können Sie diese Eigenschaften auch im keys angeben. Dies lässt sich am besten anhand eines Beispiels nachvollziehen. Nehmen wir die gleiche Beispieldatenquelle wie oben gezeigt. Was wäre, wenn Sie Farben anhand einer anderen Eigenschaft ( colorCode ) und nicht nur anhand ihrer Farbe suchen möchten? Legen Sie dazu einfach keys: ["color", "meta.colorCode"] . Wenn Sie nun nach „ YW “ suchen, erscheint erwartungsgemäß der Vorschlag „Gelb“.
groupKey: "shade" festlegen, werden die Vorschläge nach der Eigenschaft „ shade “ gruppiert. In diesem Beispiel werden die Farben Grün und Oliv unter der Gruppe „ Grünlich “ ( shade ) angezeigt, während die Farbe Gelb keine Gruppe hat. groupKey unterstützt auch den Zugriff auf verschachtelte Eigenschaften mithilfe der Punktnotation. (Beispiel – groupKey: "category.title" )identity() wird verwendet, um die Einzigartigkeit jedes Vorschlags zu bestimmen. Es empfängt den Vorschlag als Parameter und muss eine für den angegebenen Vorschlag eindeutige Zeichenfolge zurückgeben. Dies ist eine optionale Eigenschaft und gibt standardmäßig den Wert zurück, der dem ersten Schlüssel zugeordnet ist, d keys[0] . Der Standardwert funktioniert jedoch möglicherweise nicht immer. Betrachten Sie beispielsweise den folgenden Code: /* Example Data source of Songs */
[
{ title : "God is Good" , artist : "Don Moen" } ,
{ title : "God is Good" , artist : "Paul Wilbur" } ,
{ title : "God is Good" , artist : "Micheal Smith" } ,
{ title : "El Shaddai" , artist : "Amy Grant" } ,
...
] Nehmen wir an, dass die Tasten auf keys: ["title"] eingestellt sind. Standardmäßig verwendet die Funktion identity() den ersten Schlüssel (dh den Titel ), um die Eindeutigkeit zu bestimmen. Wenn Sie also nach God suchen, wird Ihnen nur ein Vorschlag angezeigt, da es drei Lieder mit genau derselben title gibt. Um alle drei Vorschläge mit unterschiedlichen Künstlern anzuzeigen, müssen Sie die identity so festlegen, dass sie eine eindeutige Zeichenfolge zurückgibt –
identity ( item ) = > ` ${ item . title } ${ item . artist } ` ; Es wird dringend empfohlen, die Konfigurationsoption identity() so festzulegen, dass eine eindeutige Zeichenfolge zurückgegeben wird, wenn Ihre Datenquelle ein Array von Objekten ist.
Schauen Sie sich zur weiteren Erläuterung die Live-Beispiele an.
Derzeit ist nur 1 Haken verfügbar:
updateHits: async (resultSet, loader) => Promise<resultSet> das unmittelbar vor der Anzeige der Suchergebnisse für den Benutzer ausgeführt wird und zum Überschreiben der vom Suchindex zurückgegebenen Vorschläge verwendet werden kann. (Nützlich zum benutzerdefinierten Sortieren, Filtern, Hinzufügen oder Entfernen von Ergebnissen. Dieser Hook ist eine asynchrone Funktion, mit der Sie bei Bedarf AJAX-Anfragen stellen können, um neue Ergebnisse abzurufen.) // Example usage of "updateHits" hook
typeahead ( {
input : document . querySelector ( ".myInput" ) ,
source : {
local : [ ] ,
// ...
} ,
hooks : {
updateHits : async ( resultSet , loader ) => {
resultSet . hits . push ( { name : "new suggestion" } ) ; // add new suggestion
// resultSet.hits.filter( ... ); // filter the suggestions
// resultSet.hits.sort( ... ); // custom sort the suggestions
// resultSet.count = 5000; // to set the total results found
/*** You can also make an AJAX request to fetch results ***/
// loader(); // display the loader template
// const response = await fetch('https://example.com');
// const text = await response.text();
// resultSet.hits = text && JSON.parse(text);
// loader(false); // hide the loader template
// resultSet.updateSearchIndex = true; // updates search index if necessary. Default `false`
return resultSet ; // you must return the resultSet
} ,
} ,
templates : {
loader : ( ) => { ... } ,
}
} ) ; Einige grundlegende Stilelemente werden mit Typeahead bereitgestellt. Die Benutzeroberfläche liegt ganz bei Ihnen und ist pixelgenau anpassbar. Mit den folgenden Klassen können Sie Stile hinzufügen/überschreiben.
typeahead-standalone verpackt.tt-input Klasse.tt-hint Klasse.tt-list -Klasse verpackt. (Eine Klasse tt-hide wird hinzugefügt, wenn keine Vorschläge verfügbar sind)tt-suggestion und wenn der Vorschlag ausgewählt ist, dann hat er zusätzlich eine tt-selected -Klasse.tt-highlight -Klasse. Sie können Ihre eigenen Stile hinzufügen, indem Sie auf den übergeordneten Selektor .typeahead-standalone abzielen. Beispielsweise können wir die Hintergrundfarbe jedes Vorschlags aktualisieren, wie unten gezeigt:
/* set background color for each suggestion */
. typeahead-standalone . tt-list . tt-suggestion {
background-color : green;
} Um den Standardstil zu überschreiben , legen Sie die Konfigurationsoption „ className fest und verwenden Sie sie als Selektor. Nehmen wir an, Sie legen className: "my-typeahead" fest. Um den Stil beim Bewegen/Auswählen eines Vorschlags zu überschreiben, können Sie Folgendes verwenden:
/* override styles */
. typeahead-standalone . my-typeahead . tt-list . tt-suggestion : hover ,
. typeahead-standalone . my-typeahead . tt-list . tt-suggestion . tt-selected {
color : black;
background-color : white;
} Ab v4.0 wurden JS und CSS getrennt, was eine bessere Kontrolle über den Stil ermöglicht. Das gesamte CSS kann entweder vom CDN oder von unten abgerufen und direkt in Ihr Projekt kopiert werden, sodass Sie bei Bedarf alle Stile verwerfen/überschreiben können.
/***** basic styles *****/
. typeahead-standalone {
position : relative;
text-align : left;
color : # 000 ;
}
. typeahead-standalone . tt-input {
z-index : 1 ;
background : transparent;
position : relative;
}
. typeahead-standalone . tt-hint {
position : absolute;
left : 0 ;
cursor : default;
user-select : none;
background : # fff ;
color : silver;
z-index : 0 ;
}
. typeahead-standalone . tt-list {
background : # fff ;
z-index : 1000 ;
box-sizing : border-box;
overflow : auto;
border : 1 px solid rgba ( 50 , 50 , 50 , 0.6 );
border-radius : 4 px ;
box-shadow : 0 px 10 px 30 px 0 px rgba ( 0 , 0 , 0 , 0.1 );
position : absolute;
max-height : 70 vh ;
}
. typeahead-standalone . tt-list . tt-hide {
display : none;
}
. typeahead-standalone . tt-list div [ class ^= "tt-" ] {
padding : 0 4 px ;
}
. typeahead-standalone . tt-list . tt-suggestion : hover ,
. typeahead-standalone . tt-list . tt-suggestion . tt-selected {
background : # 55acee ;
cursor : pointer;
}
. typeahead-standalone . tt-list . tt-suggestion . tt-highlight {
font-weight : 900 ;
}
. typeahead-standalone . tt-list . tt-group {
background : # eee ;
}Sie können auch Vorlagen verwenden, um jedem Vorschlag eine Kopf- und Fußzeile hinzuzufügen und ihn weiter zu gestalten.
Mithilfe von Vorlagen kann die Darstellung der Liste angepasst werden. Ihre Verwendung ist völlig optional. Derzeit sind 7 Vorlagen verfügbar -
templates: {
header : ( resultSet ) => '<h1>List of Countries</h1>' , /* Rendered at the top of the dataset */
footer : ( resultSet ) => '<div>See more</div>' , /* Rendered at the bottom of the dataset */
suggestion : ( item , resultSet ) => { /* Used to render a single suggestion */
return `<div class="custom-suggestion"> ${ item . label } </div>` ;
} ,
group : ( groupName , resultSet ) => { /* Used to render a group */
return `<div class="custom-group"> ${ groupName } </div>` ;
} ,
empty : ( resultSet ) => { /* Rendered when the input query is empty */
return `<div>Search for Colors...</div>` ;
// OR (to display some suggestions by default)
return [ { title : "France" } , { title : "Spain" } ] ;
}
loader : ( ) = > 'Loading...' , /* Rendered while awaiting data from a remote source */
notFound : ( resultSet ) => '<span>Nothing Found</span>' , /* Rendered if no suggestions are available */
} Wie oben zu sehen ist, benötigt jede Vorlage einen Rückruf, der eine string zurückgeben muss , die später als HTML interpretiert wird. Die Vorlagen erhalten außerdem einen Parameter resultSet , der die unten gezeigte Struktur hat.
resultSet = {
query : '...' , // the input query
hits : [ ... ] , // found suggestions
count : 0 , // the total suggestions found in the search index
limit : 5 , // the number of suggestions to show
wrapper : DOMElement , // the container DOM element
} Um das Styling zu erleichtern, ist jede Vorlage in ein div -Element mit einer entsprechenden Klasse eingeschlossen. dh
header => Klasse tt-headerfooter => Klasse tt-footersuggestion => Klasse tt-suggestiongroup => Klasse tt-grouploader => Klasse tt-loaderempty => Klasse tt-emptynotFound => Klasse tt-notFound Mit der Konfigurationsoption „ classNames können Sie einfach die Standardklassennamen nach Ihren Wünschen ersetzen.
Die in typeahead verwendeten Standardklassennamen lauten wie folgt:
const classNames = {
wrapper : 'typeahead-standalone' , /* main container element */
input : 'tt-input' ,
hint : 'tt-hint' ,
highlight : 'tt-highlight' ,
list : 'tt-list' , /* container element for suggestions */
hide : 'tt-hide' ,
show : 'tt-show' ,
selected : 'tt-selected' ,
/* classes used within templates */
header : 'tt-header' ,
footer : 'tt-footer' ,
loader : 'tt-loader' ,
suggestion : 'tt-suggestion' ,
group : 'tt-group' ,
empty : 'tt-empty' ,
notFound : 'tt-notFound' ,
} ;Wenn Sie beispielsweise einen anderen Klassennamen für das Eingabeelement verwenden möchten, können Sie Typeahead wie folgt initialisieren:
typeahead ( {
input : '...' ,
source : '...' ,
classNames : {
input : 'my-custom-input-class' // this class is used instead of tt-input
}
} ) ;typeahead.reset()typeahead.addToIndex()typeahead.destroy()reset(clearLocalSrc?: boolean) Setzt die Typeahead-Instanz auf den Zustand zurück, in dem sie sich vor jeder Benutzerinteraktion befand. Es entfernt alle Elemente aus dem Suchindex mit Ausnahme derjenigen, die über eine lokale Quelle hinzugefügt wurden. Um absolut alle Elemente zu entfernen, akzeptiert die Funktion einen optionalen Parameter, der auf true gesetzt werden sollte. Reset() löscht auch zwischengespeicherte Remote-Anfragen.
const instance = typeahead ( { /* options */ } ) ;
// clear search index except items added via Local source
instance . reset ( ) ;
// clears entire search index
instance . reset ( true ) ;Diese API ist in Situationen nützlich, in denen Sie Daten nach Ablauf einer bestimmten Zeit ungültig machen müssen.
addToIndex()Fügt Elemente zum Suchindex hinzu. Nützlich, wenn Sie Daten selbst abrufen und dann zum Suchindex hinzufügen möchten. Es ähnelt dem Hinzufügen von Elementen über die lokale Quelle.
const instance = typeahead ( { /* options */ } ) ;
instance . reset ( true ) ; // or instance.reset();
instance . addToIndex ( [ 'Blue, Baige , Black' ] ) ; destroy()Zerstört die Typeahead-Instanz, löscht den Suchindex, entfernt alle Event-Handler und bereinigt das DOM. Kann verwendet werden, wenn Sie Typehead deaktivieren möchten.
const instance = typeahead ( { /* options */ } ) ;
instance . destroy ( ) ;Hier ist ein kleines Glossar der möglichen Fehlercodes, auf die man stoßen kann
| Code | Beschreibung |
|---|---|
| e01 | Fehlendes Eingabe-DOM-Element |
| e02 | Fehlende/falsche Quelle für Vorschläge. Sie müssen mindestens eine der drei möglichen Quellen – lokal, Prefetch oder Remote – mit dem erwarteten Quellformat (Ref) angeben. |
| e03 | Fehlende Schlüssel |
| e04 | Die Vorabrufanforderung ist fehlgeschlagen |
| e05 | Die Remote-Anfrage ist fehlgeschlagen |
Sind Sie daran interessiert, Funktionen und Korrekturen beizusteuern?
Lesen Sie mehr über Mitwirken.
Siehe Changelog
MIT © DigitalFortress
