Skip to content

E
Element
Commit 6c1ea22c authored by Leopoldthecoder's avatar Leopoldthecoder
Browse files
Options

Carousel: update api

parent d0619c7f
Hide whitespace changes
Inline Side-by-side
Showing with 101 additions and 75 deletions
examples/docs/en-US/carousel.md
View file @ 6c1ea22c
......@@ -61,7 +61,7 @@ Loop a series of images or texts in a limited space
Indicators can be displayed outside the carousel
::: demo The `indicator-position` attribute determines where the indicators are located. By default they are inside the carousel, and setting `indicator-position` to `outside` moves them outside.
::: demo The `indicator-position` attribute determines where the indicators are located. By default they are inside the carousel, and setting `indicator-position` to `outside` moves them outside; setting `indicator-position` to `none` hides the indicators.
```html
<template>
<el-carousel indicator-position="outside">
......@@ -129,10 +129,10 @@ You can define when arrows are displayed
When a page is wide enough but has limited height, you can activate card mode for carousels
::: demo Setting `card` to `true` activates the card mode. Apart from the appearance, the biggest difference between card mode and common mode is that clicking the slides at both sides directly switches the carousel in card mode.
::: demo Setting `type` to `card` activates the card mode. Apart from the appearance, the biggest difference between card mode and common mode is that clicking the slides at both sides directly switches the carousel in card mode.
```html
<template>
<el-carousel :interval="4000" card height="200px">
<el-carousel :interval="4000" type="card" height="200px">
<el-carousel-item v-for="item in 6">
<h3>{{ item }}</h3>
</el-carousel-item>
......@@ -159,27 +159,31 @@ When a page is wide enough but has limited height, you can activate card mode fo
```
:::
### Attributes
### Carousel Attributes
| Attribute | Description | Type | Accepted Values | Default |
|---------- |-------------- |---------- |-------------------------------- |-------- |
| height | height of the carousel | number | — | 300 |
| initial-index | index of the initially active slide (starting from 0) | number | — | 0 |
| trigger | how indicators are triggered | string | click | — |
| auto-play | whether automatically loop the slides | boolean | — | true |
| autoplay | whether automatically loop the slides | boolean | — | true |
| interval | interval of the auto loop, in milliseconds | number | — | 3000 |
| indicator-position | position of the indicators | string | out | — |
| indicator | whether indicators are shown | boolean | — | true |
| arrow | when arrows are shown | string | always/never | — |
| card | whether card mode is activated | boolean | — | false |
| indicator-position | position of the indicators | string | outside/none | — |
| arrow | when arrows are shown | string | always/hover/never | hover |
| type | type of the Carousel | string | card | — |
### Events
| Event Name | Description | Parameters |
|---------|---------|---------|
| index-change | triggers when the active slide switches | index of the new active slide, index of the old active slide |
| change | triggers when the active slide switches | index of the new active slide, index of the old active slide |
### Methods
| Method | Description | Parameters |
|---------- |-------------- | - |
| setActiveIndex | manually switch slide | index of the slide to be switched to, starting from 0 |
| slideToPrev | switch to the previous slide | — |
| slideToNext | switch to the next slide | — |
| setActiveItem | manually switch slide | index of the slide to be switched to, starting from 0; or the `name` of corresponding `el-carousel-item` |
| prev | switch to the previous slide | — |
| next | switch to the next slide | — |
### Carousel-Item Attributes
| Attribute | Description | Type | Accepted Values | Default |
|---------- |-------------- |---------- |-------------------------------- |-------- |
| name | name of the item, can be used in `setActiveItem` | string | — | — |
examples/docs/en-US/form.md
View file @ 6c1ea22c
......@@ -809,11 +809,11 @@ Form component allows you to verify your data, helping you find and correct erro
### Form Methods
| Method | Description | Parameters
| ---- | ---- | ----
| validate | the method to validate the whole form | Function(callback: Function(boolean))
| validateField | the method to validate a certain form item | Function(prop: string, callback: Function(errorMessage: string))
| resetFields | reset all the fields and remove validation result |
| Method | Description | Parameters |
| ---- | ---- | ---- |
| validate | the method to validate the whole form | Function(callback: Function(boolean)) |
| validateField | the method to validate a certain form item | Function(prop: string, callback: Function(errorMessage: string)) |
| resetFields | reset all the fields and remove validation result | — |
### Form-Item Attributes
......
examples/docs/zh-CN/carousel.md
View file @ 6c1ea22c
......@@ -113,7 +113,7 @@
可以将指示器的显示位置设置在容器外部
::: demo `indicator-position`属性定义了指示器的位置。默认情况下，它会显示在走马灯内部，设置为`outside`则会显示在外部。
::: demo `indicator-position`属性定义了指示器的位置。默认情况下，它会显示在走马灯内部，设置为`outside`则会显示在外部；设置为`none`则不会显示指示器。
```html
<template>
<el-carousel indicator-position="outside">
......@@ -179,10 +179,10 @@
### 卡片化
当页面宽度方向空间空余，但高度方向空间匮乏时，可使用卡片风格
::: demo 设置`card`属性即可启用卡片模式。从交互上来说，卡片模式和一般模式的最大区别在于，可以通过直接点击两侧的幻灯片进行切换。
::: demo 将`type`属性设置为`card`即可启用卡片模式。从交互上来说，卡片模式和一般模式的最大区别在于，可以通过直接点击两侧的幻灯片进行切换。
```html
<template>
<el-carousel :interval="4000" card height="200px">
<el-carousel :interval="4000" type="card" height="200px">
<el-carousel-item v-for="item in 6">
<h3>{{ item }}</h3>
</el-carousel-item>
......@@ -209,27 +209,31 @@
```
:::
### Attributes
### Carousel Attributes
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---------- |-------------- |---------- |-------------------------------- |-------- |
| height | 走马灯的高度 | number | — | 300 |
| initial-index | 初始状态激活的幻灯片的索引，从 0 开始 | number | — | 0 |
| trigger | 指示器的触发方式 | string | click | — |
| auto-play | 是否自动切换 | boolean | — | true |
| autoplay | 是否自动切换 | boolean | — | true |
| interval | 自动切换的时间间隔，单位为毫秒 | number | — | 3000 |
| indicator-position | 指示器的位置 | string | out | — |
| indicator | 是否显示指示器 | boolean | — | true |
| arrow | 切换箭头的显示时机 | string | always/never | — |
| card | 是否启用卡片模式 | boolean | — | false |
| indicator-position | 指示器的位置 | string | outside/none | — |
| arrow | 切换箭头的显示时机 | string | always/hover/never | hover |
| type | 走马灯的类型 | string | card | — |
### Events
### Carousel Events
| 事件名称 | 说明 | 回调参数 |
|---------|---------|---------|
| index-change | 幻灯片切换时触发 | 目前激活的幻灯片的索引，原幻灯片的索引 |
| change | 幻灯片切换时触发 | 目前激活的幻灯片的索引，原幻灯片的索引 |
### Methods
### Carousel Methods
| 方法名 | 说明 | 参数 |
|---------- |-------------- | - |
| setActiveIndex | 手动切换幻灯片 | 需要切换的幻灯片的索引，从 0 开始 |
| slideToPrev | 切换至上一张幻灯片 | — |
| slideToNext | 切换至下一张幻灯片 | — |
| setActiveItem | 手动切换幻灯片 | 需要切换的幻灯片的索引，从 0 开始；或相应 `el-carousel-item` 的 `name` 属性值 |
| prev | 切换至上一张幻灯片 | — |
| next | 切换至下一张幻灯片 | — |
### Carousel-Item Attributes
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---------- |-------------- |---------- |-------------------------------- |-------- |
| name | 幻灯片的名字，可用作 `setActiveItem` 的参数 | string | — | — |
packages/carousel/src/item.vue
View file @ 6c1ea22c
......@@ -4,13 +4,17 @@
class="el-carousel__item"
:class="{
'is-active': active,
'el-carousel__item--card': $parent.card,
'el-carousel__item--card': $parent.type === 'card',
'is-in-stage': inStage
}"
@click="handleItemClick"
:style="{ transform: `translateX(${ translate }px) scale(${ scale })` }">
:style="{
msTransform: `translateX(${ translate }px) scale(${ scale })`,
webkitTransform: `translateX(${ translate }px) scale(${ scale })`,
transform: `translateX(${ translate }px) scale(${ scale })`
}">
<div
v-if="$parent.card"
v-if="$parent.type === 'card'"
v-show="!active"
class="el-carousel__mask">
</div>
......@@ -23,6 +27,10 @@
export default {
name: 'ElCarouselItem',
props: {
name: String
},
data() {
return {
translate: 0,
......@@ -61,7 +69,7 @@
const parentWidth = this.$parent.$el.offsetWidth;
const length = this.$parent.items.length;
if (this.$parent.card) {
if (this.$parent.type === 'card') {
if (index !== activeIndex && length > 2) {
index = this.processIndex(index, activeIndex, length);
}
......@@ -78,9 +86,9 @@
handleItemClick() {
const parent = this.$parent;
if (parent && parent.card) {
if (parent && parent.type === 'card') {
const index = parent.items.indexOf(this);
parent.setActiveIndex(index);
parent.setActiveItem(index);
}
}
},
......
packages/carousel/src/main.vue
View file @ 6c1ea22c
<template>
<div
class="el-carousel"
:class="{ 'el-carousel--card': card }"
:class="{ 'el-carousel--card': type === 'card' }"
@mouseenter.stop="handleMouseEnter"
@mouseleave.stop="handleMouseLeave">
<div
......@@ -29,8 +29,8 @@
</div>
<ul
class="el-carousel__indicators"
v-if="indicator"
:class="{ 'el-carousel__indicators--out': indicatorPosition === 'outside' || card }">
v-if="indicatorPosition !== 'none'"
:class="{ 'el-carousel__indicators--outside': indicatorPosition === 'outside' || type === 'card' }">
<li
v-for="(item, index) in items"
class="el-carousel__indicator"
......@@ -45,6 +45,8 @@
<script>
import throttle from 'throttle-debounce/throttle';
import debounce from 'throttle-debounce/debounce';
import { addResizeListener, removeResizeListener } from 'element-ui/src/utils/resize-event';
export default {
name: 'ElCarousel',
......@@ -72,8 +74,11 @@ export default {
type: Boolean,
default: true
},
arrow: String,
card: Boolean
arrow: {
type: String,
default: 'hover'
},
type: String
},
data() {
......@@ -81,7 +86,6 @@ export default {
items: [],
activeIndex: -1,
containerWidth: 0,
reInitTimer: null,
timer: null,
hover: false
};
......@@ -90,7 +94,7 @@ export default {
watch: {
activeIndex(val, oldVal) {
this.resetItemPosition();
this.$emit('index-change', val, oldVal);
this.$emit('change', val, oldVal);
}
},
......@@ -106,13 +110,12 @@ export default {
},
handleItemChange() {
clearTimeout(this.reInitTimer);
this.reInitTimer = setTimeout(() => {
this.setItems();
}, 100);
debounce(100, () => {
this.updateItems();
});
},
setItems() {
updateItems() {
this.items = this.$children.filter(child => child.$options.name === 'ElCarouselItem');
},
......@@ -139,10 +142,17 @@ export default {
this.timer = setInterval(this.playSlides, this.interval);
},
setActiveIndex(index) {
setActiveItem(index) {
if (typeof index === 'string') {
const filteredItems = this.items.filter(item => item.name === index);
if (filteredItems.length > 0) {
index = this.items.indexOf(filteredItems[0]);
}
}
index = Number(index);
if (isNaN(index) || index !== Math.floor(index)) {
console.warn('index must be an integer.');
process.env.NODE_ENV !== 'production' &&
console.warn('[Element Warn][Carousel]index must be an integer.');
return;
}
let length = this.items.length;
......@@ -155,12 +165,12 @@ export default {
}
},
slideToPrev() {
this.setActiveIndex(this.activeIndex - 1);
prev() {
this.setActiveItem(this.activeIndex - 1);
},
slideToNext() {
this.setActiveIndex(this.activeIndex + 1);
next() {
this.setActiveItem(this.activeIndex + 1);
},
handleIndicatorClick(index) {
......@@ -176,17 +186,17 @@ export default {
created() {
this.throttledArrowClick = throttle(300, true, index => {
this.setActiveIndex(index);
this.setActiveItem(index);
});
this.throttledIndicatorHover = throttle(300, index => {
this.handleIndicatorHover(index);
});
window.addEventListener('resize', this.resetItemPosition);
},
mounted() {
this.setItems();
this.updateItems();
this.$nextTick(() => {
addResizeListener(this.$el, this.resetItemPosition);
if (this.initialIndex < this.items.length && this.initialIndex >= 0) {
this.activeIndex = this.initialIndex;
}
......@@ -195,7 +205,7 @@ export default {
},
beforeDestroy() {
window.removeEventListener('resize', this.resetItemPosition);
if (this.$el) removeResizeListener(this.$el, this.resetItemPosition);
}
};
</script>
packages/theme-default/src/carousel.css
View file @ 6c1ea22c
......@@ -56,7 +56,7 @@
margin: 0;
padding: 0;
@modifier out {
@modifier outside {
bottom: calc(var(--carousel-indicator-height) + var(--carousel-indicator-padding-vertical) * 2);
text-align: center;
position: static;
......
test/unit/specs/carousel.spec.js
View file @ 6c1ea22c
......@@ -44,7 +44,7 @@ describe('Carousel', () => {
vm = createVue({
template: `
<div>
<el-carousel :auto-play="false" :initial-index="1">
<el-carousel :autoplay="false" :initial-index="1">
<el-carousel-item v-for="item in 3"></el-carousel-item>
</el-carousel>
</div>
......@@ -83,11 +83,11 @@ describe('Carousel', () => {
}, 10);
});
it('index change', done => {
it('change', done => {
vm = createVue({
template: `
<div>
<el-carousel :interval="50" @index-change="handleIndexChange">
<el-carousel :interval="50" @change="handleChange">
<el-carousel-item v-for="item in 3"></el-carousel-item>
</el-carousel>
</div>
......@@ -99,7 +99,7 @@ describe('Carousel', () => {
};
},
methods: {
handleIndexChange(val, oldVal) {
handleChange(val, oldVal) {
this.val = val;
this.oldVal = oldVal;
}
......@@ -118,7 +118,7 @@ describe('Carousel', () => {
vm = createVue({
template: `
<div>
<el-carousel :auto-play="false">
<el-carousel :autoplay="false">
<el-carousel-item v-for="item in 3"></el-carousel-item>
</el-carousel>
</div>
......@@ -138,7 +138,7 @@ describe('Carousel', () => {
vm = createVue({
template: `
<div>
<el-carousel :auto-play="false" trigger="click">
<el-carousel :autoplay="false" trigger="click">
<el-carousel-item v-for="item in 3"></el-carousel-item>
</el-carousel>
</div>
......@@ -161,11 +161,11 @@ describe('Carousel', () => {
});
describe('methods', () => {
it('setActiveIndex', done => {
it('setActiveItem', done => {
vm = createVue({
template: `
<div>
<el-carousel :auto-play="false">
<el-carousel :autoplay="false">
<el-carousel-item v-for="item in 3"></el-carousel-item>
</el-carousel>
</div>
......@@ -173,7 +173,7 @@ describe('Carousel', () => {
});
setTimeout(() => {
vm.$children[0].setActiveIndex(1);
vm.$children[0].setActiveItem(1);
setTimeout(() => {
expect(vm.$el.querySelectorAll('.el-carousel__item')[1].classList.contains('is-active')).to.true;
done();
......@@ -185,7 +185,7 @@ describe('Carousel', () => {
vm = createVue({
template: `
<div>
<el-carousel :auto-play="false">
<el-carousel :autoplay="false">
<el-carousel-item v-for="item in 3"></el-carousel-item>
</el-carousel>
</div>
......@@ -193,11 +193,11 @@ describe('Carousel', () => {
});
setTimeout(() => {
vm.$children[0].slideToPrev(1);
vm.$children[0].prev(1);
const items = vm.$el.querySelectorAll('.el-carousel__item');
setTimeout(() => {
expect(items[2].classList.contains('is-active')).to.true;
vm.$children[0].slideToNext(1);
vm.$children[0].next(1);
setTimeout(() => {
expect(items[0].classList.contains('is-active')).to.true;
done();
......@@ -211,7 +211,7 @@ describe('Carousel', () => {
vm = createVue({
template: `
<div>
<el-carousel :auto-play="false" card>
<el-carousel :autoplay="false" type="card">
<el-carousel-item v-for="item in 7"></el-carousel-item>
</el-carousel>
</div>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment