Skip to content

jQuery Mobile チートシート

モバイル Web アプリ向けのタッチ最適化された HTML5 UI フレームワーク。

01

はじめに

ページ構造

jQuery Mobile は data-role 属性で HTML を拡張します。ページは、header、main、footer のセクションを含む data-role=page の div です。モバイルデバイスで正しく拡大縮小するには viewport のメタタグが不可欠です。jquery.mobile.js の前に jQuery コアを読み込みましょう。

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>

1 文書内の複数ページ

1 つの HTML ファイルに複数の data-role=page の div を置けます。アンカーの href(#about)で互いにリンクしましょう。jQuery Mobile は 1 度に 1 ページを表示し、遷移をアニメーションします。初期ロードで表示されるのは、ソース順の最初のページだけです。

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>

AJAX ナビゲーションとリンク

デフォルトでは、内部(#id)と同一オリジンのページへのリンクは AJAX で取得され、遷移と共に差し替えられます。通常のフルページロードを強制するには data-ajax=false を使いましょう(jQuery Mobile 以外のページに有用)。data-prefetch でターゲットを先取りすれば、遷移が即時になります。

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>

先取りと DOM キャッシュ

先取りはリンク先ページをバックグラウンドでロードし、ナビゲーションが即時に感じられます。デフォルトでは訪問済みページは DOM から取り除かれますが、domCache はメモリを代償に、速い「戻る」ナビゲーションのためにページを保持します。ページごとには data-dom-cache で、グローバルにはページのプロトタイプオプションで有効化しましょう。

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>

ダイアログページ

リンクに data-rel=dialog を(またはページに data-dialog=true を)加えると、閉じるボタンと遷移を備えたモーダルダイアログ風のページが開きます。前のページへ戻って閉じるには、リンクに data-rel=back を使いましょう。

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>

グローバル設定(mobileinit)

mobileinit イベントは、jQuery コアの読み込み後、jQuery Mobile の初期化前に発火します — jquery.mobile.js を読み込む「前に」ここで設定を bind しましょう。よくある上書き:デフォルトの遷移、AJAX の設定、ローディングメッセージのテキスト。autoInitializePage=false で、最初のページの初期化タイミングを制御できます。

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

ページの遷移

基本の遷移

リンクに data-transition を加えると、ナビゲーション時のアニメーションを選べます。遷移は CSS ベースです(可能な限りハードウェア加速)。'none' でアニメーションをスキップし、即時ナビゲーションになります。同じ属性がダイアログとポップアップにも効きます。

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>

遷移のタイプ

jQuery Mobile には 2D/3D の CSS 遷移のセットが付属します。3D 遷移(turn、flow、flip)は性能のあるデバイスでは素晴らしく、古いハードウェアでは優雅にフォールバックします。pop と fade が最も高性能で、ダイアログとポップアップには推奨です。

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

方向と逆再生

data-direction=reverse は遷移を逆再生します — 通常は「戻る」ボタンに使い、アニメーションが前進ナビゲーションを映し返すようにします。data-transition と組み合わせます。遷移が設定されていなければ、デフォルトが反転されます。

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>

ダイアログの遷移

ダイアログはどんな遷移でも使えますが、モーダルには pop と slidedown が最も自然に感じられます。mobileinit 中に $.mobile.defaultDialogTransition でグローバルのデフォルトを設定しましょう。ダイアログの close 操作が遷移を自動的に逆再生します。

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>

無効化とフォールバック

data-transition=none を設定するか、グローバルのデフォルトを 'none' にすればアニメーションが無効化されます — 低スペックのデバイスやアクセシビリティに有用です。jQuery Mobile は 3D transform の対応を自動検出し、非対応のとき 3D 遷移(flip、turn、flow)を単純な fade へ劣化させます。

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

ツールバー(Header と Footer)

固定の Header と Footer

data-position=fixed を加えると、ページがスクロールしても header や footer がビューポートの上端/下端に張り付きます。デフォルトではページをタップするとツールバーの表示がトグルします。ツールバーの後ろに隠れないよう、ページのコンテンツにパディングが付きます。

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>

フルスクリーンのツールバー

data-fullscreen=true は、スペースを確保する代わりに、固定ツールバーをコンテンツの上に(半透明で)重ねます。コンテンツが画面を満たすべきフォトビューアや地図に最適です。ツールバーは固定ツールバーと同じく、タップで現れたり消えたりします。

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>

永続的なツールバー

2 つのページが同じ data-id と data-position=fixed を持つ footer(または header)を持つとき、ツールバーはページと共にアニメーションせず、ページ遷移をまたいで持続します。これが永続的な下部ナビゲーションバーの標準パターンです — ページごとに変化するのはアクティブなリンクだけです。

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>

タップトグルの挙動

固定ツールバーは、ユーザーがページをタップすると表示がトグルします。ツールバーを常に表示させるには data-tap-toggle=false を設定しましょう。関連する要素ごとのオプション:data-hide-during-focus(入力にフォーカスしたとき隠す)、data-update-page-padding(リサイズ時にページのパディングを再適用)。

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>

ツールバーのテーマとボタン

header には、ui-btn-left / ui-btn-right のクラスで配置されたボタンを置けます。data-theme がバーのカラースウォッチを設定し、data-iconpos=notext でコンパクトな見た目にアイコンだけを表示します。header 内のボタンは自動的にインラインボタンとして整形されます。

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>

ツールバーの動的な更新

実行時にツールバーのマークアップを変えた後は、$(el).toolbar('refresh') を呼び、スタイリングとパディングを再適用しましょう。toolbar ウィジェット(1.4 で導入)が固定位置とタップトグルを管理します。ページ作成後にツールバーを追加した場合は、$().toolbar() で手動初期化しましょう。

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

ボタン

ボタンの基本

class=ui-btn(または data-role=button)を持つ任意の <a> に加え、<button> と <input type=button|submit|reset> は、自動的にスタイル付きボタンへ拡張されます。ui-btn クラスが、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>

インラインボタン

デフォルトのボタンは全幅(block)です。ui-btn-inline(または data-inline=true)を加えると、ボタンがラベルの幅だけになり、複数のボタンが横に並びます。「キャンセル | 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>

ボタンのアイコン

アイコンを加えるには ui-icon-{name} を、配置するには ui-btn-icon-{pos} を使います(left、right、top、bottom、notext)。ui-btn-icon-notext はテキストを隠しアイコンだけを示します — アクセシビリティ/スクリーンリーダーのために、いずれにせよテキストを用意しましょう。

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>

アイコンの位置とインライン

data-iconpos 属性は、ui-btn-icon-* クラスのレガシーな等価物です。'notext' はアイコンだけを示します(スクリーンリーダーのために要素のテキストは常に残す)。インラインとアイコンのクラスは 1 つのボタンで自由に組み合わせられます。

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>

Mini と無効なボタン

ui-mini(または data-mini=true)を加えると、より小さくコンパクトなボタンになります — 密なツールバーに有用です。ボタンの無効化には ui-state-disabled(<button>/<input> ならネイティブの disabled 属性)を使います。無効化されたボタンはタップを無視します。

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>

ボタングループ(Controlgroup)

controlgroup がボタンを視覚的にまとめます — 隣接するボタンが角丸を共有し隙間がなくなります。data-type=horizontal で 1 行に並びます(セグメントコントロールに良い)。デフォルトの縦は積み重ねます。checkbox/radio も統一されたセットとしてグループ化されます。

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

リストビュー

基本の Listview

<ul> に data-role=listview を加えると、全幅でタップ可能な行を持つタッチフレンドリーなリストになります。<a> を含む各 <li> が、右矢印付きのリンク行になります。data-inset=true で、端から端までではなく角丸とマージン付きのインセット表示になります。

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>

Inset リスト

端から端までのリストは全幅に広がります(フルスクリーンのメニューに良い)。inset リストは角丸と周囲のマージンを持ちます(ページ内のコンテンツセクションに良い)。inset リストには data-inset=true を使いましょう。グループ化された設定パネルのように見えます。

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>

リストの区切り

data-role=list-divider を持つ <li> が、クリック不可のセクションのヘッダーになります。data-autodividers=true で、各項目のテキストの最初の文字に基づき区切りが自動挿入されます — アルファベット順の連絡先リストに最適です。

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>

カウントバブルとサムネイル

<li> の内側に class=ui-li-count の span を加えると、右側に数値のカウントバブルが表示されます。左のサムネイルには、class=ui-li-thumb(通常 80x80)の <img> を使いましょう。<h3>/<p> と組み合わせれば、アプリ風のリッチなリスト行になります。

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>

検索フィルタ

data-filter=true で、リストの上に検索入力が加わり、テキストでアイテムをリアルタイムにフィルタします。data-filter-placeholder でプロンプトをカスタマイズでき、data-filter-reveal=true はユーザーが入力するまで全アイテムを隠します — オートコンプリート風の検索に有用です。

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>

スプリットボタンとネストしたリスト

<li> が 2 つの <a> 要素を含むとき、jQuery Mobile はスプリットボタンを描画します:メインの行が最初のリンクへナビゲートし、右側の別のアイコンボタン(data-split-icon で設定)が 2 番目を開きます。<li> の内側にネストした <ul> は、自動的にドリルダウンのサブページになります。

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

フォームコントロール

フォームの構造と AJAX 送信

jQuery Mobile はフォーム入力を自動拡張し、デフォルトでフォームを AJAX 経由で送信します。ローディングのスピナーを表示し、結果ページへ遷移します。従来のフルページ送信にするには data-ajax=false を設定しましょう(モダンな API を使わないファイルアップロードでは必須です)。

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>

テキスト入力とクリアボタン

すべての HTML5 の入力タイプ(text、email、tel、number、password、date など)が一貫して整形されます。data-clear-btn=true でフィールド内のクリア(x)ボタンが加わります。コントロールを jQuery Mobile のスタイリングなしの素のネイティブ入力のままにするには data-role=none を使いましょう。

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

フィールドコンテナ

ラベル + コントロールのペアを、class=ui-field-contain の div で包みましょう。幅広の画面ではラベルと入力が横に並び、狭い携帯では縦に積み重なります。このレスポンシブな挙動が、古い 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 type=search> は、虫眼鏡アイコン付きの検索フィールドへ拡張されます。リストビューと組み合わせるには、入力に id を与え、リストビューのフィルタに data-input=#id を設定しましょう — これで検索ボックスをページのどこにでも置けます。

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 と Hidden 入力

textarea は他の入力と一致するよう整形され、デフォルトではタイピングに合わせて自動的に伸びます。高さを固定しスクロールバーにするには data-autogrow=false を設定しましょう。hidden 入力はそのまま通ります。すべての入力と同様、レスポンシブなラベルのために ui-field-contain で包みましょう。

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

自動拡張の無効化

任意のコントロールに data-role=none を加えれば、jQuery Mobile の拡張がスキップされネイティブのままになります。プロジェクト全体のルールとしては、mobileinit 中に keepNative を、決して拡張すべきでない要素のセレクタ文字列に設定しましょう — カスタムスタイルのコントロールを 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

スライダー

基本のレンジスライダー

min、max、value、step を持つ <input type=range> が、値のバブルを持つタッチフレンドリーなスライダーへ拡張されます。value 属性が初期位置を設定します。スライダーは値を入力へ書き戻すため、フォームと共に通常どおり送信されます。

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

ハイライト付きスライダー

data-highlight=true で、トラックのハンドルの左側がアクティブテーマの色で満たされ、現在のレベルが明確に視覚化されます。なければトラックは単一のフラットな色です。音量や明るさのような設定に有用です。

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

Mini スライダー

data-mini=true は、より小さくコンパクトなスライダーを描画し、縦のスペースを節約します — 設定パネルで複数のコントロールをまとめるときに便利です。通常のスライダーと同じ挙動で、サイズが減っただけです。

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 と複数のスライダー

step が刻み幅を制御します(step=5 なら 0、5、10、... にスナップします)。各 range 入力は独立したスライダーです。デュアルハンドルのレンジには、カスタムウィジェットを作るかサードパーティのプラグインが必要です。ネイティブの value、min、max 属性が挙動を駆動します。

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

スライダーのイベント

スライダーは、ユーザーがハンドルをドラッグし始めると slidestart を、ドラッグが終わると slidestop を出します。ドラッグ中の継続的な更新には、背後の range 入力のネイティブな 'input' か 'change' イベントに bind しましょう。値の読み書きには $(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

Flip トグルスイッチ

基本の Flip トグル

flip スイッチは、ちょうど 2 つの <option> 要素と data-role=slider を持つ <select> です。iOS 風のオン/オフのトグルとして描画されます。選択された option が初期状態を決め、値は通常の select のように送信されます(選ばれた option の value)。

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>

カスタムラベル

2 つの option のテキストが、スイッチの両側のラベルになります。短いテキストなら何でも使えます(On/Off、Yes/No、Enabled/Disabled)。小さい画面で切り詰められずトグル内に収まるよう、ラベルは短く保ちましょう。

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>

Mini の Flip スイッチ

data-mini=true は、より小さい flip スイッチを描画し、縦のスペースを節約します。mini スライダーや他の mini コントロールと一致します。一貫したコンパクトな見た目のため、mini コントロールを密な設定パネルでペアにしましょう。

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>

Flip のテーマ

data-theme がスイッチのハンドルの色を設定し、data-track-theme が背後のトラックの色を設定します。スウォッチを混ぜると(明るいトラックに暗いハンドルなど)、アクティブ状態が視覚的によりはっきり分かります。

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>

プログラム的なトグル

$(el).val(value) で値を設定し、.slider('refresh') を呼べば、視覚的なトグルが一致するよう更新されます。現在の状態の読み取りは .val() です。プログラム的に背後の select の値を変えた後は必ず refresh しましょう — さもないとハンドルが動きません。

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

Checkbox と Radio

Checkbox

checkbox は、<label for=id> で包まれた(または隣接する)通常の <input type=checkbox> です。jQuery Mobile がラベルをタップ可能なブロックとして整形します。ラベルが入力を包んでいれば、for 属性は省略可能です。チェック状態はフォームと共に通常どおり送信されます。

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>

Radio ボタン

radio は同じ name 属性でグループ化しましょう。グループを、data-role=controlgroup の fieldset(と <legend>)で包めば、共有された角丸で視覚的にまとまります。同名のグループでチェックできる radio は一度に 1 つだけです。

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>

水平の Controlgroup

data-type=horizontal が、縦の積み重ねの代わりに、checkbox や radio を 1 行にセグメントコントロールとして並べます。コンパクトで、短いラベル(S/M/L、Yes/No)に適しています。狭い画面で収まるよう、ラベルは短く保ちましょう。

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 とテーマ

data-mini=true でコントロールが縮み、data-theme がチェック/アクティブ時に適用されるスウォッチを設定します。ページの背景から目立つよう、アクティブ状態をテーマ化しましょう。これらのオプションは controlgroup 全体に一度に適用されます。

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

コードで checkbox/radio の checked プロパティを設定した後は、.checkboxradio('refresh') を呼び、拡張された見た目を一致させましょう。controlgroup の内側の入力を実行時に追加・削除したら、.controlgroup('refresh') でグループ化されたスタイリングを再適用します。

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

Select メニュー

ネイティブ Select

デフォルトでは jQuery Mobile はカスタムスタイルの select を示しますが、背後の OS のピッカーが依然開きます。デバイスのネイティブなドロップダウンを完全に使うには data-native-menu=true(または data-role=none)を設定しましょう — より速く馴染みやすいですが、プラットフォーム間の見た目の一貫性は低くなります。

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>

カスタム Select メニュー

data-native-menu=false で、ネイティブのピッカーの代わりに jQuery Mobile スタイルのポップアップメニューが開き、全デバイスで一貫した見た目になります。携帯では「完了」ボタン付きのフルスクリーンダイアログとして現れ、タブレットではフィールドの近くに小さいポップアップとして現れます。

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

空の値の最初の option がプレースホルダーとして振る舞います。data-overlay-theme がカスタムメニューの背景色を設定します。multiple 属性を加えると、カスタムメニューがチェックリストのダイアログになり、複数の option を選べ、ボタン上にカンマ区切りで表示されます。

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>

Select のテーマとオーバーレイ

data-theme が select ボタン自体を整形し、data-overlay-theme がポップアップ/背景の色を設定し、data-divider-theme がメニュー内の list-divider 区切りを色付けします。option の間に <li data-role=list-divider> を挿入すれば、視覚的にグループ化できます。

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>

Select のイベント

選択に反応するには標準の 'change' イベントを listen しましょう。コードで値を変えた(または option を置き換えた)後は、.selectmenu('refresh') を呼び、ボタンのラベルが新しい選択に一致するよう更新します。再初期化ではなく 'refresh' でメニューを更新しましょう。

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

ポップアップ

基本のポップアップ

ポップアップは data-role=popup の div です。data-rel=popup 付きでその id へリンクすれば開きます。ポップアップはデフォルトで中央に重なります。パディングには ui-content を加え、閉じるには内側のリンクに data-rel=back を使いましょう。

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>

ポップアップの遷移

アニメーションを選ぶには、開くリンクに(またはポップアップ自体に)data-transition を使います。ポップアップには pop と fade が最も自然です。ページ用の遷移セットがここでも適用され、close 操作が遷移を自動的に逆再生します。

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>

ポップアップの位置

data-position-to がポップアップが現れる場所を制御します:'origin'(開いた要素、デフォルト)、'#someId'(特定の要素)、'window'(画面中央)。popup('open', x, y) でプログラム的に開くときは、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>

ポップアップメニューとツールチップ

ポップアップはどんなコンテンツでも含められます — listview はコンテキストメニューになり、段落はツールチップになります。ポップアップは data-theme で、内側のコンテンツは独自のテーマで整形しましょう。ユーザーが外側をタップするとポップアップは自動的に閉じます(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>

ダイアログポップアップ

ウィンドウの中央に配置され、閉じるボタンを持つポップアップがモーダルダイアログとして振る舞います。角に X ボタン(ui-btn-icon-notext 付きの ui-icon-delete)を加えましょう。真のダイアログの見た目のため、全幅のシートではなく max-width スタイルで幅を制限します。

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>

プログラム的な開閉と Dismissible

コードからポップアップを開閉するには .popup('open'/'close') を使います。data-dismissible=false は外側のタップでの閉鎖を防ぎ、ユーザーに閉じるボタンの使用を強制します — 必須の確認に理想的です。開くときは x/y 座標か position オブジェクトも渡せます。

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

パネル

基本のパネル

パネルは data-role=panel の div で、ページの内側に(通常は header の前に)置きます。ボタンでその id へリンクすれば開きます。閉じるには内側のリンクに data-rel=close を使いましょう。パネルはスライドアウトのナビゲーションメニューに最適です。

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>

パネルの表示モード

data-display が開くアニメーションを制御します:'reveal'(デフォルト)はページを滑らせ、下のパネルを明らかにし、'overlay' はパネルをページの上に滑らせ、'push' はパネルを滑り込ませつつページを横へ動かします。メニューには overlay が最も一般的です。

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

パネルの位置

data-position=left(デフォルト)か right で、パネルがどちらの側から滑り込むかが決まります。同じページに左と右の両方のパネルを持てます。一度に開けるパネルは 1 つで、2 つ目を開くと 1 つ目が閉じます。

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 とスワイプ

data-dismissible=true(デフォルト)は、ユーザーがパネルの外側をタップすると閉じます。data-swipe-close=true で、逆方向にスワイプすれば閉じられます(例:右スワイプで左パネルが閉じる)。どちらも 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>

パネルのイベント

パネルは panelbeforeopen、panelopen、panelbeforeclose、panelclose のイベントを発火します。'before' ハンドラから false を返すと操作がキャンセルされます — 閉じる前の確認に有用です。コードからの開閉は .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

Collapsible

基本の Collapsible

data-role=collapsible の div が、見出し(h1〜h6)をクリック可能なヘッダーとして、残りを展開可能なコンテンツとして包みます。デフォルトで折りたたまれて始まります。ヘッダーのクリックで、+/- アイコンと共にコンテンツが開閉します。

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>

Collapsible のアイコンとテーマ

インジケーターは data-collapsed-icon と data-expanded-icon でカスタマイズします(デフォルトはプラス/マイナス)。data-theme がヘッダーを整形し、data-content-theme が展開されたコンテンツ領域を整形します。data-collapsed=false で、折りたたみではなく展開された状態で始まります。

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>

Collapsible Set(アコーディオン)

collapsibleset が collapsible をグループ化し、一度に 1 つだけ開きます — アコーディオンです。1 つを開くと他が自動的に閉じます。(1.4 では属性は data-role=collapsibleset で、古い collapsible-set の名前も動きます。)セット全体が統一されたテーマを共有します。

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>

事前展開と Inset

collapsibleset 内では、初期状態で開きたいセクションに data-collapsed=false を設定しましょう。data-inset=true(セットではデフォルト)がグループに角丸とマージンを与えます。端から端までのセットには data-inset=false を使い、全幅に広げます。

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>

Listview 付きの Collapsible

collapsible は listview を含むどんなウィジェットも含められます。長いリストを折りたたみヘッダーの下にまとめる素晴らしいパターンです。collapsible に data-filter=true を加えれば、ヘッダー領域内の検索ボックスで、内側の listview のアイテムをフィルタできます。

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>

プログラム的な展開/折りたたみ

コードから collapsible を制御するには .collapsible('expand') と .collapsible('collapse') を使います。ユーザーのトグルに反応するには 'collapse' と 'expand' のイベントを listen しましょう。セットでは、プログラム的に 1 セクションを展開すると他が自動的に折りたたまれます。

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

tabs ウィジェットは、navbar(タブのリンク)と、リンクの href と一致する id を持つコンテンツパネルを含む data-role=tabs の div です。ui-btn-active のリンクが最初に表示されます。タブのクリックでそのパネルが表示され、他が隠れます — ページ遷移はありません。

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

タブのリンクに ui-icon-{name} と ui-btn-icon-top のクラスを加えると、ラベルの上にアイコンが現れ、アプリ風のタブバーになります。アクティブなタブは ui-btn-active を保ちます。タブストリップでアイコンをテキストの上に置くには ui-btn-icon-top を使いましょう。

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>

AJAX Tabs

タブのリンクの href が URL(#id ではない)のとき、tabs ウィジェットがアクティベーション時にそのページを AJAX でコンテナへロードします。最初のタブはページ初期化時に自動的にロードされます。タブごとに重いコンテンツを遅延ロードするのに有用です。

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>

Tabs の永続化

タブはデフォルトではリロードをまたいでアクティブな状態を覚えません。tabsactivate イベント(ui.newPanel/ui.oldPanel を与える)と localStorage を使い、選択を永続化しましょう。ロード時に保存されたタブのクリックを再トリガーすれば復元できます。

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>

Tab のイベント

tabsbeforeactivate はタブ切り替えの前に発火し(false を返すとキャンセル)、tabsactivate は後に発火します。どちらも ui.newTab/ui.oldTab(<a> のリンク)と ui.newPanel/ui.oldPanel(コンテンツの div)を与えます。コンテンツの遅延ロード、分析の記録、切り替え前の検証に使いましょう。

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

テーマ

テーマのスウォッチ(a〜e)

jQuery Mobile のテーマは、1 色ではなく文字の「スウォッチ」(a〜e)を使います。a が最もコントラストの高い(暗い)もので、header/footer のデフォルトです。b は青いアクセントで、c がデフォルトの明るいページ背景です。任意の要素に data-theme でスウォッチを適用しましょう。

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>

テーマの適用

ボタンには ui-btn-{swatch} クラスを使います(例:青いボタンは ui-btn-b)。他の要素には data-theme={swatch} を使います。明示的に設定しない限り、子は親のスウォッチを継承します。デフォルトのページスウォッチは 'c'(明るいグレー)です。

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

オーバーレイテーマ

data-overlay-theme が、ポップアップ、ダイアログ、カスタムの select メニューの背後の暗くなった背景の色を設定します。前景のコンテンツが目立つよう、オーバーレイには暗いスウォッチ(a か b)を使いましょう。ポップアップ自体の data-theme がポップアップのボックスの色を制御します。

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>

リストとボタンのテーマ

listview は別々のテーマを受け付けます:行には data-theme、区切りのヘッダーには data-divider-theme、カウントバブルには data-count-theme。これで、行を控えめに保ちつつ区切りをハイライトできます。同じきめ細かいテーマ化が、ボタンとフォームにも適用されます。

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>

カスタムスウォッチ

各スウォッチは CSS クラスのセットにすぎません(.ui-bar-{x}、.ui-body-{x}、.ui-btn-up-{x} など)。カスタムスウォッチ 'f' を加えるには、これらのルールをコピーして色を変えましょう — または ThemeRoller ツールで完全なカスタムテーマファイルを生成します。その後 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>

テーマの継承

要素は、自分のスウォッチを設定していなければ、最も近い祖先のスウォッチを継承します。内側のすべてを一貫してテーマ化するには、高いところ(ページなど)でスウォッチを設定し、必要に応じて個々の要素を上書きしましょう。グローバルのデフォルトページテーマは 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

レスポンシブレイアウト

Grid レイアウト

グリッドはウィジェットではなく CSS クラスです。ui-grid-a が 2 列のグリッド、ui-grid-b が 3 列、ui-grid-d(5 列)まで。子は順に ui-block-a、ui-block-b、... を受け取り、自動的に折り返します。グリッドは常に 100% 幅で、自分ではブレークポイントに反応しません。

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>

レスポンシブグリッド

jQuery Mobile のグリッドには組み込みのブレークポイントがありませんが、カスタムのメディアクエリを加えられます:狭い幅ではブロックに width:100% と float:none を設定して縦に積み重ね、幅広の画面ではデフォルトの列を適用させましょう。ルールをスコープするためマーカークラスを加えます。

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>

Reflow テーブル

reflow テーブル(data-mode=reflow)は、狭い画面で積み重ねたカードレイアウトに再構成され、各列のヘッダーが値の横のラベルとして繰り返されます。ui-responsive クラスを加えれば、reflow がブレークポイント未満でだけ発動し、幅広の画面では通常のテーブルが保たれます。

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

Column Toggle テーブル

columntoggle テーブルは、「Columns...」ボタンを加え、ユーザーがどの列を表示するか選べるようにします。省略可能な列には data-priority=1..6 を割り当てましょう(低いほど重要で、広いブレークポイントで表示される)。優先度のない列は常に表示されます。最重要の列が携帯に残り、残りはメニューにしまわれます。

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>

ブレークポイントとヘルパークラス

jQuery Mobile にはユーティリティのブレークポイントクラスがありません。カスタムレイアウトには自分でメディアクエリを書きましょう。組み込みの 40em(640px)ブレークポイントが制御するのは、レスポンシブテーブル(ui-responsive)が積み重ねと表形式を切り替えるタイミングだけです。グリッドとパネルには、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

タッチイベント

Tap と Taphold

tap は素早いタッチで発火します(モバイルの click、約 300ms 待つ、より速く信頼性があります)。taphold は、ユーザーが指を約 750ms 押し続けたとき発火します。どちらもマウスとタッチで動くよう正規化されるため、同じコードがデスクトップとモバイルで動きます。

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 とスワイプの方向

swipe は水平方向のスワイプで発火し、swipeleft と swiperight が方向を教えます — 画像カルーセルやページナビゲーションに便利です。これらは水平移動ベースです。垂直スクロールは意図的にスワイプとして扱われないため、通常のページスクロールが動き続けます。

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>

Swipe のしきい値

スワイプが登録されるのは、durationThreshold(デフォルト 1000ms)内で少なくとも horizontalDistanceThreshold(デフォルト 30px)をカバーし、垂直では verticalDistanceThreshold 未満に留まるときだけです。水平のしきい値を上げれば長いスワイプが求められ、下げればより敏感になります。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>

仮想マウスイベント

vmouse* イベントは、jQuery Mobile の統一された mouse/touch/pointer イベントです — 指でもマウスでも一貫して発火します。モバイルの 300ms 遅延を避けるには、click の代わりに vclick を使いましょう。tap と swipe の基礎となる積み木です。

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>

向きの変更

orientationchange はデバイスが回転したとき発火し、e.orientation が 'portrait' か 'landscape' になります。ビューポートの寸法はイベント発火後にわずかに更新されるため、レイアウト依存のコードは短い setTimeout で包みましょう。ジャイロのないデバイスのフォールバックとして 'resize' イベントも listen しましょう。

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 とスロットリング

scrollstart と scrollstop は、jQuery Mobile のスロットリングされたスクロールイベントです(ブラウザがネイティブにスクロールハンドラを絞りますが、これらは明確な開始/停止の瞬間を与えます)。要素でのスクロール/ズームを防ぐには(描画キャンバスや地図など)、touchmove を bind し 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

ページイベントとライフサイクル

ページ初期化のイベント

pagebeforecreate は、jQuery Mobile がページのマークアップを拡張する前に発火します — クラスやウィジェットを注入する最良の場所で、それらも拡張されます。pagecreate は拡張完了の直後に発火します — イベントハンドラの bind とプラグインの初期化に使いましょう。それぞれページごとに 1 回発火します。

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

pagebeforeshow/pageshow はページが見えるようになる前後に、pagebeforehide/pagehide は隠れる前後に発火します。'show' のイベントは、ページが表示されるたびに(1 回だけではなく)発火するため、ページに戻るときの動的データの更新に適した場所です。

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 はあらゆるナビゲーションの前に発火し、横取りやリダイレクトの場所です(キャンセルには preventDefault を呼ぶ)。pagechange はナビゲーションの成功後に発火し、pagechangefailed はターゲットページの読み込みがエラーになったとき発火します。内部(#id)でも 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>

ページコンテナのロード

pageload は、AJAX で取得されたページが DOM へ正常に挿入されたとき発火します(data.url と data.page が提供されます)。pageloadfailed はロードエラーで発火します — デフォルトでは jQM がエラーメッセージを示します。ハンドラから false を返せば、自分で処理したことを jQM に伝えられます。

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>

ページイベントへの bind

ページイベントは、ページの #id セレクタでフィルタしつつ、document 上のイベント委譲で bind しましょう — 後から AJAX で取り込まれたページでも機能します。プログラム的なナビゲーションには、pagecontainer ウィジェットの 'change' メソッド($.mobile.changePage のモダンな代替)を使い、ターゲットとオプションを渡しましょう。

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>

ページの削除と後始末

デフォルトで jQuery Mobile は、ページから離れた後にそのページを DOM から取り除きます(domCache が有効でなければ)。pageremove は削除の直前に発火します — ここでインターバル、リスナー、プラグインのインスタンスを後始末しましょう。pagehide イベントの ui.prevPage が、隠れたページの jQuery オブジェクトを与え、テアダウンに使えます。

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.