review update

examples/docs/en-US/carousel.md

@@ -61,10 +61,10 @@ 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 `out` 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.
 ```html
 <template>
-  <el-carousel indicator-position="out">
+  <el-carousel indicator-position="outside">
     <el-carousel-item v-for="item in 4">
       <h3>{{ item }}</h3>
     </el-carousel-item>
@@ -95,10 +95,10 @@ Indicators can be displayed outside the carousel
 
 You can define when arrows are displayed
 
-::: demo The `show-arrow` attribute determines when arrows are displayed. By default they appear when mouse hovers over the carousel. Setting `show-arrow` to `always` or `never` shows/hides the arrows permanently.
+::: demo The `arrow` attribute determines when arrows are displayed. By default they appear when mouse hovers over the carousel. Setting `arrow` to `always` or `never` shows/hides the arrows permanently.
 ```html
 <template>
-  <el-carousel :interval="5000" show-arrow="always">
+  <el-carousel :interval="5000" arrow="always">
     <el-carousel-item v-for="item in 4">
       <h3>{{ item }}</h3>
     </el-carousel-item>
@@ -165,11 +165,11 @@ When a page is wide enough but has limited height, you can activate card mode fo
 | 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 | — |
-| arrow-size | size of the arrows | number | — | 36 |
+| auto-play | whether automatically loop the slides | boolean | — | true |
-| interval | interval of the auto loop, in milliseconds. If less than or equal to 0, the carousel will not loop | number | — | 3000 |
+| interval | interval of the auto loop, in milliseconds | number | — | 3000 |
 | indicator-position | position of the indicators | string | out | — |
-| show-indicator | whether indicators are shown | boolean | — | true |
+| indicator | whether indicators are shown | boolean | — | true |
-| show-arrow | when arrows are shown | string | always/never | — |
+| arrow | when arrows are shown | string | always/never | — |
 | card | whether card mode is activated | boolean | — | false |
 
 ### Events
@@ -181,3 +181,5 @@ When a page is wide enough but has limited height, you can activate card mode fo
 | 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 | — |

examples/docs/zh-CN/carousel.md

@@ -68,11 +68,11 @@
 
 适用广泛的基础用法
 
-::: demo 结合使用`el-carousel`和`el-carousel-item`标签就得到了一个走马灯。幻灯片的内容是任意的，需要放在`el-carousel-item`标签中。默认情况下，在鼠标 hover 底部的切换条时就会触发切换。通过设置`trigger`属性为`click`，可以达到点击触发的效果。
+::: demo 结合使用`el-carousel`和`el-carousel-item`标签就得到了一个走马灯。幻灯片的内容是任意的，需要放在`el-carousel-item`标签中。默认情况下，在鼠标 hover 底部的指示器时就会触发切换。通过设置`trigger`属性为`click`，可以达到点击触发的效果。
 ```html
 <template>
   <div class="block">
-    <span class="demonstration">默认 Hover 切换条触发</span>
+    <span class="demonstration">默认 Hover 指示器触发</span>
     <el-carousel height="150px">
       <el-carousel-item v-for="item in 4">
         <h3>{{ item }}</h3>
@@ -80,7 +80,7 @@
     </el-carousel>
   </div>
   <div class="block">
-    <span class="demonstration">Click 切换条触发</span>
+    <span class="demonstration">Click 指示器触发</span>
     <el-carousel trigger="click" height="150px">
       <el-carousel-item v-for="item in 4">
         <h3>{{ item }}</h3>
@@ -109,14 +109,14 @@
 ```
 :::
 
-### 切换条
+### 指示器
 
-可以将切换条的显示位置设置在容器外部
+可以将指示器的显示位置设置在容器外部
 
-::: demo `indicator-position`属性定义了切换条的位置。默认情况下，它会显示在走马灯内部，设置为`out`则会显示在外部。
+::: demo `indicator-position`属性定义了指示器的位置。默认情况下，它会显示在走马灯内部，设置为`outside`则会显示在外部。
 ```html
 <template>
-  <el-carousel indicator-position="out">
+  <el-carousel indicator-position="outside">
     <el-carousel-item v-for="item in 4">
       <h3>{{ item }}</h3>
     </el-carousel-item>
@@ -146,10 +146,10 @@
 ### 切换箭头
 可以设置切换箭头的显示时机
 
-::: demo `show-arrow`属性定义了切换箭头的显示时机。默认情况下，切换箭头只有在鼠标 hover 到走马灯上时才会显示；若将`show-arrow`设置为`always`，则会一直显示；设置为`never`，则会一直隐藏。
+::: demo `arrow`属性定义了切换箭头的显示时机。默认情况下，切换箭头只有在鼠标 hover 到走马灯上时才会显示；若将`arrow`设置为`always`，则会一直显示；设置为`never`，则会一直隐藏。
 ```html
 <template>
-  <el-carousel :interval="5000" show-arrow="always">
+  <el-carousel :interval="5000" arrow="always">
     <el-carousel-item v-for="item in 4">
       <h3>{{ item }}</h3>
     </el-carousel-item>
@@ -214,12 +214,12 @@
 |---------- |-------------- |---------- |--------------------------------  |-------- |
 | height | 走马灯的高度 | number | — | 300 |
 | initial-index | 初始状态激活的幻灯片的索引，从 0 开始 | number | — | 0 |
-| trigger | 切换条的触发方式 | string | click | — |
+| trigger | 指示器的触发方式 | string | click | — |
-| arrow-size | 切换箭头的大小 | number | — | 36 |
+| auto-play | 是否自动切换 | boolean | — | true |
-| interval | 自动切换的时间间隔，单位为毫秒。若小于等于 0，则不会自动切换 | number | — | 3000 |
+| interval | 自动切换的时间间隔，单位为毫秒 | number | — | 3000 |
-| indicator-position | 切换条的位置 | string | out | — |
+| indicator-position | 指示器的位置 | string | out | — |
-| show-indicator | 是否显示切换条 | boolean | — | true |
+| indicator | 是否显示指示器 | boolean | — | true |
-| show-arrow | 切换箭头的显示时机 | string | always/never | — |
+| arrow | 切换箭头的显示时机 | string | always/never | — |
 | card | 是否启用卡片模式 | boolean | — | false |
 
 ### Events
@@ -231,3 +231,5 @@
 | 方法名      | 说明          | 参数 |
 |---------- |-------------- | - |
 | setActiveIndex | 手动切换幻灯片 | 需要切换的幻灯片的索引，从 0 开始 |
+| slideToPrev | 切换至上一张幻灯片 | — |
+| slideToNext | 切换至下一张幻灯片 | — |

packages/carousel/src/item.vue

@@ -4,7 +4,7 @@
     class="el-carousel__item"
     :class="{
       'is-active': active,
-      'is-card': $parent.card,
+      'el-carousel__item--card': $parent.card,
       'is-in-stage': inStage
     }"
     @click="handleItemClick"

packages/carousel/src/main.vue

@@ -1,7 +1,7 @@
 <template>
   <div
     class="el-carousel"
-    :class="{ 'is-card': card }"
+    :class="{ 'el-carousel--card': card }"
     @mouseenter.stop="handleMouseEnter"
     @mouseleave.stop="handleMouseLeave">
     <div
@@ -9,27 +9,19 @@
       :style="{ height: height }">
       <transition name="carousel-arrow-left">
         <button
-          v-if="showArrow !== 'never'"
+          v-if="arrow !== 'never'"
-          v-show="showArrow === 'always' || hover"
+          v-show="arrow === 'always' || hover"
-          :style="{
-            height: `${ arrowSize }px`,
-            width: `${ arrowSize }px`
-          }"
           @click.stop="throttledArrowClick(activeIndex - 1)"
-          class="el-carousel__arrow is-left">
+          class="el-carousel__arrow el-carousel__arrow--left">
           <i class="el-icon-arrow-left"></i>
         </button>
       </transition>
       <transition name="carousel-arrow-right">
         <button
-          v-if="showArrow !== 'never'"
+          v-if="arrow !== 'never'"
-          v-show="showArrow === 'always' || hover"
+          v-show="arrow === 'always' || hover"
-          :style="{
-            height: `${ arrowSize }px`,
-            width: `${ arrowSize }px`
-          }"
           @click.stop="throttledArrowClick(activeIndex + 1)"
-          class="el-carousel__arrow is-right">
+          class="el-carousel__arrow el-carousel__arrow--right">
           <i class="el-icon-arrow-right"></i>
         </button>
       </transition>
@@ -37,8 +29,8 @@
     </div>
     <ul
       class="el-carousel__indicators"
-      v-if="showIndicator"
+      v-if="indicator"
-      :class="{ 'is-out': indicatorPosition === 'out' || card }">
+      :class="{ 'el-carousel__indicators--out': indicatorPosition === 'outside' || card }">
       <li
         v-for="(item, index) in items"
         class="el-carousel__indicator"
@@ -67,20 +59,20 @@ export default {
       type: String,
       default: 'hover'
     },
-    arrowSize: {
+    autoPlay: {
-      type: Number,
+      type: Boolean,
-      default: 36
+      default: true
     },
     interval: {
       type: Number,
       default: 3000
     },
     indicatorPosition: String,
-    showIndicator: {
+    indicator: {
       type: Boolean,
       default: true
     },
-    showArrow: String,
+    arrow: String,
     card: Boolean
   },
 
@@ -130,7 +122,7 @@ export default {
       });
     },
 
-    autoPlay() {
+    playSlides() {
       if (this.activeIndex < this.items.length - 1) {
         this.activeIndex++;
       } else {
@@ -143,13 +135,16 @@ export default {
     },
 
     startTimer() {
-      if (this.interval <= 0) return;
+      if (this.interval <= 0 || !this.autoPlay) return;
-      this.timer = setInterval(this.autoPlay, this.interval);
+      this.timer = setInterval(this.playSlides, this.interval);
     },
 
     setActiveIndex(index) {
       index = Number(index);
-      if (isNaN(index)) return;
+      if (isNaN(index) || index !== Math.floor(index)) {
+        console.warn('index must be an integer.');
+        return;
+      }
       let length = this.items.length;
       if (index < 0) {
         this.activeIndex = length - 1;
@@ -160,6 +155,14 @@ export default {
       }
     },
 
+    slideToPrev() {
+      this.setActiveIndex(this.activeIndex - 1);
+    },
+
+    slideToNext() {
+      this.setActiveIndex(this.activeIndex + 1);
+    },
+
     handleIndicatorClick(index) {
       this.activeIndex = index;
     },

packages/theme-default/src/carousel-item.css

@@ -14,7 +14,7 @@
       transition: .4s ease-in-out;
       overflow: hidden;
 
-      @when card {
+      @modifier card {
         width: 50%;
         z-index: calc(var(--index-normal) - 1);
         &.is-in-stage {

packages/theme-default/src/carousel.css

@@ -17,6 +17,7 @@
       outline: none;
       padding: 0;
       margin: 0;
+      size: var(--carousel-arrow-size);
       cursor: pointer;
       transition: .3s;
       border-radius: 50%;
@@ -29,11 +30,11 @@
       text-align: center;
       font-size: var(--carousel-arrow-font-size);
 
-      @when left {
+      @modifier left {
         left: 16px;
       }
 
-      @when right {
+      @modifier right {
         right: 16px;
       }
 
@@ -55,7 +56,7 @@
       margin: 0;
       padding: 0;
 
-      @when out {
+      @modifier out {
         bottom: calc(var(--carousel-indicator-height) + var(--carousel-indicator-padding-vertical) * 2);
         text-align: center;
         position: static;

packages/theme-default/src/common/var.css

@@ -548,6 +548,7 @@
   /* Carousel
   --------------------------*/
   --carousel-arrow-font-size: 12px;
+  --carousel-arrow-size: 36px;
   --carousel-arrow-background: rgba(31, 45, 61, 0.11);
   --carousel-arrow-hover-background: rgba(31, 45, 61, 0.23);
   --carousel-indicator-width: 30px;

test/unit/specs/carousel.spec.js

@@ -44,7 +44,7 @@ describe('Carousel', () => {
     vm = createVue({
       template: `
         <div>
-          <el-carousel :interval="0" :initial-index="1">
+          <el-carousel :auto-play="false" :initial-index="1">
             <el-carousel-item v-for="item in 3"></el-carousel-item>
           </el-carousel>
         </div>
@@ -118,7 +118,7 @@ describe('Carousel', () => {
       vm = createVue({
         template: `
         <div>
-          <el-carousel :interval="0">
+          <el-carousel :auto-play="false">
             <el-carousel-item v-for="item in 3"></el-carousel-item>
           </el-carousel>
         </div>
@@ -126,7 +126,7 @@ describe('Carousel', () => {
       });
 
       setTimeout(() => {
-        vm.$children[0].handleIndicatorHover(1);
+        vm.$children[0].throttledIndicatorHover(1);
         setTimeout(() => {
           expect(vm.$el.querySelectorAll('.el-carousel__item')[1].classList.contains('is-active')).to.true;
           done();
@@ -138,7 +138,7 @@ describe('Carousel', () => {
       vm = createVue({
         template: `
         <div>
-          <el-carousel :interval="0" trigger="click">
+          <el-carousel :auto-play="false" trigger="click">
             <el-carousel-item v-for="item in 3"></el-carousel-item>
           </el-carousel>
         </div>
@@ -150,7 +150,54 @@ describe('Carousel', () => {
         vm.$el.querySelectorAll('.el-carousel__indicator')[2].click();
         setTimeout(() => {
           expect(items[2].classList.contains('is-active')).to.true;
-          vm.$el.querySelector('.el-carousel__arrow.is-right').click();
+          vm.$el.querySelector('.el-carousel__arrow--right').click();
+          setTimeout(() => {
+            expect(items[0].classList.contains('is-active')).to.true;
+            done();
+          }, 10);
+        }, 10);
+      }, 10);
+    });
+  });
+
+  describe('methods', () => {
+    it('setActiveIndex', done => {
+      vm = createVue({
+        template: `
+        <div>
+          <el-carousel :auto-play="false">
+            <el-carousel-item v-for="item in 3"></el-carousel-item>
+          </el-carousel>
+        </div>
+      `
+      });
+
+      setTimeout(() => {
+        vm.$children[0].setActiveIndex(1);
+        setTimeout(() => {
+          expect(vm.$el.querySelectorAll('.el-carousel__item')[1].classList.contains('is-active')).to.true;
+          done();
+        }, 10);
+      }, 10);
+    });
+
+    it('slide', done => {
+      vm = createVue({
+        template: `
+        <div>
+          <el-carousel :auto-play="false">
+            <el-carousel-item v-for="item in 3"></el-carousel-item>
+          </el-carousel>
+        </div>
+      `
+      });
+
+      setTimeout(() => {
+        vm.$children[0].slideToPrev(1);
+        const items = vm.$el.querySelectorAll('.el-carousel__item');
+        setTimeout(() => {
+          expect(items[2].classList.contains('is-active')).to.true;
+          vm.$children[0].slideToNext(1);
           setTimeout(() => {
             expect(items[0].classList.contains('is-active')).to.true;
             done();
@@ -164,7 +211,7 @@ describe('Carousel', () => {
     vm = createVue({
       template: `
         <div>
-          <el-carousel :interval="0" card>
+          <el-carousel :auto-play="false" card>
             <el-carousel-item v-for="item in 7"></el-carousel-item>
           </el-carousel>
         </div>
@@ -179,7 +226,7 @@ describe('Carousel', () => {
       items[1].click();
       setTimeout(() => {
         expect(items[1].classList.contains('is-active')).to.true;
-        vm.$el.querySelector('.el-carousel__arrow.is-left').click();
+        vm.$el.querySelector('.el-carousel__arrow--left').click();
         setTimeout(() => {
           expect(items[0].classList.contains('is-active')).to.true;
           items[6].click();