微信小程序 scroll‑view 组件实战：实现纵向与横向滚动-平芜编程栈

前言

scroll‑view是微信小程序中非常重要的滚动视图组件，可以实现纵向滚动和横向滚动，很多轮播、长列表、横向滑动卡片都是基于该组件开发。本篇通过完整案例，带你掌握 scroll‑view 常用属性、滚动事件、自动定位到指定子元素，同时讲解伪元素居中、webview 渲染引擎踩坑点。

实现效果：页面分为上下两部分，上方纵向滚动区域初始化自动定位到第二页；下方横向滚动区域，初始偏移 50px；滚动时控制台打印对应日志；支持滚动到顶部、底部触发回调。

效果预览

纵向滚动：可以上下滑动切换第 1、2、3 页，页面初始化自动滚动到page2；
横向滚动：可以左右滑动页面；
滚动监听：滑动过程控制台打印滚动日志；滚动触达顶部 / 底部会输出提示信息。

踩坑提示：本案例使用换行符\n，Skyline 渲染引擎不支持，app.json需要配置renderer:"webview"。

一、新建小程序项目

打开微信开发者工具新建项目：

项目名称：scroll‑view组件
后端服务：不使用云服务
模板选择：不使用模板
填入 AppID，点击创建。

修改app.json，设置 webview 渲染引擎：

{ "pages": [ "pages/index/index" ], "window": { "navigationBarTextStyle": "black", "navigationStyle": "custom" }, "style": "v2", "renderer": "webview", "componentFramework": "glass‑easel", "sitemapLocation": "sitemap.json", "lazyCodeLoading": "requiredComponents" }

如果是 skyline 渲染引擎，\n换行不会生效，务必改为 webview。

二、编写 index.wxml 页面结构

<!--index.wxml--> <navigation‑bar title="scroll‑view组件" back="{{false}}" color="black" background="#FFF"></navigation‑bar> <scroll‑view class="scrollarea" scroll‑y type="list"> <view class="box"> <view class="title">滚动视图示例</view> <view class="page‑section‑title"> <text>Vertical Scroll\n纵向滚动</text> </view> <!--纵向滚动 scroll‑y --> <scroll‑view scroll‑y="true" style="height: 300rpx;" class="sheet" scroll‑into‑view="page2" bindscrolltoupper="upper" bindscrolltolower="lower" bindscroll="scroll_y"> <view id="page1" class="scroll‑view‑item‑y page1"></view> <view id="page2" class="scroll‑view‑item‑y page2"></view> <view id="page3" class="scroll‑view‑item‑y page3"></view> </scroll‑view> <view class="page‑section‑title"> <text>Horizontal Scroll\n横向滚动</text> </view> <!--横向滚动 scroll‑x --> <scroll‑view scroll‑x="true" class="scroll‑view‑x" scroll‑left="50" bindscroll="scroll_x"> <view class="scroll‑view‑item‑x page1"></view> <view class="scroll‑view‑item‑x page2"></view> <view class="scroll‑view‑item‑x page3"></view> </scroll‑view> </view> </scroll‑view>

scroll‑view 核心属性说明

表格

属性	说明
`scroll‑y="true"`	开启垂直纵向滚动，必须设置固定高度才会生效
`scroll‑x="true"`	开启水平横向滚动，子元素需要`inline‑block`，父容器`white‑space:nowrap`禁止换行
`scroll‑into‑view="id"`	自动滚动到指定 id 的子节点，id 不能数字开头；本案例初始化直接跳到 page2
`scroll‑left`	横向滚动初始偏移像素值
`bindscrolltoupper`	滚动触达顶部 / 最左边触发
`bindscrolltolower`	滚动触达底部 / 最右边触发
`bindscroll`	滚动过程持续触发

三、编写样式代码

app.wxss 全局样式

/**app.wxss**/ .box { /* 设置外边距 */ margin: 20rpx; /* 设置内边距 */ padding: 20rpx; /* 设置边框 */ border: 2rpx solid silver; } .title { /* 设置字体大小 */ font‑size: 40rpx; /* 设置字体加粗 */ font‑weight: bolder; /* 设置居中对齐 */ text‑align: center; /* 设置下外边距 */ margin‑bottom: 30rpx; /* 设置字体颜色 */ color: red; }

index.wxss 页面样式

/**index.wxss**/ page { height: 100vh; /* flex布局 */ display: flex; /* 按纵向排列 */ flex‑direction: column; } .scrollarea { flex: 1; overflow‑y: hidden; } .page‑section‑title { font‑size: 40rpx; text‑align: center; margin‑top: 40rpx; margin‑bottom: 20rpx; } .scroll‑view‑item‑y { height: 300rpx; } .scroll‑view‑item‑x { /* 创建了一个内联级块容器 */ display: inline‑block; width: 100%; height: 300rpx; } .sheet { font‑size: 50rpx; /* 字符间距 */ letter‑spacing: 1.2em; } .page1 { /* 相对定位 */ position: relative; background‑color: #1AAD19; color: #FFFFFF; } /* 伪类选择器 */ .page1::before { content: '第一页'; /* 绝对定位 */ position: absolute; /* 元素从父元素的顶部向下移动50% */ top: 50%; /* 元素从父元素的最左端往右移动50% */ left: 50%; /* 元素在水平方向上向左移动自身宽度的50%，向上移动自身宽度的50% */ transform: translate(-50%, -50%); } .page2 { /* 相对定位 */ position: relative; background‑color: #2782D7; color: #FFFFFF; } /* 伪类选择器 */ .page2::before { content: '第二页'; /* 绝对定位 */ position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); } .page3 { /* 相对定位 */ position: relative; background‑color: purple; color: #FFFFFF; } /* 伪类选择器 */ .page3::before { content: '第三页'; position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); } .scroll‑view‑x { /* 不换行 */ white‑space: nowrap; }

知识点：position+transform:translate(-50%,-50%)实现文字完美居中；横向滚动子元素必须inline‑block，父容器white‑space:nowrap禁止自动换行，否则横向滚动失效。

四、编写 index.js 逻辑代码

// index.js Page({ /** * 滚动到达顶部/左侧触发 */ upper(e) { console.log('to upper'); }, /** * 滚动到达底部/右侧触发 */ lower(e) { console.log('to lower'); }, /** * 纵向滚动过程持续触发 */ scroll_y(e) { console.log('vertical scrolling'); }, /** * 横向滚动过程持续触发 */ scroll_x(e) { console.log('Horizontal Scrolling'); } })

事件说明

upper：纵向滚动滑到最顶部、横向滚动滑到最左侧触发；
lower：纵向滚动滑到底部、横向滚动滑到最右侧触发；
scroll_y：纵向滚动过程持续执行；
scroll_x：横向滚动过程持续执行；

在调试器 Console 面板，可以观察打印日志。

五、作业拓展：横向滚动新增页面

需求：横向滚动视图增加一页，背景为土黄色，文字 “阳光灿烂”

在横向的scroll‑view内部新增 view，增加 class；

<view class="scroll‑view‑item‑x page4"></view>

在index.wxss增加 page4 样式，使用::before伪元素写文字：

.page4 { position: relative; background‑color: #cc7722; color: #ffffff; } .page4::before{ content:"阳光灿烂"; position:absolute; top:50%; left:50%; transform: translate(-50%,‑50%); }

保存运行，横向滑动即可看到新增页面。

六、知识点总结

表格

知识点	要点
scroll‑y 纵向滚动	必须给 scroll‑view 设置固定高度，否则滚动无效；`scroll‑into‑view`自动滚动到指定 id 节点
scroll‑x 横向滚动	子元素`display:inline‑block`，父容器`white‑space:nowrap`禁止换行；`scroll‑left`设置初始偏移
滚动事件	bindscrolltoupper 到顶、bindscrolltolower 到底，bindscroll 滚动中持续触发
CSS 居中技巧	relative+absolute+transform:translate (-50%,‑50%) 完美居中；::before 伪元素填充文本
渲染引擎坑	`\n`换行符号在 skyline 不支持，app.json 改为`renderer:"webview"`