Skip to content

jQuery Mobile Aide-mémoire

Framework UI HTML5 optimisé pour le tactile, pour les applications web mobiles.

01

Démarrage

Structure de page

jQuery Mobile emploie des attributs data-role pour enrichir le HTML. Une page est une div avec data-role=page contenant des sections header, main et footer. La balise meta viewport est essentielle pour une mise à l'échelle correcte sur mobile. Chargez le cœur de jQuery avant jquery.mobile.js.

jquery-mobile
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="https://code.jquery.com/jquery-1.11.1.min.js"></script>
  <script src="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
  <div data-role="page" id="home">
    <div data-role="header"><h1>Home</h1></div>
    <div data-role="main" class="ui-content">Content</div>
    <div data-role="footer"><h4>Footer</h4></div>
  </div>
</body>
</html>

Plusieurs pages dans un document

On peut placer plusieurs div data-role=page dans un même fichier HTML. Reliez-les par des hrefs d'ancre (#about). jQuery Mobile montre une page à la fois et anime les transitions. Seule la première page dans l'ordre source s'affiche au chargement initial.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="header"><h1>Home</h1></div>
  <div data-role="main" class="ui-content">
    <a href="#about" class="ui-btn">Go to About</a>
  </div>
</div>

<div data-role="page" id="about" data-theme="b">
  <div data-role="header"><h1>About</h1></div>
  <div data-role="main" class="ui-content">
    <a href="#home" class="ui-btn" data-direction="reverse">Back</a>
  </div>
</div>

Navigation AJAX et liens

Par défaut, les liens vers des pages internes (#id) ou de même origine sont récupérés par AJAX et échangés avec une transition. Employez data-ajax=false pour forcer un chargement complet normal (utile pour les pages hors jQuery Mobile). data-prefetch précharge la cible pour une transition instantanée.

jquery-mobile
<!-- Default: links load via AJAX and animate a transition -->
<a href="detail.html" class="ui-btn">Open detail (AJAX)</a>

<!-- Force a full page reload (no AJAX) -->
<a href="external.html" data-ajax="false">Full reload</a>

<!-- Open in new window/tab -->
<a href="https://example.com" rel="external">External site</a>

<!-- Prefetch a page when this page loads -->
<a href="next.html" data-prefetch="true" class="ui-btn">Prefetch next</a>

Préchargement et cache DOM

Le préchargement charge les pages liées en arrière-plan pour que la navigation paraisse instantanée. Par défaut, les pages visitées sont retirées du DOM, mais domCache les conserve pour un retour plus rapide, au prix de la mémoire. Activez-le par page avec data-dom-cache ou globalement via l'option du prototype de page.

jquery-mobile
<!-- Prefetch several pages -->
<a href="page1.html" data-prefetch="true">Page 1</a>
<a href="page2.html" data-prefetch="true">Page 2</a>

<!-- Globally enable DOM caching of visited pages -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.domCache = true;
});
</script>

<!-- Cache a single page -->
<div data-role="page" id="cached" data-dom-cache="true">...</div>

Pages de dialogue

Ajoutez data-rel=dialog à un lien (ou data-dialog=true sur la page) pour ouvrir une page stylée en dialogue modal avec bouton de fermeture et transition. Employez data-rel=back sur un lien pour la fermer et revenir à la page précédente.

jquery-mobile
<!-- Open a page as a dialog -->
<a href="#dialog" class="ui-btn" data-rel="dialog">Open dialog</a>

<div data-role="page" id="dialog" data-dialog="true">
  <div data-role="header"><h1>Dialog</h1></div>
  <div data-role="main" class="ui-content">
    <p>This page is styled as a dialog.</p>
    <a href="#" class="ui-btn" data-rel="back">Close</a>
  </div>
</div>

Configuration globale (mobileinit)

L'événement mobileinit se déclenche après le chargement du cœur de jQuery mais avant l'initialisation de jQuery Mobile — liez-y votre config, avant d'inclure jquery.mobile.js. Surcharges courantes : transitions par défaut, réglages AJAX et texte du message de chargement. Mettre autoInitializePage=false permet de contrôler quand la première page s'initialise.

jquery-mobile
<script src="jquery-1.11.1.min.js"></script>
<script>
// Bind BEFORE loading jquery.mobile.js
$(document).on("mobileinit", function () {
  $.mobile.defaultPageTransition = "slide";
  $.mobile.defaultDialogTransition = "pop";
  $.mobile.loadingMessage = "Loading...";
  $.mobile.ajaxEnabled = true;
  $.mobile.linkBindingEnabled = true;
  $.mobile.autoInitializePage = true;
});
</script>
<script src="jquery.mobile-1.4.5.min.js"></script>
02

Transitions de page

Transitions de base

Ajoutez data-transition à un lien pour choisir l'animation de navigation. Les transitions sont basées sur CSS (accélérées matériellement quand possible). 'none' saute l'animation pour une navigation instantanée. Le même attribut vaut pour les dialogs et popups.

jquery-mobile
<!-- Apply a transition to a link -->
<a href="#page2" data-transition="slide">Slide</a>
<a href="#page2" data-transition="fade">Fade</a>
<a href="#page2" data-transition="pop">Pop</a>
<a href="#page2" data-transition="flip">Flip</a>
<a href="#page2" data-transition="none">None (instant)</a>

Types de transition

jQuery Mobile livre un ensemble de transitions CSS 2D/3D. Les 3D (turn, flow, flip) sont superbes sur les appareils capables mais se replient avec grâce sur le vieux matériel. pop et fade sont les plus performantes, recommandées pour dialogs et popups.

jquery-mobile
<!-- Available transitions in jQuery Mobile 1.4 -->
fade      <!-- default, fade in/out -->
pop       <!-- scale in from center (good for dialogs) -->
slide     <!-- slide left to right -->
slideup   <!-- slide up from bottom -->
slidedown <!-- slide down from top -->
slidfade  <!-- slide + fade -->
turn      <!-- 3D turn -->
flow      <!-- 3D flow -->
flip      <!-- 3D flip -->
none      <!-- no animation -->

Direction et inverse

data-direction=reverse joue la transition à l'envers — typiquement sur les boutons Retour pour que l'animation reflète la navigation avant. À associer à data-transition ; sans transition définie, c'est le défaut qui est inversé.

jquery-mobile
<!-- Reverse a transition (e.g., for Back buttons) -->
<a href="#home" data-transition="slide" data-direction="reverse">Back</a>

<!-- Globally reverse the default -->
<a href="#home" data-direction="reverse">Back (uses default transition reversed)</a>

Transitions de dialogue

Les dialogs peuvent employer toute transition, mais pop et slidedown semblent les plus naturelles pour des modales. Fixez un défaut global avec $.mobile.defaultDialogTransition pendant mobileinit. La fermeture du dialogue inverse la transition automatiquement.

jquery-mobile
<!-- Combine data-rel=dialog with a transition -->
<a href="#settings" data-rel="dialog" data-transition="pop">Settings</a>
<a href="#settings" data-rel="dialog" data-transition="slidedown">Settings (slide down)</a>

<!-- Set a global default dialog transition -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.defaultDialogTransition = "pop";
});
</script>

Désactivation et repli

Mettez data-transition=none ou le défaut global à 'none' pour désactiver les animations — utile sur les appareils modestes ou pour l'accessibilité. jQuery Mobile détecte automatiquement le support des transforms 3D et dégrade les transitions 3D (flip, turn, flow) en simple fondu quand non pris en charge.

jquery-mobile
<!-- Disable transitions for a specific link -->
<a href="#page2" data-transition="none">No animation</a>

<!-- Globally disable (useful for older devices / testing) -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.defaultPageTransition = "none";
  $.mobile.defaultDialogTransition = "none";
});
</script>

<!-- 3D transitions fall back to fade when not supported -->
03

Barres d'outils (header et footer)

Header et footer fixes

Ajoutez data-position=fixed pour garder un header ou footer épinglé en haut/en bas de la fenêtre d'affichage pendant le défilement. Taper la page bascule la visibilité des barres par défaut. Le contenu de la page reçoit un padding pour ne pas se cacher derrière.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="header" data-position="fixed">
    <h1>Fixed Header</h1>
  </div>
  <div data-role="main" class="ui-content">
    <p>Scroll the page — the toolbars stay in place.</p>
  </div>
  <div data-role="footer" data-position="fixed">
    <h4>Fixed Footer</h4>
  </div>
</div>

Barres d'outils plein écran

data-fullscreen=true superpose les barres fixes au-dessus du contenu (semi-transparentes), au lieu de réserver de l'espace. Parfait pour des visionneuses de photos ou des cartes où le contenu doit remplir l'écran. Les barres apparaissent/disparaissent au tap comme les barres fixes.

jquery-mobile
<div data-role="page" id="photo">
  <div data-role="header" data-position="fixed" data-fullscreen="true">
    <h1>Photos</h1>
  </div>
  <div data-role="main" class="ui-content">
    <img src="photo.jpg" style="width:100%">
  </div>
  <div data-role="footer" data-position="fixed" data-fullscreen="true">
    <h4>Footer over content</h4>
  </div>
</div>

Barres persistantes

Quand deux pages ont des footers (ou headers) avec le même data-id et data-position=fixed, la barre persiste entre les transitions au lieu de s'animer avec la page. C'est le pattern standard de la barre de navigation basse persistante — seul le lien actif change par page.

jquery-mobile
<!-- Both pages use the SAME data-id so the footer persists -->
<div data-role="page" id="home">
  <div data-role="footer" data-id="main-nav" data-position="fixed">
    <div data-role="navbar">
      <ul><li><a href="#home" class="ui-btn-active">Home</a></li>
      <li><a href="#settings">Settings</a></li></ul>
    </div>
  </div>
</div>

<div data-role="page" id="settings">
  <div data-role="footer" data-id="main-nav" data-position="fixed">
    <div data-role="navbar">
      <ul><li><a href="#home">Home</a></li>
      <li><a href="#settings" class="ui-btn-active">Settings</a></li></ul>
    </div>
  </div>
</div>

Comportement tap toggle

Les barres fixes basculent leur visibilité quand l'utilisateur tape la page. Mettez data-tap-toggle=false pour garder une barre toujours visible. Options par élément liées : data-hide-during-focus (masquer quand des inputs prennent le focus) et data-update-page-padding (réappliquer le padding de page au redimensionnement).

jquery-mobile
<!-- Disable tap-to-toggle on a fixed toolbar -->
<div data-role="header" data-position="fixed" data-tap-toggle="false">
  <h1>Always visible</h1>
</div>

<!-- Globally turn off tap toggle -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.toolbar.prototype.options.tapToggle = false;
});
</script>

Thème et boutons des barres

Les headers peuvent porter des boutons positionnés avec les classes ui-btn-left / ui-btn-right. data-theme règle l'échantillon de couleur de la barre. data-iconpos=notext montre seulement une icône pour un rendu compact. Les boutons dans un header sont stylés automatiquement en boutons inline.

jquery-mobile
<div data-role="header" data-theme="b">
  <a href="#" class="ui-btn-left" data-icon="home" data-iconpos="notext">Home</a>
  <h1>Title</h1>
  <a href="#" class="ui-btn-right" data-icon="gear" data-iconpos="notext">Settings</a>
</div>

Mettre à jour les barres dynamiquement

Après avoir changé le balisage d'une barre à l'exécution, appelez $(el).toolbar('refresh') pour réappliquer style et padding. Le widget toolbar (introduit en 1.4) gère le positionnement fixe et le tap-toggle ; initialisez-le manuellement avec $().toolbar() si vous ajoutez une barre après la création de la page.

jquery-mobile
<script>
// Update the header title and re-enhance after DOM change
$(function () {
  $("#my-header h1").text("New Title");
  $("#my-header").toolbar("refresh");
});
</script>

<div data-role="header" id="my-header" data-position="fixed">
  <h1>Old Title</h1>
</div>
05

Boutons

Bases des boutons

Tout <a> avec class=ui-btn (ou data-role=button), plus les <button> et <input type=button|submit|reset>, sont automatiquement enrichis en boutons stylés. La classe ui-btn est la façon moderne de marquer un lien comme bouton sans dépendre de data-role.

jquery-mobile
<!-- Anchor button -->
<a href="#" class="ui-btn">Link Button</a>

<!-- <button> and <input> auto-enhanced -->
<button class="ui-btn">Button Element</button>
<input type="button" value="Input Button">
<input type="submit" value="Submit">

<!-- Use data-role explicitly -->
<a href="#" data-role="button">Anchor via role</a>

Boutons inline

Par défaut, les boutons sont pleine largeur (block). Ajoutez ui-btn-inline (ou data-inline=true) pour qu'un bouton ne soit large que de son label, permettant plusieurs boutons côte à côte. Utile pour des rangées d'actions comme 'Annuler | OK'.

jquery-mobile
<!-- Inline: only as wide as the content -->
<a href="#" class="ui-btn ui-btn-inline">A</a>
<a href="#" class="ui-btn ui-btn-inline">B</a>
<a href="#" class="ui-btn ui-btn-inline">C</a>

<!-- Default (block) buttons fill the width -->
<a href="#" class="ui-btn">Full-width button</a>

Icônes de boutons

Employez ui-icon-{name} pour ajouter une icône et ui-btn-icon-{pos} pour la placer (left, right, top, bottom, notext). ui-btn-icon-notext masque le texte et ne montre que l'icône — fournissez quand même du texte pour l'accessibilité/lecteurs d'écran.

jquery-mobile
<a href="#" class="ui-btn ui-icon-home ui-btn-icon-left">Home</a>
<a href="#" class="ui-btn ui-icon-search ui-btn-icon-right">Search</a>
<a href="#" class="ui-btn ui-icon-gear ui-btn-icon-top">Settings</a>
<a href="#" class="ui-btn ui-icon-star ui-btn-icon-notext">Star (icon only)</a>
<a href="#" class="ui-btn ui-icon-delete ui-btn-icon-bottom">Delete</a>

Position d'icône et inline

L'attribut data-iconpos est l'équivalent historique des classes ui-btn-icon-*. 'notext' ne montre que l'icône (gardez toujours du texte visible pour les lecteurs d'écran via le texte de l'élément). On peut librement combiner classes inline et icône sur un même bouton.

jquery-mobile
<!-- data-* equivalents -->
<a href="#" data-role="button" data-icon="home" data-iconpos="left">Home</a>
<a href="#" data-role="button" data-icon="home" data-iconpos="notext">Home</a>

<!-- Combine inline + icon -->
<a href="#" class="ui-btn ui-btn-inline ui-icon-plus ui-btn-icon-left">Add</a>
<a href="#" class="ui-btn ui-btn-inline ui-icon-minus ui-btn-icon-left">Remove</a>

Boutons mini et désactivés

Ajoutez ui-mini (ou data-mini=true) pour un bouton plus petit et compact — utile dans des barres denses. Désactivez un bouton avec ui-state-disabled (ou l'attribut natif disabled sur <button>/<input>). Les boutons désactivés ignorent les taps.

jquery-mobile
<!-- Mini (smaller) button -->
<a href="#" class="ui-btn ui-mini">Mini</a>

<!-- Disabled button -->
<a href="#" class="ui-btn ui-state-disabled">Disabled</a>

<!-- Native disabled -->
<button disabled>Disabled button</button>
<input type="submit" value="Go" disabled>

Groupes de boutons (controlgroup)

Un controlgroup regroupe visuellement des boutons — les boutons adjacents partagent les coins arrondis sans espaces. data-type=horizontal les dispose en ligne (bien pour des contrôles segmentés) ; le défaut vertical les empile. Cela groupe aussi les checkboxes/radios en un ensemble unifié.

jquery-mobile
<div data-role="controlgroup" data-type="horizontal">
  <a href="#" class="ui-btn">Yes</a>
  <a href="#" class="ui-btn">No</a>
  <a href="#" class="ui-btn">Maybe</a>
</div>

<!-- Vertical group (default) -->
<div data-role="controlgroup">
  <a href="#" class="ui-btn">Option 1</a>
  <a href="#" class="ui-btn">Option 2</a>
</div>
06

Listes

Listview de base

Ajoutez data-role=listview à un <ul> pour en faire une liste tactile aux lignes tappables pleine largeur. Chaque <li> contenant un <a> devient une ligne liée avec flèche à droite. data-inset=true insère la liste avec coins arrondis et marges au lieu de bord à bord.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li><a href="#">Cherry</a></li>
</ul>

Listes inset

Les listes bord à bord occupent toute la largeur (bien pour des menus plein écran) ; les listes inset ont des coins arrondis et des marges (bien pour des sections de contenu dans une page). Employez data-inset=true pour les listes inset, qui ressemblent davantage à des panneaux de réglages groupés.

jquery-mobile
<!-- Edge-to-edge (default) -->
<ul data-role="listview">
  <li><a href="#">Item 1</a></li>
</ul>

<!-- Inset: rounded, with margins -->
<ul data-role="listview" data-inset="true">
  <li><a href="#">Item 1</a></li>
  <li><a href="#">Item 2</a></li>
</ul>

Séparateurs de listes

Un <li> avec data-role=list-divider devient un en-tête de section non cliquable. data-autodividers=true insère automatiquement des séparateurs selon la première lettre du texte de chaque item — parfait pour une liste de contacts alphabétique.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <li data-role="list-divider">Fruits</li>
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li data-role="list-divider">Vegetables</li>
  <li><a href="#">Carrot</a></li>
</ul>

<!-- Auto dividers from first letter -->
<ul data-role="listview" data-autodividers="true">
  <li><a href="#">Alice</a></li>
  <li><a href="#">Bob</a></li>
</ul>

Bulles de compteur et miniatures

Ajoutez un span avec class=ui-li-count dans un <li> pour montrer une bulle de compteur numérique à droite. Employez un <img> avec class=ui-li-thumb (typiquement 80x80) pour une miniature à gauche. Combinez avec <h3>/<p> pour des lignes de liste riches, façon app.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <!-- Count bubble -->
  <li><a href="#">Inbox <span class="ui-li-count">12</span></a></li>
  <!-- Thumbnail on the left -->
  <li>
    <a href="#">
      <img src="thumb.jpg" class="ui-li-thumb">
      <h3>Title</h3>
      <p>Description</p>
      <span class="ui-li-count">3</span>
    </a>
  </li>
</ul>

Filtre de recherche

data-filter=true ajoute un champ de recherche au-dessus de la liste qui filtre les items par texte en temps réel. data-filter-placeholder personnalise l'invite. data-filter-reveal=true masque tous les items jusqu'à la saisie de l'utilisateur — utile pour une recherche façon autocomplétion.

jquery-mobile
<ul data-role="listview" data-filter="true"
    data-filter-placeholder="Search fruits...">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li><a href="#">Cherry</a></li>
</ul>

<!-- Filter reveals hidden items (collapsible search) -->
<ul data-role="listview" data-filter="true" data-filter-reveal="true">
  <li><a href="#">Hidden until searched</a></li>
</ul>

Boutons séparés et listes imbriquées

Quand un <li> contient deux <a>, jQuery Mobile rend un bouton séparé : la ligne principale navigue vers le premier lien, et un bouton d'icône distinct (réglé via data-split-icon) à droite ouvre le second. Un <ul> imbriqué dans un <li> devient automatiquement une sous-page de drill-down.

jquery-mobile
<!-- Split button: row link + icon link on the right -->
<ul data-role="listview" data-split-icon="gear" data-inset="true">
  <li>
    <a href="#detail">Go to detail</a>
    <a href="#edit">Edit</a>
  </li>
</ul>

<!-- Nested list (child <ul> becomes a sub-page) -->
<ul data-role="listview">
  <li>Fruits
    <ul>
      <li><a href="#">Apple</a></li>
      <li><a href="#">Banana</a></li>
    </ul>
  </li>
</ul>
07

Contrôles de formulaire

Structure de formulaire et envoi AJAX

jQuery Mobile enrichit automatiquement les inputs de formulaire et envoie les formulaires par AJAX par défaut, montrant un spinner de chargement et transitionnant vers la page de résultat. Mettez data-ajax=false pour un envoi complet traditionnel (requis pour les uploads de fichiers sans API moderne).

jquery-mobile
<form action="/submit" method="post" data-ajax="true">
  <label for="name">Name:</label>
  <input type="text" name="name" id="name" placeholder="Your name">

  <button type="submit" class="ui-btn">Submit</button>
</form>

<!-- Disable AJAX for this form (normal full submit) -->
<form action="/upload" method="post" data-ajax="false">...</form>

Inputs texte et bouton d'effacement

Tous les types d'input HTML5 (text, email, tel, number, password, date, etc.) sont stylés de façon cohérente. data-clear-btn=true ajoute un bouton d'effacement (x) dans le champ. Employez data-role=none pour garder un contrôle en input natif simple, sans style jQuery Mobile.

jquery-mobile
<label for="email">Email</label>
<input type="email" id="email" data-clear-btn="true" placeholder="[email protected]">

<label for="phone">Phone</label>
<input type="tel" id="phone" data-clear-btn="true" data-clear-btn-text="Clear">

<!-- Non-enhanced native input -->
<input type="text" data-role="none">

Conteneurs de champs

Enveloppez une paire label + contrôle dans une div avec class=ui-field-contain. Sur écrans larges, le label et l'input se placent côte à côte ; sur téléphones étroits, ils s'empilent verticalement. Ce comportement responsif remplace l'ancien attribut data-role=fieldcontain.

jquery-mobile
<div class="ui-field-contain">
  <label for="user">Username</label>
  <input type="text" id="user">
</div>

<div class="ui-field-contain">
  <label for="pwd">Password</label>
  <input type="password" id="pwd">
</div>

Champ de recherche

Un <input type=search> est enrichi en champ de recherche avec icône de loupe. Associez-le à une listview en donnant un id à l'input et en réglant data-input=#id sur le filtre de la listview — cela permet de placer la zone de recherche n'importe où sur la page.

jquery-mobile
<label for="q">Search</label>
<input type="search" id="q" placeholder="Search...">

<!-- Search input feeding a listview filter -->
<input type="search" id="my-filter" data-type="search">
<ul data-role="listview" data-filter="true"
    data-input="#my-filter">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
</ul>

Textarea et inputs cachés

Les textareas sont stylés comme les autres inputs et grandissent automatiquement à la saisie par défaut ; mettez data-autogrow=false pour fixer la hauteur avec une barre de défilement. Les inputs cachés passent sans toucher. Comme tous les inputs, enveloppez-les dans ui-field-contain pour des labels responsifs.

jquery-mobile
<label for="bio">Bio</label>
<textarea id="bio" placeholder="Tell us about you"></textarea>

<!-- Auto-grow textarea -->
<textarea id="bio" data-autogrow="false"></textarea>

<!-- Hidden inputs are not styled -->
<input type="hidden" name="id" value="42">

Désactiver l'enrichissement automatique

Ajoutez data-role=none à tout contrôle pour sauter l'enrichissement jQuery Mobile et le garder natif. Pour une règle sur tout le projet, réglez keepNative pendant mobileinit sur une chaîne de sélecteur d'éléments à ne jamais enrichir — utile quand on mélange des contrôles stylés personnalisés aux pages jQM.

jquery-mobile
<!-- Keep a control native (no jQM styling) -->
<select data-role="none">...</select>
<input type="checkbox" data-role="none">

<!-- Globally disable enhancement for a tag -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.keepNative = "select, input[type=checkbox]";
});
</script>
08

Sliders

Slider de plage de base

Un <input type=range> avec min, max, value et step est enrichi en slider tactile avec bulle de valeur. L'attribut value fixe la position initiale. Le slider réécrit sa valeur dans l'input, il se soumet donc normalement avec le formulaire.

jquery-mobile
<label for="volume">Volume</label>
<input type="range" name="volume" id="volume"
       value="50" min="0" max="100" step="1">

Slider avec surlignage

data-highlight=true remplit la piste à gauche de la poignée avec la couleur du thème actif, donnant une vision claire du niveau courant. Sans lui, la piste est d'une seule couleur plate. Utile pour des réglages comme le volume ou la luminosité.

jquery-mobile
<label for="brightness">Brightness</label>
<input type="range" id="brightness"
       value="70" min="0" max="100"
       data-highlight="true">

Slider mini

data-mini=true rend un slider plus petit et compact qui prend moins de hauteur — pratique quand on groupe plusieurs contrôles dans un panneau de réglages. Il se comporte comme le slider normal, juste en taille réduite.

jquery-mobile
<label for="age">Age</label>
<input type="range" id="age" value="25" min="0" max="120"
       data-mini="true" data-highlight="true">

Pas et sliders multiples

step contrôle l'incrément (ex. step=5 s'aligne sur 0, 5, 10, ...). Chaque input range est un slider indépendant ; pour une plage à double poignée, il faut construire un widget personnalisé ou employer un plugin tiers. Les attributs natifs value, min, max pilotent le comportement.

jquery-mobile
<label for="temp">Temperature (step 5)</label>
<input type="range" id="temp" value="20" min="0" max="100" step="5">

<!-- Two independent sliders -->
<label for="low">Min</label>
<input type="range" id="low" value="10" min="0" max="100">
<label for="high">Max</label>
<input type="range" id="high" value="90" min="0" max="100">

Événements du slider

Le slider émet slidestart quand l'utilisateur commence à tirer la poignée et slidestop à la fin du glissement. Pour des mises à jour continues pendant le glissement, liez l'événement natif 'input' ou 'change' de l'input range sous-jacent. Lisez/écrivez la valeur avec $(el).val().

jquery-mobile
<label for="vol">Volume</label>
<input type="range" id="vol" value="50" min="0" max="100">

<script>
$("#vol").on("slidestart", function () {
  console.log("User started dragging");
});
$("#vol").on("slidestop", function () {
  console.log("Value is now " + $(this).val());
});
</script>
09

Interrupteurs flip

Flip toggle de base

Un interrupteur flip est un <select> avec exactement deux <option> et data-role=slider. Il se rend comme un interrupteur on/off à la iOS. L'option sélectionnée détermine l'état initial, et la valeur se soumet comme un select normal (la valeur de l'option choisie).

jquery-mobile
<label for="notify">Notifications</label>
<select name="notify" id="notify" data-role="slider">
  <option value="off">Off</option>
  <option value="on" selected>On</option>
</select>

Labels personnalisés

Le texte des deux options devient les labels de chaque côté de l'interrupteur. N'importe quel texte court convient (On/Off, Oui/Non, Activé/Désactivé). Gardez des labels courts pour tenir dans l'interrupteur sans troncature sur petits écrans.

jquery-mobile
<label for="wifi">Wi-Fi</label>
<select id="wifi" data-role="slider">
  <option value="disabled">Disabled</option>
  <option value="enabled" selected>Enabled</option>
</select>

Interrupteur mini

data-mini=true rend un interrupteur plus petit qui prend moins de hauteur, assorti aux sliders mini et autres contrôles mini. Associez les contrôles mini dans des panneaux de réglages denses pour un look compact cohérent.

jquery-mobile
<label for="sync">Auto-sync</label>
<select id="sync" data-role="slider" data-mini="true">
  <option value="no">No</option>
  <option value="yes" selected>Yes</option>
</select>

Thème du flip

data-theme règle la couleur de la poignée de l'interrupteur, et data-track-theme celle de la piste derrière. Mélanger les échantillons (ex. poignée sombre sur piste claire) rend l'état actif plus distinct visuellement.

jquery-mobile
<label for="darkmode">Dark mode</label>
<select id="darkmode" data-role="slider"
        data-theme="b" data-track-theme="a">
  <option value="off">Off</option>
  <option value="on" selected>On</option>
</select>

Bascule par programme

Réglez la valeur avec $(el).val(value) puis appelez .slider('refresh') pour mettre à jour l'interrupteur visuel en conséquence. Lisez l'état courant avec .val(). Rafraîchissez toujours après avoir changé la valeur du select sous-jacent par programme, sinon la poignée ne bouge pas.

jquery-mobile
<select id="power" data-role="slider">
  <option value="off">Off</option>
  <option value="on">On</option>
</select>

<script>
// Turn the switch on programmatically
$("#power").val("on").slider("refresh");
// Read current state
var state = $("#power").val(); // "on" or "off"
</script>
10

Checkboxes et radios

Checkboxes

Une checkbox est un <input type=checkbox> normal enveloppé par (ou adjacent à) un <label for=id>. jQuery Mobile style le label en bloc tappable. Quand le label enveloppe l'input, l'attribut for est optionnel. L'état coché se soumet normalement avec le formulaire.

jquery-mobile
<label for="agree"><input type="checkbox" id="agree" name="agree"> I agree</label>

<label for="news"><input type="checkbox" id="news" name="news" checked> Newsletter</label>

<!-- Wrap in ui-field-contain for layout -->
<div class="ui-field-contain">
  <label for="agree">I agree to terms</label>
  <input type="checkbox" id="agree">
</div>

Boutons radio

Regroupez les radios en leur donnant le même attribut name. Enveloppez le groupe dans un fieldset avec data-role=controlgroup (et un <legend>) pour les regrouper visuellement avec des coins partagés. Un seul radio d'un groupe de même nom peut être coché à la fois.

jquery-mobile
<fieldset data-role="controlgroup">
  <legend>Choose a color:</legend>
  <label for="r"><input type="radio" name="color" id="r" value="red" checked> Red</label>
  <label for="g"><input type="radio" name="color" id="g" value="green"> Green</label>
  <label for="b"><input type="radio" name="color" id="b" value="blue"> Blue</label>
</fieldset>

Controlgroups horizontaux

data-type=horizontal dispose les checkboxes ou radios sur une seule ligne comme un contrôle segmenté au lieu d'un empilement vertical. Compact et bien adapté aux labels courts (S/M/L, Oui/Non). Gardez des labels courts pour tenir sur les écrans étroits.

jquery-mobile
<fieldset data-role="controlgroup" data-type="horizontal">
  <legend>Size:</legend>
  <label for="s"><input type="radio" name="size" id="s" value="s" checked> S</label>
  <label for="m"><input type="radio" name="size" id="m" value="m"> M</label>
  <label for="l"><input type="radio" name="size" id="l" value="l"> L</label>
</fieldset>

Mini et thème

data-mini=true rapetisse les contrôles, et data-theme règle l'échantillon appliqué quand un item est coché/actif. Thémez l'état actif pour qu'il ressorte du fond de page. Ces options s'appliquent à tout le controlgroup d'un coup.

jquery-mobile
<fieldset data-role="controlgroup" data-mini="true" data-theme="b">
  <label for="a"><input type="checkbox" id="a"> Option A</label>
  <label for="b"><input type="checkbox" id="b"> Option B</label>
</fieldset>

Rafraîchir après changement

Après avoir réglé la propriété checked d'une checkbox/radio dans le code, appelez .checkboxradio('refresh') pour que le visuel enrichi suive. Si vous ajoutez ou retirez des inputs dans un controlgroup à l'exécution, appelez .controlgroup('refresh') pour réappliquer le style groupé.

jquery-mobile
<input type="checkbox" id="c1">

<script>
// Check programmatically and update the visual state
$("#c1").prop("checked", true).checkboxradio("refresh");

// For a controlgroup, refresh the group after adding/removing items
$("#grp").controlgroup("refresh");
</script>
11

Menus select

Select natif

Par défaut, jQuery Mobile montre un select stylé personnalisé, mais le sélecteur natif de l'OS s'ouvre quand même. Mettez data-native-menu=true (ou data-role=none) pour employer entièrement le menu déroulant natif de l'appareil — plus rapide et familier, mais moins cohérent visuellement entre plateformes.

jquery-mobile
<label for="country">Country</label>
<select id="country" data-native-menu="true">
  <option value="us">United States</option>
  <option value="ca">Canada</option>
  <option value="uk">United Kingdom</option>
</select>

<!-- data-role="none" also keeps it fully native -->
<select data-role="none">...</select>

Menu select personnalisé

data-native-menu=false ouvre un menu popup stylé jQuery Mobile au lieu du sélecteur natif, donnant un rendu cohérent sur tous les appareils. Sur téléphone il apparaît comme un dialogue plein écran avec un bouton 'Terminé' ; sur tablette comme un popup plus petit près du champ.

jquery-mobile
<label for="fruit">Fruit</label>
<select id="fruit" data-native-menu="false">
  <option value="apple">Apple</option>
  <option value="banana">Banana</option>
  <option value="cherry">Cherry</option>
</select>

Placeholder et multiple

Une première option à valeur vide sert de placeholder. data-overlay-theme règle la couleur du fond du menu personnalisé. Ajouter l'attribut multiple transforme le menu personnalisé en dialogue de liste à cocher où l'utilisateur peut choisir plusieurs options, affichées séparées par des virgules sur le bouton.

jquery-mobile
<label for="color">Color</label>
<select id="color" data-native-menu="false" data-overlay-theme="b">
  <option value="">Choose a color...</option>
  <option value="red">Red</option>
  <option value="green">Green</option>
</select>

<!-- Multiple selection (renders as a checklist dialog) -->
<label for="tags">Tags</label>
<select id="tags" multiple data-native-menu="false">
  <option value="a">A</option>
  <option value="b">B</option>
</select>

Thème du select et overlay

data-theme style le bouton du select lui-même ; data-overlay-theme règle la couleur du popup/fond ; data-divider-theme colore les séparateurs list-divider dans le menu. On peut insérer des <li data-role=list-divider> entre les options pour les grouper visuellement.

jquery-mobile
<label for="size">Size</label>
<select id="size" data-native-menu="false"
        data-theme="a" data-overlay-theme="b" data-divider-theme="a">
  <option value="s">Small</option>
  <option value="m">Medium</option>
  <li data-role="list-divider">Large sizes</li>
  <option value="l">Large</option>
</select>

Événements du select

Écoutez l'événement standard 'change' pour réagir à une sélection. Après avoir changé la valeur (ou remplacé les options) dans le code, appelez .selectmenu('refresh') pour que le label du bouton suive la nouvelle sélection. Reconstruisez le menu avec 'refresh', pas en réinitialisant.

jquery-mobile
<label for="city">City</label>
<select id="city" data-native-menu="false">
  <option value="ny">New York</option>
  <option value="la">Los Angeles</option>
</select>

<script>
$("#city").on("change", function () {
  console.log("Selected: " + $(this).val());
});
// Update options then refresh
$("#city").val("la").selectmenu("refresh");
</script>
12

Popups

Popup de base

Un popup est une div avec data-role=popup. Ouvrez-le en liant vers son id avec data-rel=popup. Le popup superpose la page centré par défaut. Ajoutez ui-content pour le padding, et employez data-rel=back sur un lien intérieur pour le fermer.

jquery-mobile
<a href="#myPopup" data-rel="popup" class="ui-btn">Open popup</a>

<div data-role="popup" id="myPopup" class="ui-content">
  <p>This is a popup.</p>
  <a href="#" class="ui-btn" data-rel="back">Close</a>
</div>

Transitions de popup

Employez data-transition sur le lien d'ouverture (ou sur le popup lui-même) pour choisir l'animation. pop et fade sont les plus naturelles pour les popups. Le même jeu de transitions que pour les pages s'applique ici ; la fermeture inverse la transition automatiquement.

jquery-mobile
<a href="#p" data-rel="popup" data-transition="pop">Pop</a>
<a href="#p" data-rel="popup" data-transition="fade">Fade</a>
<a href="#p" data-rel="popup" data-transition="slidedown">Slide down</a>

<div data-role="popup" id="p" class="ui-content" data-theme="a">
  <p>Transitioned in.</p>
</div>

Positionnement du popup

data-position-to contrôle où apparaît le popup : 'origin' (l'élément qui l'a ouvert, défaut), '#someId' (un élément précis), ou 'window' (centré à l'écran). On peut aussi passer des coordonnées x/y à l'ouverture par programme avec popup('open', x, y).

jquery-mobile
<!-- Position relative to an element / coordinates -->
<a href="#tip" data-rel="popup" data-position-to="origin">Tip (on the link)</a>
<a href="#tip" data-rel="popup" data-position-to="#target">Tip (on #target)</a>
<a href="#tip" data-rel="popup" data-position-to="window">Centered</a>

<div data-role="popup" id="tip" class="ui-content">
  <p>Positioned popup.</p>
</div>

Menu popup et tooltip

Un popup peut contenir n'importe quel contenu — une listview devient un menu contextuel, un paragraphe un tooltip. Thémez le popup avec data-theme et le contenu intérieur avec son propre thème. Les popups se ferment automatiquement quand l'utilisateur tape dehors (sauf data-dismissible=false).

jquery-mobile
<a href="#menu" data-rel="popup" class="ui-btn">Menu</a>
<div data-role="popup" id="menu" data-theme="b">
  <ul data-role="listview" data-inset="true" data-theme="d">
    <li data-role="divider">Actions</li>
    <li><a href="#">Edit</a></li>
    <li><a href="#">Share</a></li>
    <li><a href="#">Delete</a></li>
  </ul>
</div>

Popup dialogue

Un popup positionné au centre de la fenêtre avec un bouton de fermeture agit comme un dialogue modal. Ajoutez un bouton X (ui-icon-delete avec ui-btn-icon-notext) dans le coin. Contraintez la largeur avec un style max-width pour un vrai look de dialogue au lieu d'une feuille pleine largeur.

jquery-mobile
<a href="#dlg" data-rel="popup" data-position-to="window"
   data-transition="pop" class="ui-btn">Open dialog</a>

<div data-role="popup" id="dlg" data-theme="a" class="ui-content"
     style="max-width:400px;">
  <a href="#" data-rel="back" class="ui-btn ui-corner-all ui-icon-delete
     ui-btn-icon-notext ui-btn-right">Close</a>
  <h3>Confirm</h3>
  <p>Are you sure?</p>
  <a href="#" class="ui-btn ui-btn-b" data-rel="back">Yes</a>
  <a href="#" class="ui-btn" data-rel="back">No</a>
</div>

Ouverture par programme et dismissible

Ouvrez ou fermez un popup depuis le code avec .popup('open'/'close'). data-dismissible=false empêche la fermeture en tapant dehors, forçant l'usage d'un bouton Fermer — idéal pour des confirmations obligatoires. On peut passer des coordonnées x/y ou un objet position à l'ouverture.

jquery-mobile
<div data-role="popup" id="p2" data-dismissible="false">
  <p>Cannot close by tapping outside.</p>
  <a href="#" class="ui-btn" data-rel="back">Close</a>
</div>

<script>
// Open programmatically (optionally at coordinates)
$("#p2").popup("open");
$("#p2").popup("open", { x: 100, y: 200 });
// Close programmatically
$("#p2").popup("close");
</script>
13

Panels

Panel de base

Un panel est une div avec data-role=panel, placée dans une page (généralement avant le header). Ouvrez-le en liant vers son id avec un bouton. Employez data-rel=close sur un lien intérieur pour fermer le panel. Les panels sont parfaits pour les menus de navigation coulissants.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="panel" id="myPanel">
    <h2>Menu</h2>
    <p>Panel content here.</p>
    <a href="#" class="ui-btn" data-rel="close">Close</a>
  </div>

  <div data-role="header">
    <a href="#myPanel" class="ui-btn ui-btn-inline ui-corner-all ui-icon-bars ui-btn-icon-notext">Menu</a>
    <h1>Home</h1>
  </div>
  <div data-role="main" class="ui-content">
    <p>Page content.</p>
  </div>
</div>

Modes d'affichage du panel

data-display contrôle l'animation d'ouverture : 'reveal' (défaut) écarte la page pour découvrir le panel dessous ; 'overlay' fait glisser le panel au-dessus de la page ; 'push' déplace à la fois le panel et la page. Overlay est le plus courant pour les menus.

jquery-mobile
<div data-role="panel" id="p1" data-display="reveal">Reveal</div>
<div data-role="panel" id="p2" data-display="overlay">Overlay</div>
<div data-role="panel" id="p3" data-display="push">Push</div>

<!-- data-display controls how the panel interacts with the page:
     reveal : panel sits under the page, page slides away
     overlay: panel slides over the page (page stays)
     push   : both panel and page slide -->

Position du panel

data-position=left (défaut) ou right règle le côté d'où glisse le panel. On peut avoir un panel gauche et un droit dans la même page. Un seul panel peut être ouvert à la fois ; en ouvrir un second ferme le premier.

jquery-mobile
<!-- Left panel (default) -->
<div data-role="panel" id="leftP" data-position="left">Left</div>

<!-- Right panel -->
<div data-role="panel" id="rightP" data-position="right">Right</div>

<a href="#leftP" class="ui-btn">Open left</a>
<a href="#rightP" class="ui-btn">Open right</a>

Dismissible et swipe

data-dismissible=true (défaut) ferme le panel quand l'utilisateur tape dehors. data-swipe-close=true permet de fermer en glissant dans le sens opposé (ex. glisser à droite ferme un panel gauche). Les deux sont actifs par défaut pour les panels overlay.

jquery-mobile
<div data-role="panel" id="p"
     data-dismissible="true"
     data-swipe-close="true"
     data-position="left"
     data-display="overlay">
  <p>Tap outside or swipe to close.</p>
</div>

Événements du panel

Les panels émettent les événements panelbeforeopen, panelopen, panelbeforeclose et panelclose. Renvoyer false depuis un handler 'before' annule l'action — utile pour confirmer avant de fermer. Ouvrez/fermez depuis le code avec .panel('open'/'close').

jquery-mobile
<div data-role="panel" id="p">...</div>

<script>
$("#p").on("panelopen", function () {
  console.log("Panel opened");
});
$("#p").on("panelbeforeclose", function () {
  // return false here to prevent closing
  console.log("About to close");
});
$("#p").on("panelclose", function () {
  console.log("Panel closed");
});

// Open / close programmatically
$("#p").panel("open");
$("#p").panel("close");
</script>
14

Collapsibles

Collapsible de base

Une div avec data-role=collapsible enveloppe un titre (h1-h6) comme en-tête cliquable et le reste comme contenu dépliable. Elle démarre repliée par défaut. Cliquer l'en-tête bascule le contenu avec une icône +/-.

jquery-mobile
<div data-role="collapsible">
  <h3>Section title</h3>
  <p>Hidden content shown when expanded.</p>
  <p>Click the header to toggle.</p>
</div>

Icônes et thème du collapsible

Personnalisez l'indicateur avec data-collapsed-icon et data-expanded-icon (défaut plus/minus). data-theme style l'en-tête ; data-content-theme style la zone de contenu dépliée. data-collapsed=false fait démarrer la section dépliée au lieu de repliée.

jquery-mobile
<div data-role="collapsible"
     data-collapsed-icon="carat-r"
     data-expanded-icon="carat-d"
     data-theme="b" data-content-theme="a"
     data-collapsed="false">
  <h3>Initially open</h3>
  <p>Custom icons and theme.</p>
</div>

Ensemble de collapsibles (accordéon)

Un collapsibleset groupe des collapsibles pour qu'un seul soit ouvert à la fois — un accordéon. En ouvrir un referme automatiquement les autres. (En 1.4 l'attribut est data-role=collapsibleset ; l'ancien nom collapsible-set fonctionne encore.) Tout l'ensemble partage un thème unifié.

jquery-mobile
<div data-role="collapsibleset" data-theme="a" data-content-theme="a">
  <div data-role="collapsible">
    <h3>Section 1</h3>
    <p>Only one section open at a time.</p>
  </div>
  <div data-role="collapsible" data-collapsed="false">
    <h3>Section 2 (open by default)</h3>
    <p>Opening this closes Section 1.</p>
  </div>
  <div data-role="collapsible">
    <h3>Section 3</h3>
    <p>Third section.</p>
  </div>
</div>

Pré-déplié et inset

Dans un collapsibleset, mettez data-collapsed=false sur la section à ouvrir initialement. data-inset=true (défaut pour les ensembles) donne au groupe des coins arrondis et des marges. Les ensembles bord à bord emploient data-inset=false pour occuper toute la largeur.

jquery-mobile
<!-- A set always starts with one open by default; control with data-collapsed -->
<div data-role="collapsibleset" data-inset="true">
  <div data-role="collapsible" data-collapsed="false">
    <h3>Open first</h3>
    <p>Content</p>
  </div>
  <div data-role="collapsible">
    <h3>Closed second</h3>
    <p>Content</p>
  </div>
</div>

Collapsible avec listview

Un collapsible peut contenir n'importe quel widget, dont une listview. Excellent pattern pour regrouper une longue liste sous un en-tête dépliable. Ajoutez data-filter=true au collapsible pour filtrer les items de la listview intérieure via une zone de recherche dans la zone d'en-tête.

jquery-mobile
<div data-role="collapsible" data-filter="true">
  <h3>Contacts</h3>
  <ul data-role="listview">
    <li><a href="#">Alice</a></li>
    <li><a href="#">Bob</a></li>
    <li><a href="#">Carol</a></li>
  </ul>
</div>

Déplier/replier par programme

Contrôlez un collapsible depuis le code avec .collapsible('expand') et .collapsible('collapse'). Écoutez les événements 'collapse' et 'expand' pour réagir au basculement utilisateur. Dans un ensemble, déplier une section par programme referme automatiquement les autres.

jquery-mobile
<div data-role="collapsible" id="c">
  <h3>Section</h3>
  <p>Content</p>
</div>

<script>
// Expand or collapse from code
$("#c").collapsible("expand");
$("#c").collapsible("collapse");
// Toggle based on current state
$("#c h3").click(); // simplest manual toggle
</script>
15

Onglets

Onglets de base

Un widget tabs est une div avec data-role=tabs contenant une navbar (les liens d'onglets) et des panneaux de contenu dont les ids correspondent aux href des liens. Le lien avec ui-btn-active s'affiche en premier. Cliquer un onglet montre son panneau et masque les autres — sans transition de page.

jquery-mobile
<div data-role="tabs" id="myTabs">
  <div data-role="navbar">
    <ul>
      <li><a href="#tab1" class="ui-btn-active">One</a></li>
      <li><a href="#tab2">Two</a></li>
      <li><a href="#tab3">Three</a></li>
    </ul>
  </div>
  <div id="tab1" class="ui-body-d ui-content">Content 1</div>
  <div id="tab2" class="ui-body-d ui-content">Content 2</div>
  <div id="tab3" class="ui-body-d ui-content">Content 3</div>
</div>

Onglets avec icônes

Ajoutez les classes ui-icon-{name} et ui-btn-icon-top aux liens d'onglets pour montrer des icônes au-dessus des labels, donnant une barre d'onglets façon app. L'onglet actif garde ui-btn-active. Employez ui-btn-icon-top pour que l'icône soit au-dessus du texte dans la barre d'onglets.

jquery-mobile
<div data-role="tabs">
  <div data-role="navbar">
    <ul>
      <li><a href="#t1" class="ui-btn-active ui-icon-home ui-btn-icon-top">Home</a></li>
      <li><a href="#t2" class="ui-icon-search ui-btn-icon-top">Search</a></li>
      <li><a href="#t3" class="ui-icon-gear ui-btn-icon-top">Settings</a></li>
    </ul>
  </div>
  <div id="t1" class="ui-content">Home tab</div>
  <div id="t2" class="ui-content">Search tab</div>
  <div id="t3" class="ui-content">Settings tab</div>
</div>

Onglets AJAX

Quand le href d'un lien d'onglet est une URL (pas un #id), le widget tabs charge cette page par AJAX dans le conteneur à l'activation. Le premier onglet se charge automatiquement à l'initialisation de la page. Utile pour charger paresseusement un contenu lourd par onglet.

jquery-mobile
<div data-role="tabs">
  <div data-role="navbar">
    <ul>
      <li><a href="ajax-tab1.html" class="ui-btn-active">One</a></li>
      <li><a href="ajax-tab2.html">Two</a></li>
    </ul>
  </div>
  <!-- The first tab's content is loaded into this container -->
  <div class="ui-content" id="ajax-content"></div>
</div>

Persistance des onglets

Les onglets ne mémorisent pas leur état actif entre les rechargements par défaut. Employez l'événement tabsactivate (qui donne ui.newPanel/ui.oldPanel) plus localStorage pour persister la sélection. Re-déclenchez le clic de l'onglet sauvegardé au chargement pour le restaurer.

jquery-mobile
<div data-role="tabs" id="t">
  <div data-role="navbar">
    <ul>
      <li><a href="#a" class="ui-btn-active">A</a></li>
      <li><a href="#b">B</a></li>
    </ul>
  </div>
  <div id="a" class="ui-content">A</div>
  <div id="b" class="ui-content">B</div>
</div>

<script>
// Remember the active tab across reloads
var saved = localStorage.getItem("activeTab") || "#a";
$("#t a[href='" + saved + "']").click();
$("#t").on("tabsactivate", function (e, ui) {
  localStorage.setItem("activeTab", "#" + ui.newPanel.attr("id"));
});
</script>

Événements des onglets

tabsbeforeactivate se déclenche avant un changement d'onglet (renvoyez false pour annuler) ; tabsactivate après. Les deux donnent ui.newTab/ui.oldTab (les liens <a>) et ui.newPanel/ui.oldPanel (les div de contenu). Servez-vous en pour charger paresseusement du contenu, journaliser de l'analytique ou valider avant de changer.

jquery-mobile
<div data-role="tabs" id="t">...</div>

<script>
$("#t").on("tabsbeforeactivate", function (e, ui) {
  // ui.newTab, ui.oldTab, ui.newPanel, ui.oldPanel
  // return false to cancel the switch
  console.log("Switching to", ui.newPanel.attr("id"));
});
$("#t").on("tabsactivate", function (e, ui) {
  console.log("Now showing", ui.newPanel.attr("id"));
});
</script>
16

Thèmes

Échantillons de thème (a-e)

Le theming de jQuery Mobile emploie des « swatches » lettrés (a-e) plutôt qu'une seule couleur. a est le plus contrasté (sombre) et le défaut des headers/footers ; b est un accent bleu ; c est le fond de page clair par défaut. Appliquez un swatch avec data-theme sur tout élément.

jquery-mobile
<!-- jQuery Mobile ships with 5 swatches: a, b, c, d, e -->
<!-- a = black (high contrast), b = blue, c = light gray,
     d = medium gray, e = yellow -->

<div data-role="page" data-theme="b">
  <div data-role="header" data-theme="a"><h1>Dark header</h1></div>
  <div data-role="main" class="ui-content">Page body</div>
  <div data-role="footer" data-theme="a"><h4>Dark footer</h4></div>
</div>

Appliquer les thèmes

Pour les boutons, employez la classe ui-btn-{swatch} (ex. ui-btn-b pour un bouton bleu). Pour les autres éléments, data-theme={swatch}. Un enfant hérite du swatch de son parent sauf si vous en réglez un explicitement. Le swatch de page par défaut est 'c' (gris clair).

jquery-mobile
<!-- Per element -->
<a href="#" class="ui-btn ui-btn-a">Swatch A button</a>
<a href="#" class="ui-btn ui-btn-b">Swatch B button</a>

<!-- On bars, lists, forms -->
<div data-role="header" data-theme="b">...</div>
<ul data-role="listview" data-theme="c">...</ul>
<input type="text" data-theme="b">

Thème d'overlay

data-overlay-theme règle la couleur du fond assombri derrière un popup, dialogue ou menu select personnalisé. Employez un swatch sombre (a ou b) pour l'overlay pour que le contenu de premier plan ressorte. Le data-theme du popup contrôle la couleur de la boîte du popup.

jquery-mobile
<!-- Overlay theme for popups, dialogs, custom selects -->
<div data-role="popup" id="p" data-overlay-theme="b" data-theme="a"
     class="ui-content">
  <p>Dark backdrop, light popup.</p>
</div>

<a href="#p" data-rel="popup" data-transition="pop" class="ui-btn">Open</a>

Thèmes des listes et boutons

Les listviews acceptent des thèmes séparés : data-theme pour les lignes, data-divider-theme pour les en-têtes de séparateurs, et data-count-theme pour les bulles de compteur. Cela permet de mettre les séparateurs en valeur tout en gardant des lignes discrètes. Le même theming fin s'applique aux boutons et formulaires.

jquery-mobile
<ul data-role="listview" data-theme="d" data-divider-theme="b"
    data-count-theme="b" data-inset="true">
  <li data-role="list-divider">Group (swatch b)</li>
  <li><a href="#">Item (swatch d) <span class="ui-li-count">5</span></a></li>
</ul>

Échantillons personnalisés

Chaque swatch n'est qu'un ensemble de classes CSS (.ui-bar-{x}, .ui-body-{x}, .ui-btn-up-{x}, etc.). Pour ajouter un swatch personnalisé 'f', copiez ces règles et recolorez-les — ou employez l'outil ThemeRoller pour générer un fichier de thème personnalisé complet. Puis référencez-le avec data-theme=f.

jquery-mobile
/* Add a custom swatch 'f' by copying the .ui-bar-f, .ui-body-f,
   .ui-btn-up-f, .ui-btn-hover-f, .ui-btn-down-f rules and changing
   the colors. ThemeRoller generates these for you. */
.ui-bar-f { background: #6c2; color: #fff; }
.ui-body-f { background: #efe; color: #030; }
.ui-btn-up-f { background: #6c2; color: #fff; }
.ui-btn-hover-f { background: #5b1; color: #fff; }

<!-- Use it like any built-in swatch -->
<div data-role="header" data-theme="f"><h1>Green header</h1></div>

Héritage de thème

Les éléments héritent du swatch de l'ancêtre le plus proche quand ils ne définissent pas le leur. Réglez un swatch haut (ex. sur la page) pour thèmer tout l'intérieur de façon cohérente, puis surchargez les éléments individuels au besoin. Changez le thème de page global par défaut pendant mobileinit.

jquery-mobile
<div data-role="page" data-theme="b">
  <!-- Inherits swatch b unless overridden -->
  <div data-role="main" class="ui-content">
    <a href="#" class="ui-btn">Inherits b</a>
    <a href="#" class="ui-btn ui-btn-a">Explicit a</a>
    <a href="#" class="ui-btn" data-theme="a">Explicit a (attr)</a>
  </div>
</div>

<!-- Global default swatch -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.theme = "b";
});
</script>
17

Mise en page responsif

Disposition en grille

Les grilles sont des classes CSS, pas des widgets. ui-grid-a fait une grille de 2 colonnes, ui-grid-b 3 colonnes, jusqu'à ui-grid-d (5 colonnes). Les enfants reçoivent ui-block-a, ui-block-b, ... dans l'ordre et passent à la ligne automatiquement. Les grilles font toujours 100% de large et ne réagissent pas seules aux breakpoints.

jquery-mobile
<!-- 2-column grid (ui-grid-a) -->
<div class="ui-grid-a">
  <div class="ui-block-a"><div class="ui-bar">A</div></div>
  <div class="ui-block-b"><div class="ui-bar">B</div></div>
</div>

<!-- 3-column grid (ui-grid-b), 4 = ui-grid-c, 5 = ui-grid-d -->
<div class="ui-grid-b">
  <div class="ui-block-a">A</div>
  <div class="ui-block-b">B</div>
  <div class="ui-block-c">C</div>
</div>

Grilles responsives

Les grilles de jQuery Mobile n'ont pas de breakpoints intégrés, mais on peut ajouter une media query personnalisée : aux largeurs étroites, réglez les blocs sur width:100% et float:none pour les empiler verticalement, et sur écrans plus larges laissez les colonnes par défaut s'appliquer. Ajoutez une classe marqueur pour borner la règle.

jquery-mobile
<style>
/* Stack grid columns on phones, side-by-side on tablets */
@media (max-width: 40em) {
  .ui-responsive .ui-block-a,
  .ui-responsive .ui-block-b { width: 100%; float: none; }
}
</style>

<div class="ui-grid-a ui-responsive">
  <div class="ui-block-a">Left (stacks on phone)</div>
  <div class="ui-block-b">Right (stacks on phone)</div>
</div>

Table reflow

Un table reflow (data-mode=reflow) se réorganise en disposition de cartes empilées sur écrans étroits, en répétant l'en-tête de chaque colonne comme label à côté de sa valeur. Ajoutez la classe ui-responsive pour que le reflow ne s'active que sous le breakpoint, gardant un tableau normal sur écrans larges.

jquery-mobile
<table data-role="table" data-mode="reflow" class="ui-responsive">
  <thead><tr><th>Name</th><th>Age</th><th>City</th></tr></thead>
  <tbody>
    <tr><td>Alice</td><td>30</td><td>NYC</td></tr>
    <tr><td>Bob</td><td>25</td><td>LA</td></tr>
  </tbody>
</table>

<!-- On narrow screens each cell shows its column header as a label -->

Table column toggle

Un table columntoggle ajoute un bouton « Colonnes... » qui laisse les utilisateurs choisir les colonnes affichées. Assignez data-priority=1..6 aux colonnes optionnelles (plus bas = plus important, montré aux breakpoints larges) ; les colonnes sans priorité s'affichent toujours. Les colonnes les plus importantes restent sur téléphone ; le reste se range dans le menu.

jquery-mobile
<table data-role="table" data-mode="columntoggle"
       class="ui-responsive" id="tbl">
  <thead>
    <tr>
      <th data-priority="1">Rank</th>
      <th data-priority="2">Name</th>
      <th>Team</th>           <!-- priority 'persist' (always shown) -->
      <th data-priority="3">Points</th>
      <th data-priority="4">Wins</th>
    </tr>
  </thead>
  <tbody><tr><td>1</td><td>Alice</td><td>Red</td><td>100</td><td>10</td></tr></tbody>
</table>

Breakpoints et classes helper

jQuery Mobile n'a pas de classes de breakpoints utilitaires ; écrivez vos propres media queries pour les dispositions personnalisées. Le breakpoint intégré 40em (640px) ne gouverne que le passage des tables responsives (ui-responsive) entre modes empilé et tabulaire. Pour grilles et panels, définissez vos propres breakpoints avec des requêtes en em.

jquery-mobile
<!-- jQuery Mobile doesn't ship breakpoint classes like Bootstrap,
     but you can combine media queries with jQM structure. -->

<style>
@media (min-width: 45em) { /* tablet+ */
  .split { width: 50%; float: left; box-sizing: border-box; padding: 0 .5em; }
}
</style>

<div class="split">Left panel</div>
<div class="split">Right panel</div>

<!-- ui-responsive class triggers table breakpoints at 40em (640px) -->
18

Événements tactiles

Tap et taphold

tap se déclenche sur un toucher rapide (plus rapide et fiable que click sur mobile, qui attend ~300 ms). taphold se déclenche quand l'utilisateur maintient le doigt ~750 ms. Les deux sont normalisés pour la souris et le tactile, donc le même code tourne sur desktop et mobile.

jquery-mobile
<div id="box" class="ui-bar">Tap or hold me</div>

<script>
$("#box").on("tap", function () {
  $(this).css("background", "yellow");
});
$("#box").on("taphold", function () {
  $(this).css("background", "red");
});
</script>

Swipe et direction

swipe se déclenche sur tout glissement horizontal ; swipeleft et swiperight indiquent la direction — pratique pour des carrousels d'images ou la navigation de page. Ils se basent sur le mouvement horizontal ; le défilement vertical n'est volontairement pas traité comme un swipe pour que le défilement normal fonctionne.

jquery-mobile
<div id="card" class="ui-bar">Swipe me</div>

<script>
$("#card").on("swipe", function () {
  console.log("Swiped in any direction");
});
$("#card").on("swipeleft", function () {
  $(this).text("Swiped left -> next");
});
$("#card").on("swiperight", function () {
  $(this).text("Swiped right -> prev");
});
</script>

Seuils de swipe

Un swipe ne s'enregistre que s'il couvre au moins horizontalDistanceThreshold (défaut 30px) dans durationThreshold (défaut 1000ms), tout en restant sous verticalDistanceThreshold verticalement. Augmentez le seuil horizontal pour exiger des glissements plus longs ; baissez-le pour plus de sensibilité. Réglez ces valeurs pendant mobileinit.

jquery-mobile
<script>
// Globally tune swipe sensitivity (bind before jQM loads)
$(document).on("mobileinit", function () {
  $.event.special.swipe.horizontalDistanceThreshold = 60; // px, default 30
  $.event.special.swipe.durationThreshold = 800;          // ms, default 1000
  $.event.special.swipe.verticalDistanceThreshold = 40;   // px, default 75
});
</script>

<script src="jquery.mobile-1.4.5.min.js"></script>

Événements souris virtuels

Les événements vmouse* sont les événements unifiés souris/tactile/pointeur de jQuery Mobile — ils se déclenchent de façon cohérente avec le doigt ou la souris. Employez vclick au lieu de click pour éviter le délai mobile de 300 ms. Ce sont les briques sur lesquelles tap et swipe sont construits.

jquery-mobile
<script>
// vmouse events unify mouse + touch + pointer
$("#el").on("vmousedown", function () { /* finger down / mouse down */ });
$("#el").on("vmouseup",   function () { /* finger up / mouse up   */ });
$("#el").on("vmousemove", function () { /* drag                    */ });
$("#el").on("vmouseover", function () { /* hover-in (best-effort)  */ });
$("#el").on("vmouseout",  function () { /* hover-out (best-effort) */ });
$("#el").on("vclick",     function () { /* tap/click unified       */ });
</script>

Changement d'orientation

orientationchange se déclenche quand l'appareil tourne, avec e.orientation valant 'portrait' ou 'landscape'. Enveloppez le code dépendant de la disposition dans un court setTimeout car les dimensions de la fenêtre d'affichage se mettent à jour légèrement après l'événement. Écoutez 'resize' comme repli sur les appareils sans gyroscope.

jquery-mobile
<script>
$(window).on("orientationchange", function (e) {
  // e.orientation is "portrait" or "landscape"
  console.log("Now " + e.orientation);
});

// React after the rotation finishes (layout is settled)
$(window).on("orientationchange", function (e) {
  setTimeout(function () {
    $("body").removeClass("portrait landscape").addClass(e.orientation);
  }, 300);
});
</script>

Scroll et étranglement

scrollstart et scrollstop sont les événements de scroll étranglés de jQuery Mobile (le navigateur étrangle nativement les handlers de scroll, mais ceux-ci donnent des moments début/fin clairs). Pour empêcher le défilement/zoom sur un élément — ex. un canvas de dessin ou une carte — liez touchmove et renvoyez false.

jquery-mobile
<script>
// scrollstart / scrollstop are throttled for performance
$(document).on("scrollstart", function () {
  $("#hint").hide();
});
$(document).on("scrollstop", function () {
  $("#hint").show();
});

// Silence touch scroll on a specific element
$("#canvas").on("touchmove", false);
</script>
19

Événements de page et cycle de vie

Événements d'initialisation de page

pagebeforecreate se déclenche avant que jQuery Mobile enrichisse le balisage de la page — le meilleur endroit pour injecter classes ou widgets pour qu'ils soient enrichis aussi. pagecreate se déclenche juste après la fin de l'enrichissement — employez-le pour lier les handlers et initialiser les plugins. Chacun se déclenche une fois par page.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="main" class="ui-content">
    <a href="#second" class="ui-btn">Go to second</a>
  </div>
</div>

<script>
$(document).on("pagebeforecreate", "#home", function () {
  // Before enhancement — good place to add classes/widgets
});
$(document).on("pagecreate", "#home", function () {
  // After enhancement, before show — bind widgets here
  console.log("Home page created");
});
</script>

Show et hide de page

pagebeforeshow/pageshow se déclenchent avant/après qu'une page devienne visible ; pagebeforehide/pagehide avant/après qu'elle soit masquée. Les événements 'show' se déclenchent à chaque affichage de la page (pas une seule fois) — le bon endroit pour rafraîchir des données dynamiques au retour sur une page.

jquery-mobile
<script>
$(document).on("pagebeforeshow", "#home", function () {
  console.log("About to show home");
});
$(document).on("pageshow", "#home", function () {
  console.log("Home shown (transition done)");
});
$(document).on("pagebeforehide", "#home", function () {
  console.log("About to leave home");
});
$(document).on("pagehide", "#home", function () {
  console.log("Home hidden");
});
</script>

Page before change

pagebeforechange se déclenche avant toute navigation et permet de l'intercepter ou la rediriger (appelez preventDefault pour annuler). pagechange se déclenche après une navigation réussie ; pagechangefailed si le chargement de la page cible a échoué. Ils se déclenchent pour les navigations internes (#id) comme AJAX.

jquery-mobile
<script>
$(document).on("pagebeforechange", function (e, data) {
  // data.toPage is the target (URL string or jQuery object)
  // data.options has transition, reverse, etc.
  // return false (or e.preventDefault()) to cancel navigation
  if (typeof data.toPage === "string" && data.toPage.indexOf("block") > -1) {
    e.preventDefault();
    alert("Blocked");
  }
});
$(document).on("pagechange", function (e, data) {
  console.log("Navigation completed");
});
$(document).on("pagechangefailed", function (e, data) {
  console.log("Navigation failed");
});
</script>

Chargement du conteneur de pages

pageload se déclenche quand une page récupérée par AJAX est insérée avec succès dans le DOM (data.url et data.page sont fournis). pageloadfailed se déclenche en cas d'erreur de chargement — par défaut jQM montre un message d'erreur ; renvoyer false depuis un handler indique à jQM que vous l'avez géré vous-même.

jquery-mobile
<script>
// Fires when a page is loaded via AJAX into the DOM
$(document).on("pageload", function (e, data) {
  console.log("Loaded: " + data.url);
  console.log("Page obj:", data.page);
});
$(document).on("pageloadfailed", function (e, data) {
  // return false to let jQM show its default error message
  console.log("Failed to load: " + data.url);
});
</script>

Lier les événements de page

Liez les événements de page par délégation d'événements sur document, en filtrant par le sélecteur #id de la page — cela fonctionne même pour les pages tirées plus tard par AJAX. Pour une navigation par programme, employez la méthode 'change' du widget pagecontainer (le remplaçant moderne de $.mobile.changePage), en passant la cible et les options.

jquery-mobile
<script>
// Delegate by page id — works for AJAX-loaded pages too
$(document).on("pagecreate", "#settings", function () {
  var page = $(this);
  page.find("#save").on("tap", function () {
    alert("Saved settings");
  });
});

// Use the pagecontainer widget (1.4+) for programmatic navigation
$(":mobile-pagecontainer").pagecontainer("change", "#settings", {
  transition: "slide",
  reverse: false
});
</script>

Suppression et nettoyage de page

Par défaut, jQuery Mobile retire une page du DOM après qu'on l'a quittée (sauf si domCache est actif). pageremove se déclenche juste avant la suppression — nettoyez ici les intervalles, écouteurs ou instances de plugins. L'événement pagehide donne via ui.prevPage l'objet jQuery de la page venant d'être masquée, pour le démontage.

jquery-mobile
<script>
// Fires when a page is removed from the DOM (default behavior for
// non-cached pages after navigation away)
$(document).on("pageremove", function (e, ui) {
  console.log("Page removed from DOM:", ui.prevPage);
});

// Clean up resources when a page is hidden for good
$(document).on("pagehide", "#temp", function () {
  clearInterval($(this).data("timer"));
});
</script>

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.