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>
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.
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.
<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.
| 名前 | 型 / デフォルト値 | 概要 |
|---|---|---|
| direction | String | カルーセルの方向を指定します。”horizontal”か”vertical”を指定できます。”horizontal”がデフォルト値です。 Optional. |
| fullscreen | この属性があると、absoluteポジションを使ってカルーセルが自動的に画面いっぱいに広がります。 Optional. | |
| overscrollable | この属性がある時、タッチやドラッグで端までスクロールした時に、バウンドするような効果が当たります。 Optional. | |
| centered | この属性がある時、選んでいるons-carousel-itemはカルーセルの真ん中へ行きます。項目がカルーセルよりも小さい場合にのみ、これは便利です。 Optional. | |
| item-width | String | ons-carousel-itemの幅を指定します。この属性は、direction属性に”horizontal”を指定した時のみ有効になります。 Optional. |
| item-height | String | ons-carousel-itemの高さを指定します。この属性は、direction属性に”vertical”を指定した時のみ有効になります。 Optional. |
| auto-scroll | この属性がある時、一番近いcarousel-itemの境界まで自動的にスクロールするようになります。 Optional. | |
| auto-scroll-ratio | Number | 0.0から1.0までの値を指定します。カルーセルの要素をどれぐらいの割合までドラッグすると次の要素に自動的にスクロールするかを指定します。 Optional. |
| swipeable | この属性がある時、カルーセルをスワイプやドラッグで移動できるようになります。 Optional. | |
| disabled | この属性がある時、dragやtouchやswipeを受け付けなくなります。 Optional. | |
| initial-index |
Number
0 |
最初に表示するons-carousel-itemを0始まりのインデックスで指定します。デフォルト値は 0 です。 Optional. 初期化時のみ有効 |
| auto-refresh | この属性がある時、子要素の数が変わるとカルーセルは自動的に更新されるようになります。 Optional. | |
| animation | String |
If this attribute is set to "none" the transitions will not be animated.
（翻訳中）
Optional.
|
| animation-options | Expression | アニメーション時のduration, timing, delayをオブジェクトリテラルで指定します。例：{duration: 0.2, delay: 1, timing: ‘ease-in’} Optional. |
| active-index | 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の大きさを動的に変える際に利用します。 |
表示する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. （翻訳中） |
現在表示されているons-carousel-item要素のインデックスを返します。
返り値: 現在表示しているカルーセル要素のインデックスが返されます。
次の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. （翻訳中） |
前の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. （翻訳中） |
最初の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. （翻訳中） |
最後の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. （翻訳中） |
レイアウトや内部の状態を最新のものに更新します。ons-carousel-itemを動的に増やしたり、ons-carouselの大きさを動的に変える際に利用します。
| 名前 | 概要 |
|---|---|
| postchange | 現在表示しているカルーセルの要素が変わった時に発火します。 |
| prechange | Fired just before the current carousel item changes. （翻訳中） |
| refresh | カルーセルが更新された時に発火します。 |
| overscroll | カルーセルがオーバースクロールした時に発火します。 |
| swipe | Fires when the carousel swipes. （翻訳中） |
現在表示しているカルーセルの要素が変わった時に発火します。
| 名前 | 型 | 概要 |
|---|---|---|
| event | Object | イベントオブジェクトです。 |
| event.carousel | Object | イベントが発火したCarouselオブジェクトです。 |
| event.activeIndex | Number | 現在アクティブになっている要素のインデックス。 |
| event.lastActiveIndex | Number | 以前アクティブだった要素のインデックス。 |
Fired just before the current carousel item changes. （翻訳中）
| 名前 | 型 | 概要 |
|---|---|---|
| event | Object | イベントオブジェクトです。 |
| event.carousel | Object | イベントが発火したCarouselオブジェクトです。 |
| event.activeIndex | Number | 現在アクティブになっている要素のインデックス。 |
| event.lastActiveIndex | Number | 以前アクティブだった要素のインデックス。 |
カルーセルが更新された時に発火します。
| 名前 | 型 | 概要 |
|---|---|---|
| event | Object | イベントオブジェクトです。 |
| event.carousel | Object | イベントが発火したCarouselオブジェクトです。 |
カルーセルがオーバースクロールした時に発火します。
| 名前 | 型 | 概要 |
|---|---|---|
| event | Object | イベントオブジェクトです。 |
| event.carousel | Object | カルーセルが更新された時に発火します。 |
| event.activeIndex | Number | 現在アクティブになっている要素のインデックス。 |
| event.direction | String | オーバースクロールされた方向が得られます。”up”, “down”, “left”, “right”のいずれかの方向が渡されます。 |
| event.waitToReturn | Function | この関数はPromiseオブジェクトを引数として受け取ります。渡したPromiseオブジェクトがresolveされるかrejectされるまで、カルーセルはスクロールバックしません。 |
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に記載をお願いいたします。
あわせて、下記の情報も参考にしてください。