typeahead standalone
v5.4.0
Une bibliothèque de saisie semi-automatique autonome rapide et complète
? Points forts ?
Trouvez ici des documents détaillés avec des démos en direct pour typeahead-standalone.js .
Aperçu d'un exemple de base :
# you can install typeahead with npm
$ npm install --save typeahead-standalone
# Alternatively you can use Yarn
$ yarn add typeahead-standaloneIncluez ensuite la bibliothèque dans votre application/page.
En tant que module,
// 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' ) ;Dans le contexte du navigateur,
<!-- 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 > La bibliothèque sera disponible en tant qu'objet global sur window.typeahead
Typeahead nécessite un élément input auquel s'attacher et une Data source (locale/distante) pour afficher des suggestions.
Voici un exemple très basique (voir démo pour des exemples avancés)
<!-- 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: {...}
}
} ) ; Vous pouvez transmettre les options de configuration suivantes à typeahead-standalone :
| Paramètre | Description | Défaut |
|---|---|---|
input | L'élément d'entrée DOM doit être transmis avec ce paramètre et la saisie anticipée s'attachera à ce champ. | - (Requis) |
source | Il s'agit de la source de données à partir de laquelle les suggestions seront calculées. La source peut être locale, préextraite ou récupérée à partir d'un point de terminaison distant. Détails | - (Requis) |
minLength | Spécifiez la longueur minimale pendant laquelle les suggestions doivent apparaître à l'écran. | 1 |
limit | Spécifiez le nombre maximum de suggestions à afficher. | 5 |
highlight | Les lettres correspondantes à la requête sont mises en évidence dans la liste des suggestions. Un tt-highlight est ajouté pour faciliter le coiffage | true |
autoSelect | Si défini sur true, présélectionne la première suggestion affichée | false |
hint | Met à jour l’espace réservé d’entrée pour qu’il soit égal à la première suggestion correspondante. Un tt-hint est ajouté pour faciliter le style | true |
diacritics | Indicateur pour activer/désactiver la recherche prise en charge par les signes diacritiques de langue (c'est-à-dire la recherche en convertissant les caractères accentués en leurs équivalents non accentués) | undefined |
classNames: Object | L'objet classNames peut être utilisé pour définir des classes personnalisées pour chaque élément HTML injecté dans le DOM. Détails | undefined |
templates | Un objet contenant des modèles pour l'en-tête, le pied de page, la suggestion, le groupe et l'état notFound. Voir la section modèles pour plus de précisions | undefined |
preventSubmit | Si votre élément de saisie est utilisé à l'intérieur d'un élément de formulaire, cet indicateur permet d'empêcher l'action de soumission par défaut lorsque la touche ENTRÉE est enfoncée. | false |
onSubmit(event, selectedItem?) | Lorsque vous souhaitez utiliser la saisie anticipée en dehors d'un élément de formulaire, ce gestionnaire peut être utilisé pour traiter/soumettre la valeur d'entrée. Se déclenche en appuyant sur la touche ENTRÉE. Le premier paramètre est l'événement clavier et le 2ème paramètre est l'élément sélectionné ou non défini si aucun élément n'a été sélectionné | undefined |
display(selectedItem, event?) => string | Ce rappel est exécuté lorsque l'utilisateur sélectionne un élément parmi les suggestions. La suggestion/l'élément actuel est passé en paramètre et doit renvoyer une chaîne définie comme valeur d'entrée. Le deuxième event de paramètre facultatif est un événement Souris/Clavier qui peut être utilisé pour suivre l'interaction de l'utilisateur ou à des fins d'analyse. La valeur par défaut est null . | Renvoie la représentation sous forme de chaîne de l'élément sélectionné |
tokenizer?: (words: string) => string[] | La fonction tokenizer est utilisée pour diviser la requête de recherche et les données de recherche par un ou plusieurs caractères donnés. Cette fonction est utile lorsque vous souhaitez rechercher des mots avec trait d'union ou des mots avec un certain préfixe/suffixe | les mots sont divisés par des espaces (nouvelle ligne, tabulation, espaces) |
listScrollOptions?: ScrollIntoViewOptions | Permet un contrôle précis du comportement de défilement pour une grande liste de suggestions nécessitant un défilement. Ces options sont transmises à la fonction scrollIntoView() . Réf MDN | { block: "nearest", inline: "nearest", behaviour: "auto"} |
retainFocus | Ce paramètre est utile pour contrôler le focus sur l'appui sur la touche "Tab" lorsque la liste des suggestions est ouverte. S'il est activé, il sélectionne l'option en surbrillance, puis renvoie le focus sur l'entrée de recherche. S'il est désactivé, appuyer sur "Tabulation" sélectionnera l'option en surbrillance et déplacera le focus vers l'élément focalisable suivant dans votre formulaire. | true |
hooks | L'option de configuration des hooks est utile pour exécuter du code arbitraire à des moments spécifiques du cycle de vie de la saisie anticipée. Détails | indéfini |
Il s'agit de la source de données à partir de laquelle des suggestions seront fournies. Il s'agit du format attendu de l'objet source.
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 est utilisée lorsque vous souhaitez fournir des suggestions à partir d'une source locale comme une variable.prefetch est utilisée lorsque vous souhaitez précharger à l'avance les suggestions d'un point de terminaison distant. Vous devez fournir le paramètre url qui pointe vers le point de terminaison qui renverra des suggestions. Vous pouvez fournir un paramètre when facultatif qui définit le moment où la demande de prélecture doit se produire. La valeur par défaut est onInit ce qui signifie que les suggestions seront préchargées dès que la saisie anticipée sera initialisée. Vous pouvez le définir sur onFocus ce qui entraînera le préchargement des suggestions uniquement lorsque l'utilisateur concentrera la zone de saisie de recherche. L'indicateur done est facultatif et peut être utilisé pour désactiver la demande de prélecture par programme. Sa valeur par défaut est false . Il est automatiquement défini sur true lorsque les données sont préextraites pour la première fois (pour éviter plusieurs requêtes réseau). En définissant done: true , la demande de prélecture ne se produira pas. Un exemple de cas d'utilisation pour ce faire est lorsque vous utilisez localStorage pour stocker des suggestions mais que localStorage avait déjà stocké des suggestions auparavant, éliminant ainsi le besoin de pré-extraire les données. Le rappel process(suggestions) est facultatif. Il est exécuté après la demande de prélecture. Il reçoit les suggestions transformées en tant que paramètre et, à titre d'exemple, peut être utilisé pour stocker les suggestions reçues dans localStorage pour être utilisées ultérieurement.remote est utilisée lorsque vous souhaitez interroger un point de terminaison distant pour récupérer des données.remote , vous devez définir les options url et wildcard . wildcard sera remplacé par la chaîne de recherche lors de l'exécution de la requête.debounce est utilisée pour retarder l'exécution des requêtes http (en millisecondes). C'est facultatif et la valeur par défaut est de 200 ms.GET .transform() facultative qui est appelée immédiatement après que le point de terminaison prefetch/distant renvoie une réponse. Vous pouvez modifier la réponse avant qu'elle ne soit traitée par saisie anticipée.keys est requis lorsque la source de données est un tableau d'objets. La première clé est utilisée pour identifier quelle propriété de l'objet doit être utilisée comme texte pour afficher les suggestions. Par exemple, disons que la source de données ressemble à ceci : /* 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" } ,
...
] Maintenant, si nous souhaitons utiliser le texte défini dans la propriété color pour apparaître comme suggestions, alors les clés doivent inclure la couleur comme première clé. (c'est-à-dire keys: ["color"] ).
Si vous souhaitez ajouter plus de propriétés à l'index de recherche, vous pouvez également spécifier ces propriétés dans le tableau keys . Cela peut être mieux compris avec un exemple. Prenons le même exemple de source de données que celui indiqué ci-dessus. Et si vous vouliez rechercher des couleurs par une autre propriété ( colorCode ) et pas seulement par sa couleur ? Pour ce faire, définissez simplement keys: ["color", "meta.colorCode"] . Si vous recherchez maintenant « YW », la suggestion « Jaune » apparaît comme prévu.
groupKey: "shade" , les suggestions seront regroupées par la propriété " shade ". Dans cet exemple, les couleurs Vert et Olive apparaîtront sous le groupe « Verdâtre » ( shade ) alors que la couleur Jaune n'aura pas de groupe. groupKey prend également en charge l'accès aux propriétés imbriquées à l'aide de la notation par points. (exemple - groupKey: "category.title" )identity() est utilisée pour déterminer le caractère unique de chaque suggestion. Il reçoit la suggestion en tant que paramètre et doit renvoyer une chaîne unique à la suggestion donnée. Il s'agit d'une propriété facultative et elle renvoie par défaut la valeur associée à la première clé, c'est-à-dire keys[0] . Cependant, la valeur par défaut peut ne pas fonctionner à chaque fois. Par exemple, considérons le code suivant - /* 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" } ,
...
] Supposons que les clés soient définies sur keys: ["title"] . Par défaut, la fonction identity() utilise la première clé (c'est-à-dire le title ) pour déterminer l'unicité. Donc, si vous recherchez God , vous ne trouverez qu'une seule suggestion affichée puisqu'il y a 3 chansons avec exactement la même propriété title . Afin d'afficher les 3 suggestions avec différents artistes, vous devez définir la propriété identity de telle sorte qu'elle renvoie une chaîne unique -
identity ( item ) = > ` ${ item . title } ${ item . artist } ` ; Il est fortement recommandé de définir l'option de configuration identity() pour renvoyer une chaîne unique lorsque votre source de données est un tableau d'objets.
Consultez les exemples en direct pour plus de précisions.
Actuellement, il n’y a qu’un seul hook disponible :
updateHits: async (resultSet, loader) => Promise<resultSet> qui est exécuté juste avant que les résultats de la recherche ne soient affichés à l'utilisateur et peut être utilisé pour remplacer les suggestions renvoyées par l'index de recherche. (utile pour le tri personnalisé, le filtrage, l'ajout ou la suppression de résultats. Ce hook est une fonction asynchrone vous permettant de faire des requêtes AJAX pour récupérer de nouveaux résultats si nécessaire) // 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 : ( ) => { ... } ,
}
} ) ; Certains styles de base sont fournis avec la saisie anticipée. L'interface utilisateur dépend entièrement de vous et est personnalisable au pixel près. Vous pouvez utiliser les classes suivantes pour ajouter/remplacer des styles.
typeahead-standalone .tt-input .tt-hint .tt-list . (Une classe tt-hide est ajoutée lorsqu'aucune suggestion n'est disponible)tt-suggestion et si la suggestion est sélectionnée, elle a en plus une classe tt-selected .tt-highlight . Vous pouvez ajouter vos propres styles en ciblant le sélecteur parent .typeahead-standalone . Par exemple, nous pouvons mettre à jour la couleur d'arrière-plan de chaque suggestion comme indiqué ci-dessous :
/* set background color for each suggestion */
. typeahead-standalone . tt-list . tt-suggestion {
background-color : green;
} Pour remplacer le style par défaut, définissez l'option de configuration className et utilisez-la comme sélecteur. Disons que vous définissez className: "my-typeahead" , puis pour remplacer le style lors du survol/sélection d'une suggestion, vous pouvez utiliser :
/* 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;
} À partir de v4.0 , le JS et le CSS ont été séparés, permettant un meilleur contrôle sur le style. L'intégralité du CSS peut être récupérée à partir du CDN ou ci-dessous et être copiée directement dans votre projet, vous permettant ainsi de supprimer/remplacer tous les styles si nécessaire.
/***** 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 ;
}Vous pouvez également utiliser des modèles pour ajouter un en-tête, un pied de page et styliser davantage chaque suggestion.
Des modèles peuvent être utilisés pour personnaliser le rendu de la liste. Leur utilisation est totalement facultative. Actuellement, 7 modèles sont disponibles -
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 */
} Comme vu ci-dessus, chaque modèle prend un rappel qui doit renvoyer une string qui est ensuite interprétée comme HTML. Les modèles reçoivent également un paramètre resultSet qui a une structure comme indiqué ci-dessous.
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
} Pour faciliter le style, chaque modèle est enveloppé dans un élément div avec une classe correspondante. c'est à dire
header => classe tt-headerfooter => classe tt-footersuggestion => classe tt-suggestiongroup => classe tt-grouploader => classe tt-loaderempty => classe tt-emptynotFound => classe tt-notFound L'option de configuration classNames vous permet simplement de remplacer les noms de classe par défaut selon votre choix.
Les noms de classe par défaut utilisés dans la saisie anticipée sont les suivants :
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' ,
} ;À titre d'exemple, si vous souhaitez utiliser un nom de classe différent pour l'élément d'entrée , vous pouvez initialiser la saisie anticipée comme ceci :
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) Réinitialise l’instance de saisie anticipée à l’état dans lequel elle se trouvait avant toute interaction de l’utilisateur. Il supprime tous les éléments de l'index de recherche, à l'exception de ceux qui ont été ajoutés via une source locale. Pour supprimer absolument tous les éléments, la fonction accepte un paramètre facultatif qui doit être défini sur true . Reset() efface également les requêtes distantes mises en cache.
const instance = typeahead ( { /* options */ } ) ;
// clear search index except items added via Local source
instance . reset ( ) ;
// clears entire search index
instance . reset ( true ) ;Cette API est utile dans les situations où vous devez invalider des données après un certain temps.
addToIndex()Ajoute des éléments à l'index de recherche. Utile lorsque vous souhaitez récupérer des données vous-même, puis les ajouter à l'index de recherche. Cela revient à ajouter des éléments via la source locale.
const instance = typeahead ( { /* options */ } ) ;
instance . reset ( true ) ; // or instance.reset();
instance . addToIndex ( [ 'Blue, Baige , Black' ] ) ; destroy()Détruit l'instance de saisie anticipée, efface l'index de recherche, supprime tous les gestionnaires d'événements et nettoie le DOM. Peut être utilisé si vous souhaitez désactiver la saisie anticipée.
const instance = typeahead ( { /* options */ } ) ;
instance . destroy ( ) ;Voici un petit glossaire des codes d'erreurs possibles que l'on peut rencontrer
| Code | Description |
|---|---|
| e01 | Élément DOM d'entrée manquant |
| e02 | Source de suggestions manquante/incorrecte. Vous devez fournir au moins une des 3 sources possibles - locale, prefetch ou distante avec le format source attendu (Ref) |
| e03 | Clés manquantes |
| e04 | La demande de prélecture a échoué |
| e05 | La requête à distance a échoué |
Vous souhaitez contribuer à des fonctionnalités et à des correctifs ?
En savoir plus sur la contribution.
Voir le journal des modifications
MIT © DigitalFortress
