ons-carousel

実例

A carousel is a UI component that is used to display several items in the same place. Switching between the content can either be automatic or controlled by the user.

In Onsen UI a carousel is created using the <ons-carousel> element.

<ons-carousel>
  <ons-carousel-item>
    ...
  </ons-carousel-item>
  <ons-carousel-item>
    ...
  </ons-carousel-item>
  ...
</ons-carousel>

Customization

The <ons-carousel> element has a large number of attributes that control its behavior.

By default the carousel can not be controlled by swiping. The swipeable attribute will enabled this.

To make it automatically snap to item borders the auto-scroll attribute is used. The overscrollable attribute makes it possible to scroll past the first and last element of the carousel.

To make it cover the whole screen you can use the fullscreen attribute. If the carousel is not fullscreen you may need to specify the height or the width of the items through CSS.

Changing the direction

The carousel goes from left to right by default. It is possible to make scroll vertically by using the direction attribute.

<ons-carousel direction="vertical">
  ...
</ons-carousel>

You can try adding the direction="vertical" attribute to this example to see how it works.

Compilation

<ons-carousel> element slightly modifies its content to make it swipeable by adding div.ons-swiper-target wrapper. The final results look like this:

<ons-carousel>
  <div class="ons-swiper-target">
    <ons-carousel-item></ons-carousel-item>
    <ons-carousel-item></ons-carousel-item>
    <ons-carousel-item></ons-carousel-item>
  </div>
</ons-carousel>

This wrapper can also be manually provided.

関連情報

名前 型 / デフォルト値 概要
String カルーセルの方向を指定します。”horizontal”か”vertical”を指定できます。”horizontal”がデフォルト値です。 Optional.
この属性があると、absoluteポジションを使ってカルーセルが自動的に画面いっぱいに広がります。 Optional.
この属性がある時、タッチやドラッグで端までスクロールした時に、バウンドするような効果が当たります。 Optional.
この属性がある時、選んでいるons-carousel-itemはカルーセルの真ん中へ行きます。項目がカルーセルよりも小さい場合にのみ、これは便利です。 Optional.
String ons-carousel-itemの幅を指定します。この属性は、direction属性に”horizontal”を指定した時のみ有効になります。 Optional.
String ons-carousel-itemの高さを指定します。この属性は、direction属性に”vertical”を指定した時のみ有効になります。 Optional.
この属性がある時、一番近いcarousel-itemの境界まで自動的にスクロールするようになります。 Optional.
Number 0.0から1.0までの値を指定します。カルーセルの要素をどれぐらいの割合までドラッグすると次の要素に自動的にスクロールするかを指定します。 Optional.
この属性がある時、カルーセルをスワイプやドラッグで移動できるようになります。 Optional.
この属性がある時、dragやtouchやswipeを受け付けなくなります。 Optional.
Number
0
最初に表示するons-carousel-itemを0始まりのインデックスで指定します。デフォルト値は 0 です。 Optional. 初期化時のみ有効
この属性がある時、子要素の数が変わるとカルーセルは自動的に更新されるようになります。 Optional.
String If this attribute is set to "none" the transitions will not be animated. (翻訳中) Optional.
Expression アニメーション時のduration, timing, delayをオブジェクトリテラルで指定します。例:{duration: 0.2, delay: 1, timing: ‘ease-in’} Optional.
Number Specify the index of the carousel item that should be shown. (翻訳中) Optional.
名前 概要
fullscreen この属性があると、absoluteポジションを使ってカルーセルが自動的に画面いっぱいに広がります。
autoRefresh この属性がある時、子要素の数が変わるとカルーセルは自動的に更新されるようになります。
itemCount カルーセル要素の数です。
swipeable swipeableであればtrueを返します。
onSwipe Hook called whenever the user slides the carousel. It gets a decimal index and an animationOptions object as arguments. (翻訳中)
autoScroll オートスクロールが有効であればtrueを返します。
autoScrollRatio 現在のオートスクロールのratio値。
disabled 無効化されている場合にtrue
overscrollable overscrollできればtrueを返します。
centered centered状態になっていればtrueを返します。
animationOptions アニメーション時のduration, timing, delayをオブジェクトリテラルで指定します。例:{duration: 0.2, delay: 1, timing: ‘ease-in’}
activeIndex Specify the index of the carousel item that should be shown. (翻訳中)
シグネチャ 概要
setActiveIndex(index, [options]) 表示するons-carousel-itemをindexで指定します。
getActiveIndex() 現在表示されているons-carousel-item要素のインデックスを返します。
next([options]) 次のons-carousel-itemを表示します。
prev([options]) 前のons-carousel-itemを表示します。
first() 最初のons-carousel-itemを表示します。
last() 最後のons-carousel-itemを表示します。
refresh() レイアウトや内部の状態を最新のものに更新します。ons-carousel-itemを動的に増やしたり、ons-carouselの大きさを動的に変える際に利用します。
setActiveIndex(index, [options]): Promise

表示するons-carousel-itemをindexで指定します。

返り値:

パラメーター
名前 概要
index Number carousel要素のインデックスを指定します。
options Object Parameter object. (翻訳中)
options.callback Function A function that will be called after the animation is finished. (翻訳中)
options.animation String If this attribute is set to "none" the transitions will not be animated. (翻訳中)
options.animationOptions Object An object that can be used to specify duration, delay and timing function of the animation. (翻訳中)
getActiveIndex(): Number

現在表示されているons-carousel-item要素のインデックスを返します。

返り値: 現在表示しているカルーセル要素のインデックスが返されます。

next([options]): Promise

次のons-carousel-itemを表示します。

返り値:

パラメーター
名前 概要
options Object Parameter object. (翻訳中)
options.callback Function A function that will be executed after the animation has finished. (翻訳中)
options.animation String If this attribute is set to "none" the transitions will not be animated. (翻訳中)
options.animationOptions Object An object that can be used to specify the duration, delay and timing function of the animation. (翻訳中)
prev([options]): Promise

前のons-carousel-itemを表示します。

返り値:

パラメーター
名前 概要
options Object Parameter object. (翻訳中)
options.callback Function A function that will be executed after the animation has finished. (翻訳中)
options.animation String If this attribute is set to "none" the transitions will not be animated. (翻訳中)
options.animationOptions Object An object that can be used to specify the duration, delay and timing function of the animation. (翻訳中)
first(): Promise

最初のons-carousel-itemを表示します。

返り値:

パラメーター
名前 概要
options Object Parameter object. (翻訳中)
options.callback Function A function that will be executed after the animation has finished. (翻訳中)
options.animation String If this is set to "none", the transitions will not be animated. (翻訳中)
options.animationOptions Object An object that can be used to specify the duration, delay and timing function of the animation. (翻訳中)
last(): Promise

最後のons-carousel-itemを表示します。

返り値: Resolves to the carousel element

パラメーター
名前 概要
options Object Parameter object. (翻訳中)
options.callback Function A function that will be executed after the animation has finished. (翻訳中)
options.animation String If this attribute is set to "none" the transitions will not be animated. (翻訳中)
options.animationOptions Object An object that can be used to specify the duration, delay and timing function of the animation. (翻訳中)
refresh()

レイアウトや内部の状態を最新のものに更新します。ons-carousel-itemを動的に増やしたり、ons-carouselの大きさを動的に変える際に利用します。

名前 概要
postchange 現在表示しているカルーセルの要素が変わった時に発火します。
prechange Fired just before the current carousel item changes. (翻訳中)
refresh カルーセルが更新された時に発火します。
overscroll カルーセルがオーバースクロールした時に発火します。
swipe Fires when the carousel swipes. (翻訳中)
postchange

現在表示しているカルーセルの要素が変わった時に発火します。

パラメーター
名前 概要
event Object イベントオブジェクトです。
event.carousel Object イベントが発火したCarouselオブジェクトです。
event.activeIndex Number 現在アクティブになっている要素のインデックス。
event.lastActiveIndex Number 以前アクティブだった要素のインデックス。
prechange

Fired just before the current carousel item changes. (翻訳中)

パラメーター
名前 概要
event Object イベントオブジェクトです。
event.carousel Object イベントが発火したCarouselオブジェクトです。
event.activeIndex Number 現在アクティブになっている要素のインデックス。
event.lastActiveIndex Number 以前アクティブだった要素のインデックス。
refresh

カルーセルが更新された時に発火します。

パラメーター
名前 概要
event Object イベントオブジェクトです。
event.carousel Object イベントが発火したCarouselオブジェクトです。
overscroll

カルーセルがオーバースクロールした時に発火します。

パラメーター
名前 概要
event Object イベントオブジェクトです。
event.carousel Object カルーセルが更新された時に発火します。
event.activeIndex Number 現在アクティブになっている要素のインデックス。
event.direction String オーバースクロールされた方向が得られます。”up”, “down”, “left”, “right”のいずれかの方向が渡されます。
event.waitToReturn Function この関数はPromiseオブジェクトを引数として受け取ります。渡したPromiseオブジェクトがresolveされるかrejectされるまで、カルーセルはスクロールバックしません。
swipe

Fires when the carousel swipes. (翻訳中)

パラメーター
名前 概要
event Object イベントオブジェクト。
event.index Number 現在アクティブになっているons-carouselのインデックスを返します。
event.options Object Animation options object. (翻訳中)

お困りですか?

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

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

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