• Evénements tactiles
  • tap
  • taphold
  • swipe
    • scrollSupressionThreshold
    • durationThreshold
    • horizontalDistanceThreshold
    • verticalDistanceThreshold
  • swipeleft
  • swiperight
• Événements virtuels de souris
  • vmouseover
  • vmousedown
  • vmousemove
  • vmouseup
  • vclick
  • vmousecancel
• Événement lors du changement d'orientation
  • orientationchange
• Événements lors du défilement d'une page (scroll)
  • scrollstart
  • scrollstop
• Événements lors du chargement d'une page
  • pagebeforeload
  • pageload
  • pageloadfailed
• Événement lors du changement de page
• pagebeforechange
• pagechange
• pagechangefailed
• Événements lors de la transition entre pages
  • pagebeforeshow
  • pagebeforehide
  • pageshow
  • pagehide
• Événements lors de l'initialisation de la page
  • pagebeforecreate
  • pagecreate
  • pageinit
• Événement lors de la suppression d'une page
  • pageremove
• Événement lors de la mise en page
  • updatelayout
• Événements animation

jQuery Mobile offre plusieurs événements spécifiques, s'appuyant sur les événements natifs, sur lesquels vous pouvez vous appuyer lors du développement. Notez que ces événements emploient divers événements liés au toucher (touch), à la souris (mouse) et à la fenêtre (window), selon l'existence de l'événement, donc vous pouvez vous lier à eux pour une utilisation dans vos environnements portatifs (smartphones) et fixes (ordinateur de bureau). Vous pouvez vous lier à ces événements à l'aide de live() ou bind(), comme vous le feriez avec les autres événements de jQuery.

Evénements liés au touché

tap

Déclenché après un événement tactile complet et rapide.

taphold

Déclenché après un événement tactile complet et durable (près d'une seconde).

swipe

Déclenché lors d'un glissement horizontal de 30px ou plus (et moins de 20px verticalement) se produit dans un laps de temps de 1 seconde, mais celles-ci peuvent être configurés :

• scrollSupressionThreshold (defaut: 10px) – Plus que ce déplacement hrizontal, et nous supprimons le défilement.
• durationThreshold (defaut: 1000ms) – Plus que ce temps, et ce n'est pas balayé.
• horizontalDistanceThreshold (defaut: 30px) – Déplacement par balayage horizontal doit être supérieur à celui-ci.
• verticalDistanceThreshold (defaut: 75px) – Déplacement par balayage vertical doit être inférieur à celui-ci.

swipeleft

Déclenché lorsqu'un événement swipe (balayage) a eu lieu vers la gauche.

swiperight

Déclenché lorsqu'un événement swipe (balayage) a eu lieu vers la gauche.

Événements de souris virtuelle

Nous fournissons un ensemble d'événements "virtuels" de souris qui tentent de faire abstraction des événements tactiles et de souris. Ceci permet au développeur d'enregistrer des auditeurs d'événements basiques pour la souris, tels que mousedown, mousemove, mouseup et click, et le plugin prendra soin d'inscrire, en arrière plan, les auditeurs corrects pour invoquer l'auditeur au moment le plus rapide possible pour ce périphérique . Dans les environnements tactiles, le plugin conserve l'ordre de déclenchement des événements tout comme pour les événements traditionnels liés à la souris. Ainsi par exemple, vmouseup est toujours envoyé avant vmousedown et vmousedown avant vclick, etc. Les événements de souris virtuelle normalisent également la façon dont les informations lées aux coordonnées sont extraites de l'événement, ainsi dans les environnements basés sur le tactile, les coordonnées sont disponibles à partir des propriétés pageX, pageY, screenX, screenY, clientX, et clientY, directement sur l'objet événement.

vmouseover

Événement normalisé pour gérer les événements touch ou mouseover.

vmousedown

Événement normalisé pour gérer les événements touchstart ou mousedown.

vmousemove

Événement normalisé pour gérer les événements touchmove ou mousemove.

vmouseup

Événement normalisé pour gérer les événements touchend ou mouseup.

vclick

Événement normalisé pour gérer les événements touchend ou click de la souris. Sur les appareils tactiles, cet événement est distribué *APRES* vmouseup.

vmousecancel

Événement normalisé pour gérer les événements touch ou mousecancel de la souris.

 

Événement lors du changement d'orientation

orientationchange

Se déclenche lors d'un changement d'orientation de l'appareil (en le tournant verticalement ou horizontalement). Lorsqu'elle est liée à cet événement, votre fonction de callback peut exploiter un second argument, qui contient une propriété orientation valant "portrait" ou "landscape". Ces valeurs sont également ajoutées sous forme de classes à l'élément HTML, vous permettant de les exploiter dans vos sélecteurs CSS. Notez qu'actuellement nous l'avons lié à l'événement resize lorsque orientationChange n'est pas supporté nativement, ou lorsque $.mobile.orientationChangeEnabled est défini sur false.

Événement lors du défilement d'une page (Scroll)

scrollstart

Déclenché quand un défilement commence. Notez que les appareils iOSgèlent la manipulation du DOM durant le défilement, pour les placer dans une file d'attente et les appliquer dès que le défilement prend fin. Nous étudions actuellement les moyens pour permettre les manipulations du DOM à appliquer avant que le défilement débute.

scrollstop

Déclenché quand un défilement s'achève.

Événements lors du chargement d'une page

Quand une page externe est chargée dans l'application DOM, deux événements sont déclenchés. Le premier est pagebeforeload. Le second événement sera soit pageload, soit pageloadfailed.

pagebeforeload

Déclenché avant que toute requête de chargement (load) soit faite. Les callbacks liés à cet événement peuvent appeler preventDefault() sur l'événement pour indiquer qu'ils gèrent la requête de chargement (load). Les callbacks qui font cela *DOIVENT* s'assurer qu'ils appellent resolve() ou reject() sur la référence objet différée contenue dans l'objet de données passé au callback.

L'object data, passé en second argument dans la fonction de callback, contient les propriétés suivantes :

• url (chaîne)
  • L'URL absolue ou relative qui a été passée dans $.mobile.loadPage() par l'appelant.
• absUrl (chaîne)
  • La version absolue de l'URL. Si l'URL est relative, elle est déterminée à partir de l'URL utilisée pour charger la page active courante.
• dataUrl (chaîne)
  • La version filtrée de absUrl pour être utilisée lors de l'identification de la page et mettre à jour l'emplacement du navigateur lorsque la page est rendue active.
• deferred (objet)
  • Fonctions de rappel qui appellent preventDefault() sur l'événement, *DOIVENT* appeler resolve() ou reject() sur cet objet de telle sorte que la requête changePage() reprenne le traitement. Les observateurs de l'objet deferred attendent l'objet deferred pour être résolu comme ceci :

    $( document ).bind( "pagebeforeload", function( event, data ){
    
    	/**
    	 *  Avise le framework que nous allons gérer le chargement.
    	 */
    
    	event.preventDefault();
    
    	/**
    	 * 	... charger le document puis l'insérer dans le DOM...
    	 * à un certain moment, que ce soit dans ce rappel, 
    	 * ou par tout autre moyen asynchrone, appelez resolve, 
    	 * en lui passant les arguments suivants, et un objet de 
    	 * collection jQuery contenant l'élément DOM de la page.
    	 */
    
    	data.deferred.resolve( data.absUrl, data.options, page );
    
    });
    

    ou rejeté comme ceci :

    $( document ).bind( "pagebeforeload", function( event, data ){
    
    	/**
    	 *  Avise le framework que nous allons gérer le chargement.
    	 */
    
    	event.preventDefault();
    
    	/**
    	 * 	... charger le document puis l'insérer dans le DOM...
    	 * à un certain moment, si le chargement échoue, que ce
    	 * soit dans ce rappel, ou par tout autre moyen asynchrone,
    	 * appelez reject comme ceci :
    	 */
    
    	data.deferred.reject( data.absUrl, data.options );
    
    });
    

• options (objet)
  • Cet objet contient les options qui ont été passées dans $.mobile.loadPage().

pageload

Déclenché une fois que la page a été chargée avec succès et insérée dans le DOM. Les fonctions de rappels liées à cet événement passeront un objet data en second argument. Cet objet contient les informations suivantes :

• url (chaîne)
  • L'URL absolue ou relative qui a été transmis à $.mobile.loadPage() par l'appelant..
• absUrl (chaîne)
  • La version absolue de l'url. Si l'url est relative, elle est résolue contre l'URL utilisée pour charger la page active.
• dataUrl (chaîne)
  • La version filtrée de absUrl à utiliser lorsque l'identification de la page et la mise à jour l'emplacement du navigateur lorsque la page est rendue active.
• options (objet)
  • Cet objet contient les options qui ont été transmises à $.mobile.loadPage().
• xhr (objet)
  • L'objet XMLHttpRequest de jQuery utilisé lors d'une tentative de chargement de la page. C'est ce qui est transmis comme 3ème argument à la fonction de rappel success $.ajax() du framework.
• textStatus (null ou string)
  • Selon la documentation de base de jQuery , il s'agira d'une chaîne décrivant l'état. C'est ce qui est transmis comme second argument à la fonction de rappel error $.ajax() du framework.

pageloadfailed

Triggered if the page load request failed. By default, after dispatching this event, the framework will display a page failed message and call reject() on the deferred object contained within the event's data object. Callbacks can prevent this default behavior from executing by calling preventDefault() on the event.

L'objet data, passé en second argument à la fonction de rappel contient les propriétés suivantes :

• url (chaîne)
  • L'URL absolue ou relative qui a été transmise à $.mobile.loadPage() par l'appelant.
• absUrl (chaîne)
  • La version absolue de l'URL. Si l'URL était relative, elle est résolue à l'encontre de l'URL utilisée pour charger la page active actuelle.
• dataUrl (chaîne)
  • La version filtrée d'absUrl à utiliser lors de l'identification de la page et de la mise à jour de l'emplacement du navigateur lorsque la page est rendue active.
• deferred (objet)
  • Les fonctions de rappels qui appellent preventDefault() sur l'événement, *DOIVENT * appeler resolve() ou reject() sur cet objet afin que la requête changePage() reprenne le traitement. Les observateurs d'objet deffered attendent l'objet deffered pour être résolu (resolve) comme ceci:

    $( document ).bind( "pageloadfailed", function( event, data ){
    
    	/**
    	 *  Avise le framework que nous allons gérer les choses.
    	 */
    
    	event.preventDefault();
    
    	/**
    	 * 	... tenter de charger une autre page...
    	 * à un certain moment, que ce soit dans ce rappel, 
    	 * ou par tout autre moyen asynchrone, appelez resolve, 
    	 * en lui passant les arguments suivants, et un objet de 
    	 * collection jQuery contenant l'élément DOM de la page.
    	 */
    
    	data.deferred.resolve( data.absUrl, data.options, page );
    
    });
    

    ou rejeté (reject) comme ceci :

    $( document ).bind( "pageloadfailed", function( event, data ){
    
    	/**
    	 *  Avise le framework que nous allons gérer les choses.
    	 */
    
    	event.preventDefault();
    
    	/**
    	 * 	... tenter de charger une autre page...
    	 * à un certain moment, si le chargement échoue, que ce
    	 * soit dans ce rappel, ou par tout autre moyen asynchrone,
    	 * appelez reject comme ceci :
    	 */
    
    	data.deferred.reject( data.absUrl, data.options );
    
    });
    

• options (objet)
  • Cet objet contient les options qui ont été transmises à $.mobile.loadPage().
• xhr (objet)
  • L'objet XMLHttpRequest jQuery utilisé lorsque l'on tente de charger une page. C'est ce qui est passé comme premier argument à la fonction de rappel error $.ajax() du framework.
• textStatus (null ou string)
  • D'après la documentation jQuery, les valeurs possibles pour cette propriété, à par null, sont "timeout", "error", "abort", et "parsererror". C'est ce qui est passé en second argument à la fonction de rappel error $.ajax() du framework.
• errorThrown (null, chaîne, objet)
  • >D'après la documentation jQuery, cette propriété peut être un objet d'exception si elle se produit, ou si une erreur HTTP s'est produite celle-ci sera définie dans la portion textuelle du statut HTTP. C'est ce qui est passé en troisième argument à la fonction de rappel error $.ajax() du framework.

Événements lors du changement de page

La navigation de page en page dans l'application est généralement accomplie via un appel à $.mobile.changePage(). Cette fonction est chargée de s'assurer que la page où nous naviguons est chargée et insérée dans le DOM, puis dès lors de démarrer l'animation de transition entre la page courante active, et la page que le visiteur souhaite rendre active. Au cours de ce processus, qui est habituellement asynchrone, changePage() va déclencher deux événements. Le premier est pagebeforechange. Le second événement dépend de la réussite ou de l'échec de la requête de chnagement. Il sera soit pagechange ou pagechangefailed.

pagebeforechange

Cet événement est déclenché avant chargement de page ou transition. Les fonctions de rappels peuvent empêcher l'exécution de la fonction changePage() en appelant preventDefault sur l'objet événement passé dans la fonction de rappel. La fonction de rappel reçoit également un objet data comme second argument. L'objet data possède les propriétés suivantes :

• toPage (objet ou chaîne)
  • Cette propriété représente la page que l'appelant souhaite rendre active. Elle peut être soit un objet collection jQuery contenant l'élément DOM de la page, ou une URL absolue/relative vers une page interne ou externe. La valeur correspond exactement au premier argument de l'appel de changePage() qui a déclenché l'événement.
• options (objet)
  • Cet objet contient les options de configuration à utiliser pour l'appel en cours de changePage().

Il convient de noter que les fonctions de rappel peuvent modifier les propriétés toPage et options pour modifier le comportement de l'appel changePage() actuel. Ainsi, par exemple, toPage peut être mappé vers une URL différente depuis l'intérieur d'une fonction de rappel pour faire une sorte de redirection.

pagechange

Cet événement est déclenché aune fois que la requête changePage() ait fini de charger la page dans le DOM et que toutes les animations de transition entres pages soient terminées. Notez que tous les événements pageshow ou pagehide seront déclenchés *AVANT* que cet événement soit déclenché. Les fonctions de rappel pour cet événement particulier seront passées un objet data en second argument. Les propriétés de cet objet sont les suivantes :

• toPage (objet ou chaîne)
  • Cette propriété représente la page que l'appelant souhaite rendre active. Elle peut être soit un objet collection jQuery contenant l'élément DOM de la page, soit une URL absolue/relative vers une page interne ou externe. La valeur correspond exactement au premier argument dans l'appel changePage() qui a déclenché l'événement.
• options (objet)
  • Cet objet contient les options de configuration à utiliser pour l'appel de changePage() en cours.

pagechangefailed

Cet événement est déclenché lorsque la requête changePage() échoue pour charger la page. Les fonctions de rappel pour cet événement particulier seront passées à un objet data comme second argument. Les propriétés de cet objet sont les suivantes :

• toPage (objet ou chaîne)
  • Cette propriété représente la page que l'appelant souhaite rendre active. Elle peut être soit un objet collection jQuery contenant l'élément DOM de la page, soit une URL absolue/relative vers une page interne ou externe. La valeur correspond exactement au premier argument dans l'appel changePage() qui a déclenché l'événement.
• options (objet)
  • Cet objet contient les options de configuration à utiliser pour l'appel de changePage() en cours.

Événements lors de la transition entre pages

Les transitions entre pages sont utilisées pour animer le changement de page entre la page active (fromPage) et la nouvelle page (toPage). Les événements sont déclenchés avant et après ces transitions afin que les observateurs puissent être informés chaque fois que les pages sont affichées ou masquées. Les événements déclenchés sont les suivants :

pagebeforeshow

Déclenché sur la page "toPage" vers laquelle se fait la transition, avant que l'animation de transition réelle soit lancée. Les fonctions de rappel pour cet événement recevront un objet data comme second argument. Cet objet data possède les propriétés suivantes :

• prevPage (objet)
  • Un objet de la collection jQuery qui contient l'élément DOM de la page précédant la transition. Notez que cette collection est vide lorsque la première page est en cours de transition au démarrage de l'application.

pagebeforehide

Déclenché sur la page "fromPage" depuis laquelle se fait la transition, avant que l'animation de transition réelle soit lancée. Les fonctions de rappel pour cet événement recevront un objet data comme second argument. Cet objet data possède les propriétés suivantes :

• nextPage (objet)
  • Un objet de la collection jQuery qui contient l'élément DOM de la page suivant la transition.

Notez que cet événement ne sera pas envoyé au cours de la transition de la première page de démarrage de l'application car il n'existe aucune page précédemment active.

pageshow

Déclenché sur la page "toPage" après que l'animation de transition soit terminée. Les fonctions de rappel pour cet événement recevront un objet data comme second argument. Cet objet data possède les propriétés suivantes :

• prevPage (objet)
  • Un objet de la collection jQuery qui contient l'élément DOM de la page précédent la transition. Notez que cette collection est vide lorsque la première page est en cours de transition au démarrage de l'application.

pagehide

Déclenché sur la page "fromPage" après que l'animation de transition soit terminée. Les fonctions de rappel pour cet événement recevront un objet data comme second argument. Cet objet data possède les propriétés suivantes :

• nextPage (objet)
  • Un objet de la collection jQuery qui contient l'élément DOM de la page vers laquelle s'est faite la transition.

Notez que cet événement ne sera pas envoyé lors de la transition de la première page au démarrage de l'application car il n'existe aucune page précédemment active.

Vous pouvez accéder aux propriétés prevPage ou nextPage via le second argument de la fonction de rappel liée. Par exemple :

$( 'div' ).live( 'pageshow', function(event, ui){

	alert( 'Cette page vient juste d´être cachée : '+ ui.prevPage);
	
});



$( 'div' ).live( 'pagehide',function(event, ui){

	alert( 'Cette page vient juste d´être affichée : '+ ui.nextPage);
	
});

Aussi, pour que ces gestionnaires soient invoqués au cours du chargement initial de la page, vous devez les lier avant que jQuery Mobile ne soit executé. Ceci peut être fait dans le gestionnaire mobileinit, tel que décrit dans la page configuration globale.

Événements lors de l'initialisation de le page

En interne, jQuery Mobile auto-initialise les plugins basés sur les conventions de balisage dans une "page" donnée. Par exemple, élément input avec un type égal à range génèrera automatiquement un contrôle personnalisé de type curseur.

Cette auto-initialisation est contrôlée par le plugin "page", qui envoie les événements avant et après s'être exécuté, vous permettant de manipuler une page soit avant, soit après l'initialisation, ou encore fournir votre propre comportement d'initialisation et d'empêcher que les auto-initialisations se produisent. Notez que ces événements se déclencheront une seule fois par "page", par opposition aux événements afficher/masquer, qui se déclenchent chaque fois qu'une page est affichée et cachée.

pagebeforecreate

Déclenchée sur la page initialisée, avant que la plupart des plugins d'auto-initialisation ne se produisent.

$( '#aboutPage' ).live( 'pagebeforecreate', function(event){

	alert( 'Cette page vient juste d´être insérée dans le DOM !' );
	
});

Notez qu'en se liant à pagebeforecreate, vous pouvez manipuler le balisage avant que les widgets par défaut de jQuery Mobile ne soient auto-initialisés. Par exemple, imaginons que vous vouliez ajouter des attributs data- via JavaScript plutôt que dans le code source HTML, c'est l'événement que vous devriez utiliser.

$( '#aboutPage' ).live( 'pagebeforecreate', function(event){
	
	/**
	 * manipuler cette page avant que ses widgets soient auto-initialisés
	 */
	 
});

pagecreate

Déclenché lorsque la page a été créée dans le DOM (via ajax ou autre) mais avant que tous les widgets aient eu l'occasion d'améliorer le balisage du contenu. Cet événement est plus utile pour l'utilisateur souhaitant créer ses propres widgets personnalisés pour l'amélioration de balisage enfant comme le font les widgets de jQuery Mobile.

$( '#aboutPage' ).live( 'pagecreate', function(event){

	( ":jqmData(role='sweet-plugin')" ).sweetPlugin();

});

pageinit

Déclenché sur la page en cours d'initialisation, après l'initialisation. Nous vous recommandons la liaison à cet événement au lieu de DOM ready(), parce que cela fonctionnera indépendamment de la question de savoir si la page est chargée directement ou si le contenu est tiré dans une autre page, dans le cadre du système de navigation Ajax.

$( '#aboutPage' ).live( 'pageinit', function(event){

	alert( 'Cette page vient juste d'être améliorée par jQuery Mobile !' );

});

Événement lors de la suppression d'une page

Par défaut, le framework supprime du DOM toutes pages externes non actives chargées dynamiquement dès que l'utilisateur navigue vers une autre page. L'événement pageremove est envoyé juste avant que le framework tente de supprimer la page du DOM.

pageremove

Cet événement est déclenché juste avant que le framework tente de supprimer du DOM une page externe. Les fonctions de rappel (callback) d'événement peuvent appeler preventDefault sur l'objet événement pour empêcher que la page soit supprimée.

Événement lors de la mise en page

Certains composants à l'intérieur du framework, tels que les zones rétractables ou les listes avec moteur de recherche, masquent et affichent dynamiquement leur contenu en fonction des événements utilisateur. Ce masquage/affichage du contenu affecte la taille de la page et peut entraîner le navigateur à ajuster/faire défiler la fenêtre pour accueillir le nouveau format de page. Étant donné que cela peut affecter d'autres éléments tels que les entêtes et pieds de page fixes, les composants, tels que les zones rétractables ou les listes, déclenchent un événement updatelayout personnalisé, pour avertir les autres composants qu'ils doivent ajuster leurs mise en page en réponse aux modifications de leur contenu. Les développeurs qui construisent des applications dynamiques qui injectent, masquent, ou suppriment du contenu dans la page ou la manipulent de sorte que cela affecte les dimensions de la page, peuvent également déclencher manuellement l'événement updatelayout afin d'assurer la mise à jour des composants de la page suite aux changements.

updatelayout

Cet événement est déclenché par des composants au sein du framework qui affichent/masquent dynamiquement le contenu, et est conçu comme un mécanisme générique pour avertir les autres composants qu'il leur faudra peut-être mettre à jour leur taille ou leur position. Dans le framework, cet événement est déclenché sur l'élément composant dont le contenu a été affiché/masqué et se propage (bouillonnement) jusqu'à l'élément document.

$( '#foo' ).hide().trigger( 'updatelayout' );

Événements Animation

jQuery Mobile propose le plugin animationComplete, que vous pouvez utiliser après l'ajout ou la suppression d'une classe qui applique une transition CSS.