Learn How to Use - Onsen UI Framework v1

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>コンポーネントを配置するのが一般的です。ツールバーには、戻るボタンを設置したり、ページタイトルを描画したりします。

Click to Load this example.

Expand/Contract

Open an Example in New Window

新しいページを表示

スタックに新しいページを追加するには、ナビゲーターオブジェクトの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()メソッドでは、下記のアニメーションを選択できます: slide、lift、fade、none。

スライド（タイプ: slide、デフォルト）

アニメーションの表現は、ネイティブ遷移と合わせるためにiOSとAndroidで異なるものとなります。
```
navigator.pushPage("page2.html", { animation: "slide" }):
```
リフトアップ / リフトダウン（タイプ: lift）
```
navigator.pushPage("page2.html", { animation: "lift" }):
```
フェードイン / フェードアウト（タイプ: fade）
```
navigator.pushPage("page2.html", { animation: "fade" }):
```

アニメーションなし（タイプ: none）

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

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

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

ページスタックの管理

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

navigator.getCurrentPage()

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

destroy()メソッド

このメソッドを呼び出すと、ページスタックからページが削除されます。
optionsオブジェクト

ページの設定パラメータを保有するオブジェクトです。詳細についてはpushPage()メソッドの説明を参照してください。

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

navigator.getPages()

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

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

navigator.insertPage(index, page, options)

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

navigator.replacePage(page, options)

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

navigator.resetToPage(page, options)

ページスタックをクリアし、指定した新しいページをスタックに追加します。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>

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

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

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

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

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

検索ボックスを用いた例

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

カスタムなイメージを表示する例

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

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

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

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

`prepush`と`prepop`イベント

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

currentPage: 現在のpageオブジェクト。詳細は、ページスタックを管理するを参照してください
cancel(): 画面遷移をキャンセルする
navigator: 保有する<ons-navigator>オブジェクト

`postpush`と`postpop`イベント

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

leavePage: 現在のページのpageオブジェクト
enterPage: 新しいページのpageオブジェクト
navigator: 保有する<ons-navigator>オブジェクト

スライディングメニュー

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

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

`<ons-sliding-menu>`の概要

<ons-sliding-menu>コンポーネントではmain-pageとmenu-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>

Click to Load this example.

Expand/Contract

Open an Example in New Window

メニューの表示 / 非表示

<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番目の引数にパラメータを指定できます。

closeMenu: 実行後にメニューを閉じる場合はtrueを指定します。
callback: アニメーションが完了したときにコールバック関数を実行します。

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

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

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

アニメーションの種類

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

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

スライディングメニューには、preopen、postopen、preclose、postcloseの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>

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

デフォルトでは、タブバーは画面下部に配置されます。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>

Click to Load this example.

Expand/Contract

Open an Example in New Window

タブのカスタマイズ

タブの見た目をカスタマイズするためには、<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>

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

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

タブがアクティブの時と非アクティブの時でコンテンツを切り替えることができます。そのためには、ons-tab内にons-tab-activeとons-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には、下記のプロパティを指定して挙動を変更できます。

keepPage: trueを指定すると、新しいページを表示せずに、タブのインデックスだけ変更します。デフォルトはfalseです。
animation: ページへの遷移アニメーションを指定します。現在は、noneとfadeを指定できます。デフォルトはnoneです。

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

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

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

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

tabbar.loadPage('newpage.html');

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

タブバーのイベント

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

index: 次ページのインデックス番号
tabItem: ページを保有するオブジェクト

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

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

リストを使う

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 + "を削除します");
  }
};

configureItemScopeは、その要素に関する情報を返します。このメソッドは、要素の配列を用いて動的に作成されたり、呼び出されます。
calculateItemHeightは、その要素の高さをピクセル単位で返します。各要素が別の高さを返すことができます。
countItemsは全体の要素数を返します。
destroyItemScopeは要素が取り除かれた場合に呼ばれるメソッドを指定できます。メモリーリークを防ぐために要素を削除したり、イベントリスナーを解除する場合に使用してください。

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 + "を削除します");
  }
}

createItemContentはindexで指定した要素の内容を、HTMLエレメントして返します。
calculateItemHeightは要素の高さをピクセル単位で返します。各要素が別の高さを返すことができます。
countItemsは全体の要素数を返します。
destroyItemContentは要素が取り除かれた場合に呼ばれるメソッドを指定できます。メモリーリークを防ぐために要素を削除したり、イベントリスナーを解除する場合に使用してください。

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

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();
}

Click to Load this example.

Expand/Contract

Open an Example in New Window

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();
}

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

アラートダイアログ

ons.notification.alert()関数を呼び出すと、ボタンとテキストメッセージが含まれたダイアログを表示できます。メッセージはHTMLで記述することもできます。

ons.notification.alert({
  message: 'メッセージ',
  // もしくはmessageHTML: '<div>HTML形式のメッセージ</div>',
  title: 'ダイアログのタイトル',
  buttonLabel: 'OK',
  animation: 'default', // もしくは'none'
  // modifier: 'optional-modifier'
  callback: function() {
    // ボタンがタップされた
  }
});

確認ダイアログ

ons.notification.confirm()関数はアラートダイアログと似ていますが、複数のボタンを配置できます。

ons.notification.confirm({
  message: 'このダイアログを閉じてもいいですか？',
  // もしくは messageHTML: '<div>HTML形式のメッセージ</div>',
  title: 'ダイアログのタイトル',
  buttonLabels: ['はい', 'いいえ'],
  animation: 'default', // もしくは'none'
  primaryButtonIndex: 1,
  cancelable: true,
  callback: function(index) {
    // -1: キャンセルされた
    // 0-: 左から0ではじまるボタン番号
  }
});

入力ダイアログ

ons.notification.prompt()関数を使うと、テキスト入力ボックスを持つダイアログを作成できます。

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

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

上記の例のように、カスタムなアラートダイアログを表示する場合は、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>

Click to Load this example.

Expand/Contract

Open an Example in New Window

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(options)、hide(options)

ダイアログを開く、もしくは閉じます。optionsパラメータには、animationsおよびcallbackパラメータを指定できます。
isShown()

ダイアログが表示されている場合はtrueを返します。
destroy()

ダイアログを非表示にし、関連するDOM要素をすべて除去します。
setDisabled(disabled)、isDisabled()

ダイアログを無効にし、ユーザーが操作できないようにします。
setCancelable(cancelable)、isCancelable()

ダイアログをキャンセルできるようにし、戻るボタンを押したときに自動的に閉じるようにします。
getDeviceBackButtonHandler()

戻るボタンのハンドラーを取得します。より詳細な情報については、戻るボタンのサポートを参照してください。

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

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

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

preshow、prehide

ダイアログを表示する前、もしくは非表示にする前に呼ばれます。コールバック関数にはdialogプロパティ（もしくはalertDialogプロパティ）と、cancel関数が渡されます。cancel関数を実行すると、その操作をキャンセルすることができます。
```
myDialog.on("preshow", function(e) {
  // e.dialogにはDialogViewオブジェクトが格納される
  e.cancel());
});
```
postshow、posthide

ダイアログを表示した後、もしくは非表示にした後に呼ばれます。コールバック関数には、dialogプロパティ（もしくはalertDialogプロパティ）が渡されます。

カルーセルを使う

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

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

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

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

<ons-carousel fullscreen swipeable overscrollable auto-scroll>
  <ons-carousel-item>
     カルーセルアイテム１
  </ons-carousel-item>
  <ons-carousel-item>
     カルーセルアイテム２
  </ons-carousel-item>
</ons-carousel>

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

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

<ons-carousel style="height: 200px; width: 50%" swipeable overscrollable auto-scroll>
  <ons-carousel-item>
     カルーセルアイテム１
  </ons-carousel-item>
  <ons-carousel-item>
     カルーセルアイテム２
  </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>
     カルーセル要素１
  </ons-carousel-item>
  <ons-carousel-item>
     カルーセル要素２
  </ons-carousel-item>
</ons-carousel>

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

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

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

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

複数の要素を表示する

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

他のオプション

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

auto-scroll属性

この属性がセットされると、カルーセルアイテムは自動的にクロールされ、コンテナーに合わさります。
swipeableおよびdraggable属性

カルーセルをスワイプで操作したり、ドラッグで操作できるようにします。

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

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

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

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

next(options)、prev(options)

次の（もしくは前の）アイテムに移動します。見つからない場合は、最初の（もしくは最後の）アイテムに移動します。
first(options)、last(options)

最初の、もしくは最後のアイテムに移動します。
setActiveCarouselItemIndex(index, options)

indexで指定したアイテムを表示します。現在のアイテムの番号は、getActiveCarouselItemIndex()メソッドで取得できます。

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

myCarousel.next({
  animation: "none",
  callback: function() {
    // スクロールが完了したときに実行される
  }
});

カルーセルアイテムをJavaScriptで追加する

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

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

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

postchange

アクティブなアイテムが変更した後に呼ばれます。コールバック関数には、carousel、activeIndexおよびlastActiveIndexプロパティを持つオブジェクトが渡されます。
- carousel: カルーセルオブジェクトが格納されます。
- activeIndex: 現在のアクティブなアイテムの番号が格納されます。
- lastActiveIndex: 前のアクティブなアイテムの番号が格納されます。
カルーセルがauto-scroll属性を持っていない場合は、これらのイベントは呼び出されません。また、各アイテムの大きさがコンテナの大きさと異なる場合にも呼び出されません。
refresh

カルーセルのレイアウトが変更されたり、refresh()メソッドが実行された場合に呼ばれます。
overscroll

項目がオーバースクロール状態になった場合に呼ばれます。コールバック関数には、carousel、activeIndexおよびlastActiveIndexプロパティを持つオブジェクトが渡されます。
- carousel: カルーセルオブジェクトが格納されます。
- direction: オーバースクロールの方向（left、right、upもしくはdownのいずれか）が格納されます。
- activeIndex: 現在のアクティブなアイテムの番号が格納されます。
- waitToReturn(): Promiseオブジェクトをとり、それが解決されるまでスクロールが戻らないように指示できます。
下記の例はwaitToReturn(promise)メソッドを使用して、処理が完了するまでオーバースクロール状態を維持する例です。
```
carousel.on('overscroll', function(event) {
  var deferred = $q.defer(); // AngularJSの$qサービスを使用しています
  event.waitToReturn(deferred.promise);
  window.setTimeout(function() {
    deferred.resolve();
  }, 3000);
  // 3秒間カルーセルはオーバースクロール状態を維持します
})
```
Click to Load this example.

Expand/Contract

Open an Example in New Window

モーダルを使う

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

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

ポップオーバーを使う

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

ポップオーバーを表示するには、<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形式で返されます。

show(target[, options])

指定したtargetの位置に、ポップオーバーを表示します。targetには、DomElement、クエリセレクターもしくはAngularJSの$eventを指定できます。

optionsには、下記のプロパティを指定できます。
- animation: アニメーション方法をnoneもしくはfadeで指定できます。
hide()

ポップオーバーを非表示にします。不要になった場合は、destroy()メソッドを呼び出してメモリリークを回避してください。

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

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

外見を変更する

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

開く方向を指定する

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

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

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

preshow、prehide

ポップオーバーを表示する前、もしくは非表示にする前に呼ばれます。コールバック関数には、下記のプロパティを持ったオブジェクトが返ります。
- popover: ポップオーバーのオブジェクトが格納されます。
- cancel: 操作をキャンセルするためのメソッドが格納されます。
ポップオーバーの操作をキャンセルしたい場合は、下記のように記述します。
```
myPopover.on("preshow", function(e) {
  e.cancel();
});
```
postshow、posthide

ポップオーバーを開いたり閉じた後に呼ばれます。コールバック関数には、popoverプロパティを持つオブジェクトが返ります。

プルフックを使う

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

プルフックを表示する

プルフックコンポーネントを表示するには、<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つの状態を持ち、それぞれ見た目をカスタマイズすることができます。

initial: デフォルトの状態で、ユーザーが操作する前の状態です。指定した高さを超えてプルダウンされるまでは、この状態となります。
preaction: 手を離したら実行に移れる状態です。この場合でも、上向きにドラッグをすることで、ユーザーは操作をキャンセルすることができます。
action: 実行中の状態です。$done()関数が呼ばれたらinitial状態に戻ります。

プルフックのアクション

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

ng-action: プルダウンしたときの挙動を指定するために使用します。操作が完了した後で$done()関数を呼び出します。
on-action: ng-actionと同様の働きをしますが、AngularJSを使わずに記述できます。操作が完了した後で、done関数を呼び出します。

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

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

height: この属性でコンポーネントの高さを指定します。この値を超えてプルダウンを行った場合にpreaction状態に遷移します。デフォルトは64pxです。
threshold-height: 高さのしきい値を指定します。この値を超えてプルダウンを行った場合にaction状態に遷移します。デフォルトの値は96pxです。マイナス値、もしくはheightよりも小さな数値を指定した場合は、このプロパティが無効になります。

フォームを使う

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

ボタン

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

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

スイッチ

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

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

テキスト入力

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

テキスト入力

<input class="text-input" id="my-input">

テキストエリア

<textarea class="textarea" id="my-textarea"></textarea>

検索ボックス

<input type="search" class="search-input">

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

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

チェックボックスとラジオボタンは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>にはalign、size、offset属性を指定できます。size属性については、pxもしくは%で指定できます。

レイアウトの例

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

アイコンを使う

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

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

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>

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

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

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

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

main-page: メイン側に表示するページを指定できます
secondary-page: サイド側に表示するページを指定できます

Click to Load this example.

Expand/Contract

Open an Example in New Window

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

<ons-split-view>のcollapse属性を用いて、サイドページを非表示にする条件を指定できます。この属性が取り得る値として、portrait、landscapeもしくは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.platform.isWebView(): WebView上で実行されている場合にtrueを返します。
ons.platform.isIOS(): iOSデバイス上で実行されている場合にtrueを返します。
ons.platform.isAndroid(): Androidデバイス上で実行されている場合にtrueを返します。
ons.platform.isIPhone(): iPhoneデバイス上で実行されている場合にtrueを返します。
ons.platform.isIPad(): iPadデバイス上で実行されている場合にtrueを返します。
ons.platform.isBlackBerry(): BlackBerryデバイス上で実行されている場合にtrueを返します。
ons.platform.isOpera(): Operaブラウザー上で実行されている場合にtrueを返します。
ons.platform.isFirefox(): Firefoxブラウザー上で実行されている場合にtrueを返します。
ons.platform.isSafari(): Safariブラウザー上で実行されている場合にtrueを返します。
ons.platform.isChrome(): Chromeブラウザー上で実行されている場合にtrueを返します。
ons.platform.isIE(): Internet Explorerブラウザー上で実行されている場合にtrueを返します。
ons.platform.isIOS7(): iOS 7以降のブラウザーもしくはWebViewだった場合にtrueを返します。

画面向きの判定

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>

対応するジェスチャー

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

ドラッグ操作: drag, dragleft, dragright, dragup, dragdown
ホールド操作: hold, release
スワイプ操作: swipe, swipeleft, swiperight, swipeup, swipedown
タップ操作: tap, doubletap
ピンチ操作: pinch, pinchin, pinchout
その他: touch, transform, rotate

ソフトキーボードの対応

ソフトウェアキーボードの状態に応じて、特定のコードを実行したり、見た目を切り替えたい場合があります。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-navigatorとons-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-navigatorはpushPage()とpopPage()メソッドが用意されており、それぞれページを追加したり削除したりする目的で使用します。

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

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

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

<ons-navigator var="myNavigator">

これで、myNavigator変数はJavaScriptコードのどこからでもアクセスできるようになりました。より正確には、myNavigatorはwindowオブジェクトのプロパティとして、そして、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内にあるコンポーネントを検索します。たとえば、idがmy-switchのons-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属性を持つすべてのコンポーネントでは、下記のメソッドが提供されます。

hasModifier(name): 指定した名前のModifierを有していればtrueを返します。スペース区切りで複数のModifier名を指定した場合は、すべてのModifierを有していた場合にtrueを返します。
removeModifier(name): 指定した名前のModifierを取り除きます。
addModifier(name): 指定した名前のModifierを追加します。
setModifier(name): すべてのModifierを削除し、nameで指定したModifierを追加します。
toggleModifier(name): Modifierの追加もしくは削除を行います。

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

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

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

Onsen UIのスタイルはonsenui.cssとonsen-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をプロジェクトに組み込む →

お困りですか?

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

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

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

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

AngularJSからOnsen UIを使う

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

複数のページを管理する

ナビゲーション型

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

タブバー型

スプリットビュー型

ページナビゲーション

<ons-navigator>の概要

新しいページを表示

一つ前のページに戻る

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

ページスタックの管理

navigator.getCurrentPage()

navigator.getPages()

navigator.insertPage(index, page, options)

navigator.replacePage(page, options)

navigator.resetToPage(page, options)

ツールバーの追加

ツールバーのインライン表示

Androidの戻るボタンへの対応

ナビゲーターのイベント

prepushとprepopイベント

postpushとpostpopイベント

スライディングメニュー

<ons-sliding-menu>の概要

メニューの表示 / 非表示

背景のタップで非表示にする

JavaScriptからページを指定する

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

アニメーションの種類

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

タブバーを使う

<ons-tabbar>の概要

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

タブのカスタマイズ

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

任意のコンテンツを表示する

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

タブの切り替え時に再読み込みを行わない

タブバーアイテムの管理

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

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

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

タブバーのイベント

リストを使う

<ons-list>の概要

基本的なリスト

右矢印付きのリスト

フォームと共に使用する

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

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

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

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

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

非同期で内容を生成する

AngularJSを用いた書き方

AngularJSを使わない書き方

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

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

ダイアログを使う

ダイアログを表示する

DialogViewオブジェクトを使う

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

カルーセルを使う

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

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

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

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

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

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

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

複数の要素を表示する

他のオプション

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

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

カルーセルアイテムをJavaScriptで追加する

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

モーダルを使う

`<ons-navigator>`の概要

`prepush`と`prepop`イベント

`postpush`と`postpop`イベント

`<ons-sliding-menu>`の概要

`<ons-tabbar>`の概要

`<ons-list>`の概要

`DialogView`オブジェクトを使う

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

`<ons-icon>`の概要

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

`ons.ready`関数

`ons.bootstrap`関数

`ons.compile`関数

`ons.disableAutoStatusBarFill`関数

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

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

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

AngularJSの`$templateCache`を使用する