ons-navigator

実例

The Navigator

The <ons-navigator> element handles a stack of pages. This is a very common type of navigation in mobile apps where one page is pushed on top of another using a transition animation.

To change the animation you can use the animation attribute:

<ons-navigator animation="fade"></ons-navigator>

Available animations are:

  • fade
  • lift
  • slide
  • none

For iOS’ “swipe to pop” feature, add the swipeable attribute. Note that this behavior is automatically removed on Android platforms unless swipeable="force" is specified.

Defining pages

The pages that you push to the Navigator are defined using a <template> element.

<template id="page2.html">
  <ons-page>
    ...
  </ons-page>
</template>

The id attribute is used to reference the pages when pushing.

Pushing pages

To push a new page to the top of the stack, the pushPage(page, options) method is used.

In Onsen UI all such methods are attached to the element so you need to create a reference to it. You can do this by using var attribute:

<ons-navigator var="myNavigator"></ons-navigator>

This will allow you to call Navigator’s method like this: myNavigator.pushPage('page2.html');

pushPage method returns a Promise object that is resolved when the transition is finished. You can try adding the following code:

myNavigator
  .pushPage('page2.html')
  .then(function() {
    ons.notification.alert('Page pushed!');
  });

Sending custom data to a new page

It may be useful to have access to custom data when we push a new page. This is achieved by passing options.data parameter:

myNavigator
  .pushPage('page2.html', {
    data: {
      title: 'New Page',
      // ...
    },
    // Other options
  });

options.data object can be safely accessed after the init event of the new page. ons-init handler can be used to handle this event. It is also possible to access this object from scope functions or views with myNavigator.topPage.data.

Going back

To go back to a previous page the popPage(options) method is used.

Another way is to use the <ons-back-button> element. It can be added to the left side of the toolbar and renders as an arrow:

<ons-toolbar>
  <div class="left">
    <ons-back-button>Back</ons-back-button>
  </div>
</ons-toolbar>

It will automatically find the Navigator element and trigger a popPage() call so there is no need to attach any click handlers to it.

関連情報

属性

名前 型 / デフォルト値 概要
page String ナビゲーターが初期化された時に表示するページを指定します。 Optional. 初期化時のみ有効
swipeable Boolean Enable iOS “swipe to pop” feature. (翻訳中) Optional.
swipe-target-width String
20px
スワイプの判定領域をピクセル単位で指定します。画面の端から指定した距離に達するとページが表示されます。 Optional.
swipe-threshold Number
0.2
Specify how much the page needs to be swiped before popping. A value between 0 and 1. (翻訳中) Optional.
animation String
default

Animation name. Available animations are "slide", "lift", "fade" and "none". These are platform based animations. For fixed animations, add "-ios" or "-md" suffix to the animation name. E.g. "lift-ios", "lift-md". Defaults values are "slide-ios" and "fade-md" depending on the platform.

(翻訳中)
Optional.
animation-options Expression アニメーション時のduration, timing, delayをオブジェクトリテラルで指定します。e.g. {duration: 0.2, delay: 1, timing: 'ease-in'} Optional.
var String このナビゲーターを参照するための名前を指定します。 Optional. 初期化時のみ有効
ons-prepush Expression “prepush”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
ons-prepop Expression “prepop”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
ons-postpush Expression “postpush”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
ons-postpop Expression “postpop”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
ons-init Expression ページの”init”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
ons-show Expression ページの”show”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
ons-hide Expression ページの”hide”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
ons-destroy Expression ページの”destroy”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効

プロパティ概要

名前 概要
pageLoader PageLoaderインスタンスを格納しています。
page 初期化時に読み込むページを指定します。page属性で指定した値よりもpageプロパティに指定した値を優先します。
onDeviceBackButton バックボタンハンドラ。
topPage 現在のページを取得します。pushPage()やresetToPage()メソッドの引数を取得できます。
pages Copy of the navigator’s page stack. (翻訳中)
onSwipe Hook called whenever the user slides the navigator (swipe-to-pop). It gets a decimal ratio (0-1) and an animationOptions object as arguments. (翻訳中)
options Default options object. Attributes have priority over this property. (翻訳中)
options.animation

Animation name. Available animations are "slide", "lift", "fade" and "none". These are platform based animations. For fixed animations, add "-ios" or "-md" suffix to the animation name. E.g. "lift-ios", "lift-md". Defaults values are "slide-ios" and "fade-md".

(翻訳中)
options.animationOptions アニメーション時のduration, delay, timingを指定します。e.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}
options.callback このメソッドによる画面遷移が終了した際に呼び出される関数オブジェクトを指定します。

メソッド

シグネチャ 概要
popPage([options]) 現在表示中のページをページスタックから取り除きます。一つ前のページに戻ります。
pushPage(page, [options]) 指定したpageを新しいページスタックに追加します。新しいページが表示されます。
replacePage(page, [options]) 現在表示中のページをを指定したページに置き換えます。
insertPage(index, page, [options]) 指定したpageをページスタックのindexで指定した位置に追加します。
removePage(index, [options]) 指定したインデックスにあるページを削除します。
resetToPage(page, [options]) ページスタックをリセットし、指定したページを表示します。
bringPageTop(item, [options]) 指定したページをページスタックの一番上に移動します。もし指定したページが無かった場合新しくpushされます。
on(eventName, listener) イベントリスナーを追加します。
once(eventName, listener) 一度だけ呼び出されるイベントリスナーを追加します。
off(eventName, [listener]) イベントリスナーを削除します。もしイベントリスナーを指定しなかった場合には、そのイベントに紐づく全てのイベントリスナーが削除されます。
popPage([options]): Promise

現在表示中のページをページスタックから取り除きます。一つ前のページに戻ります。

返り値: 明らかにしたページを解決するPromiseを返します。

パラメーター
名前 概要
options Object オプションを指定するオブジェクト。
options.animation String

Animation name. Available animations are "slide", "lift", "fade" and "none". These are platform based animations. For fixed animations, add "-ios" or "-md" suffix to the animation name. E.g. "lift-ios", "lift-md". Defaults values are "slide-ios" and "fade-md".

(翻訳中)
options.animationOptions String アニメーション時のduration, delay, timingを指定します。e.g. {duration: 0.2, delay: 0.4, timing: ‘ease-in’}
options.callback Function このメソッドによる画面遷移が終了した際に呼び出される関数オブジェクトを指定します。
options.data Object Custom data that will be stored in the new page element. (翻訳中)
options.times Number Number of pages to be popped. Only one animation will be shown. (翻訳中)
pushPage(page, [options]): Promise

指定したpageを新しいページスタックに追加します。新しいページが表示されます。

返り値: 追加したページを解決するPromiseを返します。

パラメーター
名前 概要
page String pageのURLか、もしくは<template>で宣言したテンプレートのid属性の値を指定できます。
options Object オプションを指定するオブジェクト。
options.page String Page URL. Only necessary if page parameter is null or undefined. (翻訳中)
options.pageHTML String HTML code that will be computed as a new page. Overwrites page parameter. (翻訳中)
options.animation String

Animation name. Available animations are "slide", "lift", "fade" and "none". These are platform based animations. For fixed animations, add "-ios" or "-md" suffix to the animation name. E.g. "lift-ios", "lift-md". Defaults values are "slide-ios" and "fade-md".

(翻訳中)
options.animationOptions String アニメーション時のduration, delay, timingを指定します。e.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}
options.callback Function pushPage()による画面遷移が終了した時に呼び出される関数オブジェクトを指定します。
options.data Object Custom data that will be stored in the new page element. (翻訳中)
replacePage(page, [options]): Promise

現在表示中のページをを指定したページに置き換えます。

返り値: 新しいページを解決するPromiseを返します。

insertPage(index, page, [options]): Promise

指定したpageをページスタックのindexで指定した位置に追加します。

返り値: 指定したページを解決するPromiseを返します。

パラメーター
名前 概要
index Number スタックに挿入する位置のインデックスを指定します。
removePage(index, [options]): Promise

指定したインデックスにあるページを削除します。

返り値: 削除によって表示されたページを解決するPromiseを返します。

パラメーター
名前 概要
index Number スタックから削除するページのインデックスを指定します。
resetToPage(page, [options]): Promise

ページスタックをリセットし、指定したページを表示します。

返り値: 新しいトップページを解決するPromiseを返します。

パラメーター
名前 概要
options.pop Boolean Performs ‘pop’ effect if true instead of ‘push’ or none. This also sets options.animation value to default instead of none. (翻訳中)
bringPageTop(item, [options]): Promise

指定したページをページスタックの一番上に移動します。もし指定したページが無かった場合新しくpushされます。

返り値: 新しいトップページを解決するPromiseを返します。

パラメーター
名前 概要
item String|Number ページのURLかもしくはons-navigatorのページスタックのインデックス値を指定します。
on(eventName, listener)

イベントリスナーを追加します。

パラメーター
名前 概要
eventName String イベント名を指定します。
listener Function このイベントが発火された際に呼び出される関数オブジェクトを指定します。
once(eventName, listener)

一度だけ呼び出されるイベントリスナーを追加します。

パラメーター
名前 概要
eventName String イベント名を指定します。
listener Function イベントが発火した際に呼び出される関数オブジェクトを指定します。
off(eventName, [listener])

イベントリスナーを削除します。もしイベントリスナーを指定しなかった場合には、そのイベントに紐づく全てのイベントリスナーが削除されます。

パラメーター
名前 概要
eventName String イベント名を指定します。
listener Function 削除するイベントリスナーを指定します。

イベント

名前 概要
prepush pageがpushされる直前に発火されます。
prepop pageがpopされる直前に発火されます。
postpush pageがpushされてアニメーションが終了してから発火されます。
postpop pageがpopされてアニメーションが終わった後に発火されます。
prepush

pageがpushされる直前に発火されます。

パラメーター
名前 概要
event Object Event object.
event.navigator Object コンポーネントのオブジェクト。
event.currentPage Object 現在のpageオブジェクト。
event.cancel Function この関数を呼び出すと、push処理がキャンセルされます。
prepop

pageがpopされる直前に発火されます。

パラメーター
名前 概要
event Object Event object.
event.navigator Object コンポーネントのオブジェクト。
event.currentPage Object 現在のpageオブジェクト。
event.cancel Function この関数を呼び出すと、pageのpopがキャンセルされます。
postpush

pageがpushされてアニメーションが終了してから発火されます。

パラメーター
名前 概要
event Object Event object.
event.navigator Object コンポーネントのオブジェクト。
event.enterPage Object pushされたpageオブジェクト。
event.leavePage Object 以前のpageオブジェクト。
postpop

pageがpopされてアニメーションが終わった後に発火されます。

パラメーター
名前 概要
event Object Event object.
event.navigator Object コンポーネントのオブジェクト。
event.enterPage Object popされて表示されるページのオブジェクト。
event.leavePage Object popされて消えるページのオブジェクト。

お困りですか?

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

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

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