Merge pull request #669 from Tencent/docs/swiper

feat(Swiper): support pagination-position
Tencent · Jul 29, 2022 · 8d7100f · 8d7100f
2 parents ef2a351 + 1ca3e46
commit 8d7100f
Show file tree

Hide file tree

Showing 31 changed files with 620 additions and 402 deletions.
diff --git a/src/swiper/README.md b/src/swiper/README.md
@@ -21,84 +21,71 @@ isComponent: true
 
 swiper 必须配合 swiper-item 使用，swiper-item 作为轮播条目组件，宽高默认 100%。
 
-## 代码演示
 
-### 基础轮播图
+### 主题定制
+CSS 变量名|说明
+--|--
+--td-swiper-nav-dot-color | 点状导航器颜色
+--td-swiper-nav-dot-active-color | 点状导航器激活态颜色
+--td-swiper-nav-fraction-color | 分式导航器颜色
+--td-swiper-nav-fraction-bg-color | 分式导航器背景颜色
+--td-swiper-nav-btn-color | 按钮导航器颜色
+--td-swiper-nav-btn-bg-color | 按钮导航器背景颜色
+
+
+## 代码演示
 
 多种轮播样式，通过 `navigation` 设置导航样式，没有值则不显示，也可以自定义 `nav` 组件
 
 <img src="https://tdesign.gtimg.com/miniprogram/readme/swiper.gif" width="375px" height="50%">
 
-```html
-<!-- 默认样式 -->
-<t-swiper t-class="swiper-wrap" current="{{current}}" bindchange="onChange" navigation>
-  <t-swiper-item wx:for="{{items}}" wx:key="index">
-    <view class="item {{item.cls}}">{{index}}<image src="{{item.image}}" class="img" /></view>
-  </t-swiper-item>
-</t-swiper>
-
-<!-- 使用插槽组合 自定义nav组件 -->
-<t-swiper current="{{1}}" autoplay="{{true}}" duration="{{500}}" interval="{{5000}}">
-  <t-swiper-item wx:for="{{items}}" wx:key="index">
-    <view class="item {{item.cls}}">{{index}}<image src="{{item.image}}" class="img" /></view>
-  </t-swiper-item>
-  <t-swiper-nav slot="nav" type="dots-bar" />
-</t-swiper>
-```
 
-```js
-data: {
-  current: 1,
-  items: [
-    {
-      cls: 'item0',
-      image: `01.png`,
-    },
-    {
-      cls: 'item1',
-      image: `02.png`,
-    },
-    {
-      cls: 'item2',
-      image: `03.png`,
-    },
-    {
-      cls: 'item3',
-      image: `04.png`,
-    },
-    {
-      cls: 'item4',
-      image: `05.png`,
-    },
-  ],
-},
-
-onChange(e) {
-  const {
-    detail: { current, source },
-  } = e;
-  console.log(current, source)
-},
-```
+### 点状(dots)轮播图
+{{ base }}
 
-## API
+### 分式(fraction)导航器轮播图
+
+{{ fraction }}
 
+### 插槽自定义导航器轮播图
+
+{{ custom }}
+
+### 按钮导航器轮播图
+
+{{ nav-btn }}
+
+### 轮播图垂直样式
+
+{{ vertical }}
+
+## API
 ### Swiper Props
 
-| 名称       | 类型    | 默认值     | 说明                                                                                                                                                                                                                                                                                                                  | 必传 |
-| ---------- | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
-| animation  | String  | slide      | 轮播切换动画效果类型。可选项：slide                                                                                                                                                                                                                                                                                   | N    |
-| autoplay   | Boolean | true       | 是否自动播放                                                                                                                                                                                                                                                                                                          | N    |
-| current    | Number  | 0          | 当前轮播在哪一项（下标）                                                                                                                                                                                                                                                                                              | N    |
-| direction  | String  | horizontal | 轮播滑动方向，包括横向滑动和纵向滑动两个方向。可选项：horizontal/vertical                                                                                                                                                                                                                                             | N    |
-| duration   | Number  | 300        | 滑动动画时长                                                                                                                                                                                                                                                                                                          | N    |
-| height     | Number  | -          | 当使用垂直方向滚动时的高度                                                                                                                                                                                                                                                                                            | N    |
-| interval   | Number  | 5000       | 轮播间隔时间                                                                                                                                                                                                                                                                                                          | N    |
-| navigation | Object  | -          | 导航配置。`navigation.type` 表示导航器风格，圆点/分式等，没有值则不显示。`navigation.minShowNum` 表示小于这个数字不会显示导航器。`navigation.showSlideBtn` 表示是否显示两侧的滑动控制按钮。TS 类型：`Navigation`。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/swiper/type.ts) | N    |
+名称 | 类型 | 默认值 | 说明 | 必传
+-- | -- | -- | -- | --
+animation | String | slide | 轮播切换动画效果类型。可选项：slide | N
+autoplay | Boolean | true | 是否自动播放 | N
+current | Number | 0 | 当前轮播在哪一项（下标） | N
+default-current | Number | undefined | 当前轮播在哪一项（下标）。非受控属性 | N
+direction | String | horizontal | 轮播滑动方向，包括横向滑动和纵向滑动两个方向。可选项：horizontal/vertical | N
+duration | Number | 300 | 滑动动画时长 | N
+height | Number | - | 当使用垂直方向滚动时的高度 | N
+interval | Number | 5000 | 轮播间隔时间 | N
+loop | Boolean | true | 【开发中】是否循环播放 | N
+navigation | Object / Slot | - | 导航器全部配置 | N
+pagination-position | String | bottom-right | 页码信息展示位置。可选项：top-left/top/top-right/bottom-left/bottom/bottom-right | N
 
 ### Swiper Events
 
 名称 | 参数 | 描述
 -- | -- | --
 change | `(current: number, source: SwiperChangeSource)` | 轮播切换时触发。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/swiper/type.ts)。<br/>`type SwiperChangeSource = 'autoplay' | 'touch' | ''`<br/>
 
+### SwiperNavigation
+
+名称 | 类型 | 默认值 | 说明 | 必传
+-- | -- | -- | -- | --
+min-show-num | Number | - | 小于这个数字不会显示导航器 | N
+show-slide-btn | Boolean | - | 表示是否显示两侧的滑动控制按钮 | N
+type | String | - | 导航器类型，点状(dots)、点条状(dots-bar)、分式(fraction)等。TS 类型：`SwiperNavigationType` `type SwiperNavigationType = 'dots' | 'dots-bar' | 'fraction'`。[详细类型定义](https://github.com/Tencent/tdesign-miniprogram/tree/develop/src/swiper/type.ts) | N
diff --git a/src/swiper/_example/base/index.js b/src/swiper/_example/base/index.js
@@ -0,0 +1,37 @@
+const imageCdn = 'https://tdesign.gtimg.com/site/swiper';
+const swiperList = [
+  {
+    image: `${imageCdn}/01.png`,
+  },
+  {
+    image: `${imageCdn}/02.png`,
+  },
+  {
+    image: `${imageCdn}/03.png`,
+  },
+  {
+    image: `${imageCdn}/04.png`,
+  },
+  {
+    image: `${imageCdn}/05.png`,
+  },
+];
+
+Component({
+  data: {
+    current: 1,
+    autoplay: true,
+    duration: 500,
+    interval: 5000,
+    swiperList,
+  },
+
+  methods: {
+    onChange(e) {
+      const {
+        detail: { current, source },
+      } = e;
+      console.log(current, source);
+    },
+  },
+});
diff --git a/src/swiper/_example/base/index.json b/src/swiper/_example/base/index.json
@@ -0,0 +1,7 @@
+{
+  "component": true,
+  "usingComponents": {
+    "t-swiper": "tdesign-miniprogram/swiper/swiper",
+    "t-swiper-item": "tdesign-miniprogram/swiper/swiper-item"
+  }
+}
diff --git a/src/swiper/_example/base/index.wxml b/src/swiper/_example/base/index.wxml
@@ -0,0 +1,12 @@
+<t-swiper
+  current="{{current}}"
+  autoplay="{{autoplay}}"
+  duration="{{duration}}"
+  interval="{{interval}}"
+  bindchange="onChange"
+  navigation
+>
+  <t-swiper-item wx:for="{{swiperList}}" wx:key="index">
+    <image src="{{item.image}}" class="img" />
+  </t-swiper-item>
+</t-swiper>
diff --git a/src/swiper/_example/base/index.wxss b/src/swiper/_example/base/index.wxss
@@ -0,0 +1,4 @@
+.img {
+  width: 100%;
+  height: 100%;
+}
diff --git a/src/swiper/_example/custom/index.js b/src/swiper/_example/custom/index.js
@@ -0,0 +1,28 @@
+const imageCdn = 'https://tdesign.gtimg.com/site/swiper';
+const swiperList = [
+  {
+    image: `${imageCdn}/01.png`,
+  },
+  {
+    image: `${imageCdn}/02.png`,
+  },
+  {
+    image: `${imageCdn}/03.png`,
+  },
+  {
+    image: `${imageCdn}/04.png`,
+  },
+  {
+    image: `${imageCdn}/05.png`,
+  },
+];
+
+Component({
+  data: {
+    current: 1,
+    autoplay: true,
+    duration: 500,
+    interval: 5000,
+    swiperList,
+  },
+});
diff --git a/src/swiper/_example/custom/index.json b/src/swiper/_example/custom/index.json
@@ -0,0 +1,8 @@
+{
+  "component": true,
+  "usingComponents": {
+    "t-swiper": "tdesign-miniprogram/swiper/swiper",
+    "t-swiper-item": "tdesign-miniprogram/swiper/swiper-item",
+    "t-swiper-nav": "tdesign-miniprogram/swiper/swiper-nav"
+  }
+}
diff --git a/src/swiper/_example/custom/index.wxml b/src/swiper/_example/custom/index.wxml
@@ -0,0 +1,7 @@
+<t-swiper current="{{current}}" autoplay="{{autoplay}}" duration="{{duration}}" interval="{{interval}}">
+  <t-swiper-item wx:for="{{swiperList}}" wx:key="index">
+    <image src="{{item.image}}" class="img" />
+  </t-swiper-item>
+  <!-- 使用插槽组合，可自定义nav组件 -->
+  <t-swiper-nav slot="nav" type="dots-bar" />
+</t-swiper>
diff --git a/src/swiper/_example/custom/index.wxss b/src/swiper/_example/custom/index.wxss
@@ -0,0 +1,4 @@
+.img {
+  width: 100%;
+  height: 100%;
+}
diff --git a/src/swiper/_example/fraction/index.js b/src/swiper/_example/fraction/index.js
@@ -0,0 +1,30 @@
+const imageCdn = 'https://tdesign.gtimg.com/site/swiper';
+const swiperList = [
+  {
+    image: `${imageCdn}/01.png`,
+  },
+  {
+    image: `${imageCdn}/02.png`,
+  },
+  {
+    image: `${imageCdn}/03.png`,
+  },
+  {
+    image: `${imageCdn}/04.png`,
+  },
+  {
+    image: `${imageCdn}/05.png`,
+  },
+];
+
+Component({
+  data: {
+    current: 2,
+    autoplay: true,
+    duration: 500,
+    interval: 5000,
+    paginationPosition: 'bottom-right',
+    swiperList,
+    navigation: { type: 'fraction' },
+  },
+});
diff --git a/src/swiper/_example/fraction/index.json b/src/swiper/_example/fraction/index.json
@@ -0,0 +1,7 @@
+{
+  "component": true,
+  "usingComponents": {
+    "t-swiper": "tdesign-miniprogram/swiper/swiper",
+    "t-swiper-item": "tdesign-miniprogram/swiper/swiper-item"
+  }
+}
diff --git a/src/swiper/_example/fraction/index.wxml b/src/swiper/_example/fraction/index.wxml
@@ -0,0 +1,12 @@
+<t-swiper
+  current="{{current}}"
+  autoplay="{{autoplay}}"
+  duration="{{duration}}"
+  interval="{{interval}}"
+  navigation="{{navigation}}"
+  paginationPosition="{{paginationPosition}}"
+>
+  <t-swiper-item wx:for="{{swiperList}}" wx:key="index">
+    <image src="{{item.image}}" class="img" />
+  </t-swiper-item>
+</t-swiper>
diff --git a/src/swiper/_example/fraction/index.wxss b/src/swiper/_example/fraction/index.wxss
@@ -0,0 +1,4 @@
+.img {
+  width: 100%;
+  height: 100%;
+}
diff --git a/src/swiper/_example/nav-btn/index.js b/src/swiper/_example/nav-btn/index.js
@@ -0,0 +1,29 @@
+const imageCdn = 'https://tdesign.gtimg.com/site/swiper';
+const swiperList = [
+  {
+    image: `${imageCdn}/01.png`,
+  },
+  {
+    image: `${imageCdn}/02.png`,
+  },
+  {
+    image: `${imageCdn}/03.png`,
+  },
+  {
+    image: `${imageCdn}/04.png`,
+  },
+  {
+    image: `${imageCdn}/05.png`,
+  },
+];
+
+Component({
+  data: {
+    current: 3,
+    autoplay: true,
+    duration: 500,
+    interval: 5000,
+    swiperList,
+    navigation: { type: '', hasNavBtn: true },
+  },
+});
diff --git a/src/swiper/_example/nav-btn/index.json b/src/swiper/_example/nav-btn/index.json
@@ -0,0 +1,7 @@
+{
+  "component": true,
+  "usingComponents": {
+    "t-swiper": "tdesign-miniprogram/swiper/swiper",
+    "t-swiper-item": "tdesign-miniprogram/swiper/swiper-item"
+  }
+}
diff --git a/src/swiper/_example/nav-btn/index.wxml b/src/swiper/_example/nav-btn/index.wxml
@@ -0,0 +1,11 @@
+<t-swiper
+  current="{{current}}"
+  autoplay="{{autoplay}}"
+  duration="{{duration}}"
+  interval="{{interval}}"
+  navigation="{{navigation}}"
+>
+  <t-swiper-item wx:for="{{swiperList}}" wx:key="index">
+    <image src="{{item.image}}" class="img" />
+  </t-swiper-item>
+</t-swiper>
diff --git a/src/swiper/_example/nav-btn/index.wxss b/src/swiper/_example/nav-btn/index.wxss
@@ -0,0 +1,4 @@
+.img {
+  width: 100%;
+  height: 100%;
+}
diff --git a/src/swiper/_example/swiper.json b/src/swiper/_example/swiper.json
@@ -3,6 +3,11 @@
   "navigationBarBackgroundColor": "#fff",
   "backgroundColor": "#fff",
   "usingComponents": {
-    "t-demo": "../../components/demo-block/index"
+    "t-demo": "../../components/demo-block/index",
+    "base": "./base",
+    "fraction": "./fraction",
+    "nav-btn": "./nav-btn",
+    "custom": "./custom",
+    "vertical": "./vertical"
   }
 }