Scrolling Container
ScrollView
Usage Instructions
Scrolling Container can achieve the scrolling effect for pages or functional modules. When the total width/height occupied by the component content inside the scrolling container exceeds the width/height of the scrolling container itself, scroll bars will appear, allowing users to slide the scroll bars to view all content within the container. Example as below:
- Drag a Scrolling Container component and set its height to 300
- Add three image components to the scrolling container, setting the height of each image component to 200. This will make the total height of the components inside the container exceed the container's own height, causing the scroll bar to appear.
Property Introduction
组件接收的外部传入的属性
属性名 | 属性标识 | 类型 | 说明 |
|---|
| 允许横向滚动 | scrollX | boolean | 开启后，将开启横向滚动条，组件支持左右滚动 示例：false |
| 允许纵向滚动 | scrollY | boolean | 开启后，将开启纵向滚动条，组件支持上下滚动 示例：true |
| 滚到的元素ID(WEB端) | scrollIntoView | string | 小程序暂时不支持此特性 将当前的元素滚动到浏览器窗口的可视区域内 |
| 横向滚动条位置 | scrollLeft | number | 输入默认值，横向滚动条将默认移动到该位置 |
| 竖向滚动条位置 | scrollTop | number | 输入默认值，竖向滚动条将默认移动到该位置 |
| 距底部/右边多远时，触发scrolltolower事件 | lowerThreshold | number | 示例：50 |
| 距顶部/左边多远时，触发scrolltoupper事件 | upperThreshold | number | 示例：50 |
| 滚动条显隐控制(小程序) | showScrollbar | boolean | 隐藏滚动条需启用 scroll-view 增强特性后生效 控制滚动条是否显示/隐藏 示例：true |
| 启用 scroll-view 增强特性(小程序) | enhanced | boolean | 开启scroll-view增强特性 示例：false |
| iOS 下 scroll-view 边界弹性控制(小程序) | bounces | boolean | 示例：true |
| 分页滑动效果(小程序) | pagingEnabled | boolean | 示例：false |
| 滑动减速速率控制(小程序) | fastDeceleration | boolean | 示例：false |
| 开启自定义下拉刷新(小程序) | refresherEnabled | boolean | 开启后可自定义对下拉刷新进行相关配置 示例：false |
| 设置自定义下拉刷新阈值(小程序) | refresherThreshold | number | 示例：50 |
| 设置自定义下拉刷新默认样式(小程序) | refresherDefaultStyle | string | 示例："block" |
| 设置自定义下拉刷新区域背景颜色(小程序) | refresherBackground | string | 示例："#fff" |
| 设置当前下拉刷新状态(小程序) | refresherTriggered | boolean | 示例：false |
| 开启 scroll anchoring 特性(小程序) | scrollAnchoring | boolean | 开启scroll-anchoring特性 示例：false |
| 启用 flexbox 布局(小程序) | enableFlex | boolean | 开启flexbox布局 示例：false |
| iOS点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向(小程序) | enableBackToTop | boolean | 开启后当执行对应操作后滚动条将自动返回顶部 示例：false |
| 在设置滚动条位置时使用动画过渡(小程序) | scrollWithAnimation | boolean | 开启滚动条动画 示例：false |
Event Introduction
组件暴露的事件，可以监听组件的事件来触发一些外部的动作
事件名 | 事件code | 事件出参 event.detail | 适用情况 | 说明 |
|---|
| 滚动时触发 | scroll | 兼容三端 | - | |
| 滚动到底部/右边时触发 | scrolltolower | 兼容三端 | - | |
| 滚动到顶部/左边时触发 | scrolltoupper | 兼容三端 | - | |
| 滑动开始事件(同时开启 enhanced 属性后生效) | dragstart | 小程序 | - | |
| 滑动事件(同时开启 enhanced 属性后生效) | dragging | 小程序 | - | |
| 滑动结束事件(同时开启 enhanced 属性后生效) | dragend | 小程序 | - | |
| 自定义下拉刷新控件被下拉 | refresherpulling | 小程序 | - | |
| 自定义下拉刷新被触发 | refresherrefresh | 小程序 | - | |
| 自定义下拉刷新被复位 | refresherrestore | 小程序 | - | |
| 自定义下拉刷新被中止 | refresherabort | 小程序 | - |
Frequently Asked Questions
What is the difference between General Container / Grid Layout / Scrolling Container?
General Container / Grid Layout / Scrolling Container are three commonly used container types in WeDa, and their differences are as follows:
- General Container: The most basic container type used to hold text, images, and other content within a page. It can nest other components and achieve different layout effects through style settings. By default, it lacks scrolling functionality. Content will automatically expand vertically if no height is specified. Similar to
Viewin mini-programs anddivin Web development. - Grid Layout: A container designed for layout purposes that extends flexible layout capabilities beyond basic containers like the general container. It divides the page into individual grids, allowing arbitrary combinations of different grids to create various layouts such as left-right arrangements and multi-column rows. It also supports displaying different layout patterns across multiple devices.
- Scrolling Container: A container with scroll bars. After setting its width and height, if the content exceeds the container's boundaries, the content can be scrolled within the container. Similar to
ScrollViewin mini-programs.
In actual development, it is recommended to use Grid Layout for detailed arrangements of entire pages and internal modules. For multi-device requirements, display effects can be configured across different platforms. When scrolling beyond content areas is needed, Scrolling Containers can be utilized.
How to implement local scrolling?
Scrolling Containers can be used to display content that requires scrolling when it exceeds the visible area.
When the total width/height of component content within a scrolling container exceeds the container's own width/height, scroll bars will appear, allowing users to view all content by sliding the scroll bars.
Note that you must set the width and height for the scrolling container, ensuring the content dimensions exceed those of the container itself, to enable the scrolling effect.
If only horizontal scrolling is required, ensure the scrolling container's width is less than the width of the content it contains.
If only vertical scrolling is required, ensure the scrolling container's height is less than the width of the content it contains.