v-ons-navigator

実例

Stack navigation

The VOnsNavigator is a component that provides stack based navigation. It is a very common navigation pattern in mobile apps. After pushing a page to the top of the stack, it will be displayed using transition animation. When the user goes back to the previous page the top page will be popped from the top of the stack and hidden with a corresponding transition animation.

An array of VOnsPage components must be passed as a prop to VOnsNavigator.

<v-ons-navigator :page-stack="[p1, p2, p3]"></v-ons-navigator>

Whenever the page stack is modified, VOnsNavigator will perform the corresponding transition. Pushing or popping multiple pages at once is allowed, although only 1 animation will be performed.

Any action will throw corresponding prepush, postpush, prepop and postpop events.

Modifying the stack

The page stack can be modified from any place where the array is accessible either by calling array methods (push, pop, splice…) or assigning a new value (pageStack = [...pageStack, newPage]). This “pageStack” can be created at any component level but it must be passed to v-ons-navigator as a prop.

For example, if there is a VOnsSplitter as a parent component of VOnsNavigator that also needs to modify the stack, the splitter will create the array and then pass it to the child navigator. This way, both components (parent splitter and child navigator) will be able to modify the stack.

In order to push a new page from the current one (sibling pages), pages must have access to the stack array as well. There are many ways to achieve this sort of component communication in Vue. First one, we can define custom actions as event listeners:

<v-ons-navigator :page-stack="pageStack"
  @push-page="pageStack.push($event)"
  @replace-page="pageStack.pop(); pageStack.push($event)"
></v-ons-navigator>

VOnsNavigator sets custom listeners (i.e. anything except @prepush, @postpush, @prepop and @postpop) directly to its child pages. This way, you can name your events however you like and do any action you want. With the previous example, we can push a new page from any existing page as follows:

// import newPage from ...
this.$emit('push-page', newPage);

Passing data around

Navigator’s pages are sibling elements, which means that communication among them in Vue is fairly challenging. Vuex is a good solution for this, but not the only one. When you push a new page component and want to add some initial data, you can simply extend it and let Vue merge the new data prop with the original one in newPage component:

this.$emit('push-page', {
  extends: newPage,
  data() {
    myCustomDataHere: 42
  }
});

Alternatively, since 2.5.2 we can also pass props to the pages through the onsNavigatorProps property:

this.$emit('push-page', {
  ...newPage, // Or 'extends: newPage'
  onsNavigatorProps: {
    myCustomPropHere: 42,
    // ...
  }
});

Any props passed using onsNavigatorProps must be defined using props on the extended page, or they will not be available. For example, newPage as used above might look like this:

const newPage = {
  name: 'newPage',
  template: `<v-ons-page>{{myCustomPropHere}}</v-ons-page>`,
  props: {
    myCustomPropHere: {
      type: Number,
      required: true
    }
  }
}

In order to pass data back to the previous page, we can either use Vuex, an event bus, or simply pass a function that modifies the corresponding context. If page A pushes page B, it can send a function as a prop or data (mentioned above) that modifies page A’s context. This way, whenever we want to send anything to page A from page B, the latter just needs to call the function and pass some arguments:

// Page A
this.$emit('push-page', {
  extends: pageB,
  onsNavigatorProps: {
    passDataBack(data) {
      this.dataFromPageB = data;
    }
  }
});

Customizing the animation

There are several animations available for VOnsNavigator component. It can be specified with the options.animation prop. Available animations are slide, lift and fade. Setting the property to none will make the transition instantly.

It is also possible to customize the duration, delay and timing function of the animation using the options.animationOptions property.

<v-ons-navigator
  :options="{
    animation: 'fade',
    animationOptions: {duration: 0.2, timing: 'ease-in'}
  }"
>
</v-ons-navigator>

The same options can be passed through the onsNavigatorOptions property when pushing pages in order to modify only specific pages:

this.$emit('push-page', {
  extends: newPage,
  onsNavigatorOptions: {
    animation: 'lift',
    animationOptions: { duration: 0.5 }
  }
});
`

For iOS’ “swipe to pop” feature, add the swipeable prop. Note that this behavior only works with animations that support this feature, such as slide-ios (default slide animation on iOS).

The back button

The VOnsBackButton component can be used to display a back button in the navigation bar. By default, this component automatically finds its parent VOnsNavigator component and pops a page when pressed. However, this default behavior can be overriden by running event.preventDefault in a click handler (or using Vue’s .prevent shorthand modifier):

<v-ons-back-button
  @click.prevent="pageStack.splice(1, pageStack.length - 1)"
>
  Back
</v-ons-back-button>

The previous code resets the pageStack to its first page instead of popping 1 single page. It assumes pageStack variable exists in the current context.

関連情報

Prop一覧

名前 型 / デフォルト値 概要
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" depending on the platform.

(翻訳中)
Optional.
options.animationOptions Expression アニメーション時のduration, timing, delayをオブジェクトリテラルで指定します。e.g. {duration: 0.2, delay: 1, timing: 'ease-in'} Optional.
options.callback Function このメソッドによる画面遷移が終了した際に呼び出される関数オブジェクトを指定します。 Optional.
page-stack Array Array of VOnsPage components that represents VOnsNavigator page stack. (翻訳中) 必須
swipe-target-width String スワイプの判定領域をピクセル単位で指定します。画面の端から指定した距離に達するとページが表示されます。 Optional.
swipe-threshold Number Specify how much the page needs to be swiped before popping. A value between 0 and 1. (翻訳中) Optional.
swipeable Boolean Enable iOS “swipe to pop” feature. (翻訳中) Optional.

イベント

名前 概要
prepush pageがpushされる直前に発火されます。
prepop pageがpopされる直前に発火されます。
postpush pageがpushされてアニメーションが終了してから発火されます。
postpop pageがpopされてアニメーションが終わった後に発火されます。
deviceBackButton Fired on device back button. Default behavior is popping 1 page when pageStack contains more than 1. Otherwise, calls parent handler. (翻訳中)
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されて消えるページのオブジェクト。
deviceBackButton

Fired on device back button. Default behavior is popping 1 page when pageStack contains more than 1. Otherwise, calls parent handler. (翻訳中)

パラメーター
名前 概要
event Object Event object. (翻訳中)
event.preventDefault Function Avoids the default behavior. (翻訳中)
event.callParentHandler Function Runs the handler for the immediate parent that supports device back button. (翻訳中)

お困りですか?

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

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

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