Merge pull request #77 from FriedRiceNoodles/docs/carousel

Update documentation and demos of carousel.
FriedRiceNoodles · Mar 18, 2024 · 89523fc · 89523fc
2 parents 32874d8 + b5e1a2a
commit 89523fc
Show file tree

Hide file tree

Showing 24 changed files with 297 additions and 38 deletions.
diff --git a/docs/example/Carousel/demos/autoHeight.tsx b/docs/example/Carousel/demos/autoHeight.tsx
@@ -4,7 +4,6 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
 export default function autoHeight() {
   const style = `

diff --git a/docs/example/Carousel/demos/autoplay.tsx b/docs/example/Carousel/demos/autoplay.tsx
@@ -4,7 +4,6 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
 export default function autoplay() {
   const style = `
@@ -20,7 +19,7 @@ export default function autoplay() {
     `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel autoplay autoplayDelay={5000} loop>
         <div className="demo-slide">1</div>
@@ -29,6 +28,6 @@ export default function autoplay() {
         <div className="demo-slide">4</div>
         <div className="demo-slide">5</div>
       </Carousel>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/demos/demo0.tsx → docs/example/Carousel/demos/basicUsage.tsx b/docs/example/Carousel/demos/demo0.tsx → docs/example/Carousel/demos/basicUsage.tsx
@@ -3,9 +3,8 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
-export default function CarouselDemo0() {
+export default function BasicUsage() {
   const style = `
     .demo-slide {
       height: 300px;
@@ -19,7 +18,7 @@ export default function CarouselDemo0() {
   `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel>
         <div className="demo-slide">1</div>
@@ -28,6 +27,6 @@ export default function CarouselDemo0() {
         <div className="demo-slide">4</div>
         <div className="demo-slide">5</div>
       </Carousel>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/demos/demo3.tsx b/docs/example/Carousel/demos/demo3.tsx
@@ -4,7 +4,6 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
 export default function CarouselDemo3() {
   const style = `

diff --git a/docs/example/Carousel/demos/disableDrag.tsx b/docs/example/Carousel/demos/disableDrag.tsx
@@ -4,7 +4,6 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
 export default function disableDrag() {
   const style = `
@@ -20,7 +19,7 @@ export default function disableDrag() {
      `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel disableDrag navigation>
         <div className="demo-slide">1</div>
@@ -29,6 +28,6 @@ export default function disableDrag() {
         <div className="demo-slide">4</div>
         <div className="demo-slide">5</div>
       </Carousel>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/demos/disableFill.tsx b/docs/example/Carousel/demos/disableFill.tsx
@@ -4,7 +4,6 @@
  */
 
 import { Carousel, Divider } from '@banana-ui/react';
-import React from 'react';
 
 export default function disableFill() {
   const style = `
@@ -20,7 +19,7 @@ export default function disableFill() {
      `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel slidesPerView={3} gap={50}>
         <div className="demo-slide">1</div>
@@ -33,6 +32,6 @@ export default function disableFill() {
         <div className="demo-slide">1</div>
         <div className="demo-slide">2</div>
       </Carousel>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/demos/gap.tsx b/docs/example/Carousel/demos/gap.tsx
@@ -4,7 +4,6 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
 export default function gap() {
   const style = `
@@ -20,7 +19,7 @@ export default function gap() {
     `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel gap={50} slidesPerView={3} loop>
         <div className="demo-slide">1</div>
@@ -29,6 +28,6 @@ export default function gap() {
         <div className="demo-slide">4</div>
         <div className="demo-slide">5</div>
       </Carousel>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/demos/indicator.tsx b/docs/example/Carousel/demos/indicator.tsx
@@ -4,7 +4,6 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
 export default function Indicator() {
   const style = `
@@ -20,7 +19,7 @@ export default function Indicator() {
    `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel indicator>
         <div className="demo-slide">1</div>
@@ -29,6 +28,6 @@ export default function Indicator() {
         <div className="demo-slide">4</div>
         <div className="demo-slide">5</div>
       </Carousel>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/demos/demo1.tsx → docs/example/Carousel/demos/loop.tsx b/docs/example/Carousel/demos/demo1.tsx → docs/example/Carousel/demos/loop.tsx
@@ -4,9 +4,8 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
-export default function CarouselDemo1() {
+export default function Loop() {
   const style = `
      .demo-slide {
        height: 300px;
@@ -20,7 +19,7 @@ export default function CarouselDemo1() {
    `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel loop>
         <div className="demo-slide">1</div>
@@ -29,6 +28,6 @@ export default function CarouselDemo1() {
         <div className="demo-slide">4</div>
         <div className="demo-slide">5</div>
       </Carousel>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/demos/navigation.tsx b/docs/example/Carousel/demos/navigation.tsx
@@ -4,7 +4,6 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
 export default function Navigation() {
   const style = `
@@ -20,7 +19,7 @@ export default function Navigation() {
    `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel navigation>
         <div className="demo-slide">1</div>
@@ -29,6 +28,6 @@ export default function Navigation() {
         <div className="demo-slide">4</div>
         <div className="demo-slide">5</div>
       </Carousel>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/demos/demo2.tsx → .../example/Carousel/demos/slidesPerView.tsx b/docs/example/Carousel/demos/demo2.tsx → .../example/Carousel/demos/slidesPerView.tsx
@@ -4,9 +4,8 @@
  */
 
 import { Carousel } from '@banana-ui/react';
-import React from 'react';
 
-export default function CarouselDemo2() {
+export default function SlidesPerView() {
   const style = `
       .demo-slide {
         height: 300px;

diff --git a/docs/example/Carousel/demos/useRef.tsx b/docs/example/Carousel/demos/useRef.tsx
@@ -1,12 +1,13 @@
-/* eslint-disable @typescript-eslint/no-unsafe-return */
-/* eslint-disable @typescript-eslint/no-unsafe-call */
 /**
  * title: 使用useRef手动改变currentIndex
  * debug: true
  */
 
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+/* eslint-disable @typescript-eslint/no-unsafe-call */
+
 import { Button, Carousel } from '@banana-ui/react';
-import React, { useRef } from 'react';
+import { useRef } from 'react';
 
 export default function CarouselDemo0() {
   const carousel = useRef(null);
@@ -24,7 +25,7 @@ export default function CarouselDemo0() {
    `;
 
   return (
-    <div>
+    <>
       <style>{style}</style>
       <Carousel ref={carousel} slidesPerView={5} loop gap={20}>
         <div className="demo-slide">1</div>
@@ -41,6 +42,6 @@ export default function CarouselDemo0() {
 
       <Button onclick={() => carousel.current?.goto(0)}>go 1</Button>
       <Button onclick={() => carousel.current?.goto(9)}>go 10</Button>
-    </div>
+    </>
   );
 }
diff --git a/docs/example/Carousel/index.md b/docs/example/Carousel/index.md
@@ -14,9 +14,9 @@ group: 组件
 
 ## 代码演示
 
-<code src="./demos/demo0.tsx"></code>
-<code src="./demos/demo1.tsx"></code>
-<code src="./demos/demo2.tsx"></code>
+<code src="./demos/basicUsage.tsx"></code>
+<code src="./demos/loop.tsx"></code>
+<code src="./demos/slidesPerView.tsx"></code>
 <code src="./demos/demo3.tsx"></code>
 <code src="./demos/autoplay.tsx"></code>
 <code src="./demos/navigation.tsx"></code>
@@ -26,3 +26,67 @@ group: 组件
 <code src="./demos/disableFill.tsx"></code>
 <code src="./demos/useRef.tsx"></code>
 <code src="./demos/autoHeight.tsx"></code>
+
+## 属性 - Attributes & Properties
+
+| 属性                                                 | 说明                                                                                          | 类型      | 默认值 |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------- | ------ |
+| loop                                                 | 是否循环                                                                                      | `boolean` | false  |
+| slidesPerView <br /> (slides-per-view)               | 同时显示的轮播图数量                                                                          | `number`  | 1      |
+| autoplay                                             | 是否自动播放                                                                                  | `boolean` | false  |
+| autoplayDelay <br /> (autoplay-delay)                | 自动播放的间隔时间，单位为毫秒                                                                | `number`  | 3000   |
+| noPauseOnMouseEnter <br /> (no-pause-on-mouse-enter) | 默认情况下，鼠标移入后会暂停自动播放，传入此属性可以取消这个行为                              | `boolean` | false  |
+| disableDrag <br /> (disable-drag)                    | 是否禁用拖拽                                                                                  | `boolean` | false  |
+| navigation                                           | 是否显示前进后退按钮                                                                          | `boolean` | false  |
+| gap                                                  | 轮播图之间的间隔                                                                              | `number`  | 0      |
+| disableFill <br /> (disable-fill)                    | 默认情况下，当你传入的轮播图个数小于 slidesPerView 时，会自动填充，传入此属性可以取消这个行为 | `boolean` | false  |
+| autoHeight                                           | 是否自动调整高度                                                                              | `boolean` | false  |
+| indicator                                            | 是否显示指示器（默认为小圆点）                                                                | `boolean` | false  |
+
+## 方法 - Methods
+
+| 方法                | 说明               | 参数                |
+| ------------------- | ------------------ | ------------------- |
+| prev()              | 切换到上一张轮播图 | -                   |
+| next()              | 切换到下一张轮播图 | -                   |
+| goto(index: number) | 切换到指定的轮播图 | index: 轮播图的索引 |
+| calcHeight()        | 重新计算并修改高度 | -                   |
+
+## 事件 - Events
+
+| 事件   | 说明             | Event Detail               |
+| ------ | ---------------- | -------------------------- |
+| change | 轮播图切换时触发 | `{ currentIndex: number }` |
+
+## 插槽 - Slots
+
+| 插槽        | 说明            |
+| ----------- | --------------- |
+| (default)   | 轮播图的内容    |
+| prev-button | 切换按钮-上一张 |
+| next-button | 切换按钮-下一张 |
+
+## CSS Parts
+
+| Part                         | 说明                 |
+| ---------------------------- | -------------------- |
+| base                         | 包裹组件的容器       |
+| external-wrapper             | 轮播图内容的外层容器 |
+| slides-wrapper               | 轮播图内容的容器     |
+| slide                        | 轮播图内容的默认插槽 |
+| indicators                   | 指示器的容器         |
+| indicator                    | 指示器               |
+| indicator--active            | 激活状态的指示器     |
+| navigation-buttons           | 切换按钮             |
+| navigation-buttons--disabled | 切换按钮-禁用状态    |
+| navigation-button--previous  | 切换按钮-上一张      |
+| navigation-button--next      | 切换按钮-下一张      |
+
+## 样式变量
+
+| 变量                                  | 说明                                              | 默认值                             |
+| ------------------------------------- | ------------------------------------------------- | ---------------------------------- |
+| --banana-carousel-transition-duration | 切换动画和调整高度时动画的持续时间                | 250ms                              |
+| --banana-carousel-indicator-gap       | 指示器之间的间隔                                  | `--banana-carousel-indicator-size` |
+| --banana-carousel-indicator-size      | 指示器的大小                                      | 8px                                |
+| --banana-carousel-indicator-color     | 指示器的颜色（非激活状态的指示器`opacity`为 0.5） | rgba(46, 50, 56, 1)                |
diff --git a/packages/banana/src/carousel/index.styles.ts b/packages/banana/src/carousel/index.styles.ts
@@ -28,6 +28,8 @@ export default [
     .slides-wrapper {
       display: flex;
       transition: transform var(--banana-carousel-transition-duration, ${unsafeCSS(Var.TransitionNormal)});
+      /* This variable should not be used directly, use the gap property instead */
+      /* DO NOT PUT IT IN THE DOCUMENTATION */
       gap: calc(var(--banana-carousel-gap, 0) * 1px);
     }
 
@@ -36,6 +38,8 @@ export default [
     }
 
     .slides-wrapper ::slotted(*) {
+      /* This variable should not be used directly, use the slidesPerView property instead */
+      /* DO NOT PUT IT IN THE DOCUMENTATION */
       width: calc(
         (100% - (var(--banana-carousel-slidesPerView) - 1) * var(--banana-carousel-gap) * 1px) /
           var(--banana-carousel-slidesPerView)

diff --git a/public/Carousel/autoHeight.html b/public/Carousel/autoHeight.html
@@ -0,0 +1,26 @@
+<style>
+  .autoheight .demo-slide {
+    height: 300px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: linear-gradient(to bottom right, #5193e9, #0e61cd);
+    color: #fff;
+    font-size: 48px;
+  }
+
+  .autoheight .demo-slide:nth-child(2n) {
+    background: linear-gradient(to bottom right, #0e61cd, #5193e9);
+    height: 500px;
+  }
+</style>
+
+<div class="autoheight">
+  <b-carousel navigation auto-height>
+    <div class="demo-slide">1</div>
+    <div class="demo-slide">2</div>
+    <div class="demo-slide">3</div>
+    <div class="demo-slide">4</div>
+    <div class="demo-slide">5</div>
+  </b-carousel>
+</div>