scroll

2023-08-09 00:11| 来源: 网络整理| 查看: 265

# scroll-view

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

相关文档: Skyline 渲染引擎、Skyline 迁移起步

渲染框架支持情况：Skyline （使用最新 Nighly 工具调试）、WebView

# 功能描述

可滚动视图区域。使用竖向滚动时，需要给scroll-view一个固定高度，通过 WXSS 设置 height。组件属性的长度单位默认为px，2.4.0起支持传入单位(rpx/px)。

横向滚动需打开 enable-flex 以兼容 WebView，如滚动条的长度是预估的，若直接子节点的高度差别较大，则滚动条长度可能会不准确 # 通用属性属性类型默认值必填说明最低版本 scroll-x boolean false 否允许横向滚动 1.0.0 scroll-y boolean false 否允许纵向滚动 1.0.0 upper-threshold number/string 50 否距顶部/左边多远时，触发 scrolltoupper 事件 1.0.0 lower-threshold number/string 50 否距底部/右边多远时，触发 scrolltolower 事件 1.0.0 scroll-top number/string 否设置竖向滚动条位置 1.0.0 scroll-left number/string 否设置横向滚动条位置 1.0.0 scroll-into-view string 否值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素 1.0.0 scroll-with-animation boolean false 否在设置滚动条位置时使用动画过渡 1.0.0 enable-back-to-top boolean false 否 iOS点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向。自 2.27.3 版本开始，若非显式设置为 false，则在显示尺寸大于屏幕 90% 时自动开启。 1.0.0 enable-passive boolean false 否开启 passive 特性，能优化一定的滚动性能 2.25.3 refresher-enabled boolean false 否开启自定义下拉刷新 2.10.1 refresher-threshold number 45 否设置自定义下拉刷新阈值 2.10.1 refresher-default-style string "black" 否设置自定义下拉刷新默认样式，支持设置 black | white | none， none 表示不使用默认样式 2.10.1 refresher-background string "#FFF" 否设置自定义下拉刷新区域背景颜色 2.10.1 refresher-triggered boolean false 否设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发 2.10.1 bounces boolean true 否 iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效) 2.12.0 show-scrollbar boolean true 否滚动条显隐控制 (同时开启 enhanced 属性后生效) 2.12.0 fast-deceleration boolean false 否滑动减速速率控制, 仅在 iOS 下生效 (同时开启 enhanced 属性后生效) 2.12.0 binddragstart eventhandle 否滑动开始事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft } 2.12.0 binddragging eventhandle 否滑动事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft } 2.12.0 binddragend eventhandle 否滑动结束事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft, velocity } 2.12.0 bindscrolltoupper eventhandle 否滚动到顶部/左边时触发 1.0.0 bindscrolltolower eventhandle 否滚动到底部/右边时触发 1.0.0 bindscroll eventhandle 否滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} 1.0.0 bindrefresherpulling eventhandle 否自定义下拉刷新控件被下拉 2.10.1 bindrefresherrefresh eventhandle 否自定义下拉刷新被触发 2.10.1 bindrefresherrestore eventhandle 否自定义下拉刷新被复位 2.10.1 bindrefresherabort eventhandle 否自定义下拉刷新被中止 2.10.1 # Skyline 特有属性属性类型默认值必填说明最低版本 type string list 是渲染模式合法值说明最低版本 list 列表模式。只会渲染在屏节点，会根据直接子节点是否在屏来按需渲染，若只有一个直接子节点则性能会退化 2.25.2 custom 自定义模式。只会渲染在屏节点，子节点可以是 sticky-section list-view grid-view 等组件 2.29.0 reverse boolean false 否是否反向滚动。一般初始滚动位置是在顶部，反向滚动则是在底部。 2.27.2 clip boolean true 否是否对溢出进行裁剪，默认开启 2.32.1 enable-back-to-top boolean false 否仅 iOS 支持，其余同 WebView 同名组件 2.32.1 cache-extent number 否指定视口外渲染区域的距离，默认情况下视口外节点不渲染。指定 cache-extent 可优化滚动体验和加载速度，但会提高内存占用且影响首屏速度，可按需启用。 2.29.0 min-drag-distance number 18 否指定 scroll-view 触发滚动的最小拖动距离。仅在 scroll-view 和其他组件存在手势冲突时使用，可通过调整该属性使得滚动更加灵敏。 2.33.0 scroll-into-view-within-extent boolean false 否只 scroll-into-view 到 cacheExtent 以内的目标节点，性能更佳 2.29.0 scroll-into-view-alignment string start 否指定 scroll-into-view 目标节点在视口内的位置 2.29.0 合法值说明 start 目标节点显示在视口开始处 center 目标节点显示在视口中间 end 目标节点显示在视口结束处 nearest 目标节点在就近的视口边缘显示，若节点已在视口内则不触发滚动 bind:scrollstart eventhandle 否滚动开始事件，仅支持非 worklet 的组件方法作为回调。event.detail = { isDrag } 2.29.0 bind:scroll eventhandle 否滚动事件，多返回 isDrag 字段，仅支持非 worklet 的组件方法作为回调。event.detail = { isDrag } bind:scrollend eventhandle 否滚动结束事件，仅支持非 worklet 的组件方法作为回调。event.detail = { isDrag } 2.29.0 worklet:onscrollstart worklet 否同 bindscrollstart，但仅支持 worklet 作为回调 2.29.2 worklet:onscrollupdate worklet 否 bindscroll ，但仅支持 worklet 作为回调 2.29.2 worklet:onscrollend worklet 否同 bindscrollend，但仅支持 worklet 作为回调 2.29.2 bind:refresherwillrefresh eventhandle 否自定义下拉刷新即将触发刷新（拖动超过 refresher-threshold 时）的事件 2.29.0 clip boolean true 否是否对溢出进行裁剪 2.31.1 padding Array [0, 0, 0, 0] 否长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距 3.0.0 refresher-two-level-enabled boolean false 否开启下拉二级能力 3.0.0 refresher-two-level-triggered boolean false 否设置打开/关闭二级 3.0.0 refresher-two-level-threshold number 150 否下拉二级阈值 3.0.0 refresher-two-level-close-threshold number 80 否滑动返回时关闭二级的阈值 3.0.0 refresher-two-level-scroll-enabled boolean false 否处于二级状态时是否可滑动 3.0.0 refresher-ballistic-refresh-enabled boolean false 否惯性滚动是否触发下拉刷新 3.0.0 refresher-two-level-pinned boolean false 否即将打开二级时否定住 3.0.0 bind:refresherstatuschange eventhandle 否下拉刷新状态回调 3.0.0 # WebView 特有属性属性类型默认值必填说明最低版本 enable-flex boolean false 否启用 flexbox 布局。开启后，当前节点声明了 display: flex 就会成为 flex container，并作用于其孩子节点。 2.7.3 scroll-anchoring boolean false 否开启 scroll anchoring 特性，即控制滚动位置不随内容变化而抖动，仅在 iOS 下生效，安卓下可参考 CSS overflow-anchor 属性。 2.8.2 enhanced boolean false 否启用 scroll-view 增强特性，启用后可通过 ScrollViewContext 操作 scroll-view 2.12.0 paging-enabled boolean false 否分页滑动效果 (同时开启 enhanced 属性后生效) 2.12.0 # Bug & Tip tip: 基础库 2.4.0以下不支持嵌套textarea、map、canvas、video 组件 tip: scroll-into-view 的优先级高于 scroll-top tip: 在滚动 scroll-view 时会阻止页面回弹，所以在 scroll-view 中滚动，是无法触发 onPullDownRefresh tip: 若要使用下拉刷新，请使用页面的滚动，而不是 scroll-view ，这样也能通过点击顶部状态栏回到页面顶部 tip: scroll-view 自定义下拉刷新节点需要声明为 slot="refresher"，可参考自定义下拉刷新示例 tip: scroll-view 自定义下拉刷新可以结合 WXS 事件响应开发交互动画 # bind:refresherstatuschange

返回值 evt.detail = { status, dy }，其中 status 的枚举状态如下

export enum RefreshStatus { // 空闲 Idle, // 超过下拉刷新阈值，同 bind:refresherwillRefresh 触发时机 CanRefresh, // 下拉刷新，同 bind:refresherrefresh 触发时机 Refreshing, // 下拉刷新完成，同 bind:refresherrestore 触发时机 Completed, // 下拉刷新失败 Failed, // 超过下拉二级阈值 CanTwoLevel, // 开始打开二级 TwoLevelOpening, // 打开二级 TwoLeveling, // 开始关闭二级 TwoLevelClosing, } # 下拉二级相关接口

触发下拉刷新 ScrollViewContext.triggerRefresh 关闭下拉刷新 ScrollViewContext.closeRefresh 触发下拉二级 ScrollViewContext.triggerTwoLevel 关闭下拉二级 ScrollViewContext.closeTwoLevel

# 下拉二级使用方法

下拉二楼是下拉刷新的一部份，需同时开启 refresher-enabled 和 refresher-two-level-enabled。

当用户下拉 scroll-view 至 refresher-threshold 时松手触发下拉刷新继续下拉至 refresher-two-level-threshold 松手触发下拉二级开启 refresher-two-level-scroll-enabled 后，二级页面可以滑动关闭，是否关闭的阈值由 refresher-two-level-close-threshold 指定下拉刷新和下拉二级的展示区域由 slot=refresher 定义，开发者可根据 refresherstatuschange 判定当前阶段，展示不同内容，例如 buildText(status: RefreshStatus) { switch (status) { case RefreshStatus.Idle: return '下拉刷新' case RefreshStatus.CanRefresh: return '松手刷新，下拉进入二楼' case RefreshStatus.Refreshing: return '正在刷新' case RefreshStatus.Completed: return '刷新成功' case RefreshStatus.Failed: return '刷新失败' case RefreshStatus.CanTwoLevel: return '松手进入二楼' default: return '' } }, # 下拉二级示例代码

在开发者工具中预览效果

# scroll-view 自定义下拉刷新示例

在开发者工具中预览效果

# 示例代码

在开发者工具中预览效果

【本文地址】

公司简介

联系我们