jQuery UI API - Widget Autocomplete

Catégories

Widgets

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 natifchangeé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,appendTol'option ne doit pas être modifiée.

Exemples de code :

Initialisez un autocomplete avec le paramètre spécifiéappendTooption:

$( ".selector" ).autocomplete({ appendTo: "#someElem" });
    

Après l'initialisation, obtenir ou définir l'appendTooption:

// 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éautoFocusoption:

$( ".selector" ).autocomplete({ autoFocus: true });
    

Après l'initialisation, obtenir ou définir l'autoFocusoption:

// 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édelayoption:

$( ".selector" ).autocomplete({ delay: 500 });
    

Après l'initialisation, obtenir ou définir l'delayoption:

// 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édisabledoption:

$( ".selector" ).autocomplete({ disabled: true });
    

Après l'initialisation, obtenir ou définir l'disabledoption:

// 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éminLengthoption:

$( ".selector" ).autocomplete({ minLength: 0 });
    

Après l'initialisation, obtenir ou définir l'minLengthoption:

// 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épositionoption:

$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
    

Après l'initialisation, obtenir ou définir l'positionoption:

// 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 sursourceles différentes variantes de l'option - vous pouvez trouver celle qui correspond à votre utilisation et consulter le code associé.

Plusieurs types sont pris en charge :

  • Array: Un tableau peut être utilisé pour des données locales. Deux formats sont pris en charge :
    • Tableau de chaînes :[ "Choice1", "Choice2" ]
    • Un tableau d'objets aveclabeletvalueattributs :[ { label: "Choice1", value: "value1" }, ... ]
    L'attribut label est affiché dans le menu de suggestions. Lorsque l'utilisateur sélectionne un élément, la valeur est insérée dans l'élément input. Si un seul attribut est spécifié, cet attribut est traité à la fois comme le label et la valeur. Par exemple, si vous ne fournissez quevaluel'attribut, la valeur est également traitée comme le label.
  • Chaîne: Lors de l'utilisation d'une chaîne, le plugin Autocomplete s'attend à ce que la chaîne pointe vers une ressource URL pouvant renvoyer des données JSON. Elle peut être sur le même hôte ou sur un hôte différent (doit fournir JSONP). Le plugin Autocomplete ne filtre pas les résultats, mais, à la place, au moyen d'untermchamp, ajoute une chaîne de requête pour que le script côté serveur filtre les résultats. Par exemple, sisourcel'option est définie sur"http://example.com", et que l'utilisateur saisitfoo, la requête GET seraithttp://example.com?term=foo. Le format des données lui-même peut être identique à celui des données locales décrites précédemment.
  • Fonction: La troisième variable, une fonction de rappel, offre la plus grande flexibilité et peut être utilisée pour connecter n'importe quelle source de données à l'Autocomplete. La fonction de rappel accepte deux paramètres :
    • unrequestobjet, avec untermattribut, représentant la valeur dans le champ de saisie de texte actuel. Par exemple, si l'utilisateur saisit dans le champ ville"new yo", alors le terme d'Autocomplete est équivalent à"new yo"。
    • aresponsefonction de rappel, fournissant un seul paramètre : les données suggérées à l'utilisateur. Les données doivent être filtrées en fonction du terme fourni et peuvent être dans l'un des formats de données locales décrits ci-dessus. Utilisée pour fournir une fonction de rappel source personnalisée afin de gérer les erreurs pendant la requête. Même si une erreur est rencontrée, vous devez appelerresponsela fonction de rappel. Cela garantit que le widget est toujours dans l'état correct.

    Lors du filtrage des données locales, vous pouvez utiliser la$.ui.autocomplete.escapeRegexfonction intégrée. Elle accepte un argument de type chaîne, échappe tous les caractères d'expression régulière et rend le résultat sûr à transmettre ànew RegExp()。

Exemple de code :

Initialisez l'autocomplete avec lessourceoptions spécifiées :

$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });
    

Après l'initialisation, obtenir ou définir l'sourceoption:

// 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.
  • Cette méthode n'accepte aucun argument.

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.
  • Cette méthode n'accepte aucun argument.

Exemple de code :

Invoquer la méthode destroy :

$( ".selector" ).autocomplete( "destroy" );
    
disable() jQuery (plugin uniquement) Désactive l'autocomplétion.
  • Cette méthode n'accepte aucun argument.

Exemple de code :

Invoquer la méthode disable :

$( ".selector" ).autocomplete( "disable" );
    
enable() jQuery (plugin uniquement) Active l'autocomplétion.
  • Cette méthode n'accepte aucun argument.

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.
  • optionName
    Type : String
    Description : Le nom de l'option à obtenir.

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.
  • Cette méthode n'accepte aucun argument.

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.
  • optionName
    Type : String
    Description : Le nom de l'option à définir.
  • value
    Type : Object
    Description : La valeur à définir pour l'option.

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.
  • options
    Type : Object
    Description : Les paires option-valeur à définir.

Exemple de code :

Invoquez la méthode :

$( ".selector" ).autocomplete( "option", { disabled: true } );
    
widget() jQuery Renvoie unjQueryobjet contenant l'élément de menu.
  • Cette méthode n'accepte aucun argument.

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'<ul> élément créé doit contenir un <a> élément pour la compatibilité avec le widget de menu. Voir l'exemple ci-dessous.

  • ul
    Type : jQuery
    Description : L'élément nouvellement créé<li>doit être ajouté à l'<ul>élément.
  • item
    Type : Object
    • label
      Type : String
      Description : La chaîne à afficher pour l'entrée.
    • item
      Type : String
      Description : La valeur insérée dans le champ de saisie lorsque l'entrée est sélectionnée.

Exemple de code :

Ajouter la valeur de l'entrée comme<li>un attribut de données sur

_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.
  • ul
    Type : jQuery
    Description : Un élément vide<ul>élément à utiliser comme menu du widget.
  • items
    Type : Array
    Description : Un tableau d'éléments correspondant à la saisie de l'utilisateur. Chaque élément est un objet avec unelabeletvaluepropriété.

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.
  • Cette méthode n'accepte aucun argument.

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.
  • event
    Type : Event
  • ui
    Type : Object
    • item
      Type : Object
      Description : L'élément sélectionné dans le menu, sinon la propriété estnull。

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.
  • event
    Type : Event
  • ui
    Type : Object

Remarque :uiL'objet est vide ; il est inclus pour assurer la cohérence avec les autres événements.

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éé.
  • event
    Type : Event
  • ui
    Type : Object

Remarque :uiL'objet est vide ; il est inclus pour assurer la cohérence avec les autres événements.

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.
  • event
    Type : Event
  • ui
    Type : Object
    • item
      Type : Object
      Description : L'élément qui a obtenu 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.
  • event
    Type : Event
  • ui
    Type : Object

Remarque :uiL'objet est vide ; il est inclus pour assurer la cohérence avec les autres événements.

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é.
  • event
    Type : Event
  • ui
    Type : Object
    • content
      Type : Array
      Description : Contient les données de réponse et peut être modifié pour changer les résultats affichés. Ces données sont déjà normalisées, donc si vous modifiez les données, assurez-vous que chaque élément contient lesvalueetlabelpropriété.

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 ) {} );
    
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.
  • event
    Type : Event
  • ui
    Type : Object
    • item
      Type : Object
      Description : Un objet avec leslabeletvaluepropriétés de l'élément sélectionné.

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