Skip to content

jQuery Mobile Folha de referência

Framework de UI HTML5 otimizado para toque, para apps web móveis.

01

Primeiros passos

Estrutura de página

O jQuery Mobile usa atributos data-role para aprimorar o HTML. Uma página é uma div com data-role=page contendo seções header, main e footer. A meta tag viewport é essencial para a escala correta em dispositivos móveis. Carregue o núcleo do jQuery antes do 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>

Múltiplas páginas num documento

Você pode colocar múltiplas divs data-role=page num único arquivo HTML. Ligue-as com hrefs de âncora (#about). O jQuery Mobile mostra uma página por vez e anima as transições. Só a primeira página na ordem do código é exibida no carregamento inicial.

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>

Navegação AJAX e links

Por padrão, links para páginas internas (#id) e da mesma origem são buscados via AJAX e trocados com uma transição. Use data-ajax=false para forçar um carregamento normal de página inteira (útil para páginas que não são jQuery Mobile). data-prefetch pré-carrega o alvo para que a transição seja instantânea.

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>

Prefetch e cache de DOM

O prefetch carrega páginas linkadas em segundo plano para que a navegação pareça instantânea. Por padrão, páginas visitadas são removidas do DOM, mas domCache as mantém para navegação de volta mais rápida, ao custo de memória. Habilite por página com data-dom-cache ou globalmente via a opção do protótipo de página.

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>

Páginas de diálogo

Adicione data-rel=dialog a um link (ou data-dialog=true na página) para abrir uma página estilizada como dialog modal, com botão de fechar e transição. Use data-rel=back num link para fechá-la e voltar à página anterior.

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>

Configuração global (mobileinit)

O evento mobileinit dispara após o núcleo do jQuery carregar, mas antes de o jQuery Mobile inicializar — vincule sua configuração aqui, antes de incluir jquery.mobile.js. Sobrescritas comuns: transições padrão, configurações AJAX e texto da mensagem de carregamento. Definir autoInitializePage=false permite controlar quando a primeira página inicializa.

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

Transições de página

Transições básicas

Adicione data-transition a um link para escolher a animação ao navegar. As transições são baseadas em CSS (aceleradas por hardware quando possível). 'none' pula a animação para navegação instantânea. O mesmo atributo funciona para dialogs e 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>

Tipos de transição

O jQuery Mobile traz um conjunto de transições CSS 2D/3D. Transições 3D (turn, flow, flip) ficam ótimas em dispositivos capazes, mas caem graciosamente em hardware antigo. pop e fade são as mais performáticas e recomendadas para dialogs e 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 -->

Direção e reverse

data-direction=reverse reproduz a transição ao contrário — tipicamente usada em botões Voltar para que a animação espelhe a navegação de ida. Combina com data-transition; se nenhuma transição estiver definida, a padrão é invertida.

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>

Transições de dialog

Dialogs podem usar qualquer transição, mas pop e slidedown parecem mais naturais para modals. Defina um padrão global com $.mobile.defaultDialogTransition durante o mobileinit. A ação de fechar do dialog reverte a transição automaticamente.

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>

Desabilitando e fallback

Defina data-transition=none ou o padrão global como 'none' para desabilitar animações — útil em dispositivos de baixo custo ou para acessibilidade. O jQuery Mobile detecta automaticamente o suporte a transforms 3D e degrada transições 3D (flip, turn, flow) para um fade simples quando sem suporte.

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

Toolbars (header e footer)

Header e footer fixos

Adicione data-position=fixed para manter um header ou footer preso ao topo/base da viewport enquanto a página rola. Tocar na página alterna a visibilidade das toolbars por padrão. O conteúdo da página recebe padding para não ficar escondido atrás das toolbars.

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>

Toolbars fullscreen

data-fullscreen=true sobrepõe as toolbars fixas sobre o conteúdo (semitransparentes), em vez de reservar espaço. Ótimo para visualizadores de fotos ou mapas, em que o conteúdo deve preencher a tela. As toolbars aparecem/desaparecem ao toque, como as fixas.

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>

Toolbars persistentes

Quando duas páginas têm footers (ou headers) com o mesmo data-id e data-position=fixed, a toolbar persiste entre as transições de página em vez de animar com a página. É o padrão padrão para uma barra de navegação inferior persistente — só o link ativo muda por página.

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>

Comportamento tap toggle

Toolbars fixas alternam a visibilidade quando o usuário toca na página. Defina data-tap-toggle=false para manter uma toolbar sempre visível. Opções por elemento relacionadas: data-hide-during-focus (oculta quando inputs recebem foco) e data-update-page-padding (reaplica o padding da página ao redimensionar).

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>

Tema e botões da toolbar

Headers podem conter botões posicionados com as classes ui-btn-left / ui-btn-right. data-theme define a amostra de cor da barra. data-iconpos=notext mostra só um ícone para um visual compacto. Botões dentro de um header são estilizados automaticamente como botões 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>

Atualizando toolbars dinamicamente

Depois de mudar a marcação de uma toolbar em runtime, chame $(el).toolbar('refresh') para reaplicar estilização e padding. O widget toolbar (introduzido na 1.4) gerencia o posicionamento fixo e o tap-toggle; inicialize-o manualmente com $().toolbar() se adicionar uma toolbar depois da criação da página.

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

Botões

Básico de botões

Qualquer <a> com class=ui-btn (ou data-role=button), além de <button> e <input type=button|submit|reset>, é aprimorado automaticamente em botões estilizados. A classe ui-btn é a forma moderna de marcar um link como botão sem depender 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>

Botões inline

Por padrão, os botões são de largura total (block). Adicione ui-btn-inline (ou data-inline=true) para que um botão fique apenas tão largo quanto seu rótulo, permitindo vários botões lado a lado. Útil para linhas de ação como 'Cancelar | 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>

Ícones de botão

Use ui-icon-{name} para adicionar um ícone e ui-btn-icon-{pos} para posicioná-lo (left, right, top, bottom, notext). ui-btn-icon-notext oculta o texto e mostra só o ícone — forneça o texto de qualquer forma por acessibilidade/leitores de tela.

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>

Posição do ícone e inline

O atributo data-iconpos é o equivalente legado das classes ui-btn-icon-*. 'notext' mostra só o ícone (mantenha sempre o texto visível para leitores de tela via o texto do elemento). Você pode combinar livremente classes inline e de ícone num mesmo botão.

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>

Botões mini e desabilitados

Adicione ui-mini (ou data-mini=true) para um botão menor e mais compacto — útil em toolbars densas. Desabilite um botão com ui-state-disabled (ou o atributo nativo disabled em <button>/<input>). Botões desabilitados ignoram toques.

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>

Grupos de botões (controlgroup)

Um controlgroup agrupa botões visualmente — botões adjacentes compartilham cantos arredondados e não têm espaços. data-type=horizontal dispõe-os numa linha (bom para controles segmentados); o padrão vertical os empilha. Também agrupa checkboxes/radios num conjunto unificado.

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

List views

Listview básica

Adicione data-role=listview a uma <ul> para transformá-la numa lista amigável ao toque, com linhas tocáveis de largura total. Cada <li> contendo um <a> vira uma linha linkada com uma seta à direita. data-inset=true recua a lista com cantos arredondados e margens, em vez de borda a borda.

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>

Listas inset

Listas de borda a borda atravessam a largura total (boas para menus de tela cheia); listas inset têm cantos arredondados e margens ao redor (boas para seções de conteúdo dentro de uma página). Use data-inset=true para listas inset, que parecem mais com painéis de configurações agrupados.

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>

Divisórias de lista

Um <li> com data-role=list-divider vira um cabeçalho de seção não clicável. data-autodividers=true insere divisórias automaticamente com base na primeira letra do texto de cada item — perfeito para uma lista de contatos em ordem alfabética.

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>

Bolhas de contagem e thumbnails

Adicione um span com class=ui-li-count dentro de um <li> para mostrar uma bolha de contagem numérica à direita. Use um <img> com class=ui-li-thumb (tipicamente 80x80) para uma miniatura à esquerda. Combine com <h3>/<p> para linhas de lista ricas, parecidas com 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>

Filtro de busca

data-filter=true adiciona um input de busca acima da lista que filtra itens por texto em tempo real. data-filter-placeholder personaliza o aviso. data-filter-reveal=true oculta os itens até o usuário digitar — útil para uma consulta estilo autocomplete.

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>

Botões divididos e listas aninhadas

Quando um <li> contém dois elementos <a>, o jQuery Mobile renderiza um botão dividido: a linha principal navega ao primeiro link, e um botão de ícone separado (definido via data-split-icon) à direita abre o segundo. Uma <ul> aninhada dentro de um <li> vira uma subpágina de drill-down automaticamente.

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

Controles de formulário

Estrutura de formulário e envio AJAX

O jQuery Mobile aprimora inputs de formulário automaticamente e envia formulários via AJAX por padrão, mostrando um spinner de carregamento e transicionando para a página de resultado. Defina data-ajax=false para um envio tradicional de página inteira (necessário para uploads de arquivo que não usam uma API moderna).

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 de texto e botão de limpar

Os tipos de input HTML5 (text, email, tel, number, password, date etc.) são estilizados de forma consistente. data-clear-btn=true adiciona um botão de limpar (x) dentro do campo. Use data-role=none para manter um controle como input nativo simples, sem estilização do 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">

Containers de campo

Envolva um par label + controle numa div com class=ui-field-contain. Em telas largas, o label e o input ficam lado a lado; em celulares estreitos, empilham verticalmente. Esse comportamento responsivo substitui o atributo antigo 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>

Input de busca

Um <input type=search> é aprimorado num campo de busca com ícone de lupa. Pareie-o com uma listview dando um id ao input e definindo data-input=#id no filtro da listview — isso permite colocar a caixa de busca em qualquer lugar da página.

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 e inputs ocultos

Textareas são estilizadas para casar com os outros inputs e crescem automaticamente enquanto você digita, por padrão; defina data-autogrow=false para fixar a altura com uma barra de rolagem. Inputs ocultos passam intocados. Como os inputs, envolva-os em ui-field-contain para labels responsivos.

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">

Desabilitando o aprimoramento automático

Adicione data-role=none a qualquer controle para pular o aprimoramento do jQuery Mobile e mantê-lo nativo. Para uma regra em o projeto, defina keepNative durante o mobileinit como uma string de seletor de elementos que nunca devem ser aprimorados — útil ao misturar controles com estilização personalizada e páginas 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 faixa básico

Um <input type=range> com min, max, value e step é aprimorado num slider amigável ao toque, com uma bolha de valor. O atributo value define a posição inicial. O slider escreve seu valor de volta no input, então é enviado normalmente com o formulário.

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

Slider com destaque

data-highlight=true preenche a trilha à esquerda da alça com a cor do tema ativo, dando uma visão clara do nível atual. Sem ele, a trilha é uma cor plana única. Útil para configurações como volume ou brilho.

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 renderiza um slider menor e mais compacto, que ocupa menos espaço vertical — prático ao agrupar vários controles num painel de configurações. Comporta-se identicamente ao slider regular, só em tamanho reduzido.

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

Step e múltiplos sliders

step controla o incremento (por exemplo, step=5 encaixa em 0, 5, 10, ...). Cada input range é um slider independente; para uma faixa de alça dupla, você precisa construir um widget personalizado ou usar um plugin de terceiros. Os atributos nativos value, min, max dirigem o comportamento.

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">

Eventos do slider

O slider emite slidestart quando o usuário começa a arrastar a alça e slidestop quando o arrasto termina. Para atualizações contínuas durante o arrasto, vincule ao evento nativo 'input' ou 'change' no input range subjacente. Leia/escreva o valor com $(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

Interruptores flip

Flip toggle básico

Um flip switch é um <select> com exatamente dois elementos <option> e data-role=slider. Renderiza como um interruptor liga/desliga estilo iOS. A opção selecionada determina o estado inicial, e o valor é enviado como um select normal (o valor da opção escolhida).

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>

Rótulos personalizados

O texto das duas opções vira os rótulos em cada lado do interruptor. Você pode usar qualquer texto curto (Ligado/Desligado, Sim/Não, Ativado/Desativado). Mantenha os rótulos curtos para caberem no toggle sem truncar em telas pequenas.

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>

Flip switch mini

data-mini=true renderiza um flip switch menor, que ocupa menos espaço vertical, combinando com sliders mini e outros controles mini. Pareie controles mini juntos em painéis de configurações densos para um visual compacto consistente.

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>

Tema do flip

data-theme define a cor da alça do interruptor, e data-track-theme define a cor da trilha atrás dela. Misturar amostras (por exemplo, alça escura em trilha clara) torna o estado ativo visualmente mais distinto.

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>

Alternância programática

Defina o valor com $(el).val(value) e depois chame .slider('refresh') para atualizar o toggle visual de acordo. Leia o estado atual com .val(). Sempre faça refresh depois de mudar o valor do select subjacente programaticamente, ou a alça não se move.

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 e radios

Checkboxes

Um checkbox é um <input type=checkbox> normal envolvido por (ou adjacente a) um <label for=id>. O jQuery Mobile estiliza o label como um bloco tocável. Quando o label envolve o input, o atributo for é opcional. O estado marcado é enviado como de costume com o formulário.

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>

Botões de rádio

Agrupe radios dando a eles o mesmo atributo name. Envolva o grupo num fieldset com data-role=controlgroup (e um <legend>) para agrupá-los visualmente com cantos compartilhados. Só um radio num grupo de mesmo nome pode estar marcado por vez.

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 horizontais

data-type=horizontal dispõe os checkboxes ou radios numa única linha como um controle segmentado, em vez de uma pilha vertical. Isso é compacto e funciona bem para rótulos curtos (P/M/G, Sim/Não). Mantenha os rótulos curtos para caberem em telas estreitas.

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 e tema

data-mini=true encolhe os controles, e data-theme define a amostra aplicada quando um item está marcado/ativo. Tematize o estado ativo para se destacar do fundo da página. Essas opções aplicam ao controlgroup inteiro de uma vez.

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>

Refresh após mudança

Depois de definir a propriedade checked de um checkbox/radio em código, chame .checkboxradio('refresh') para que o visual aprimorado corresponda. Se você adicionar ou remover inputs dentro de um controlgroup em runtime, chame .controlgroup('refresh') para reaplicar a estilização agrupada.

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 nativo

Por padrão, o jQuery Mobile mostra um select com estilização personalizada, mas o seletor nativo do sistema ainda abre. Defina data-native-menu=true (ou data-role=none) para usar totalmente o dropdown nativo do dispositivo — mais rápido e familiar, mas menos consistente visualmente entre plataformas.

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 personalizado

data-native-menu=false abre um menu popup estilizado pelo jQuery Mobile em vez do seletor nativo, dando uma aparência consistente nos dispositivos. Num celular aparece como um dialog de tela cheia com um botão 'Concluído'; num tablet como um popup menor perto do campo.

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 e multiple

Uma primeira opção de valor vazio age como placeholder. data-overlay-theme define a cor do backdrop do menu personalizado. Adicionar o atributo multiple transforma o menu personalizado num dialog de checklist em que o usuário pode escolher várias opções, exibidas separadas por vírgula no botão.

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>

Tema e overlay do select

data-theme estiliza o botão do select em si; data-overlay-theme define a cor do popup/backdrop; data-divider-theme colore separadores list-divider dentro do menu. Você pode inserir elementos <li data-role=list-divider> entre as opções para agrupá-las visualmente.

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>

Eventos do select

Escute o evento padrão 'change' para reagir a uma seleção. Depois de mudar o valor (ou substituir as opções) em código, chame .selectmenu('refresh') para que o rótulo do botão se atualize conforme a nova seleção. Reconstrua o menu com 'refresh', não re-init.

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 básico

Um popup é uma div com data-role=popup. Abra-o linkando ao seu id com data-rel=popup. O popup sobrepõe a página centrado por padrão. Adicione ui-content para padding, e use data-rel=back num link interno para fechá-lo.

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>

Transições de popup

Use data-transition no link de abertura (ou no próprio popup) para escolher a animação. pop e fade são as mais naturais para popups. O mesmo conjunto de transições usado para páginas se aplica aqui; a ação de fechar reverte a transição automaticamente.

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>

Posicionamento do popup

data-position-to controla onde o popup aparece: 'origin' (o elemento que o abriu, padrão), '#algumId' (um elemento específico) ou 'window' (centrado na tela). Você também pode passar coordenadas x/y ao abrir programaticamente com 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 e tooltip

Um popup pode conter qualquer conteúdo — uma listview vira um menu de contexto, um parágrafo vira um tooltip. Estilize o popup com data-theme e o conteúdo interno com seu próprio tema. Popups fecham automaticamente quando o usuário toca fora (a menos que 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 de dialog

Um popup posicionado no centro da janela, com um botão de fechar, age como um dialog modal. Adicione um botão X (ui-icon-delete com ui-btn-icon-notext) no canto. Restrinja a largura com um estilo max-width para um verdadeiro visual de dialog, em vez de uma folha de largura total.

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>

Abertura programática e dismissible

Abra ou feche um popup por código com .popup('open'/'close'). data-dismissible=false impede fechar tocando fora, forçando o usuário a usar um botão Fechar — ideal para confirmações obrigatórias. Você pode passar coordenadas x/y ou um objeto de posição ao abrir.

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 básico

Um panel é uma div com data-role=panel, colocada dentro de uma página (geralmente antes do header). Abra-o linkando ao seu id com um botão. Use data-rel=close num link interno para fechar o panel. Panels são perfeitos para menus de navegação deslizantes.

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>

Modos de exibição do panel

data-display controla a animação de abertura: 'reveal' (padrão) desliza a página para revelar o panel por baixo; 'overlay' desliza o panel sobre a página; 'push' move o panel para dentro e a página para o lado. Overlay é o mais comum para 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 -->

Posição do panel

data-position=left (padrão) ou right define de que lado o panel desliza. Você pode ter um panel à esquerda e outro à direita na mesma página. Só um panel pode estar aberto por vez; abrir um segundo fecha o primeiro.

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 e swipe

data-dismissible=true (padrão) fecha o panel quando o usuário toca fora dele. data-swipe-close=true permite ao usuário deslizar na direção oposta para fechá-lo (por exemplo, deslizar à direita fecha um panel à esquerda). Ambos vêm ligados por padrão em 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>

Eventos do panel

Panels disparam os eventos panelbeforeopen, panelopen, panelbeforeclose e panelclose. Retornar false de um handler 'before' cancela a ação — útil para confirmar antes de fechar. Abra/feche por código com .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 básico

Uma div com data-role=collapsible envolve um título (h1-h6) como cabeçalho clicável e o resto como conteúdo expansível. Começa colapsado por padrão. Clicar no cabeçalho alterna o conteúdo aberto/fechado com um ícone +/-.

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>

Ícones e tema do collapsible

Personalize o indicador com data-collapsed-icon e data-expanded-icon (padrão mais/menos). data-theme estiliza o cabeçalho; data-content-theme estiliza a área de conteúdo expandida. data-collapsed=false faz a seção começar expandida em vez de colapsada.

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>

Conjunto de collapsibles (accordion)

Um collapsibleset agrupa collapsibles para que só um fique aberto por vez — um accordion. Abrir um fecha automaticamente os outros. (Na 1.4 o atributo é data-role=collapsibleset; o nome antigo collapsible-set ainda funciona.) O conjunto inteiro compartilha um tema unificado.

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é-expandido e inset

Num collapsibleset, defina data-collapsed=false na seção que você quer aberta inicialmente. data-inset=true (padrão para conjuntos) dá ao grupo cantos arredondados e margens. Conjuntos de borda a borda usam data-inset=false para atravessar a largura total.

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 com listview

Um collapsible pode conter qualquer widget, incluindo uma listview. É um ótimo padrão para agrupar uma lista longa sob um cabeçalho collapsible. Adicione data-filter=true ao collapsible para filtrar os itens da listview interna via uma caixa de busca dentro da área do cabeçalho.

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>

Expandir/colapsar programaticamente

Controle um collapsible por código com .collapsible('expand') e .collapsible('collapse'). Escute os eventos 'collapse' e 'expand' para reagir à alternância do usuário. Num conjunto, expandir uma seção programaticamente colapsa as outras automaticamente.

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

Tabs

Tabs básicas

Um widget de tabs é uma div com data-role=tabs contendo uma navbar (os links de aba) e painéis de conteúdo cujos ids correspondem aos hrefs dos links. O link com ui-btn-active é mostrado primeiro. Clicar numa aba mostra seu painel e oculta os demais — sem transição de página.

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>

Tabs com ícones

Adicione as classes ui-icon-{name} e ui-btn-icon-top aos links de aba para mostrar ícones acima dos rótulos, dando uma barra de abas parecida com app. A aba ativa mantém ui-btn-active. Use ui-btn-icon-top para que o ícone fique acima do texto na faixa de abas.

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>

Tabs AJAX

Quando o href de um link de aba é uma URL (não #id), o widget de tabs carrega aquela página via AJAX no container ao ativar. A primeira aba é carregada automaticamente quando a página inicializa. Útil para carregar conteúdo pesado de forma lazy por aba.

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>

Persistência das tabs

Tabs não lembram seu estado ativo entre recarregamentos por padrão. Use o evento tabsactivate (que dá ui.newPanel/ui.oldPanel) mais localStorage para persistir a seleção. Re-dispare o clique da aba salva ao carregar para restaurá-la.

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>

Eventos de tab

tabsbeforeactivate dispara antes de uma troca de aba (retorne false para cancelar); tabsactivate dispara depois. Ambos dão ui.newTab/ui.oldTab (os links <a>) e ui.newPanel/ui.oldPanel (as divs de conteúdo). Use-os para carregar conteúdo lazy, registrar analytics ou validar antes de trocar.

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

Temas

Amostras de tema (a-e)

A tematização do jQuery Mobile usa 'swatches' com letras (a-e) em vez de uma cor só. a é a de maior contraste (escura) e é o padrão para headers/footers; b é um destaque azul; c é o fundo claro padrão da página. Aplique uma swatch com data-theme em qualquer elemento.

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>

Aplicando temas

Para botões use a classe ui-btn-{swatch} (por exemplo, ui-btn-b para um botão azul). Para outros elementos use data-theme={swatch}. Um filho herda a swatch do pai, a menos que você defina uma explicitamente. A swatch padrão da página é 'c' (cinza claro).

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">

Tema de overlay

data-overlay-theme define a cor do backdrop escurecido atrás de um popup, dialog ou menu select personalizado. Use uma swatch escura (a ou b) para o overlay, para que o conteúdo em primeiro plano se destaque. O data-theme do próprio popup controla a cor da caixa do 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>

Temas de lista e botão

Listviews aceitam temas separados: data-theme para linhas, data-divider-theme para os cabeçalhos divisores e data-count-theme para as bolhas de contagem. Isso permite destacar as divisórias mantendo as linhas sutis. A mesma tematização fina se aplica a botões e formulários.

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>

Swatches personalizadas

Cada swatch é apenas um conjunto de classes CSS (.ui-bar-{x}, .ui-body-{x}, .ui-btn-up-{x} etc.). Para adicionar uma swatch personalizada 'f', copie essas regras e recolore-as — ou use a ferramenta ThemeRoller para gerar um arquivo de tema personalizado completo. Depois referencie com 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>

Herança de tema

Elementos herdam a swatch do ancestral mais próximo quando não definem a própria. Defina uma swatch bem acima (por exemplo, na página) para tematizar tudo dentro de forma consistente, e depois sobrescreva elementos individuais conforme necessário. Mude o tema padrão global da página durante o 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

Layout responsivo

Layout de grid

Grids são classes CSS, não widgets. ui-grid-a faz um grid de 2 colunas, ui-grid-b é de 3, até ui-grid-d (5 colunas). Os filhos recebem ui-block-a, ui-block-b, ... em ordem e quebram linha automaticamente. Grids são sempre 100% de largura e não respondem a breakpoints por si só.

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>

Grids responsivos

Grids do jQuery Mobile não têm breakpoints embutidos, mas você pode adicionar uma media query personalizada: em larguras estreitas, defina os blocos como width:100% e float:none para empilhar verticalmente, e em telas mais largas deixe as colunas padrão valerem. Adicione uma classe marcadora para delimitar a regra.

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>

Tabela reflow

Uma tabela reflow (data-mode=reflow) se reorganiza num layout de cards empilhados em telas estreitas, repetindo o cabeçalho de cada coluna como rótulo ao lado do seu valor. Adicione a classe ui-responsive para que o reflow só atue abaixo do breakpoint, mantendo uma tabela normal em telas largas.

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 -->

Tabela column toggle

Uma tabela columntoggle adiciona um botão 'Colunas...' que permite aos usuários escolher quais colunas mostrar. Atribua data-priority=1..6 às colunas opcionais (menor = mais importante, mostrada em breakpoints mais largos); colunas sem prioridade sempre aparecem. As colunas mais importantes permanecem nos celulares; o resto fica guardado no 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 e classes auxiliares

O jQuery Mobile não tem classes utilitárias de breakpoint; você escreve suas próprias media queries para layouts personalizados. O breakpoint embutido de 40em (640px) só governa quando as tabelas responsivas (ui-responsive) alternam entre os modos empilhado e tabular. Para grids e panels, defina seus próprios breakpoints com queries em 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

Eventos de toque

Tap e taphold

tap dispara num toque rápido (mais rápido e confiável que click no mobile, que espera ~300ms). taphold dispara quando o usuário mantém o dedo por ~750ms. Ambos são normalizados para funcionar com mouse e toque, então o mesmo código roda em desktop e 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 e direção

swipe dispara em qualquer deslize horizontal; swipeleft e swiperight indicam a direção — prático para carousels de imagens ou navegação de páginas. Baseiam-se em movimento horizontal; a rolagem vertical intencionalmente não é tratada como swipe, para que a rolagem normal da página continue funcionando.

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>

Limiares de swipe

Um swipe só registra se cobrir pelo menos horizontalDistanceThreshold (padrão 30px) dentro de durationThreshold (padrão 1000ms), e permanecer sob verticalDistanceThreshold na vertical. Aumente o limiar horizontal para exigir deslizes mais longos; reduza-o para uma sensação mais sensível. Defina-os durante o 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>

Eventos de mouse virtual

Eventos vmouse* são os eventos unificados de mouse/toque/ponteiro do jQuery Mobile — disparam consistentemente, seja com dedo ou mouse. Use vclick em vez de click para evitar o delay de 300ms do mobile. São os blocos construtores sobre os quais tap e swipe se apoiam.

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>

Mudança de orientação

orientationchange dispara quando o dispositivo gira, com e.orientation igual a 'portrait' ou 'landscape'. Envolva código dependente de layout num setTimeout curto, porque as dimensões da viewport se atualizam um pouco depois de o evento disparar. Escute o evento 'resize' como fallback em dispositivos sem giroscópio.

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 e throttling

scrollstart e scrollstop são os eventos de scroll com throttle do jQuery Mobile (o navegador limita os handlers de scroll nativamente, mas estes dão momentos claros de início/fim). Para impedir rolagem/zoom num elemento — por exemplo, um canvas de desenho ou um mapa — vincule touchmove e retorne 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

Eventos e ciclo de vida de página

Eventos de inicialização de página

pagebeforecreate dispara antes de o jQuery Mobile aprimorar a marcação da página — o melhor lugar para injetar classes ou widgets, para que também sejam aprimorados. pagecreate dispara logo após o aprimoramento completar — use-o para vincular handlers de evento e inicializar plugins. Cada um dispara uma vez por página.

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>

Page show e hide

pagebeforeshow/pageshow disparam antes/depois de uma página ficar visível; pagebeforehide/pagehide disparam antes/depois de ela ser ocultada. Os eventos 'show' disparam toda vez que a página é exibida (não só uma vez), então são o lugar certo para atualizar dados dinâmicos ao voltar a uma página.

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 dispara antes de qualquer navegação e é o lugar para interceptá-la ou redirecioná-la (chame preventDefault para cancelar). pagechange dispara após uma navegação bem-sucedida; pagechangefailed dispara se o carregamento da página alvo deu erro. Disparam tanto para navegações internas (#id) quanto 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>

Carregamento do page container

pageload dispara quando uma página buscada via AJAX é inserida com sucesso no DOM (data.url e data.page são fornecidos). pageloadfailed dispara em erro de carregamento — por padrão o jQM mostra uma mensagem de erro; retornar false de um handler diz ao jQM que você tratou por conta própria.

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>

Vinculando a eventos de página

Vincule eventos de página com delegação de eventos no document, filtrando pelo seletor #id da página — funciona até para páginas puxadas depois via AJAX. Para navegação programática, use a função 'change' do widget pagecontainer (o substituto moderno de $.mobile.changePage), passando o alvo e as opções.

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>

Remoção e limpeza de página

Por padrão, o jQuery Mobile remove uma página do DOM depois que você navega para longe dela (a menos que domCache esteja ligado). pageremove dispara logo antes da remoção — limpe intervals, listeners ou instâncias de plugin aqui. O ui.prevPage do evento pagehide dá o objeto jQuery da página recém-ocultada para teardown.

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.