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 v-model: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 by assigning it a new value (pageStack = [...pageStack, newPage]). Array mutation methods, which mutate the prop without assigning it a new value, (push, pop, splice…) are not allowed. Instead assign the pack stack a new value. For example, to pop a page, instead of using pageStack.pop(), use pageStack = pageStack.slice(0, -1).

The navigator keeps its own internal view of the page stack, so use v-model:page-stack to keep the page stack prop in sync.

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 = [...pageStack, $event]"
  @replace-page="pageStack = [...pageStack.slice(0, -1), $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. Pinia 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, 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 Pinia, 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 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 animationOptions property.

<v-ons-navigator
  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 = [pageStack[0]]"
>
  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.

関連情報

名前 型 / デフォルト値 概要
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.
animationOptions Expression アニメーション時のduration, timing, delayをオブジェクトリテラルで指定します。e.g. {duration: 0.2, delay: 1, timing: 'ease-in'} Optional.
page ナビゲーターが初期化された時に表示するページを指定します。 Optional.
pageStack Array Array of VOnsPage components that represents VOnsNavigator page stack. (翻訳中) 必須
swipeable Boolean Enable iOS “swipe to pop” feature. (翻訳中) Optional.
swipeTargetWidth String スワイプの判定領域をピクセル単位で指定します。画面の端から指定した距離に達するとページが表示されます。 Optional.
swipeThreshold Number Specify how much the page needs to be swiped before popping. A value between 0 and 1. (翻訳中) Optional.
名前 概要
prepush pageがpushされる直前に発火されます。
prepop pageがpopされる直前に発火されます。
postpush pageがpushされてアニメーションが終了してから発火されます。
postpop pageがpopされてアニメーションが終わった後に発火されます。
swipe Fired whenever the user slides the navigator (swipe-to-pop). (翻訳中)
update:pageStack Fired when the page stack is updated. For compatability with v-model. (翻訳中)
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されて消えるページのオブジェクト。
event.swipeToPop Object True if the pop was triggered by the user swiping to pop. (翻訳中)
event.onsBackButton Object True if the pop was caused by pressing an ons-back-button. (翻訳中)
swipe

Fired whenever the user slides the navigator (swipe-to-pop). (翻訳中)

パラメーター
名前 概要
event Object Event object.
event.ratio Object Decimal ratio (0-1). (翻訳中)
event.animationOptions Object (翻訳中)
update:pageStack

Fired when the page stack is updated. For compatability with v-model. (翻訳中)

パラメーター
名前 概要
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に記載をお願いいたします。

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