一、组件概述swiper 是微信小程序内置的滑块视图容器轮播图组件用于在有限空间内循环展示多张内容视图。它通常与子组件 swiper-item 配合使用swiper 负责容器与滑动行为swiper-item 负责承载每一屏的具体内容。每个 swiper 中只显示一个 swiper-item切换时通过滑动动画过渡。本项目 swiper-switch 演示了 swiper 的四个核心开关属性——指示点、自动播放、衔接滑动、竖向滑动并通过 switch 开关组件实时切换这些属性直观展示各属性的效果差异。1.1 组件构成swiper轮播容器只能放置 swiper-item 作为直接子节点。swiper-item轮播的每一屏宽度和高度默认为 100%仅能放置在 swiper 中。switch开关选择器本项目用它来动态切换 swiper 的属性。1.2 项目文件结构swiper-switch/ ├── app.js # 小程序逻辑 ├── app.json # 全局配置页面、渲染器、自定义导航 ├── app.wxss # 全局样式.box / .title ├── project.config.json # 项目配置 ├── sitemap.json # 索引配置 ├── components/ │ └── navigation-bar/ # 自定义导航栏组件 └── pages/ └── index/ ├── index.js # 页面数据与事件逻辑 ├── index.wxml # swiper switch 结构 ├── index.wxss # 页面样式 └── index.json # 组件注册二、swiper 常用属性swiper 组件支持的属性较多下表列出最常用的部分其中前四项是本示例项目通过开关实时控制的属性。属性名类型默认值说明indicator-dotsBooleanfalse是否显示面板指示点autoplayBooleanfalse是否自动切换circularBooleanfalse是否采用衔接滑动滑到最后一张后回到第一张verticalBooleanfalse滑动方向是否为纵向intervalNumber5000自动切换时间间隔单位毫秒durationNumber500滑动动画时长单位毫秒currentNumber0当前所在滑块的索引indexindicator-colorColorrgba(0,0,0,.3)指示点颜色indicator-active-colorColor#000000当前选中的指示点颜色display-multiple-itemsNumber1同时显示的滑块数量previous-marginString0px前边距可用于露出前一项的一小部分next-marginString0px后边距可用于露出后一项的一小部分easing-functionStringdefault指定 swiper 切换缓动动画类型bindchangeEventHandle—current 改变时触发event.detail {current, source}bindtransitionEventHandle—swiper-item 位置改变时触发bindanimationfinishEventHandle—动画结束时触发说明属性名在 WXML 中写作短横线形式如 indicator-dots在 JavaScript 中通过 setData 控制时使用小驼峰形式如 indicatorDots两者自动对应。2.1 本示例使用的属性组合swiper属性绑定写法swiper indicator-dots{{indicatorDots}} autoplay{{autoplay}} circular{{circular}} vertical{{vertical}} interval{{interval}} duration{{duration}}三、页面结构与实现3.1 WXML 结构pages/index/index.wxml页面整体由自定义导航栏、滚动区域组成。滚动区域内部是一个信息卡片包含标题、swiper 轮播体以及下方的四个开关控制项。完整WXML结构!--index.wxml-- navigation-bar titleWeixin back{{false}} colorblack background#FFF /navigation-bar scroll-view classscrollarea scroll-y typelist view classbox view classtitle中国精神/view swiper indicator-dots{{indicatorDots}} autoplay{{autoplay}} circular{{circular}} vertical{{vertical}} interval{{interval}} duration{{duration}} block wx:for{{background}} wx:keyindex swiper-item view class{{item}} common{{text[index]}}/view /swiper-item /block /swiper view classlayout view classwalkuang text classmy-left指示点/text switch checked{{indicatorDots}} bindchangechangeIndicatorDots/ /view view classwalkuang text classmy-left自动播放/text switch checked{{autoplay}} bindchangechangeAutoplay/ /view view classwalkuang text classmy-left衔接滑动/text switch checked{{circular}} bindchangechangeCircular/ /view view classwalkuang text classmy-left竖向/text switch checked{{vertical}} bindchangechangeVertical/ /view /view /view /scroll-view关键点解析wx:for 遍历 background 数组生成 4 个 swiper-itemwx:keyindex 使用索引作为唯一标识。class{{item}} 动态绑定背景色类名bc-red / bc-green / bc-blue / bc-orange。{{text[index]}} 取出与背景色一一对应的文案井冈山精神、长征精神、延安精神、红岩精神。switch 的 checked 绑定状态变量bindchange 绑定切换处理函数实现“点开关 → 改数据 → 视图更新”的闭环。3.2 页面逻辑pages/index/index.js页面数据与事件处理// index.js Page({ data: { indicatorDots: true, // 显示指示点 autoplay: false, // 不自动播放 circular: false, // 不衔接滑动 vertical: false, // 横向滑动 interval: 2000, // 自动切换间隔 2 秒 duration: 500, // 动画时长 500 毫秒 background: [bc-red, bc-green, bc-blue, bc-orange], text: [井冈山精神, 长征精神, 延安精神, 红岩精神] }, changeIndicatorDots() { this.setData({ indicatorDots: !this.data.indicatorDots }) }, changeAutoplay() { this.setData({ autoplay: !this.data.autoplay }) }, changeCircular() { this.setData({ circular: !this.data.circular }) }, changeVertical() { this.setData({ vertical: !this.data.vertical }) }, })四个处理函数模式完全一致取反当前布尔值后 setData 回去。小程序数据绑定是单向的视图层的属性值来自 datasetData 触发重新渲染因此开关状态与 swiper 表现始终保持同步。3.3 样式index.wxss 摘要关键样式bc-red { background-color: red; } .bc-green { background-color: green; } .bc-blue { background-color: blue; } .bc-orange{ background-color: orange; } .common{ width: 100%; line-height: 320rpx; /* 撑开轮播高度 */ font-size: 60rpx; font-weight: bolder; text-align: center; letter-spacing: 1em; color: yellow; } .walkuang{ display: flex; flex-direction: row; border-bottom: 2rpx solid black; margin: 20rpx 0; padding: 20rpx 0; }注意swiper 默认高度为 150px。若不显式设置高度内容可能被裁剪。本项目通过 .common 的 line-height: 320rpx 撑起每屏高度更规范的做法是直接给 swiper 设置固定高度或 100%。四、四个开关属性的效果说明开关标签绑定属性开启效果关闭效果指示点indicator-dots轮播底部竖向时为右侧显示小圆点标记当前页不显示任何指示点自动播放autoplay每隔 interval 毫秒自动切到下一屏只能手动滑动切换衔接滑动circular滑到最后一张继续滑可回到第一张形成循环滑到最后一张后无法继续向后竖向vertical上下方向滑动指示点移到右侧左右方向滑动默认4.1 属性组合建议自动播放 衔接滑动最常见的轮播广告组合可无限循环播放。指示点 自动播放用户既能看进度也能看到当前页位置。竖向滑动适合做公告栏、滚动消息等纵向内容此时需要足够的容器高度。interval 与 duration 需配合duration 应明显小于 interval否则动画会显得急促、不连贯。五、常用事件与交互swiper 提供三个绑定事件可用于监听轮播状态变化。事件名触发时机event.detail内容bindchangecurrent 改变时{ current, source }source 取值 autoplay / touch / 空bindtransitionswiper-item 位置改变时{ dx, dy }表示在 x / y 轴上的偏移量bindanimationfinish动画结束时无特殊字段swiper bindchangeonSwiperChange bindanimationfinishonAnimFinish ... /swiper // index.js onSwiperChange(e) { console.log(当前第, e.detail.current, 屏来源, e.detail.source) }, onAnimFinish() { console.log(本次滑动动画结束) },六、完整使用步骤若要在新的小程序页面中复用这套写法按以下步骤操作第1步在页面WXML中书写swiper结构swiper indicator-dots{{indicatorDots}} autoplay{{autoplay}} circular{{circular}} vertical{{vertical}} interval{{interval}} duration{{duration}} block wx:for{{list}} wx:keyid swiper-item view classitem{{item.title}}/view /swiper-item /block /swiper第2步在页面JS中定义数据与事件Page({ data: { indicatorDots: true, autoplay: false, circular: false, vertical: false, interval: 2000, duration: 500, list: [ { id: 1, title: 第一屏 }, { id: 2, title: 第二屏 }, { id: 3, title: 第三屏 } ] }, changeIndicatorDots() { this.setData({ indicatorDots: !this.data.indicatorDots }) }, changeAutoplay() { this.setData({ autoplay: !this.data.autoplay }) }, changeCircular() { this.setData({ circular: !this.data.circular }) }, changeVertical() { this.setData({ vertical: !this.data.vertical }) } })第3步设置尺寸与样式swiper { height: 320rpx; /* 必须给高度否则内容会被裁剪 */ } .item { width: 100%; height: 100%; display: flex; align-items: center; justify-content: center; font-size: 60rpx; color: #fff; }第4步若使用自定义导航栏在页面json中注册组件{ usingComponents: { navigation-bar: /components/navigation-bar/navigation-bar } }七、注意事项与常见问题问题现象原因解决办法轮播内容显示不全或被裁剪swiper 默认高度为 150px为 swiper 显式设置高度px 或 rpxswiper-item 里的内容不居中或溢出swiper-item 默认宽高 100%内部元素未设置尺寸给内部元素设置 width/height 100% 并使用 flex 居中竖向滑动时高度不够竖向模式对高度要求更高增大 swiper 高度并确认外层容器有确定高度自动播放不生效autoplay 为 false或 interval 与 duration 值不合理设置 autoplay 为 true且 interval duration属性写了却不生效属性名写成小驼峰或值未用 {{ }} 绑定WXML 中用短横线形式动态值必须用 {{ }} 包裹wx:key 警告wx:for 未提供唯一 key使用 wx:keyindex 或数据中的唯一字段7.1 性能与体验建议swiper-item 数量不宜过多一般控制在 3~8 屏数量大时建议做懒加载。避免在 swiper-item 中放置过于复杂的节点树Skyline 渲染下尤其注意层级。autoplay 与页面隐藏onHide应配合处理用户离开页面时可暂停自动播放以节省资源。本轮示例项目在 app.json 中启用了 Skyline 渲染器与 glass-easel 组件框架基础库版本需 3.0.0 及以上。7.2 相关子属性速查indicator-color指示点未选中时的颜色默认 rgba(0,0,0,.3)。indicator-active-color当前指示点颜色默认 #000000。display-multiple-items一屏同时显示多个滑块适合做卡片式轮播。previous-margin / next-margin左右留白让相邻卡片露出一部分增强层次感。
一、组件概述swiper 是微信小程序内置的滑块视图容器轮播图组件用于在有限空间内循环展示多张内容视图。它通常与子组件 swiper-item 配合使用swiper 负责容器与滑动行为swiper-item 负责承载每一屏的具体内容。每个 swiper 中只显示一个 swiper-item切换时通过滑动动画过渡。本项目 swiper-switch 演示了 swiper 的四个核心开关属性——指示点、自动播放、衔接滑动、竖向滑动并通过 switch 开关组件实时切换这些属性直观展示各属性的效果差异。1.1 组件构成swiper轮播容器只能放置 swiper-item 作为直接子节点。swiper-item轮播的每一屏宽度和高度默认为 100%仅能放置在 swiper 中。switch开关选择器本项目用它来动态切换 swiper 的属性。1.2 项目文件结构swiper-switch/ ├── app.js # 小程序逻辑 ├── app.json # 全局配置页面、渲染器、自定义导航 ├── app.wxss # 全局样式.box / .title ├── project.config.json # 项目配置 ├── sitemap.json # 索引配置 ├── components/ │ └── navigation-bar/ # 自定义导航栏组件 └── pages/ └── index/ ├── index.js # 页面数据与事件逻辑 ├── index.wxml # swiper switch 结构 ├── index.wxss # 页面样式 └── index.json # 组件注册二、swiper 常用属性swiper 组件支持的属性较多下表列出最常用的部分其中前四项是本示例项目通过开关实时控制的属性。属性名类型默认值说明indicator-dotsBooleanfalse是否显示面板指示点autoplayBooleanfalse是否自动切换circularBooleanfalse是否采用衔接滑动滑到最后一张后回到第一张verticalBooleanfalse滑动方向是否为纵向intervalNumber5000自动切换时间间隔单位毫秒durationNumber500滑动动画时长单位毫秒currentNumber0当前所在滑块的索引indexindicator-colorColorrgba(0,0,0,.3)指示点颜色indicator-active-colorColor#000000当前选中的指示点颜色display-multiple-itemsNumber1同时显示的滑块数量previous-marginString0px前边距可用于露出前一项的一小部分next-marginString0px后边距可用于露出后一项的一小部分easing-functionStringdefault指定 swiper 切换缓动动画类型bindchangeEventHandle—current 改变时触发event.detail {current, source}bindtransitionEventHandle—swiper-item 位置改变时触发bindanimationfinishEventHandle—动画结束时触发说明属性名在 WXML 中写作短横线形式如 indicator-dots在 JavaScript 中通过 setData 控制时使用小驼峰形式如 indicatorDots两者自动对应。2.1 本示例使用的属性组合swiper属性绑定写法swiper indicator-dots{{indicatorDots}} autoplay{{autoplay}} circular{{circular}} vertical{{vertical}} interval{{interval}} duration{{duration}}三、页面结构与实现3.1 WXML 结构pages/index/index.wxml页面整体由自定义导航栏、滚动区域组成。滚动区域内部是一个信息卡片包含标题、swiper 轮播体以及下方的四个开关控制项。完整WXML结构!--index.wxml-- navigation-bar titleWeixin back{{false}} colorblack background#FFF /navigation-bar scroll-view classscrollarea scroll-y typelist view classbox view classtitle中国精神/view swiper indicator-dots{{indicatorDots}} autoplay{{autoplay}} circular{{circular}} vertical{{vertical}} interval{{interval}} duration{{duration}} block wx:for{{background}} wx:keyindex swiper-item view class{{item}} common{{text[index]}}/view /swiper-item /block /swiper view classlayout view classwalkuang text classmy-left指示点/text switch checked{{indicatorDots}} bindchangechangeIndicatorDots/ /view view classwalkuang text classmy-left自动播放/text switch checked{{autoplay}} bindchangechangeAutoplay/ /view view classwalkuang text classmy-left衔接滑动/text switch checked{{circular}} bindchangechangeCircular/ /view view classwalkuang text classmy-left竖向/text switch checked{{vertical}} bindchangechangeVertical/ /view /view /view /scroll-view关键点解析wx:for 遍历 background 数组生成 4 个 swiper-itemwx:keyindex 使用索引作为唯一标识。class{{item}} 动态绑定背景色类名bc-red / bc-green / bc-blue / bc-orange。{{text[index]}} 取出与背景色一一对应的文案井冈山精神、长征精神、延安精神、红岩精神。switch 的 checked 绑定状态变量bindchange 绑定切换处理函数实现“点开关 → 改数据 → 视图更新”的闭环。3.2 页面逻辑pages/index/index.js页面数据与事件处理// index.js Page({ data: { indicatorDots: true, // 显示指示点 autoplay: false, // 不自动播放 circular: false, // 不衔接滑动 vertical: false, // 横向滑动 interval: 2000, // 自动切换间隔 2 秒 duration: 500, // 动画时长 500 毫秒 background: [bc-red, bc-green, bc-blue, bc-orange], text: [井冈山精神, 长征精神, 延安精神, 红岩精神] }, changeIndicatorDots() { this.setData({ indicatorDots: !this.data.indicatorDots }) }, changeAutoplay() { this.setData({ autoplay: !this.data.autoplay }) }, changeCircular() { this.setData({ circular: !this.data.circular }) }, changeVertical() { this.setData({ vertical: !this.data.vertical }) }, })四个处理函数模式完全一致取反当前布尔值后 setData 回去。小程序数据绑定是单向的视图层的属性值来自 datasetData 触发重新渲染因此开关状态与 swiper 表现始终保持同步。3.3 样式index.wxss 摘要关键样式bc-red { background-color: red; } .bc-green { background-color: green; } .bc-blue { background-color: blue; } .bc-orange{ background-color: orange; } .common{ width: 100%; line-height: 320rpx; /* 撑开轮播高度 */ font-size: 60rpx; font-weight: bolder; text-align: center; letter-spacing: 1em; color: yellow; } .walkuang{ display: flex; flex-direction: row; border-bottom: 2rpx solid black; margin: 20rpx 0; padding: 20rpx 0; }注意swiper 默认高度为 150px。若不显式设置高度内容可能被裁剪。本项目通过 .common 的 line-height: 320rpx 撑起每屏高度更规范的做法是直接给 swiper 设置固定高度或 100%。四、四个开关属性的效果说明开关标签绑定属性开启效果关闭效果指示点indicator-dots轮播底部竖向时为右侧显示小圆点标记当前页不显示任何指示点自动播放autoplay每隔 interval 毫秒自动切到下一屏只能手动滑动切换衔接滑动circular滑到最后一张继续滑可回到第一张形成循环滑到最后一张后无法继续向后竖向vertical上下方向滑动指示点移到右侧左右方向滑动默认4.1 属性组合建议自动播放 衔接滑动最常见的轮播广告组合可无限循环播放。指示点 自动播放用户既能看进度也能看到当前页位置。竖向滑动适合做公告栏、滚动消息等纵向内容此时需要足够的容器高度。interval 与 duration 需配合duration 应明显小于 interval否则动画会显得急促、不连贯。五、常用事件与交互swiper 提供三个绑定事件可用于监听轮播状态变化。事件名触发时机event.detail内容bindchangecurrent 改变时{ current, source }source 取值 autoplay / touch / 空bindtransitionswiper-item 位置改变时{ dx, dy }表示在 x / y 轴上的偏移量bindanimationfinish动画结束时无特殊字段swiper bindchangeonSwiperChange bindanimationfinishonAnimFinish ... /swiper // index.js onSwiperChange(e) { console.log(当前第, e.detail.current, 屏来源, e.detail.source) }, onAnimFinish() { console.log(本次滑动动画结束) },六、完整使用步骤若要在新的小程序页面中复用这套写法按以下步骤操作第1步在页面WXML中书写swiper结构swiper indicator-dots{{indicatorDots}} autoplay{{autoplay}} circular{{circular}} vertical{{vertical}} interval{{interval}} duration{{duration}} block wx:for{{list}} wx:keyid swiper-item view classitem{{item.title}}/view /swiper-item /block /swiper第2步在页面JS中定义数据与事件Page({ data: { indicatorDots: true, autoplay: false, circular: false, vertical: false, interval: 2000, duration: 500, list: [ { id: 1, title: 第一屏 }, { id: 2, title: 第二屏 }, { id: 3, title: 第三屏 } ] }, changeIndicatorDots() { this.setData({ indicatorDots: !this.data.indicatorDots }) }, changeAutoplay() { this.setData({ autoplay: !this.data.autoplay }) }, changeCircular() { this.setData({ circular: !this.data.circular }) }, changeVertical() { this.setData({ vertical: !this.data.vertical }) } })第3步设置尺寸与样式swiper { height: 320rpx; /* 必须给高度否则内容会被裁剪 */ } .item { width: 100%; height: 100%; display: flex; align-items: center; justify-content: center; font-size: 60rpx; color: #fff; }第4步若使用自定义导航栏在页面json中注册组件{ usingComponents: { navigation-bar: /components/navigation-bar/navigation-bar } }七、注意事项与常见问题问题现象原因解决办法轮播内容显示不全或被裁剪swiper 默认高度为 150px为 swiper 显式设置高度px 或 rpxswiper-item 里的内容不居中或溢出swiper-item 默认宽高 100%内部元素未设置尺寸给内部元素设置 width/height 100% 并使用 flex 居中竖向滑动时高度不够竖向模式对高度要求更高增大 swiper 高度并确认外层容器有确定高度自动播放不生效autoplay 为 false或 interval 与 duration 值不合理设置 autoplay 为 true且 interval duration属性写了却不生效属性名写成小驼峰或值未用 {{ }} 绑定WXML 中用短横线形式动态值必须用 {{ }} 包裹wx:key 警告wx:for 未提供唯一 key使用 wx:keyindex 或数据中的唯一字段7.1 性能与体验建议swiper-item 数量不宜过多一般控制在 3~8 屏数量大时建议做懒加载。避免在 swiper-item 中放置过于复杂的节点树Skyline 渲染下尤其注意层级。autoplay 与页面隐藏onHide应配合处理用户离开页面时可暂停自动播放以节省资源。本轮示例项目在 app.json 中启用了 Skyline 渲染器与 glass-easel 组件框架基础库版本需 3.0.0 及以上。7.2 相关子属性速查indicator-color指示点未选中时的颜色默认 rgba(0,0,0,.3)。indicator-active-color当前指示点颜色默认 #000000。display-multiple-items一屏同时显示多个滑块适合做卡片式轮播。previous-margin / next-margin左右留白让相邻卡片露出一部分增强层次感。
