Improve this
このガイドは Onsen UI 1 のものです。 Onsen UI 2 はマテリアルデザインや React, Angluar 2+ のサポート、新しいコンポーネントなど数多くの追加機能を持っています。 Onsen UI 2 のドキュメントをお探しの場合は Onsen UI 2 ガイドをご参照ください。 また、Onsen UI 1 から Onsen UI 2 への移行ガイドも併せてご利用ください。

Onsen UIをプロジェクトに組み込む

ヒント: Onsen UIの組み込み方法については、Getting Startedガイドも参考にしてください。

Onsen UIはAngularJSを用いてHTML5のCustom Elements対応を行っていますが、AngularJSの理解は必須ではありません。Onsen UIは、jQueryやBackbone.jsといったすべてのJavaScriptフレームワークと共に利用することができます。一方で、AngularJSと組み合わせることで、より高度な連携を行うことも可能です。

AngularJSからOnsen UIを使う

Onsen UIはAngularJSの上に作られています。そのため、AngularJSのユーザーであれば、下記のようにしてOnsen UIを使うことができます。

<!doctype html>
<html lang="en" ng-app="my-app">
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="lib/onsen/css/onsenui.css"/>
    <link rel="stylesheet" href="lib/onsen/css/onsen-css-components.css"/>
    <script src="lib/onsen/js/angular/angular.js"></script>
    <script src="lib/onsen/js/onsenui.js"></script>
    <script>
      var module = ons.bootstrap('my-app', ['onsen']);
      module.controller('AppController', function($scope) { });
      module.controller('PageController', function($scope) {
        ons.ready(function() {
          // Init code here
        });
      });
    </script>
  </head>
  <body ng-controller="AppController">
    <ons-navigator var="navi">
      <ons-page ng-controller="PageController">
        <!-- Page content -->
      </ons-page>
    </ons-navigator>
  </body>
</html>

AngularJSを意識せずにOnsen UIを扱う

Onsen UIはAngularJSを学ばない状態でも使い始めることができます。下記のサンプルは、Onsen UIを通常のJavaScriptのような記述で利用しています。

<!doctype html>
<meta charset="utf-8">
<link rel="stylesheet" href="lib/onsen/css/onsenui.css">
<link rel="stylesheet" href="lib/onsen/css/onsen-css-components.css">
<script src="lib/onsen/js/angular/angular.js"></script>
<script src="lib/onsen/js/onsenui.js"></script>
<script>
  ons.bootstrap();
  ons.ready(function() {
    // Add another Onsen UI element
    var content = document.getElementById("my-content");
    content.innerHTML="<ons-button>Another Button</ons-button>";
    ons.compile(content);
  });
</script>
<body>
  <ons-navigator title="Navigator" var="myNavigator">
    <ons-page>
      <ons-button onclick="myNavigator.pushPage('page2.html')">Next Page</ons-button>
      <div id="my-content"></div>
    </ons-page>
  </ons-navigator>
</body>

このコードでは、2つの特長があります。1つはOnsen UIコンポーネントに付与されたvar属性、そしてons.compile関数です。

コンポーネントを定義する時にvar属性を指定すると、そのコンポーネントのオブジェクトはwindowオブジェクトのプロパティとして定義されます。詳細についてはコードからコンポーネントオブジェクトにアクセスするを参照してください。

ons.compile関数を使うと、Onsen UIコンポーネントが定義されたHTMLコードを通常のDOM構造に変換します。(現状では)ほとんどのブラウザーはCustom Elementsをサポートしていないため、この関数を使ってOnsen UIコンポーネントをブラウザーに対応させることが必要です。

複数のページを管理する

アプリ開発に着手する前に、UIパターンを検討することが重要となります。Onsen UIはよく使われる4種類の画面パターンに対応しています。もちろん、スライディングメニュー方式のアプリにページナビゲーションを組み込むなど、複数の画面パターンを組み合わせることも一般的です。

ナビゲーション型

ページが親子関係を持つ場合に一般的に用いられるパターンです。子ページへは、ボタンのタップや、リスト要素の選択などからリンクされます。ナビゲーションパターンを実装するためには、<ons-navigator><ons-toolbar>を組み合わせます。

スライディングメニュー型

メニュー型とも呼ばれ、同じ階層に複数のページを配置するような場合に最適です。Onsen UIでは、<ons-sliding-menu>コンポーネントで実装します。スワイプ操作でメニューの表示/非表示を制御することもできます。

タブバー型

iPhoneやiPadアプリでよく見られ、ページの下部にタブバーを配置したパターンになります。通常、タブバーにはいくつかの項目(アイテム)が並び、アイコンとテキストで表現されます。複数の機能を提供したいような場合に用いられます。Onsen UIでタブバーを実装するには、<ons-tabbar>コンポーネントを使用します。

スプリットビュー型

タブレットのような大きな画面を持つデバイスや、画面を横向きにしたときに用いられます。スプリットビュー型では、画面を左と右に分割し、別々の情報を表示できます。<ons-split-view>コンポーネントを用います。小さな画面を持つデバイスや、縦向きにした場合に、自動的に画面分割を畳む機能も有しています。

ページナビゲーション

Onsen UIでは、<ons-navigator>コンポーネントでページナビゲーションを実装します。ons-navigatorは画面要素を持たない、ナビゲーションコントローラーです。そのため、一般的にはページ内にツールバーを表示するために<ons-toolbar>を組み合わせます。ナビゲーターは画面遷移をする際に自動的にアニメーションを適用し、親子関係を持つページを作成するために利用できます。

<ons-navigator>の概要

<ons-navigator>コンポーネントは、ページスタックの管理機能と、画面遷移時のアニメーション効果を提供します。ページスタックに新しいページが追加されると、自動的にアニメーションが行われ、ページが表示されます。スタック内のすべてのページは<ons-page>要素で表されます。そのため、<ons-navigator>コンポーネントの直下には<ons-page>コンポーネントのみ配置できます。

通常は、ページ上部にツールバーを設置します。そのため、<ons-page>の下には<ons-toolbar>コンポーネントを配置するのが一般的です。ツールバーには、戻るボタンを設置したり、ページタイトルを描画したりします。

Run this example.

Click to Load this example.

新しいページを表示

スタックに新しいページを追加するには、ナビゲーターオブジェクトのpushPage()メソッドを使用します。このメソッドを呼び出すために、<ons-navigator>var属性を使用し、ナビゲーターオブジェクトをJavaScriptから呼び出せるように指定します。

<ons-navigator var="myNavigator"></ons-navigator>
<script>
var options = {
  animation: 'slide', // アニメーションの種類
  onTransitionEnd: function() {} // アニメーションが完了した際によばれるコールバック
};
myNavigator.pushPage("page2.html", options);
</script>

上記のコードのように、遷移時のオプションをpushPage()メソッドに渡すことができます。

一つ前のページに戻る

popPage()メソッドを呼ぶと、ページスタックから最前面のページが削除され、一つ前のページに戻ります。

<ons-navigator var="myNavigator"></ons-navigator>
<script>
myNavigator.popPage();
</script>

遷移アニメーションの指定

pushPage()popPage()メソッドでは、下記のアニメーションを選択できます: slideliftfadenone

  1. スライド(タイプ: slide、デフォルト)

    アニメーションの表現は、ネイティブ遷移と合わせるためにiOSとAndroidで異なるものとなります。

    navigator.pushPage("page2.html", { animation: "slide" }):
    
  2. リフトアップ / リフトダウン(タイプ: lift

    navigator.pushPage("page2.html", { animation: "lift" }):
    
  3. フェードイン / フェードアウト(タイプ: fade

    navigator.pushPage("page2.html", { animation: "fade" }):
    
  4. アニメーションなし(タイプ: none

    navigator.pushPage("page2.html", { animation: "none" }):
    
Run this example.

Click to Load this example.

さらに、遷移アニメーションはカスタマイズできます。その場合はNavigatorTransitionAnimatorオブジェクトを作成し、animationパラメータに指定してください。

pushPage('page2.html', {animation: new MyCustomAnimator})

詳細については、framework/viewディレクトリ内にあるNavigatorTransitionAnimatorを参照してください。

ページスタックの管理

ナビゲーターにはページスタックを管理するためのAPIが提供されます。これらのAPIを使うことで、より細かい挙動をカスタマイズできます。

現在のページのpageオブジェクトを取得します。pageオブジェクトは、下記のプロパティと関数を有しています。

myNavigator.pushPage("page2.html", { param1: "value1", param2: "value2" });
var page = myNavigator.getCurrentPage();
console.log(page.options.param1); // "value1"が戻ります

ナビゲーターが保有するpageオブジェクトの一覧を返します。pageオブジェクトの使い方については、navigator.getCurrentPage()メソッドの説明を参照してください。

// ページスタックの上から2番目のページを削除する例
var pages = navigator.getPages();
pages[pages.length - 2].destroy();
// popPage()を行うとpages[pages.length - 3]のページに戻ります

ページスタックのindexパラメータで指定した場所にページを追加します。0を指定すると、ページスタックの最後(最下層)にページを追加します。また、マイナス値を指定すると、上からの順番で計算されます。たとえば、-1を指定すると上から2番目にページが追加されます。pageoptionsパラメータは、pushPage()メソッドと同様に指定します。

Run this example.

Click to Load this example.

現在表示中のページをを指定したページに置き換えます。optionsパラメータはnavigator.pushPage APIと同様です。

ページスタックをクリアし、指定した新しいページをスタックに追加します。optionsパラメータはnavigator.pushPage APIと同様です。

ツールバーの追加

ツールバーは<ons-toolbar>コンポーネントとして定義されます。下記にツールバーの例を掲載します。

<ons-toolbar>
  <div class="left">
    <ons-back-button>戻る</ons-back-button>
  </div>
  <div class="center">タイトル</div>
  <div class="right">
    <ons-toolbar-button>
      <ons-icon icon="fa-bars">
    </ons-toolbar-button>
  </div>
 </ons-toolbar>
Run this example.

Click to Load this example.

ツールバーは左、中央、右の3つに分けられ、それぞれに対応したクラス名(leftcenterright)として指定できます。<ons-icon>でアイコンを表示したり、<ons-toolbar-button><ons-back-button>コンポーネントでボタンを配置できます。HTMLを直接記述することもできます。

ツールバーの表示スタイルはmodifier属性で変更でき、androidもしくはiosを指定できます。指定がない場合は、プラットフォームに適したデザインを自動的に適用します。fixed-style属性を指定すると、プラットフォームにかかわらずスタイルが固定となります。

<ons-toolbar>コンポーネントを用いた例を紹介します。

  1. ボタンとアイコンを用いた例

    <ons-toolbar>
     <div class="left"><ons-toolbar-button>左ボタン</ons-toolbar-button></div>
     <div class="center">ボタンとアイコン</div>
     <div class="right"><ons-toolbar-button><ons-icon icon="fa-bars"></ons-icon></ons-toolbar-button></div>
    </ons-toolbar>
    
  2. 検索ボックスを用いた例

    <ons-toolbar>
     <div class="left"><ons-back-button>戻る</ons-back-button></div>
     <div class="center">検索</div>
     <div class="right"><input type="search" class="search-input" placeholder="キーワード"></input></div>
    </ons-toolbar>
    
  3. カスタムなイメージを表示する例

    <ons-toolbar>
     <div class="left"><ons-back-button>戻る</ons-back-button></div>
     <div class="center"><img src="custom_title.png"></div>
     <div class="right"><ons-search-input></ons-search-input></div>
    </ons-toolbar>
    
ツールバーのインライン表示

ツールバーをヘッダー外に設置したい場合は、<ons-toolbar><ons-bottom-toolbar>inline属性を指定します。

<ons-toolbar inline>
   <div class="center">Top Inline Toolbar</div>
   <div class="left">Label</div>
</ons-toolbar>
<ons-bottom-toolbar inline>
   <div class="center">Bottom Inline Toolbar</div>
   <div class="left">Label</div>
</ons-bottom-toolbar>

Androidの戻るボタンへの対応

Onsen UIではAndroidの戻るボタンにも対応します。アプリがAndroidデバイス上で実行されていて、Cordovaが用いられている場合は、戻るボタンをタップするとナビゲーターのpopPage()メソッドが呼ばれます。

また、iOS端末に限ってツールバーに戻るボタンを表示したい場合は、<ons-if-platform>を使用すると良いでしょう。

<ons-toolbar>
  <div class="left"><ons-back-button ons-if-platform="ios">戻る</ons-back-button></div>
  <div class="center">ページタイトル</div>
</ons-toolbar>

戻るボタンの対応についてより詳細にカスタマイズしたい場合は、戻るボタンへの対応を参照してください。

ナビゲーターのイベント

<ons-navigator>には、特定の操作の際にイベントを発行する仕組みが備わっています。それを用いると、たとえば特定の条件においてはページ遷移をキャンセルするといった処理を記述することができます。

prepushpostpushprepoppostpopの4つのイベントがナビゲーターに定義されています。これらはpushPageもしくはpopPageの前あるいは後に発火され、コールバック関数が呼び出されます。

コールバック関数は、eventオブジェクトを受け取ります。eventオブジェクトでは、下記に説明するいくつかのプロパティとメソッドが提供されます。たとえば、下記のコードはpushPageの実行をキャンセルすることができます。

ons.ready(function() {
  myNavigator.on('prepush', function(event) {
    var page = event.currentPage; // 現在のページオブジェクトを取得する
    if (needsCancel) {
      event.cancel(); // 画面遷移をキャンセルする
    }
  });
});
prepushprepopイベント

prepushは、pushPage、replacePage、resetToPageの前に発火します。prepopは、popPageの前に発火します。 eventオブジェクトには、下記のパラメータが備わっています。

postpushpostpopイベント

postpushは、pushPage、replacePage、resetToPageの後に発火します。postpopは、popPageの後に発火します。 eventオブジェクトには、下記のパラメータが備わっています。

スライディングメニュー

スライディングメニューは2つのページで構成され、それぞれmain-pagemenu-pageという形で指定されます。menu-pageはサイドページとも呼ばれ、通常は隠れており画面端から出現します。ボタンをタップしたり、画面端からスワイプすることで表示することができます。

menu-pageには、任意のHTMLコンテンツを含むことができます。通常は、別のページへのリンクとなるメニュー画面が一般的です。main-pageにはメインコンテンツが表示されます。<ons-navigator>と組み合わせることで、さらに深い階層のページを持つことも可能です。

<ons-sliding-menu>の概要

<ons-sliding-menu>コンポーネントではmain-pagemenu-pageを属性として指定します。また、side属性を用いると、menu-pageを画面のどちら側に設置するかを指定できます。

それぞれのページは、<ons-sliding-menu>タグの下にmenuおよびmainクラスを持った要素を作成することで指定できます。

<ons-sliding-menu>
  <div class="menu">
    <ons-page>
    メニューページの内容
  </ons-page>
  </div>
  <div class="main">
    <ons-page>
    メインページの内容
  </ons-page>
  </div>
</ons-sliding-menu>

もう一つの方法として、下記のようにテンプレートを指定することもできます。

<ons-sliding-menu
  main-page="page1.html"
  menu-page="menu.html"
  side="left"
  var="menu">
</ons-sliding-menu>

<script type="text/ons-template" id="page1.html">
  <ons-page>
    <ons-toolbar>
      <div class="left">
        <ons-toolbar-button ng-click="menu.toggleMenu()"><ons-icon icon="fa-bars"></ons-icon></ons-toolbar-button>
      </div>
      <div class="center">Page 1</div>
    </ons-toolbar>

    <h1 style="text-align: center">Page1</h1>
  </ons-page>
</script>

<script type="text/ons-template" id="page2.html">
  <ons-page>
    <ons-toolbar>
      <div class="left">
        <ons-toolbar-button onclick="menu.toggleMenu()"><ons-icon icon="fa-bars"></ons-icon></ons-toolbar-button>
      </div>
      <div class="center">Page 2</div>
    </ons-toolbar>

    <h1 style="text-align: center">Page2</h1>
  </ons-page>
</script>

<script type="text/ons-template" id="menu.html">
  <ons-list>
    <ons-list-item modifier="chevron" onclick="menu.setMainPage('page1.html', {closeMenu: true})">
      page1.html
    </ons-list-item>
    <ons-list-item modifier="chevron" onclick="menu.setMainPage('page2.html', {closeMenu: true})">
      page2.html
    </ons-list-item>
  </ons-list>
</script>
Run this example.

Click to Load this example.

メニューの表示 / 非表示

<ons-sliding-menu>コンポーネントでは、メニュー開閉のために下記のメソッドを用意しています。それらはopenMenu()closeMenu()そしてtoggleMenu()です。

アニメーション効果を無効にしたい場合は、animationパラメータにnoneを指定してください。

mySlidingMenu.openMenu({
  animation: 'none'
});
背景のタップで非表示にする

<ons-sliding-menu>close-on-tap属性を使用すると、背景をタップするだけでメニューが自動的に非表示になります。

<ons-sliding-menu close-on-tap>
</ons-sliding-menu>

JavaScriptからページを指定する

プログラムからページを指定する場合は、setMainPage()setMenuPage()メソッドを使用します。これらのメソッドでは、2番目の引数にパラメータを指定できます。

スワイプとドラッグの対応

<ons-sliding-menu>コンポーネントにswipeable属性を指定すると、スワイプ操作でメニューを開いたり閉じたりする機能が追加されます。また、この機能を使う場合は、swipe-target-widthmax-slide-distanceもあわせて指定する必要があることに注意が必要です。

コンポーネントにdraggable属性を指定すると、メニューを開いたり閉じたりする操作を、ドラッグ操作で行うことができます。

アニメーションの種類

type属性でアニメーションの種類を指定できます。現在は、reveal(デフォルト)、push、そしてoverlayに対応しています。

スライディングメニューのイベント

スライディングメニューには、preopenpostopenpreclosepostcloseの4種類のイベントに対応します。

<script>
ons.ready(function() {
  mySlidingMenu.on('preopen', function() {
    console.log("メニューページを開きます");
  });
});
</script>
<ons-sliding-menu var="mySlidingMenu">

タブバーを使う

タブバーは<ons-tabbar><ons-tab>コンポーネントを組み合わせて表現します。通常、タブバーは3から5つ程度のアイテムを保有しており、アイコンやラベルで表現できます。各タブバーのアイテムをタップすると、別のページに切り替わります。

<ons-tabbar>の概要

タブバーを設置するには、<ons-tabbar>コンポーネントを使用します。<ons-tabbar>要素の下には、<ons-tab>のみを配置できます。

タブバーアイテムではicon属性とlabel属性が指定できます。アイコンを表示する場合は、<ons-icon>と同様にアイコン名を指定します。

<ons-tabbar>
  <ons-tab page="page1.html" label="Page 1" icon="fa-square" active="true"></ons-tab>
  <ons-tab page="page2.html" label="Page 2" icon="fa-square"></ons-tab>
  <ons-tab page="page3.html" label="Page 3" icon="fa-square"></ons-tab>
  <ons-tab page="page4.html" label="Page 4" icon="fa-square"></ons-tab>
  <ons-tab page="page5.html" label="Page 5" icon="fa-square"></ons-tab>
</ons-tabbar>
Run this example.

Click to Load this example.

タブバーを上部に配置する

デフォルトでは、タブバーは画面下部に配置されます。Android端末のように上部にタブバーを設置するには、position属性にtopを指定します。ただし、この属性は初期化時に指定された場合にのみ適用されます。

<ons-tabbar position="top">
  <ons-tab page="page1.html" label="Page 1" icon="fa-square" active="true"></ons-tab>
  <ons-tab page="page2.html" label="Page 2" icon="fa-square"></ons-tab>
  <ons-tab page="page3.html" label="Page 3" icon="fa-square"></ons-tab>
</ons-tabbar>

ツールバーが配置されているページにタブバーを設置すると、ツールバーの下部に配置されます。

<ons-page>
  <ons-toolbar>
    <div class="center">Page Title</div>
  </ons-toolbar>
  <ons-tabbar position="top">
    <ons-tab page="page1.html" icon="fa-square"></ons-tab>
    <ons-tab page="page2.html" icon="fa-square"></ons-tab>
    <ons-tab page="page3.html" icon="fa-square"></ons-tab>
  </ons-tabbar>
</ons-page>
Run this example.

Click to Load this example.

タブのカスタマイズ

タブの見た目をカスタマイズするためには、<ons-tab>の属性を使用します。

ラベルとアイコンを表示する

タブにラベルとアイコンを表示するには、label属性とicon属性を指定します。

<ons-tab label="Label" icon="fa-square"></ons-tab>
任意のコンテンツを表示する

<ons-tab>内に任意のHTMLを記述することもできます。

<ons-tabbar>
  <ons-tab page="home.html">
    <p>Home</p>
  </ons-tab>
  <ons-tab page="friends.html">
    <p>Friends</p>
  </ons-tab>
</ons-tabbar>

ただし、labelicon属性がすでに指定されている場合は、子要素は適用されないので注意してください。

アクティブと非アクティブ時のコンテンツを切り替える

タブがアクティブの時と非アクティブの時でコンテンツを切り替えることができます。そのためには、ons-tab内にons-tab-activeons-tab-inactive属性を持つ要素を定義してください。

<ons-tab page="page.html">
  <div ons-tab-active>
    <!-- active時のみ表示されるコンテンツ -->
  </div>
  <div ons-tab-inactive>
    <!-- inactive時のみ表示されるコンテンツ -->
  </div>
</ons-tab>
タブの切り替え時に再読み込みを行わない

<ons-tab>コンポーネントのpersistent属性を使用すると、ユーザーがタブを切り替えたときにタブの内容がリロードされなくなります。コンテンツを動的に切り替えたい場合に使用してください。タブが変更されたことを知るには、postchangeイベントを使用すると良いでしょう。

タブバーアイテムの管理

タブバーには、ページ管理をより詳細に行うためのJavaScript APIが用意されています。これらのAPIを呼び出すには、JavaScriptからコンポーネントのAPIを呼び出すを参考にvar属性を使用する必要があります。

アクティブなタブを設定する

setActiveTab(index, options)メソッドを使うと、指定したページを表示できます。indexパラメータにはタブページのインデックスを指定し、一番左は0になります。また、optionsには、下記のプロパティを指定して挙動を変更できます。

現在のアクティブなタブを取得する

getActiveTabIndex()メソッドは、アクティブタブのインデックス番号を取得します。アクティブタブがない場合は、-1を返します。

アクティブなタブを変更しないでページを表示する

インデックスを変更せずにページの読み込みを行う場合は、loadPage()メソッドを使用します。

tabbar.loadPage('newpage.html');

ただし、この場合はprechangeおよびpostchangeイベントは発生しないので注意してください。

タブバーのイベント

<ons-tabbar>prechangepostchangeイベントを持ちます。これらのイベントは、ページが切り替わる前もしくは後に実行されます。イベントで使用できるパラメータは下記の通りです。

イベントをキャンセルする場合は、prechangeイベントオブジェクトのcancel()メソッドを呼び出します。

tabbar.on('prechange', function(event) {
  event.cancel();
});

リストを使う

リストは多用されるUIパターンで、ビューに複数のコレクションを表示するときに使用します。Onsen UIでは、<ons-list><ons-list-item>コンポーネントを用いて表現します。

<ons-list>の概要

リストを作成するには、<ons-list><ons-list-item>コンポーネントを使用します。また、<ons-list-header>を用いると、リスト要素のヘッダーを表現できます。

基本的なリスト

下記に、<ons-list>の例を掲載します。

Run this example.

Click to Load this example.

右矢印付きのリスト

<ons-navigator>と共に使用し、画面遷移を行う場合に使用します。

Run this example.

Click to Load this example.

フォームと共に使用する

リストは設定ページ等でも良く用いられます。下記に、フォームの要素と組み合わせた例を掲載します。

Run this example.

Click to Load this example.

レイジーリピート(無限スクロール)を使う

ons-lazy-repeatコンポーネントを使うと、DOMには見えている範囲の項目だけが読み込まれます。項目が見えない状態では、DOMから自動的に取り除かれます。ons-lazy-repeatを使うと、パフォーマンスが低下することなく、何百万もの要素を表示することができます。

Run this example.

Click to Load this example.

レイジーリピートのデリゲートを準備する

ons-lazy-repeatを使用するためには、リストの情報を持つデリゲートオブジェクトを作成する必要があります。

AngularJSを用いてデリゲートを作成する

デリゲートオブジェクトは、ビューからアクセスするためにリストと同じコントローラのスコープに作成します。以下は、MyDelegateという名前のデリゲートオブジェクトを作成した例です。

$scope.MyDelegate = {
  configureItemScope: function(index, itemScope) {
    console.log(index + "番目の要素を作成します");
    itemScope.item = {
      name: '要素 No.' + (index + 1)
    };
  },
  calculateItemHeight: function(index) {
    return 40;
  },
  countItems: function() {
    return 10000000;
  },
  destroyItemScope: function(index, scope) {
    console.log("要素No. " + index + "を削除します");
  }
};
jQueryを用いてデリゲートを作成する
var MyDelegate = {
  createItemContent: function(index, oldContent) {
    console.log(index + "番目の要素を作成します");

    var $element = $("<span>要素 No."+(index+1)+"</span>");
    return $element[0];
  },
  calculateItemHeight: function(index) {
    return 40;
  },
  countItems: function() {
    return 10000000;
  },
  destroyItemContent: function(index, element) {
    console.log("要素 No." + index + "を削除します");
  }
}

レイジーリピート機能をタグに付与する

ons-lazy-repeatは属性として汎用的に使用できます。今回はons-list-itemに使用しますが、高さの計算ができる他のタグ(<div>タグなど)であれば、すべてのタグに使用できます。ons-lazy-repeatをタグに付与するには、下記の例のようにデリゲートを指定します。

AngularJSを使用する場合、通常通りitemプロパティにアクセスすることができます。

<ons-list>
  <ons-list-item ons-lazy-repeat="MyDelegate">
    {{ item.name }}
  </ons-list-item>
</ons-list>

AngularJSを使用しない場合、コンテンツはcreateItemContentメソッドで生成されます。そのため、ビューには何も記述する必要がありません。

<ons-list>
  <ons-list-item ons-lazy-repeat="MyDelegate">
  </ons-list-item>
</ons-list>

非同期で内容を生成する

ons-lazy-repeatを使うと、非同期で呼び出して生成するコンテンツを要素として表示することができます。これは、HTTPリクエストやデータベースから値を取得して表示するときに便利です。この実装を行う場合、リクエストの呼び出しが完了する前に要素が破棄された場合は、リクエストをキャンセルする必要があることに注意が必要です。

AngularJSを用いた書き方
configureItemScope: function(index, itemScope) {
  if (!itemScope.item) {
    itemScope.canceler = $q.defer();
    itemScope.item = {
      title: 'Item #' + (index + 1),
      label: '',
      desc: '',
      rand: Math.random()
    };

    $http.get('https://baconipsum.com/api/?type=meat-and-filler&sentences=1', {timeout: itemScope.canceler.promise})
    .success(function(data) {
      itemScope.item.desc = data[0];
      itemScope.item.label = data[0].substr(0, data[0].indexOf(" ")) + 'bacon';
    })
    .error(function() {
      itemScope.item.desc = 'No bacon lorem ipsum';
      itemScope.item.label = 'No bacon';
    });

  }
},
destroyItemScope: function(index, itemScope) {
  itemScope.canceler.resolve();
}
Run this example.

Click to Load this example.

AngularJSを使わない書き方
createItemContent: function(index, oldContent) {
  if (oldContent) {
    return oldContent;
  }

  var $element = $("<div><span style='opacity: 0.7;'><ons-icon icon='fa-spinner' spin='true'></ons-icon> Loading bacon...</span></div>");

  var request = $.getJSON('https://baconipsum.com/api/?type=meat-and-filler&sentences=1&callback=?', function(data) {
    $element.text(data[0]);
  });

  $element.data('request', request);
  return $element[0];
},
destroyItemContent: function(index, element) {
  var request = $element.data('request');
  request.abort();
}
Run this example.

Click to Load this example.

アラートダイアログを使う

Onsen UIでは、3種類の汎用的なアラートダイアログを簡単に表示することができます。また、<ons-alert-dialog>コンポーネントを用いてカスタムなアラートダイアログを用事することもできます。

Run this example.

Click to Load this example.

アラートダイアログを簡単に表示するために、下記の関数を用意しています。

カスタムなアラートダイアログを表示する

<ons-alert-dialog>コンポーネントを使うと、自由にデザインしたアラートダイアログを表示できます。下記の例は、スタイルを修正したダイアログの例です。

<ons-template id="alert-dialog.html">
<ons-alert-dialog var="alertDialog">
  <div class="alert-dialog-title"><strong style="color: #ff3333">深刻な問題が発生しました</strong></div>
  <div class="alert-dialog-content">
    エラーが発生しました。
  </div>
  <div class="alert-dialog-footer">
    <button class="alert-dialog-button" ng-click="alertDialog.hide(); alertDialog.show()">OK</button>
  </div>
</ons-alert-dialog>
</ons-template>

<script>
ons.ready(function() {
  ons.createAlertDialog('alert-dialog.html').then(function(alertDialog) {
    alertDialog.show();
  });
});
</script>
Run this example.

Click to Load this example.

上記の例のように、カスタムなアラートダイアログを表示する場合は、ons.createAlertDialog()関数を使用し、その関数の引数にテンプレートを指定します。テンプレートには<ons-alert-dialog>タグが含まれている必要があります。

ons.createDialog()関数が呼ばれると、Promiseオブジェクトを作成しAlertDialogViewオブジェクトを返します。AlertDialogViewオブジェクトの使い方については、 in <ons-dialog>コンポーネントのDialogViewオブジェクトを使うを参照してください。

ダイアログを使う

<ons-dialog>コンポーネントを使うと、汎用的なダイアログを表示できます。

ダイアログを表示する

ダイアログを表示するには、<ons-dialog>タグを持つテンプレートを作成し、そのテンプレートをons.createDialog()関数で指定します。この関数は戻り値としてPromiseオブジェクトを返し、そのコールバック関数を通じてDialogViewオブジェクトを渡します。ダイアログを表示するには、このDialogViewオブジェクトのshow()メソッドを呼ぶ必要があります。

<ons-template id="dialogcontent.html">
  <ons-dialog>
    HTMLコードを記述します
  </ons-dialog>
</ons-template>
<script>
ons.ready(function() {
  ons.createDialog('dialogcontent.html').then(function(dialog) {
    dialog.show();
  });
});
</script>
Run this example.

Click to Load this example.

ons.createDialog() メソッドには、optionsオブジェクトも渡すことができます。 その中のoptions.parentScopeパラメータでは、ダイアログ内のスコープが継承するスコープオブジェクトを指定することができます。

angular.module('myApp').controller('MyController', function($scope) {
  ons.ready(function() {
    ons.createDialog('dialog.html', {parentScope: $scope}).then(function(dialog) {
      $scope.dialog = dialog;
    });
  });

  // この変数は、ダイアログのスコープ内でも使えるようになります。
  $scope.myVariable = 'Hello!';
});

DialogViewオブジェクトを使う

DialogViewオブジェクトを通じて、ダイアログの操作や情報を取得できます。下記のメソッドを有しています。

ダイアログのイベントを扱う

ダイアログの表示や非表示の際に、コールバック関数を指定できます。具体的にはshow()hide()メソッドを呼ぶ際に、callbackパラメータで指定します。

また、<ons-dialog>および<ons-alert-dialog>コンポーネントでは、下記のイベントを受け取ることもできます。

カルーセルを使う

カルーセルを使うと、複数の要素を1つの要素の中に表示できます。カルーセルは全画面で表示したり、他の要素の中に組み込むことができます。

それぞれのカルーセルアイテムは<ons-carousel-item>コンポーネントで表現されます。<ons-carousel>コンポーネントは、複数の<ons-carousel-item>コンポーネントを格納するコンテナの役割を持ちます。

全画面のカルーセルを表示する

全画面のカルーセルを表示するには、<ons-carousel>コンポーネントにfullscreen属性を指定します。

<ons-carousel fullscreen swipeable overscrollable auto-scroll>
  <ons-carousel-item>
     カルーセルアイテム1
  </ons-carousel-item>
  <ons-carousel-item>
     カルーセルアイテム2
  </ons-carousel-item>
</ons-carousel>
Run this example.

Click to Load this example.

ページ内にカルーセルを表示する

カルーセルを他のコンポーネントの内部に表示する場合は、CSSを用いてその高さと幅を指定します。幅が指定されていない場合は、100%を指定したものとして扱われます。

<ons-carousel style="height: 200px; width: 50%" swipeable overscrollable auto-scroll>
  <ons-carousel-item>
     カルーセルアイテム1
  </ons-carousel-item>
  <ons-carousel-item>
     カルーセルアイテム2
  </ons-carousel-item>
</ons-carousel>

カルーセル上に別のコンテンツを表示する

インディケーター付きのカルーセルを表示する場合など、<ons-carousel>コンポーネント上に何かの内容を表示したい場合があります。<ons-carousel-cover>コンポーネントを用いると、カルーセル上に必ず表示されるコンテンツを設置できます。

カルーセルのカスタマイズ

<ons-carousel>をカスタマイズすることで、様々な挙動を変更することができます。

カルーセルの初期表示アイテムを指定する

initial-index属性を使うと、最初に表示されるアイテムを番号で指定できます。インデックス番号は0から開始します。

<ons-carousel style="height: 100px; width: 100px" initial-index="1" swipeable overscrollable auto-scroll>
  <ons-carousel-item>
     カルーセル要素1
  </ons-carousel-item>
  <ons-carousel-item>
     カルーセル要素2
  </ons-carousel-item>
</ons-carousel>
Run this example.

Click to Load this example.

スクロール方向を変更する

カルーセルは左右もしくは上下にスクロールを切り替えられます。スクロール方向を切り替えるには、direction属性を使用します。値には、horizontal(デフォルト)もしくはverticalを指定できます。

オーバースクロール時のアニメーションを指定する

カルーセルのアイテムがオーバースクロールした際には、バウンドするアニメーションを付けることができます。この効果を設置するには、overscrollable属性を指定します。

複数の要素を表示する

item-widthもしくはitem-height属性を指定すると、複数のカルーセルアイテムが表示された状態となります。item-width属性はdirection属性がhorizontalの場合、item-heightverticalが指定された場合に適用されます。デフォルトでは100%と解釈されるため、カルーセル内には1つのアイテムだけが表示されます

Run this example.

Click to Load this example.

他のオプション

他にも、下記のようなオプションを用いて、挙動を変更することができます。

カルーセルをJavaScriptで制御する

カルーセルはJavaScriptから制御することもできます。そのためには、<ons-carousel>var属性を指定して、カルーセルのメソッドを呼び出します。

アイテムをスクロールする

カルーセルの各アイテムをスクロールするには、下記のメソッドを使用します。

すべてのメソッドはoptionsパラメータを指定できます。このパラメータでは、animationおよびcallbackプロパティを渡すことができます。

myCarousel.next({
  animation: "none",
  callback: function() {
    // スクロールが完了したときに実行される
  }
});
カルーセルアイテムをJavaScriptで追加する

<ons-carousel-item>コンポーネントを<ons-carousel>コンポーネントに追加した場合は、refresh()メソッドを読んでレイアウトを更新する必要があります。

カルーセルのイベントを扱う

<ons-carousel>コンポーネントでは、下記のイベントを扱うことができます。

モーダルを使う

<ons-modal>コンポーネントを使うと、モーダル画面が表示されている間は外の入力操作を禁止することができます。プログレスバーを表示したり、ユーザーの選択を確実に行う場合などに使用されます。

<ons-modal>コンポーネント内には自由にHTMLを記述できます。その内容は、toggle()show()メソッドを呼び出すことで表示されます。

Run this example.

Click to Load this example.

ポップオーバーを使う

ポップオーバーは、画面上にポップアップされて表示されるコンポーネントです。<ons-popover>コンポーネントを用いてポップオーバーを表示できます。

Run this example.

Click to Load this example.

ポップオーバーを表示する

ポップオーバーを表示するには、<ons-popover>タグを用いてHTMLを記述し、そのポップオーバーをons.createPopover()関数を呼び出します。

ポップオーバーを表示する例は下記の通りです。

<ons-template id="popover.html">
  <ons-popover
  style="height: 200px; width: 200px"
  animation="fade">
      <ons-page>
        ポップオーバーの内容
      </ons-page>
  </ons-popover>
</ons-template>
<script>
ons.ready(function() {
  var targetElement = document.getElementById("myButton");
  var popover = ons.createPopover('popover.html')
  .then(function(popover) {
      popover.show(targetElement);
    });
});
</script>

ons.createPopover()メソッドには、optionsオブジェクトも渡すことができます。 その中のoptions.parentScopeパラメータでは、ポップオーバー内のスコープが継承するスコープオブジェクトを指定することができます。

angular.module('myApp').controller('MyController', function($scope) {
  ons.ready(function() {
    ons.createPopover('popover.html', {parentScope: $scope}).then(function(popover) {
      $scope.popover = popover;
    });
  });

  // この変数は、ポップオーバーのスコープ内でも使えるようになります。
  $scope.myVariable = 'Hello!';
});

ons.createPopover()関数が呼ばれると、下記のメソッドを持つPopoverViewオブジェクトがPromise形式で返されます。

ポップオーバーのカスタマイズ

<ons-popover>のカスタマイズには、下記の属性を使用できます。

外見を変更する

modifierを用いると、ポップオーバーのデザインを変更できます。ポップオーバーでは、標準でandroidおよびiosに対応しています。独自のCSSスタイルを適用したい場合は、modifier属性に任意の名前を指定します。

Run this example.

Click to Load this example.

開く方向を指定する

ポップオーバーの開き方を変更するには、direction属性を指定します。方向には、updownleftもしくはrightから1つ、もしくは複数の方向を空白区切りで指定できます。direction属性が指定されない場合は、最適な方向で開きます。

ポップオーバーのイベントを扱う

<ons-popover>には下記のイベントが提供されます。

プルフックを使う

プルフックコンポーネントは、<ons-page><ons-scroller>コンポーネントに対して「Pull-To-Refresh(引っ張って更新する)」機能を提供するものです。外部ソース(データベース、RSSフィードやWeb APIなど)からデータを取得する場合に、この機能を便利に活用することができます。

Run this example.

Click to Load this example.

プルフックを表示する

プルフックコンポーネントを表示するには、<ons-pull-hook>タグを使用します。

<ons-pull-hook ng-action="load($done)" var="loader">
  <span ng-switch="loader.getCurrentState()">
    <span ng-switch-when="initial"><ons-icon size="35px" icon="ion-arrow-down-a"></ons-icon> 更新するにはプルダウンしてください</span>
    <span ng-switch-when="preaction"><ons-icon size="35px" icon="ion-arrow-up-a"></ons-icon> 手をはなしてください</span>
    <span ng-switch-when="action"><ons-icon size="35px" spin="true" icon="ion-load-d"></ons-icon> データを読み込んでいます...</span>
  </span>
</ons-pull-hook>

プルフックの動作はng-action="load($done)"もしくはon-action="load(done)"属性にて指定します。指定した関数は、プルダウンされて、手を離したときに呼び出されます。

プルフックは3つの状態を持ち、それぞれ見た目をカスタマイズすることができます。

プルフックのアクション

<ons-pull-hook>コンポーネントには、実行する動作を定義するための属性としてng-actionon-actionが用意されています。

プルフックの高さパラメータ

<ons-pull-hook>コンポーネントには、プルダウンしたときのしきい値を指定するための属性を指定できます。

フォームを使う

Onsen UIでは、フォームを構築するための様々なコンポーネントを用意しています。

ボタン

<ons-button>を用いて、さまざまな種類のボタンを表現できます。外見や挙動の変更には、modifiershould-spinanimationそしてdisabled属性で指定します。特にmodifier属性を使用すると、あらかじめ定義されたいくつかの外見に合わせて見た目を変更できます。

タップされた場合の処理を記述するには、onclickもしくはng-click属性を使用します。

Run this example.

Click to Load this example.

スイッチ

スイッチを表示するには、<ons-switch>を使用します。スイッチにはONとOFFの状態があり、その状態はisChecked()メソッドで取得できます。

<script>
function changed() {
  alert(mySwitch.isChecked() ? 'ON' : 'OFF');
}
</script>
<ons-switch var="mySwitch" onchange="changed()"></ons-switch>

テキスト入力

テキスト入力のためのコンポーネントはカスタムエレメント形式ではなく、あらかじめ定義されたクラス名を指定することでOnsen UIの外見に合わせることができます。

どの場合においても、document.getElementById()やjQueryのセレクターを用いて、その値を取得できます。

alert(document.getElementById("my-input").value);
alert($("#my-input").val());
Run this example.

Click to Load this example.

チェックボックスとラジオボタン

チェックボックスとラジオボタンはCSSコンポーネントとして提供されます。下記のようにして、それぞれのコンポーネントを表示できます。

<label class="checkbox">
  <input type="checkbox">
  <div class="checkbox__checkmark"></div>
  <span class="ons-checkbox-inner"></span>
</label>
<label class="radio-button">
  <input type="radio">
  <div class="radio-button__checkmark"></div>
</label>

レイアウト調整

Onsen UIのグリッドシステムを使うと、手軽にコンポーネントを画面上に配置できます。グリッドシステムは、表計算ソフトのように、画面を行と列に分割します。各グリッドの幅と高さは調整することができ、複数のグリッドを1つに結合することもできます。

<ons-row><ons-col>の概要

レイアウトの調整は、<ons-row><ons-col>コンポーネントを使用します。横幅と高さは柔軟に調整できます。

デフォルトでは、<ons-row>コンポーネント内にあるすべての<ons-col>コンポーネントは、同じ幅で表現されます。<ons-col>要素に対しては、個別に横幅を指定することができます。

<ons-row>にはalign属性を、<ons-col>にはalignsizeoffset属性を指定できます。size属性については、pxもしくは%で指定できます。

レイアウトの例

下記の例では、<ons-row><ons-col>を用いて様々なレイアウトを表現しています。

Run this example.

Click to Load this example.

アイコンを使う

Onsen UIは、Font Awesomeの400以上のアイコン、そしてIoniconsの500以上のアイコンを使うことができます。

<ons-icon>の概要

アイコンを表示するには、<ons-icon>コンポーネントを使用します。表示するアイコンは、icon属性で指定します。

Font Awesomeアイコンを使用する

icon属性の値がfa-で始まっている場合は、Font Awesomeのアイコンセットが使用されます。利用可能なアイコンの一覧は、Font AwesomeのWebサイトにて確認できます。また、icon属性に接頭辞が付与されていない場合にも、Font Awesomeのアイコンセットが使用されます。

Ioniconsアイコンを使用する

iconの値がion-で始まっている場合は、Ioniconsアイコンセットが使用されます。利用可能なアイコンの一覧は、IoniconsのWebサイトを参照してください。

下記にいくつかの例を紹介します。

<ons-icon icon="fa-angle-left"></ons-icon>
<ons-icon icon="fa-angle-left" size="40px"></ons-icon>
<ons-icon icon="fa-angle-left" size="40px" rotate="90"></ons-icon>
<ons-icon icon="fa-angle-left" spin="true"></ons-icon>

アイコンの大きさはsize属性で指定できます。

<ons-icon icon="fa-angle-left" size="40px">

アイコンを回転させることもできます。

<ons-icon icon="fa-angle-left" size="40px" rotate="90deg">

アイコンにアニメーションを適用することも可能です。スピナー画像等の表示に有効です。

<ons-icon icon="fa-angle-left" spin="yes">
Run this example.

Click to Load this example.

マルチスクリーンへの対応

Onsen UIはレスポンシブデザインに対応しているため、スクリーンサイズに応じてCSSスタイルの適用を切り替えることができます。ここではCSSメディアクエリーを用いる方法について紹介します。

また、Onsen UIではスプリットビューというコンポーネントも提供します。このコンポーネントを用いると、横向きや大画面のデバイスでは2カラムのレイアウトを、それ以外の場合は1カラムのレイアウトに自動的に切り替えます。CSSスタイルを定義することなく、スマートフォンとタブレットの両方に対応したアプリを簡単に開発できます。

CSSメディアクエリーの概要

CSSメディアクエリーを用いることで、画面サイズやアスペクト比、解像度などに応じてCSS定義を切り替えることができます。

下記のCSSメディアクエリーは画面サイズに応じてCSSの定義を切り替える例となります。

<style>
@media (min-width:320px) { /* スマートフォン、iPhoneなど */ }
@media (min-width:641px) { /* iPad縦、大きな画面を持つスマートフォンなど */ }
@media (min-width:961px) { /* タブレットやiPad横向きなど */ }
@media (min-width:1025px) { /* より大きな画面サイズ */ }
@media (min-width:1281px) { /* デスクトップや高解像度のデバイス */ }
</style>
Run this example.

Click to Load this example.

<ons-split-view>コンポーネントを使う

<ons-split-view>コンポーネントを用いると、画面を2分割して別々のページを表示することができます。

また、画面サイズが小さい時にはサイドページを非表示にすることができます。そうすることで、スマートフォンとタブレットの両方の端末に簡単に対応できます。

<ons-split-view>コンポーネントでは下記の属性が提供されます。

Run this example.

Click to Load this example.

サイドページの非表示設定

<ons-split-view>collapse属性を用いて、サイドページを非表示にする条件を指定できます。この属性が取り得る値として、portraitlandscapeもしくはwidth ##px(例width 300px)などの指定方法があります。たとえば、portraitが指定されていて、かつ、端末が縦向きの画面になっていた場合は、サイドページは非表示になります。

読み込み中画面を表示する

Onsen UIが必要なフレームワーク一式の読み込みを完了するまで、読み込み中画面を表示することができます。これはOnsen UIをWebアプリケーションで使用する場合に便利です。ons-loading-placeholder属性を持つ要素は、Onsen UIの読み込みが完了した時点で、ons-loading-placeholder要素が参照するテンプレートに置き換わります。

<body>
  <div ons-loading-placeholder="start.html">
     アプリケーションの読み込みを行っています...
  </div>
  <ons-template id="start.html">
    <div>アプリケーションへようこそ!</div>
  </ons-template>
</body>

ユーティリティAPI

ほかにも、Onsen UIを用いた開発をしやすくするためのユーティリティAPIも提供しています。

ons.ready関数

ons.ready()関数は、Onsen UIの初期化が完了したときに呼ばれます。CordovaやPhoneGapが使われている場合は、デバイスの初期化(ondevicereadyイベント)の後に実行されます。

この関数を用いると、ページ読み込み中のブランクスクリーンを表示せずに、スプラッシュ画面を動的に非表示にすることができます。たとえば、下記の例はOnsen UIの読み込みが完了するまで、スプラッシュスクリーンを表示したままにするコードとなります。

ons.ready(function() {
  // Onsen UIが読み込み終わるまでスプラッシュ画像を表示したままにする
  // APIリファレンス: https://github.com/apache/cordova-plugin-splashscreen/blob/master/doc/index.md
  navigator.splashscreen.hide()
});

ons.bootstrap関数

ons.bootstrap()関数を用いると、1行でOnsen UIの読み込みを行います。この関数は、AngularJSにOnsen UIのモジュールを追加し、どのスコープからでもOnsen UIを呼び出せるようにします。onsenui.jsの読み込みが完了した後に呼び出してください。

たとえば、下記のコードはOnsen UIと共にngAnimateモジュールを読み込みます。引数には、読み込みたいモジュールの一覧を指定できます。 ons.bootstrap()関数の引数では、読み込みたいAngularJSのモジュールを配列形式で指定できます。

<script>
  var module = ons.bootstrap(['ngAnimate']); // ngAnimateモジュールも読み込む
  module.controller("TopController", function($scope){ });
</script>

ons.bootstrap()関数を使用する際は、モジュール名を指定することもできます。

<script>
  ons.bootstrap('myApp', ['ngAnimate']); // Optionally loading ngAnimate module
  angular.module('myApp').controller("TopController", function($scope){ });
</script>

よりAngularJSに準拠した記述で表記する場合は、onsenモジュールを読み込みます。

<script>
  // 'ng-app'が'my-app'と定義されている場合の例
  var module = angular.module('my-app', ['onsen']);
  module.controller('AppController', function($scope) { });
  module.controller('PageController', function($scope) {
    ons.ready(function() {
      // 初期化コードをここに記述します
    });
  });
</script>

ons.compile関数

ons.compile()関数は、Onsen UIコンポーネントが含まれているDOM要素をコンパイルするために使用します。JavaScriptでHTMLを組み立て、描画するときに使用します。

なお、ons.compile()関数の引数には、HTMLElementオブジェクトを指定する必要があります。また、指定する要素は、ons.compile()関数を呼び出す前にDOMツリー上に配置されていいなければなりません。下記の例を参照してください。

ons.ready(function() {
  var elm = $("<ons-button>新規ボタン</ons-button>");
  elm.appendTo($("body")); // DOMツリーに追加する
  ons.compile(elm[0]); // 引数はHTMLElementオブジェクトとして指定する
});

ons.disableAutoStatusBarFill関数

iOS 7以降では、ステータスバーをWebViewの上に重ねることができます。Onsen UIでは、自動的にその余白を作り、アプリの表示領域の最適化を行います。ただし、CordovaのStatusBarプラグインを用いる場合などにおいては、ユーザーがステータスバーの配置を制御することができるため、必ずしもこの余白が必要ではありません。

Onsen UIでは余白の制御を行うために、ons.enableAutoStatusBarFill関数およびons.disableAutoStatusBarFill関数を提供しています。デフォルトでは、余白制御が有効になっています。変更する場合は、Onsen UIの初期化が完了する前(ons.ready()イベントが呼ばれる前)に関数を呼び出してください。

/**
 * Onsen UI初期化中にコールする必要があります
 */

// 余白制御を無効にする
ons.disableAutoStatusBarFill();

// 余白制御を有効にする
ons.enableAutoStatusBarFill();

ons.ready(function() { });

プラットフォームの判定

<ons-if-platform>属性を用いるか、ons.platformオブジェクトを用いて、特定のプレットフォームに応じたコンテンツのだし分けを記述できます。

<ons-if-platform>属性を使うと、特定の要素に対してプラットフォーム別の出し分けを記述できます。

<div ons-if-platform="ios">iPhoneとiPadユーザーだけのコンテンツ</div>

また、ons.platformオブジェクトを用いると、JavaScriptコードでプラットフォームの判定が行えます。

画面向きの判定

ons-if-platform属性と同様、<ons-if-orientation>属性を用いると、画面の向きに応じて画面表示を切り替えられます。

<div ons-if-orientation="portrait">縦向きの時だけ表示するコンテンツ</div>

ジェスチャーの対応

ジェスチャーを検知して特定の処理を行わせることができます。Onsen UIでは、ジェスチャーの認識にHammer.jsを使用しています。

ジェスチャーを検知するには、対象となるDOM要素を<ons-gesture-detector>コンポーネントで囲みます。たとえば、下記は特定の場所に対して左スワイプの検知を有効にした例となります。

<ons-gesture-detector>
  <div id="detect-area" style="width: 100px; height: 100px;">
    ここをスワイプ
  </div>
</ons-gesture-detector>
<script>
  $(document).on('swipeleft', '#detect-area', function() {
    console.log("左スワイプが検知されました");
  })
</script>

AngularJS方式で記述する場合は、ng-ジェスチャーイベント名属性を使用します。

<ons-gesture-detector ng-swipeleft="doSomething()">
  <div id="detect-area" style="width: 100px; height: 100px;">
    ここをスワイプ
  </div>
</ons-gesture-detector>

対応するジェスチャー

下記のジェスチャーに対応しています。

ソフトキーボードの対応

ソフトウェアキーボードの状態に応じて、特定のコードを実行したり、見た目を切り替えたい場合があります。Onsen UIでは、Cordova Keybord PluginもしくはIonic Keyboard Pluginを組み込んだ場合に、キーボードイベントを検知することができます。

<ons-keyboard-active>もしくは<ons-keyboard-inactive>属性を用いると、キーボードの状態に応じてコンテンツのだし分けを行うことができます。

<div ons-keyboard-active>
  キーボードが表示されている時に表示されるコンテンツです。
</div>
<div ons-keyboard-inactive>
  キーボードが隠れている時に表示されるコンテンツです。
</div>

JavaScriptでキーボードの状態を取得するには、ons.softwareKeyboardオブジェクトを使用できます。

// CordovaとIonic Keyboard Pluginの両方に対応しています
ons.softwareKeyboard.on('show', function() {
  // キーボードが表示された場合の処理
});
ons.softwareKeyboard.on('hide', function() {
  // キーボードが隠れた場合の処理
});

戻るボタンの対応

Androidはハードウェアの戻るボタンが備わっています。Onsen UIでは、戻るボタンがクリックされたときの挙動をカスタマイズすることができます。

端末の戻るボタンに対応するためには、<ons-page>コンポーネントのon-device-backbuttonもしくはng-device-backbutton属性を使用します。下記は、ons-pageの属性に戻るボタンのハンドラーを定義した例となります。

<ons-page on-device-backbutton="doSomething()">
  ページのコンテンツ
</ons-page>

AngularJS形式で記述すると、下記のようになります。

<ons-page ng-device-backbutton="doSomething()">
  ページのコンテンツ
</ons-page>

もしくは、ons-pageのAPIを用いて、下記のように戻るボタンのハンドラーを定義することもできます。

<ons-page var="myPage">...</ons-page>
<script>
  ons.ready(function() {
    myPage.setDeviceBackButtonHandler(function() {
      // ここに処理の内容を記述する
    });
    // 戻るボタンのハンドラーを取得して無効化する
    var handler = myPage.getDeviceBackButtonHandler();
    handler.disable();
  });
</script>

デフォルトのコンポーネントハンドラーを上書きする

ons-pageコンポーネントだけでなく、ons-navigatorons-sliding-menuコンポーネントについは、デフォルトで戻るボタンのハンドラーが定義されています。たとえば、ons-navigatorでは、戻るボタンが押された場合は、popPage()を実行します。この仕組みを無効にしたり、挙動を変更したい場合は、getDeviceBackButtonHandler() APIを使用します。

// ナビゲーターの戻るボタンを無効化する
navigator.getDeviceBackButtonHandler().disable();

// もしくは、挙動を変更する
navigator.getDeviceBackButtonHandler().setListener(function(event) {});

// もしくは、再度有効にする
navigator.getDeviceBackButtonHandler().enable();

この通り、getDeviceBackButtonHandler() APIが戻すオブジェクトは、disable()enable()isEnabled()そしてsetListener(fn)メソッドを有しています。

親のイベントハンドラーに処理を委譲する場合は、callParentHandler()メソッドを呼び出します。もしコンポーネントのハンドラーが定義されていなかったり、無効化されている場合は、親のイベントハンドラーが自動的に呼び出されます。

myPage.getDeviceBackButtonHandler().setListener(function(event) {
  // 親のイベントハンドラーを呼び出す
  event.callParentHandler();
});

デフォルトのアプリハンドラーを上書きする

Onsen UIアプリでは、デフォルトで戻るボタンが押されると、アプリを閉じる挙動を行います。これは、ほかのAndroidアプリと同じ挙動になります。

デフォルトの挙動を変更するには、ons.setDefaultDeviceBackButtonListener関数を呼び出します。下記のコードは、アプリを閉じる前に確認を行う例となります。

ons.setDefaultDeviceBackButtonListener(function() {
  if (navigator.notification.confirm("本当に閉じてもいいですか?",
    function(index) {
      if (index == 1) { // OKボタンが押された
        navigator.app.exitApp(); // アプリを閉じる
      }
    }
  ));
});

戻るボタンの処理を無効化する

Onsen UIの戻るボタンの処理を完全に無効化するには、ons.disableDeviceBackButtonHandler()関数を呼び出します。これは、CordovaやPhoneGapのイベントを直接扱いたい場合に便利です。

ons.ready(function() {
  ons.disableDeviceBackButtonHandler();

  // Cordovaのハンドラーを使用する
  window.document.addEventListener('backbutton', function() {
    // 戻るボタンが押された時の処理
  }, false);
});

JavaScriptからコンポーネントのAPIを呼び出す

コンポーネントのなかには、JavaScript関数を備えているものがあります。たとえば、ons-navigatorpushPage()popPage()メソッドが用意されており、それぞれページを追加したり削除したりする目的で使用します。

コンポーネントのAPIを呼び出す場合は、JavaScriptコードからコンポーネントを参照します。そのために、コンポーネントのvar属性を指定するか、ons.findComponent()あるいはons.findParentComponentUntil()関数を使用します。

var属性でコンポーネントを指定する

APIを呼び出すには、var属性でコンポーネントを変数に割り当てます。たとえば、下記の例では"myNavigator"という名前の変数でコンポーネントを参照できます。

<ons-navigator var="myNavigator">

これで、myNavigator変数はJavaScriptコードのどこからでもアクセスできるようになりました。より正確には、myNavigatorwindowオブジェクトのプロパティとして、そして、AngularJSのグローバルスコープとして定義されています。

そのため、JavaScriptを直接用いたり、jQueryを使って変数を呼び出す場合は、下記のコードで動作します。

<script>
  myNavigator.pushPage('newpage.html');
</script>

AngularJSを用いる場合は、下記のようにして実行できます。

<script>
  module.controller("PageController", function($scope) {
    ons.ready(function() {
      // Actually myNavigator object sits in the root scope
      $scope.myNavigator.pushPage("newpage.html");
    });
  });
</script>
コンポーネントの基底オブジェクトを変更する

上記の通り、var属性で定義されたコンポーネントは、windowオブジェクトにそのプロパティが作成されます。グローバルスコープの汚染が気になる場合は、対象オブジェクトを変更することができます。

下記の例は、onsenComponentsという名前の変数に、コンポーネントの基底オブジェクトを変更しています。

var onsenComponents;
ons.componentBase = onsenComponents;

こうすることで、下記のようにコンポーネントにアクセスすることができます。

onsenComponents.myNavigator.doSomething();

DOMツリーからコンポーネントを検索する

ons.findComponent()およびons.findParentComponentUntil()関数を使うと、変数を割り当てずにコンポーネントを参照することができます。

ons.findComponent(selector, dom)

ons.findComponent()関数は、渡されたDOM内にあるコンポーネントを検索します。たとえば、idmy-switchons-switchコンポーネントを検索したい場合は、下記のコードを記述します。

var mySwitch = ons.findComponent('ons-switch#my-switch', document.body);
ons.findParentComponentUntil(componentName, element)

ons.findParentComponentUntil()関数は、親DOMノードを探索してコンポーネントを検索します。たとえば、下記の例では、指定したボタンの要素を持つナビゲーターを検索しています。

var currentNavigator = ons.findParentComponentUntil('ons-navigator', buttonDom);

DOM APIの利用

Onsen UIのコンポーネントはCustom Elements形式ではありますが、DOM APIを使って呼び出すこともできます。

<ons-navigator class="myNavigator"></ons-navigator>
<ons-button id="my-ons-button"</ons-button>
<ons-list>
  <ons-list-item class="item1"></ons-list-item>
</ons-list>
<script>
  // DOM APIの利用例
  document.getElementById("my-ons-button");
  // jQueryの利用例
  $("ons-navigator.myNavigator");
  $("ons-list-item.item1");
  $("ons-button").onclick(function() {
    alert("Buttonがクリックされました!");
  });
</script>

イベントの利用

コンポーネントのなかには、イベントに対応したものがあります。イベントを使うと、コンポーネントの挙動を上書きし、挙動をカスタマイズすることができます。

それぞれのコンポーネントがサポートしているイベントの一覧については、コンポーネントのページを参照してください。 <ons-navigator>は、これらのイベントを発します。

イベントにハンドラーを追加するには、コンポーネントのon()off()およびonce()メソッドを使用します。そのために前述の通り、コンポーネントに変数を割り当てる必要があります。

<script>
myNavigator.on("prepush", function() {
  // prepushイベントのハンドラーを記述する
});
</script>

<script>
// on()とoff()メソッドの使用例
var callback = function(event) {
}
myNavigator.on("prepush", callback);
myNavigator.once("prepush", callback);
myNavigator.off("prepush", callback);
</script>

タップとクリックのイベント

コンポーネントに対するアクションとして、最も使われるのはタップの検出です。タップやクリックの検出には、onclickハンドラーを使用します。

<ons-button onclick="alert('タップされました')">ここをタップ</ons-button>

AngularJSのイベント処理に精通している方は、ng-clickハンドラーも使用できます。

<ons-button ng-click="alert('タップされました')">ここをタップ</ons-button>

どちらの場合でも、fastclickライブラリーを用いることで、イベントの検出に300msの遅延は発生しません。そのため、すばやくユーザーの挙動に反応します。

イベントハンドラ属性

コンポーネントのイベントハンドラは、HTML属性を使って追加することもできます。それらの属性は全て、イベント名の前にons-が付いた名前になります。<ons-navigator>の発したprepopイベントを捉えるには、ons-prepop属性を使います。

<ons-navigator ons-prepop="doSomething()">
  ...
</ons-navigator>

属性の値はAngularの式である必要があります。そのため、AngularJSを使用していないときは、これらの属性を使うことはできません。

ページ初期化のイベント

<ons-page>の初期化が完了すると、pageinitイベントが発生します。このイベントを用いて、各ページの挙動を変更してください。

<script>
document.addEventListener("pageinit", function(e) {
  if (e.target.id == "my-page") {
    document.getElementById("my-content").innerHTML = "私は元気です。";
  }
}, false);
</script>

<ons-page id="my-page">
  <div>ようこそ。元気ですか?</div>
  <div id="my-content">ここが変更されます</div>
</ons-page>

コンポーネントのDOMイベント

すべてのコンポーネントは、初期化時にons-component-name:initイベントを発行します。このイベントを用いると、コンポーネントを初期化した直後に特定の処理を記述できます。初期化されたコンポーネントは、コールバック関数にてcomponentプロパティとして取得できます。

$(document).on('ons-navigator:init', '#my-navigator', function(event) {
   var navigator = event.component;
   navigator.pushPage('login.html');
});

他の全てのコンポーネントイベントはDOMイベントとしても発火され、イベント名の前にはコンポーネント名が付きます。このDOMイベントは、コンポーネントイベントの全てのプロパティを継承します。

$(document).on('ons-dialog:preshow', '#my-dialog', function(event) {
  if (dontShowDialog()) {
    event.cancel();
  }
});

コンポーネントのイベント

<ons-navigator><ons-sliding-menu><ons-tabbar>の3コンポーネントはユーザー処理の前後にイベントを提供します。詳細については、各コンポーネントのドキュメントを参照してください。

複数のページを1つのHTMLに記述する

いくつかのコンポーネントは、別のHTMLページを指定する必要があります。たとえば、<ons-sliding-menu>コンポーネントは、下記のように別途定義されたページを指定します。

<ons-sliding-menu
  menu-page="menu.html"
  main-page="content.html">
</ons-sliding-menu>

menu.htmlとcontent.htmlを別ファイルとして作成することなく、同じページでコンテンツを定義することができます。そのためには、<ons-template>タグを使用するか、scriptタグを作成し、そのtype属性を"text/ons-template"と指定します。これはマイクロテンプレーティングとも言われ、ページファイルの数を減らすことができます。

<ons-template>タグを用いてテンプレートを定義する

<ons-template>タグはテンプレートを表します。たとえば、main.htmlという名前を持つHTMLコンテンツを定義するには、下記のように記述します。

<ons-template id="main.html">
  <!-- main.htmlのコードを記述します -->
  <div>
    これはmain.htmlのコンテンツです
  </div>
</ons-template>

<script>タグを用いてテンプレートを定義する

もう一つの方法として、scriptタグを作成し、そのtype属性を"text/ons-template"と指定することができます。 html <script type="text/ons-template" id="main.html"> <!-- main.htmlのHTMLコンテンツを定義します --> <div> これはmain.htmlのコンテンツです </div> </script>

AngularJSの$templateCacheを使用する

上記で定義したテンプレートは、AngularJSのテンプレートキャッシュとしても使用でき、$templateCacheサービスから呼び出せます。詳細は、AngularJSのドキュメントを参照してください。

Modifierを使用する

Modifierを用いると、Onsen UIのコンポーネントの外見を簡単にカスタマイズすることができます。modifier属性が用意されたコンポーネントは、クラス名に任意の名前空間を定義し、カスタムなスタイルを適用することができます。コンポーネントのなかには、あらかじめ定義されたModifierが定義されていることもあります。

たとえば、下記のボタンはそれぞれ異なる外見となります。

<ons-button modifier="quiet">Quiet</ons-button>
<ons-button modifier="light">Light</ons-button>
<ons-button modifier="large">Large</ons-button>
<ons-button modifier="cta">CTA</ons-button>

JavaScriptを用いてModifierを動的に切り替えることもできます。modifier属性を持つすべてのコンポーネントでは、下記のメソッドが提供されます。

Onsen UIコンポーネントのカスタマイズ

Onsen UIコンポーネントには、いくつかのカスタマイズ方法が用意されています。たとえば、ルック&フィールの変更や、コンポーネントのCSSの直接記述、そしてJavaScriptやHTMLコードの変更などです。

ルック&フィールのカスタマイズ

Onsen UIのスタイルはonsenui.cssonsen-css-components.cssという2つのファイルで定義されています。これらのファイルには、コンポーネントのすべての定義が記述されており、ファイルを直接変更することができます。

もしくは、Onsen UIテーマローラーを用いると、自由にカラースキームを変更できます。カスタマイズが完了したら、onsenui-css-components.cssを上書きするだけで変更点を反映できます。

CSSスタイルのオーバーライド

コンポーネントに対して、標準とは別のスタイルを割り当てたい場合があります。こういう場合には、modifier属性を用いることで、スタイル定義をオーバーライドすることができます。

たとえば、特定のボタンに対して太い枠をつけたい場合は、下記のようにしてmodifier属性を定義します。

<ons-button modifier="thick">Thick Button</ons-button>

次にstyleタグなどで、下記のように個別にスタイルを定義します。

<style>
.button--thick {
  border: 10px;
}
</style>

HTMLのカスタマイズ

コンポーネントが持つHTMLをカスタマイズする場合は、AngularJSについて理解する必要があります。AngularJSでは、ディレクティブという機能を用いて、HTMLとJavaScriptを組み合わせて1つのタグを形成します。

各コンポーネントのHTMLコードは、フレームワークのtemplatesディレクトリ以下に配置されます。たとえば、<ons-button>のHTMLコードはframework/templates/button.tplにあります。

<button class="{{item.animation}} button--{{onsType}} effeckt-button button no-select {{modifierTemplater('button--*')}}">
  <span class="label ons-button-inner" ng-transclude></span>
  <span class="spinner button__spinner {{modifierTemplater('button--*__spinner')}}"></span>
</button>

テンプレートファイルを変更したら、Onsen UIをビルドし直す必要があります。なぜなら、すべてのテンプレートはキャッシュされ、framework/directives/templates.jsファイルに格納されているためです。詳しくは、Onsen UIのビルドを参照してください。

JavaScriptコードのカスタマイズ

各コンポーネントのJavaScriptコードは、directivesディレクトリに配置されます。

Onsen UIのビルド

Onsen UIでは、ビルドシステムとしてgulpを使用しています。ビルド方法の詳細については、プロジェクトのWebサイトを参照してください。


お困りですか?

Onsen UIに関する質問は、Stack Overflowにてonsen-uiタグを付与してください。Onsen UIチームはあなたの問題解決をお手伝いします。

バグ報告や機能要望については、GitHub Issuesに記載をお願いいたします。

あわせて、下記の情報も参考にしてください。