jQuery UI API - Widget Autocomplete
Catégories
Utilisation
Description :La fonctionnalité d'autocomplétion effectue des recherches et filtre en fonction de la saisie de l'utilisateur, ce qui permet aux utilisateurs de trouver et de sélectionner rapidement parmi une liste de valeurs prédéfinies.
Version ajoutée :1.8
Tout champ pouvant recevoir une saisie peut être converti en Autocomplete, c'est-à-dire,<input>éléments input,<textarea>éléments textarea, etcontenteditableéléments avec un attribut contenteditable.
En donnant le focus au champ Autocomplete ou en y saisissant des caractères, le plugin commence à rechercher les entrées correspondantes et affiche une liste de valeurs parmi lesquelles choisir. En saisissant davantage de caractères, l'utilisateur peut filtrer la liste pour obtenir de meilleures correspondances.
Ce widget peut être utilisé pour sélectionner des valeurs précédemment sélectionnées, comme la saisie de tags d’article ou d’adresses e-mail à partir d’un carnet d’adresses. L’autocomplétion peut également être utilisée pour renseigner des informations associées, comme la saisie d’un nom de ville pour obtenir le code postal de cette ville.
Vous pouvez obtenir des données à partir d’une source locale ou d’une source distante : une source locale convient aux petits ensembles de données, comme un carnet d’adresses de 50 entrées ; une source distante convient aux grands ensembles de données, comme une base de données de centaines ou de milliers d’entrées. Pour plus d’informations sur les sources de données personnalisées, consultezsourcela documentation de l’option.
Interaction au clavier
Lorsque le menu est ouvert, les commandes clavier suivantes sont disponibles :
- UP - Déplacer le focus vers l’élément précédent. Si vous êtes sur le premier élément, déplacez le focus vers le champ de saisie. Si vous êtes sur le champ de saisie, déplacez le focus vers le dernier élément.
- DOWN - Déplacer le focus vers l’élément suivant. Si vous êtes sur le dernier élément, déplacez le focus vers le champ de saisie. Si vous êtes sur le champ de saisie, déplacez le focus vers le premier élément.
- ESCAPE - Fermer le menu.
- ENTER - Sélectionner l’élément actuellement ciblé et fermer le menu.
- TAB - Sélectionner l’élément actuellement ciblé, fermer le menu et déplacer le focus vers l’élément suivant pouvant recevoir le focus.
- PAGE UP/DOWN - Faire défiler un écran d’éléments (en fonction de la hauteur du menu).
Lorsque le menu est fermé, les commandes clavier suivantes sont disponibles :
- HAUT/BAS - Si satisfait,
minLengthpuis ouvrez le menu.
Thèmes
Le widget Autocomplete utilisele jQuery UI CSS Frameworkpour définir les styles de son apparence et de sa convivialité. Si vous avez besoin d'utiliser des styles spécifiques au widget Autocomplete, vous pouvez utiliser les noms de classes CSS suivants :
ui-autocomplete: Utilisé pour afficher lemenu correspondant.ui-autocomplete-input: L'élément input instancié par le widget Autocomplete.
Dépendances
Notes supplémentaires
- Ce widget nécessite du CSS fonctionnel, sinon il ne fonctionnera pas. Si vous créez un thème personnalisé, utilisez le fichier CSS spécifique au widget comme point de départ.
- Ce widget opère par programmation sur la valeur de l'élément, donc lorsque la valeur de l'élément change, il ne déclenchera pas l'événement natif
changeévénement.
Navigation rapide
| Options | Méthodes | Points d'extension | Événements |
|---|---|---|---|
| Options | Type | Description | Valeur par défaut |
|---|---|---|---|
| appendTo | Sélecteur | L'élément auquel le menu doit être ajouté. Lorsque cette valeur estnull, l'élément parent du champ de saisie vérifiera la présence deui-frontclasse. Si un élément avecui-frontclasse est trouvée, le menu sera ajouté à cet élément. Si aucun élément avecui-frontclasse est trouvée, le menu sera ajouté au body indépendamment de la valeur.Remarque : lorsque le menu de suggestions est ouvert, Exemples de code : Initialisez un autocomplete avec le paramètre spécifié
$( ".selector" ).autocomplete({ appendTo: "#someElem" });
Après l'initialisation, obtenir ou définir l' // getter var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" ); // setter $( ".selector" ).autocomplete( "option", "appendTo", "#someElem" ); |
null |
| autoFocus | Boolean | Si défini surtrue, lorsque le menu est affiché, le premier recevra automatiquement le focus.Exemples de code : Initialisez un autocomplete avec le paramètre spécifié
$( ".selector" ).autocomplete({ autoFocus: true });
Après l'initialisation, obtenir ou définir l' // getter var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" ); // setter $( ".selector" ).autocomplete( "option", "autoFocus", true ); |
false |
| delay | Integer | Le délai entre une frappe et l'exécution de la recherche, en millisecondes. Pour les données locales, un délai nul est pertinent (plus réactif), mais pour les données distantes, il entraîne une charge importante et réduit la réactivité. Exemples de code : Initialisez un autocomplete avec le paramètre spécifié
$( ".selector" ).autocomplete({ delay: 500 });
Après l'initialisation, obtenir ou définir l' // getter var delay = $( ".selector" ).autocomplete( "option", "delay" ); // setter $( ".selector" ).autocomplete( "option", "delay", 500 ); |
300 |
| disabled | Boolean | Si défini surtrue, l'autocomplétion est désactivée.Exemples de code : Initialisez un autocomplete avec le paramètre spécifié
$( ".selector" ).autocomplete({ disabled: true });
Après l'initialisation, obtenir ou définir l' // getter var disabled = $( ".selector" ).autocomplete( "option", "disabled" ); // setter $( ".selector" ).autocomplete( "option", "disabled", true ); |
false |
| minLength | Integer | Le nombre minimum de caractères que l'utilisateur doit saisir avant qu'une recherche soit exécutée. Pour des données locales ne contenant que quelques entrées, il est généralement défini à zéro, mais lorsqu'une recherche sur un seul caractère correspondrait à des milliers d'entrées, il est nécessaire de définir une valeur élevée. Exemples de code : Initialisez un autocomplete avec le paramètre spécifié
$( ".selector" ).autocomplete({ minLength: 0 });
Après l'initialisation, obtenir ou définir l' // getter var minLength = $( ".selector" ).autocomplete( "option", "minLength" ); // setter $( ".selector" ).autocomplete( "option", "minLength", 0 ); |
1 |
| position | Object | Spécifie la position du menu de suggestions par rapport à l'élément de saisie associé.ofL'option est définie par défaut sur l'élément de saisie, mais vous pouvez spécifier un autre élément de positionnement. Pour plus de détails sur les différentes options, consultezjQuery UI Position。Exemples de code : Initialisez un autocomplete avec le paramètre spécifié
$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
Après l'initialisation, obtenir ou définir l'
// getter
var position = $( ".selector" ).autocomplete( "option", "position" );
// setter
$( ".selector" ).autocomplete( "option", "position", { my : "right top", at: "right bottom" } );
|
{ my: "left top", at: "left bottom", collision: "none" } |
| source | Array ou String ou Function( Object request, Function response( Object data ) ) | Définit les données à utiliser et doit être spécifié. Quelle que soit la variable que vous utilisez, le libellé est toujours traité comme du texte. Si vous souhaitez que le libellé soit traité comme du html, vous pouvez utiliserl'extension html de Scott González. La démo se concentre sur Plusieurs types sont pris en charge :
Exemple de code : Initialisez l'autocomplete avec les
$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });
Après l'initialisation, obtenir ou définir l' // getter var source = $( ".selector" ).autocomplete( "option", "source" ); // setter $( ".selector" ).autocomplete( "option", "source", [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] ); |
aucune ; doit être spécifiée |
| Méthodes | Renvoie | Description |
|---|---|---|
| close() | jQuery (plugin uniquement) | Ferme le menu d'autocomplétion. Lorsqu'elle est utilisée avec lasearchméthode, elle peut être utilisée pour fermer un menu ouvert.
Exemple de code : Appelez la méthode close : $( ".selector" ).autocomplete( "close" ); |
| destroy() | jQuery (plugin uniquement) | Supprime complètement la fonctionnalité d'autocomplétion. Cela remettra l'élément dans son état de pré-initialisation.
Exemple de code : Invoquer la méthode destroy : $( ".selector" ).autocomplete( "destroy" ); |
| disable() | jQuery (plugin uniquement) | Désactive l'autocomplétion.
Exemple de code : Invoquer la méthode disable : $( ".selector" ).autocomplete( "disable" ); |
| enable() | jQuery (plugin uniquement) | Active l'autocomplétion.
Exemple de code : Invoquer la méthode enable : $( ".selector" ).autocomplete( "enable" ); |
| option( optionName ) | Object | Obtient la valeur actuellement associée au paramètre spécifiéoptionNameoption.
Exemple de code : Invoquez la méthode : var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" ); |
| option() | PlainObject | Obtient un objet contenant des paires clé/valeur qui représentent le hash actuel des options d'autocomplétion.
Exemple de code : Invoquez la méthode : var options = $( ".selector" ).autocomplete( "option" ); |
| option( optionName, value ) | jQuery (plugin uniquement) | Définit la valeur de l'option d'autocomplétion associée au paramètre spécifiéoptionNameoption.
Exemple de code : Invoquez la méthode : $( ".selector" ).autocomplete( "option", "disabled", true ); |
| option( options ) | jQuery (plugin uniquement) | Définit une ou plusieurs options pour l'autocomplétion.
Exemple de code : Invoquez la méthode :
$( ".selector" ).autocomplete( "option", { disabled: true } );
|
| search( [value ] ) | jQuery (plugin uniquement) | Déclenche lasearchévénement search, et si l'événement n'est pas annulé, appelle la source de données. Lorsqu'il est cliqué, il peut être utilisé par un bouton de type selectbox pour ouvrir les suggestions. Lorsqu'il est invoqué sans arguments, la valeur actuelle du champ de saisie est utilisée. Peut être invoqué avec une chaîne vide etminLength: 0pour afficher tous les éléments.
Exemple de code : Invoquez la méthode search : $( ".selector" ).autocomplete( "search", "" ); |
| widget() | jQuery | Renvoie unjQueryobjet contenant l'élément de menu.
Exemple de code : Invoquez la méthode widget : $( ".selector" ).autocomplete( "widget" ); |
| Points d'extension | Renvoie | Description |
|---|---|---|
| Le widget Autocomplete est créé via laWidget Factoryet peut être étendu. Lors de l'extension du widget, vous pouvez remplacer ou ajouter des comportements au widget d'extension. Les méthodes fournies ci-dessous servent de points d'extension et ont la même stabilité d'API que lesméthodes de pluginlistées ci-dessus. Pour plus d'informations sur les extensions de widgets, voirExtension des widgets avec la Widget Factory. | ||
| _renderItem( ul, item ) | jQuery | Méthode qui contrôle la création de chaque option dans le menu du widget. La méthode doit créer un nouvel <li> élément, l'ajouter au menu et le retourner.Remarque : à l'heure actuelle, l'
Exemple de code : Ajouter la valeur de l'entrée comme
_renderItem: function( ul, item ) {
return $( "<li>" )
.attr( "data-value", item.value )
.append( $( "<a>" ).text( item.label ) )
.appendTo( ul );
}
|
| _renderMenu( ul, items ) | jQuery (plugin uniquement) | Cette méthode est chargée d'ajuster la taille du menu avant que le menu ne soit affiché. L'élément de menu peut être obtenu enthis.menu.elementutilisant.
Exemple de code : Ajouter un nom de classe CSS aux anciens éléments du menu.
_renderMenu: function( ul, items ) {
var that = this;
$.each( items, function( index, item ) {
that._renderItemData( ul, item );
});
$( ul ).find( "li:odd" ).addClass( "odd" );
}
|
| _resizeMenu() | jQuery (plugin uniquement) | Cette méthode est chargée d'ajuster la taille du menu avant que le menu ne soit affiché. L'élément de menu peut être obtenu enthis.menu.elementutilisant.
Exemple de code : Le menu est toujours affiché avec une largeur de 500 pixels.
_resizeMenu: function() {
this.menu.element.outerWidth( 500 );
}
|
| Événements | Type | Description |
|---|---|---|
| change( event, ui ) | autocompletechange | Déclenché lorsque la valeur du champ de saisie change.
Exemple de code : Initialiser l'autocomplete avec la fonction de rappel change spécifiée :
$( ".selector" ).autocomplete({
change: function( event, ui ) {}
});
Lier un écouteur d'événement à l'événement autocompletechange :
$( ".selector" ).on( "autocompletechange", function( event, ui ) {} );
|
| close( event, ui ) | autocompleteclose | Déclenché lorsque le menu est masqué. Tous lescloseévénements ne sont pas accompagnés d'unchangeévénement.
Remarque : Exemple de code : Initialisez l'autocomplete avec la fonction de rappel close spécifiée :
$( ".selector" ).autocomplete({
close: function( event, ui ) {}
});
Lier un écouteur d'événement à l'événement autocompleteclose :
$( ".selector" ).on( "autocompleteclose", function( event, ui ) {} );
|
| create( event, ui ) | autocompletecreate | Déclenché lorsque l'autocomplete est créé.
Remarque : Exemple de code : Initialisez l'autocomplete avec la fonction de rappel create spécifiée :
$( ".selector" ).autocomplete({
create: function( event, ui ) {}
});
Lier un écouteur d'événement à l'événement autocompletecreate :
$( ".selector" ).on( "autocompletecreate", function( event, ui ) {} );
|
| focus( event, ui ) | autocompletefocus | Déclenché lorsque le focus se déplace vers un élément (non sélectionné). L'action par défaut consiste à remplacer la valeur du champ de texte par la valeur de l'élément ayant le focus, même si l'événement est déclenché par une interaction au clavier. L'annulation de cet événement empêche la mise à jour de la valeur, mais n'empêche pas l'élément de menu d'obtenir le focus.
Exemple de code : Initialisez l'autocomplete avec la fonction de rappel focus spécifiée :
$( ".selector" ).autocomplete({
focus: function( event, ui ) {}
});
Liez un écouteur d'événement à l'événement autocompletefocus :
$( ".selector" ).on( "autocompletefocus", function( event, ui ) {} );
|
| open( event, ui ) | autocompleteopen | Déclenché lorsque le menu de suggestions est ouvert ou mis à jour.
Remarque : Exemple de code : Initialisez l'autocomplete avec la fonction de rappel open spécifiée :
$( ".selector" ).autocomplete({
open: function( event, ui ) {}
});
Liez un écouteur d'événement à l'événement autocompleteopen :
$( ".selector" ).on( "autocompleteopen", function( event, ui ) {} );
|
| response( event, ui ) | autocompleteresponse | Déclenché après qu'une recherche est terminée et avant que le menu ne soit affiché. Utile pour la manipulation locale des données de suggestion, où unsourcecallback d'option personnalisé n'est pas requis. Cet événement est toujours déclenché lorsque la recherche se termine, et il est déclenché même si le menu n'est pas affiché parce que la recherche n'a renvoyé aucun résultat ou qu'Autocomplete est désactivé.
Exemples de code : Initialisez l'autocomplétion avec le callback de réponse spécifié :
$( ".selector" ).autocomplete({
response: function( event, ui ) {}
});
Liez un écouteur d'événement à l'événement autocompleteresponse :
$( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} );
|
| search( event, ui ) | autocompletesearch | Rempli avant l'exécution de la rechercheminLengthetdelaypuis déclenché. Si cet événement est annulé, aucune requête ne sera soumise et aucune suggestion ne sera fournie.
Remarque : Exemples de code : Initialisez l'autocomplétion avec le callback de recherche spécifié :
$( ".selector" ).autocomplete({
search: function( event, ui ) {}
});
Lier un écouteur d'événement à l'événement autocompletesearch :
$( ".selector" ).on( "autocompletesearch", function( event, ui ) {} );
|
| select( event, ui ) | autocompleteselect | Déclenché lorsqu'un élément est sélectionné dans le menu. L'action par défaut consiste à remplacer la valeur du champ de texte par la valeur de l'élément sélectionné. L'annulation de cet événement empêche la mise à jour de la valeur, mais n'empêche pas la fermeture du menu.
Exemples de code : Initialiser l'autocomplete avec le rappel select spécifié :
$( ".selector" ).autocomplete({
select: function( event, ui ) {}
});
Lier un écouteur d'événement à l'événement autocompleteselect :
$( ".selector" ).on( "autocompleteselect", function( event, ui ) {} );
|
Exemples
Exemple 1 :Un simple autocomplete jQuery UI.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>自动完成部件(Autocomplete Widget)演示</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<label for="autocomplete">选择一个编程语言:</label>
<input id="autocomplete">
<script>
$( "#autocomplete" ).autocomplete({
source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ]
});
</script>
</body>
</html>
Exemple 2 :
Utiliser un rappel de source personnalisé pour faire correspondre le début du terme.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>自动完成部件(Autocomplete Widget)演示</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<label for="autocomplete">选择一个编程语言:</label>
<input id="autocomplete">
<script>
var tags = [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ];
$( "#autocomplete" ).autocomplete({
source: function( request, response ) {
var matcher = new RegExp( "^" + $.ui.autocomplete.escapeRegex( request.term ), "i" );
response( $.grep( tags, function( item ){
return matcher.test( item );
}) );
}
});
</script>
</body>
</html>
Autres extensions