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.

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.

Methods

The carousel can also be controlled programmatically. To switch to the previous or next item the prev() and next() are used.

To switch to a specific item the setActiveIndex(index) method is used.

Events

The carousel element emits DOM event. Every time the current item has changed it emits the postchange event which is useful to make sure which is the currently displayed item.

In AngularJS this event can be handled in ons-postchange attribute:

<ons-carousel ons-postchange="console.log('Changed to ' + $event.activeIndex)"></ons-carousel>

関連情報

属性

名前 型 / デフォルト値 概要
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.
String このカルーセルを参照するための変数名を指定します。 Optional. 初期化時のみ有効
Expression “postchange”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
Expression “refresh”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
Expression “overscroll”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効
Expression “destroy”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効

プロパティ概要

名前 概要
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を返します。

メソッド

シグネチャ 概要
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の大きさを動的に変える際に利用します。
once(eventName, listener) 一度だけ呼び出されるイベントリスナを追加します。
off(eventName, [listener]) イベントリスナーを削除します。もしイベントリスナーが指定されなかった場合には、そのイベントに紐付いているイベントリスナーが全て削除されます。
on(eventName, listener) イベントリスナーを追加します。
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の大きさを動的に変える際に利用します。

once(eventName, listener)

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

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

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

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

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

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

イベント

名前 概要
postchange 現在表示しているカルーセルの要素が変わった時に発火します。
refresh カルーセルが更新された時に発火します。
overscroll カルーセルがオーバースクロールした時に発火します。
postchange

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

パラメーター
名前 概要
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されるまで、カルーセルはスクロールバックしません。

お困りですか?

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

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

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