RrenrubingOnVisibleIndexesChangeCallback在懒加载布局容器中一致性修复

ea95e310创建于 5 天前历史提交

滚动组件通用接口

滚动组件通用属性和事件目前只支持List、Grid、Scroll和WaterFlow组件。

说明：

本模块从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

属性

scrollBar¹¹⁺

scrollBar(barState: BarState): T

设置滚动条状态。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
barState	BarState	是	滚动条状态。默认值：List、Grid、Scroll组件默认BarState.Auto，WaterFlow组件默认BarState.Off。

返回值：

类型	说明
T	返回当前滚动组件。

scrollBarColor¹¹⁺

scrollBarColor(color: Color | number | string): T

设置滚动条的颜色。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
color	Color \| number \| string	是	滚动条的颜色。默认值：'#182431'（40%不透明度） number为HEX格式颜色，支持rgb或者argb，示例：0xffffff。string为rgb或者argb格式颜色，示例：'#ffffff'。

返回值：

类型	说明
T	返回当前滚动组件。

scrollBarColor²²⁺

scrollBarColor(color: Color | number | string | Resource): T

设置滚动条的颜色。与scrollBarColor¹¹⁺相比，color参数开始支持Resource类型。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
color	Color \| number \| string \| Resource	是	滚动条的颜色。默认值：'#182431'（40%不透明度） number为HEX格式颜色，支持rgb或者argb，示例：0xffffff。string为rgb或者argb格式颜色，示例：'#ffffff'。

返回值：

类型	说明
T	返回当前滚动组件。

scrollBarWidth¹¹⁺

scrollBarWidth(value: number | string): T

设置滚动条的宽度，不支持百分比设置。宽度设置后，滚动条正常状态和按压状态宽度均为滚动条的宽度值。如果滚动条的宽度超过滚动组件主轴方向的高度，则滚动条的宽度会变为默认值。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number \| string	是	滚动条的宽度。默认值：4 单位：vp 取值范围：设置为小于0的值时，按默认值处理。设置为0时，不显示滚动条。

返回值：

类型	说明
T	返回当前滚动组件。

scrollBarWidth

scrollBarWidth(value: number | string | Resource): T

设置滚动条的宽度，不支持百分比设置。宽度设置后，滚动条正常状态和按压状态宽度均为滚动条的宽度值。如果滚动条的宽度超过滚动组件主轴方向的高度，则滚动条的宽度会变为4vp，支持Resource资源类型。

未通过该接口设置时，设置滚动条的宽度为4vp。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number \| string \| Resource	是	滚动条的宽度。单位：vp 取值范围：[0, +∞)。设置为小于0的值时，按4vp处理。设置为0时，不显示滚动条。

返回值：

类型	说明
T	返回当前滚动组件。

edgeEffect¹¹⁺

edgeEffect(edgeEffect: EdgeEffect, options?: EdgeEffectOptions): T

设置边缘滑动效果。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
edgeEffect	EdgeEffect	是	滚动组件的边缘滑动效果，支持弹簧效果和阴影效果。默认值：Grid、Scroll、WaterFlow组件默认EdgeEffect.None，List组件默认EdgeEffect.Spring。
options	EdgeEffectOptions	否	组件内容大小小于组件自身时是否开启滑动效果，以及设置边缘效果生效的边缘。设置为{ alwaysEnabled: true }会开启滑动效果，{ alwaysEnabled: false }不开启。默认值： List、Grid、WaterFlow组件默认{ alwaysEnabled: false, EffectEdge: EffectEdge.START \| EffectEdge.END }，Scroll组件默认{ alwaysEnabled: true, EffectEdge: EffectEdge.START \| EffectEdge.END }。

返回值：

类型	说明
T	返回当前滚动组件。

nestedScroll¹¹⁺

nestedScroll(value: NestedScrollOptions): T

设置前后两个方向的嵌套滚动模式，实现与父组件的滚动联动。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	NestedScrollOptions	是	嵌套滚动选项。默认值：{ scrollForward: NestedScrollMode.SELF_ONLY, scrollBackward: NestedScrollMode.SELF_ONLY }

返回值：

类型	说明
T	返回当前滚动组件。

enableScrollInteraction¹¹⁺

enableScrollInteraction(value: boolean): T

设置是否支持滚动手势。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	是否支持滚动手势。设置为true时可以通过手指或者鼠标滚动，设置为false时无法通过手指或者鼠标滚动，但不影响控制器Scroller的滚动接口。默认值：true

返回值：

类型	说明
T	返回当前滚动组件。

friction¹¹⁺

friction(value: number | Resource): T

设置摩擦系数，手动划动滚动区域时生效，仅影响惯性滚动过程，对惯性滚动过程中的链式效果有间接影响。设置为小于等于0的值时，按默认值处理。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number \| Resource	是	摩擦系数。默认值：非wearable设备为0.6，wearable设备为0.9。从API version 11开始，非wearable设备默认值为0.7。从API version 12开始，非wearable设备默认值为0.75。取值范围：(0, +∞)，设置为小于等于0的值时，按默认值处理。

返回值：

类型	说明
T	返回当前滚动组件。

flingSpeedLimit¹¹⁺

flingSpeedLimit(speedLimit: number): T

限制跟手滑动结束后，惯性动效开始时的最大初始速度。

说明：

惯性动效是指手指快速滑动并离开屏幕后，滚动内容继续滚动并逐渐减速停止的效果，也称为惯性滚动。

惯性动效触发场景包括：惯性手指快速滑动并离手时，或调用fling方法。

使用鼠标滚轮、键盘方向键方式滚动，或通过scrollTo等方法直接滚动到指定位置，不会产生惯性动效。

如果惯性动效通过fling方法触发，则flingSpeedLimit设置不生效。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
speedLimit	number	是	惯性动效开始时的最大初始速度。默认值：9000 单位：vp/s 取值范围：(0, +∞)，设置为小于等于0的值时，按默认值处理。

返回值：

类型	说明
T	返回当前滚动组件。

fadingEdge¹⁴⁺

fadingEdge(enabled: Optional<boolean>, options?: FadingEdgeOptions): T

设置是否开启边缘渐隐效果及设置边缘渐隐长度。

说明：

fadingEdge是通过设置overlay属性和blendMode属性（参数值为BlendMode.SRC_OVER，BlendApplyType.OFFSCREEN）实现的。当fadingEdge生效时，会覆盖原组件的.overlay()属性和.blendMode()属性，并将导致当前组件和其子组件需要截屏的接口无法截取到正确的画面。需要截屏的接口有：blur、linearGradientBlur、brightness、visualEffect、grayscale、saturate、contrast、invert、sepia、hueRotate、colorBlend、lightUpEffect、pixelStretchEffect、blendMode、backgroundBrightness。

fadingEdge生效时，建议不在设置fadingEdge属性的组件上设置background相关属性，会影响渐隐的显示效果。

fadingEdge生效时，设置fadingEdge属性的组件会裁剪到边界，在该组件上设置clip属性为false不生效。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
enabled	Optional<boolean>	是	是否开启边缘渐隐效果。设置为true时开启边缘渐隐效果，设置为false时不开启边缘渐隐效果。默认值：false
options	FadingEdgeOptions	否	边缘渐隐参数对象。可以通过该对象定义边缘渐隐效果属性，比如设置渐隐长度。如果设置小于0的值或undefined或者不设置则取默认值，默认长度为32vp。如果设置的长度超过容器高度的一半时，渐隐长度取容器高度的一半。

返回值：

类型	说明
T	返回当前滚动组件。

clipContent¹⁴⁺

clipContent(clip: ContentClipMode | RectShape): T

设置滚动容器的内容层裁剪区域。

从API版本26.0.0开始，内容层裁剪区域内的子组件支持正常显示。API版本26.0.0以前的版本，List、Grid和WaterFlow组件内容层裁剪区域比组件自身大小更大时，完全在组件区域外但在裁剪区域内的子组件默认不会显示。若需要显示可将组件的cachedCount属性的isShow参数设置为true，但由于cachedCount属性设置的预加载子组件只会在空闲时隙时执行，组件大小变化、数据更新等场景可能存在更新不及时导致闪烁问题。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
clip	ContentClipMode \| RectShape	是	裁剪只针对滚动容器的内容，即其子节点，背景不受影响。通过RectShape传入自定义矩形区域时仅支持设置宽高和相对于组件左上角的offset，不支持圆角。默认值：Grid、Scroll的默认值为ContentClipMode.BOUNDARY，List、WaterFlow的默认值为ContentClipMode.CONTENT_ONLY。

返回值：

类型	说明
T	返回当前滚动组件。

backToTop¹⁵⁺

backToTop(backToTop: boolean): T

设置滚动组件是否支持点击状态栏回到顶部。

支持当前页面的滚动组件收到点击状态栏事件后，通过动画回到顶部。点击状态栏后，后台应用的滚动组件不受影响，不做回到顶部的动作。本属性不受enableScrollInteraction设置的影响。

原子化服务API： 从API version 15开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
backToTop	boolean	是	设置滚动组件是否支持点击状态栏回到顶部。设置为true支持点击状态栏通过动画回到顶部，设置为false不支持点击状态栏回到顶部。默认值： API version 18之前：false。 API version 18及以后：滚动方向是水平方向时为false，是垂直方向时为true。

返回值：

类型	说明
T	返回当前滚动组件。

scrollBarMargin²⁰⁺

scrollBarMargin(margin: ScrollBarMargin): T

设置滚动条的边距。边距是在滚动条避让圆角距离的基础上计算的，如果滚动条区域小于滚动条的最小长度，则不显示滚动条。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
margin	ScrollBarMargin	是	滚动条起始、末尾边距。默认值：{start: LengthMetrics.vp(0), end: LengthMetrics.vp(0)}

返回值：

类型	说明
T	返回当前滚动组件。

autoAdjustScrollBarMargin

autoAdjustScrollBarMargin(enable: boolean | undefined): T

设置滚动条是否自动调整边距。默认不会自动调整边距。

打开滚动条自动边距调整后，滚动条滚动方向上会避让组件padding、safeAreaPadding、contentStartOffset/contentEndOffset区域。如果设置了scrollBarMargin属性，则自动调整边距不生效。当padding、safeAreaPadding、contentStartOffset、contentEndOffset在水平方向上的总和大于组件的宽度，或在垂直方向上的总和大于组件的高度时，滚动条不显示。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API version 26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
enable	boolean \| undefined	是	是否自动调整边距。 true：自动调整边距。 false：不自动调整边距。 undefined：不自动调整边距。

返回值：

类型	说明
T	返回当前组件。

digitalCrownSensitivity¹⁸⁺

digitalCrownSensitivity(sensitivity: Optional<CrownSensitivity>): T

设置表冠响应事件灵敏度。

组件收到表冠事件的前提是该组件获焦，焦点控制可以通过focusable、defaultFocus、focusOnTouch进行管理。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
sensitivity	Optional<CrownSensitivity>	是	表冠响应灵敏度。默认值：CrownSensitivity.MEDIUM，响应速度适中。

返回值：

类型	说明
T	返回当前滚动组件。

contentStartOffset²²⁺

contentStartOffset(offset: number | Resource): T

设置内容区域起始偏移量。滚动组件滚动到起始位置时，内容与组件显示区域边界保留指定距离。

contentStartOffset + contentEndOffset超过滚动组件内容区长度后contentStartOffset和contentEndOffset会置0。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
offset	number \| Resource	是	内容区域起始偏移量。默认值：0 单位：vp 设置异常值如负数、非数字Resource时，按默认值处理。

返回值：

类型	说明
T	返回当前滚动组件。

contentEndOffset²²⁺

contentEndOffset(offset: number | Resource): T

设置内容区末尾偏移量。滚动组件滚动到末尾位置时，内容与组件显示区域边界保留指定距离。

contentStartOffset + contentEndOffset超过滚动组件内容区长度后contentStartOffset和contentEndOffset会置0。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
offset	number \| Resource	是	内容区末尾偏移量。默认值：0 单位：vp 设置异常值如负数、非数字Resource时，按默认值处理。

返回值：

类型	说明
T	返回当前滚动组件。

enableScrollWithMouse

enableScrollWithMouse(enabled: boolean | undefined): T

设置是否支持鼠标左键按下拖动滚动。未通过该接口设置时，默认不支持鼠标左键按下拖动滚动。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API version 26.0.0开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
enabled	boolean \| undefined	是	是否支持鼠标左键按下拖动滚动。 true：支持鼠标左键按下拖动滚动。 false：不支持鼠标左键按下拖动滚动。 undefined：不支持鼠标左键按下拖动滚动。

返回值：

类型	说明
T	返回当前组件。

事件

onReachStart¹¹⁺

onReachStart(event: () => void): T

滚动组件到达起始位置时触发。

滚动组件初始化时会触发一次，滚动到起始位置时触发一次。边缘效果为弹簧效果时，划动经过起始位置时触发一次，回弹回起始位置时再触发一次。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	() => void	是	滚动组件到达起始位置时的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onReachEnd¹¹⁺

onReachEnd(event: () => void): T

滚动组件到达末尾位置时触发。

滚动组件边缘效果为弹簧效果时，划动经过末尾位置时触发一次，回弹回末尾位置时再触发一次。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	() => void	是	滚动组件到达末尾位置时的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onScrollStart¹¹⁺

onScrollStart(event: () => void): T

滚动开始时触发。手指拖动滚动组件或拖动滚动组件的滚动条触发的滚动开始时，会触发该事件。使用Scroller滚动控制器触发的带动画的滚动，动画开始时会触发该事件。

触发该事件的条件：

滚动组件开始滚动时触发，支持键鼠操作等其他触发滚动的输入设置。
通过滚动控制器API接口调用后开始，带过渡动效。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	() => void	是	滚动开始时的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onScrollStop¹¹⁺

onScrollStop(event: () => void): T

滚动停止时触发。手拖动滚动组件或拖动滚动组件的滚动条触发的滚动，手离开屏幕后滚动停止时会触发该事件。使用Scroller滚动控制器触发的带动画的滚动，动画停止时会触发该事件。

触发该事件的条件：

滚动组件触发滚动后停止，支持键鼠操作等其他触发滚动的输入设置。
通过调用带过渡动画的滚动控制器API接口，动画停止时。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	() => void	是	滚动停止时的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onWillScroll¹²⁺

onWillScroll(handler: Optional<OnWillScrollCallback>): T

滚动事件回调，滚动组件滚动前触发。

回调当前帧将要滚动的偏移量和当前滚动状态和滚动操作来源，其中回调的偏移量为计算得到的将要滚动的偏移量值，并非最终实际滚动偏移。可以通过该回调返回值指定滚动组件将要滚动的偏移。Scroll组件的onWillScroll接口的参数类型是ScrollOnWillScrollCallback。

说明：

从API version 14开始，该接口支持在attributeModifier中调用。

调用不带动画的ScrollEdge和ScrollToIndex时，不触发onWillScroll。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
handler	Optional<OnWillScrollCallback>	是	滚动组件滑动前触发的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onDidScroll¹²⁺

onDidScroll(handler: OnScrollCallback): T

滚动组件滑动时触发，返回当前帧滑动的偏移量和当前滑动状态。

说明：

从API version 14开始，该接口支持在attributeModifier中调用。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
handler	OnScrollCallback	是	滚动组件滑动时触发的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onScroll^(deprecated)

onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void): T

滚动组件滑动时触发。

说明：

从API version 11开始支持，从API version 12开始废弃，List、Grid和WaterFlow组件的onScroll事件在布局之后触发，建议使用onDidScroll替代；Scroll组件的onScroll事件在布局之前触发，建议使用onWillScroll替代。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	(scrollOffset: number, scrollState: ScrollState) => void	是	滚动组件滑动时的回调。 scrollOffset：相对于上一帧的偏移量，滚动组件的内容向上滚动时偏移量为正，向下滚动时偏移量为负。单位vp。 scrollState：当前滑动状态。

返回值：

类型	说明
T	返回当前滚动组件。

onWillStartDragging²¹⁺

onWillStartDragging(handler: VoidCallback): T

滚动组件开始拖动时触发。

卡片能力： 从API version 21开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 21开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
handler	VoidCallback	是	滚动组件开始拖动时触发的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onWillStopDragging²⁰⁺

onWillStopDragging(handler: OnWillStopDraggingCallback): T

滚动组件划动离手时触发，使用鼠标滚轮划动时不会触发。

卡片能力： 从API version 20开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
handler	OnWillStopDraggingCallback	是	滚动组件划动离手时触发的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onDidStopDragging²¹⁺

onDidStopDragging(handler: OnDidStopDraggingCallback): T

滚动组件结束拖拽时触发。

卡片能力： 从API version 21开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 21开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
handler	OnDidStopDraggingCallback	是	滚动组件结束拖动时触发的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onWillStartFling²¹⁺

onWillStartFling(handler: VoidCallback): T

滚动组件将要开始惯性动效时触发。

说明：

如果惯性动效通过fling方法触发，则onWillStartFling不触发。

惯性动效的触发场景参考flingSpeedLimit方法的说明。

卡片能力： 从API version 21开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 21开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
handler	VoidCallback	是	滚动组件将要开始惯性动效时触发的回调。

返回值：

类型	说明
T	返回当前滚动组件。

onDidStopFling²¹⁺

onDidStopFling(handler: VoidCallback): T

滚动组件结束惯性动效后触发，进行中的惯性动效被新的滑动事件打断时不触发。

卡片能力： 从API version 21开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 21开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
handler	VoidCallback	是	滚动组件结束惯性动效后触发的回调。

返回值：

类型	说明
T	返回当前滚动组件。

ItemDragInfo对象说明

拖拽点信息对象。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
x	number	否	否	当前拖拽点的x坐标，单位vp。
y	number	否	否	当前拖拽点的y坐标，单位vp。

NestedScrollOptions¹⁰⁺对象说明

nestedScroll属性参数对象。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
scrollForward	NestedScrollMode	否	否	滚动组件往末尾端滚动时的嵌套滚动选项。
scrollBackward	NestedScrollMode	否	否	滚动组件往起始端滚动时的嵌套滚动选项。

EdgeEffectOptions¹¹⁺对象说明

edgeEffect属性参数对象。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
alwaysEnabled	boolean	否	否	组件内容大小小于组件自身时，设置是否开启滑动效果。设置为true开启滑动效果，设置为false关闭滑动效果。List、Grid和WaterFlow组件默认值是false，Scroll组件默认值是true。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
effectEdge¹⁸⁺	number	否	是	设置边缘效果生效的边缘。如果设置EffectEdge.START表示只有起始边生效。如果设置EffectEdge.END表示只有末尾边生效。默认值为EffectEdge.START \| EffectEdge.END表示双边同时生效。当设置为其它异常值时，则默认双边同时生效。如果需要双边都不生效，可将edgeEffect设置为EdgeEffect.None。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

FadingEdgeOptions¹⁴⁺对象说明

fadingEdge属性边缘渐隐参数对象。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
fadingEdgeLength	LengthMetrics	否	是	设置边缘渐隐长度。

EditModeOptions²³⁺对象说明

List/Grid组件编辑模式选项属性参数对象。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
enableGatherSelectedItemsAnimation	boolean	否	是	是否启用多选聚拢动画。设置true时启用聚拢动画，设置为false时关闭聚拢动画。只有GridItem或ListItem上设置了bindContextMenu且responseType设置为ResponseType.LongPress、preview参数设置为MenuPreviewMode.IMAGE或CustomBuilder时会显示多选聚拢动画。如果GridItem或ListItem上设置了拖拽事件，是否聚拢以dragPreviewOptions设置为准。默认值：false 原子化服务API：从API version 23开始，该接口支持在原子化服务中使用。
onGetPreviewBadge	OnGetPreviewBadgeCallback	否	是	即将启动多选长按聚拢动画时，触发用于获取选中数量的回调。缺省时用Grid或List显示范围内选中item的数量作为多选长按聚拢动画后菜单预览图的角标。原子化服务API：从API version 23开始，该接口支持在原子化服务中使用。
useDefaultMultiSelectStyle	boolean	否	是	是否使用默认多选样式。 true表示GridItem或ListItem进入多选状态后显示勾选框；false表示进入多选状态后无默认样式。默认值：true 起始版本： 26.0.0 原子化服务API：从API版本26.0.0开始，该接口支持在原子化服务中使用。
enableTwoFingerMultiSelect	boolean	否	是	是否开启双指滑动多选。 true表示双指滑动可以进入编辑模式并进行多选，只有List/Grid使用enableEditMode双向绑定或设置onEditModeChange事件回调才生效；false表示双指滑动不可进行多选。默认值：true 起始版本： 26.0.0 原子化服务API：从API版本26.0.0开始，该接口支持在原子化服务中使用。

EffectEdge¹⁸⁺枚举说明

表示当前边缘效果要生效的边缘。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	值	说明
START	1	起始边生效。
END	2	末尾边生效。

ContentClipMode¹⁴⁺枚举说明

表示滚动容器的内容裁剪模式。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

下图是组件配置了边距属性后的示意图，可理解每种枚举对应的裁剪区域。

ContentClipMode示意图

名称	值	说明
CONTENT_ONLY	0	按内容区裁剪，对应图中的绿色区域。
BOUNDARY	1	按组件区域裁剪，对应图中的整个蓝色区域。
SAFE_AREA	2	按组件配置的SafeArea区域裁剪，对应图中的整个黄色区域。

OnWillScrollCallback¹²⁺

type OnWillScrollCallback = (scrollOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => void | ScrollResult

滚动组件滑动前触发的回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
scrollOffset	number	是	相对于上一帧的偏移量，滚动组件的内容向上滚动时偏移量为正，向下滚动时偏移量为负。单位vp。
scrollState	ScrollState	是	当前滑动状态。
scrollSource	ScrollSource	是	当前滑动操作的来源。

返回值：

类型	说明
void \| ScrollResult	返回ScrollResult时按照开发者指定的相对上一帧的偏移量滑动；不返回时按回调参数scrollOffset滑动。取值范围：(-∞, +∞)

OnScrollCallback¹²⁺

type OnScrollCallback = (scrollOffset: number, scrollState: ScrollState) => void

滚动组件滑动时触发的回调。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
scrollOffset	number	是	相对于上一帧的偏移量，滚动组件的内容向上滚动时偏移量为正，向下滚动时偏移量为负。单位vp。
scrollState	ScrollState	是	当前滑动状态。

OnItemDragStartCallback²³⁺

type OnItemDragStartCallback = (event: ItemDragInfo, itemIndex: number) => CustomBuilder

开始拖拽列表或网格元素时触发的回调。

原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	ItemDragInfo	是	拖拽点的信息。
itemIndex	number	是	被拖拽列表元素索引值。

返回值：

类型	说明
CustomBuilder	返回CustomBuilder用于构建被拖拽元素的拖拽图。返回void表示不能拖拽。

OnGetPreviewBadgeCallback²³⁺

type OnGetPreviewBadgeCallback = () => boolean | number

即将启动多选长按聚拢动画时，触发用于获取选中数量的回调。

模型约束： 此接口仅可在Stage模型下使用。

原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值：

类型

说明

boolean | number

多选长按聚拢动画后菜单预览图是否显示选中数量角标，或需要显示的数量。
返回true表示显示选中数量角标，对应Grid或List显示范围内选中item数量；false表示不显示角标。
返回数字时默认显示角标，该数字表示角标中需要显示的数量。取值范围：[0, 2³¹-1]，超过取值范围时按返回true处理。
返回浮点数时，向下取整。

ScrollResult¹²⁺对象说明

OnWillScrollCallback返回值对象。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
offsetRemain	number	否	否	将要滑动偏移量，单位vp。

ChildrenMainSize¹²⁺对象说明

维护List组件或ListItemGroup组件的子组件在主轴方向的大小信息，仅支持一对一绑定到List组件或ListItemGroup组件。

说明：

提供的主轴方向大小信息必须与子组件实际在主轴方向的大小一致，子组件在主轴方向大小变化或者增删子组件时都必须通过ChildrenMainSize对象方法通知List组件或ListItemGroup组件。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

constructor¹²⁺

constructor(childDefaultSize: number)

ChildrenMainSize有参构造函数。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
childDefaultSize	number	是	子组件在主轴方向的默认大小。单位：vp 说明：必须是有限的非负数值，否则抛出异常。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.

childDefaultSize¹²⁺

set childDefaultSize(value: number)

修改子组件在主轴方向的默认大小。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number	是	子组件在主轴方向的默认大小。单位：vp 说明：必须是有限的非负数值，否则抛出异常。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.

get childDefaultSize(): number

获取子组件在主轴方向的默认大小。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

返回值：

类型	说明
number	子组件在主轴方向的默认大小。单位：vp 取值范围：[0, +∞)

splice¹²⁺

splice(start: number, deleteCount?: number, childrenSize?: Array<number>): void

批量增删改子组件在主轴方向的大小信息。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
start	number	是	从0开始计算的索引值，表示要开始修改子组件在主轴方向大小信息的位置。说明： 1. 必须是有限的非负数值，否则抛出异常。 2. 非整数会被截断为整数。 3. 超过最大索引值不生效。取值范围：[0, +∞)
deleteCount	number	否	从start开始删除的大小信息的数量。说明： 1. 必须是有限的非负数值，否则处理为0。 2. 非整数会被截断为整数。 3. start + deleteCount - 1可以超过最大索引值，会删除索引值start开始之后的所有子组件的大小信息。默认值为+∞。取值范围：[0, +∞)
childrenSize	Array<number >	否	要在start位置插入的所有子组件的主轴方向的大小。 Array中各个数值单位：vp 说明： 1.数组中数值如果是有限的非负值，则认为是指定的大小，后续不随默认大小的变化而变化。 2. 数组中数值如果不是有限的非负值，会被处理成默认大小，后续会随默认大小的变化而变化。默认值为空数组。取值范围：[0, +∞)

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.

说明：

如果仅使用start参数，表示删除索引值start及之后的子组件的大小信息。

如果仅使用start和deleteCount参数，表示删除索引值start开始的deleteCount数量的子组件的大小信息。一般在删除子组件时使用。

如果使用3个参数，表示删除索引值start开始的deleteCount数量的子组件的大小信息，再在start位置插入childrenSize中所有的大小信息。一般在增加子组件或者批量更新子组件主轴方向大小的时候使用，如果仅是增加子组件，deleteCount为0，childrenSize的元素数量和增加子组件的个数应该相等；如果仅是批量更新子组件主轴方向的大小，childrenSize的元素数量应该和deleteCount相等，即为批量更新的数量。

如果想要通知某个子组件的大小为默认大小，childrenSize中对应的值不应该给一个有限的非负值，而应该给NaN，任意负值等能被处理成默认大小的值。

update¹²⁺

update(index: number, childSize: number): void

修改指定索引值对应的子组件的主轴方向的大小信息。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
index	number	是	从0开始计算的索引值，表示要开始修改子组件在主轴方向大小信息的位置。说明： 1. 必须是有限的非负数值，否则抛出异常。 2. 非整数会被截断为整数。 3. 超过最大索引值不生效。取值范围：[0, +∞)
childSize	number	是	要更新成的大小。单位：vp 说明： 1.数值如果是有限的非负值，则认为是指定的大小，后续不随默认大小的变化而变化。 2. 数值如果不是有限的非负值，会被处理成默认大小，后续会随默认大小的变化而变化。取值范围：[0, +∞)

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.

UIScrollableCommonEvent¹⁹⁺

用于设置滚动事件回调。

setOnReachStart¹⁹⁺

setOnReachStart(callback: Callback<void> | undefined): void

设置onReachStart事件的回调。

方法入参为undefined的时候，重置对应的事件回调。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	Callback<void> \| undefined	是	onReachStart事件的回调函数。

setOnReachEnd¹⁹⁺

setOnReachEnd(callback: Callback<void> | undefined): void

设置onReachEnd事件的回调。

方法入参为undefined时，会重置事件回调。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	Callback<void> \| undefined	是	onReachEnd事件的回调函数。

setOnScrollStart¹⁹⁺

setOnScrollStart(callback: Callback<void> | undefined): void

设置onScrollStart事件的回调。

方法入参为undefined时，会重置事件回调。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	Callback<void> \| undefined	是	onScrollStart事件的回调函数。

setOnScrollStop¹⁹⁺

setOnScrollStop(callback: Callback<void> | undefined): void

设置onScrollStop事件的回调。

方法入参为undefined时，会重置事件回调。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	Callback<void> \| undefined	是	onScrollStop事件的回调函数。

setOnScrollFrameBegin¹⁹⁺

setOnScrollFrameBegin(callback: OnScrollFrameBeginCallback | undefined): void

设置onScrollFrameBegin事件的回调。

方法入参为undefined时，会重置事件回调。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	OnScrollFrameBeginCallback \| undefined	是	onScrollFrameBegin事件的回调函数。

OnWillStopDraggingCallback²⁰⁺

type OnWillStopDraggingCallback = (velocity: number) => void

滚动组件划动离手时触发的回调。

卡片能力： 从API version 20开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
velocity	number	是	划动离手速度，滚动组件的内容向上滚动时速度为正，向下滚动时速度为负。单位vp/s。

OnDidStopDraggingCallback²¹⁺

type OnDidStopDraggingCallback = (willFling: boolean) => void

滚动组件在结束拖拽时触发的回调。

卡片能力： 从API version 21开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 21开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
willFling	boolean	是	结束拖拽后是否会有惯性动效。返回true代表拖拽结束后有惯性动效，返回false代表没有惯性动效。

OnVisibleIndexesChangeCallback

type OnVisibleIndexesChangeCallback = (start: number, end: number) => void

懒加载布局容器LazyColumnLayout、LazyVGridLayout、LazyVWaterFlowLayout所显示的子组件索引发生变化时的回调类型。

说明：

当懒加载布局容器没有子组件时，start和end都返回-1。

当懒加载布局容器在可视区域内无子组件时，start和end都返回-1。

起始版本： 26.0.0

原子化服务API： 从API版本26.0.0开始，该接口支持在原子化服务中使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
start	number	是	可视区域起始位置的索引值。取值范围：[0, 子节点总数-1]
end	number	是	可视区域终止位置的索引值。取值范围：[0, 子节点总数-1]

示例

示例1（支持滚动手势）

该示例通过设置enableScrollInteraction属性，实现了使用手势滚动纵向列表，并在当前显示界面发生改变时回调索引。

ListDataSource说明及完整代码参考示例1（添加滚动事件）。

// xxx.ets
import { ListDataSource } from './ListDataSource';

@Entry
@Component
struct ListExample {
  private arr: ListDataSource = new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);

  build() {
    Column() {
      List({ space: 20, initialIndex: 0 }) {
        LazyForEach(this.arr, (item: number) => {
          ListItem() {
            Text('' + item)
              .width('100%')
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor(0xFFFFFF)
          }
        }, (item: number) => item.toString())
      }
      .enableScrollInteraction(true)
      .listDirection(Axis.Vertical) // 排列方向
      .scrollBar(BarState.Off)
      .friction(0.6)
      .divider({
        strokeWidth: 2,
        color: 0xFFFFFF,
        startMargin: 20,
        endMargin: 20
      }) // 每行之间的分界线
      .edgeEffect(EdgeEffect.Spring) // 边缘效果设置为Spring
      .onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => {
        console.info('first' + firstIndex);
        console.info('last' + lastIndex);
        console.info('center' + centerIndex);
      })
      .onScrollVisibleContentChange((start: VisibleListContentInfo, end: VisibleListContentInfo) => {
        console.info(' start index: ' + start.index +
          ' start item group area: ' + start.itemGroupArea +
          ' start index in group: ' + start.itemIndexInGroup);
        console.info(' end index: ' + end.index +
          ' end item group area: ' + end.itemGroupArea +
          ' end index in group: ' + end.itemIndexInGroup);
      })
      .onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
        console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset);
      })
      .width('90%')
    }
    .width('100%')
    .height('100%')
    .backgroundColor(0xDCDCDC)
    .padding({ top: 5 })
  }
}

zh-cn_image_0000001174264378

示例2（设置边缘渐隐）

该示例通过设置fadingEdge属性，实现了List组件开启边缘渐隐效果并设置边缘渐隐长度。

ListDataSource说明及完整代码参考示例1（添加滚动事件）。

// xxx.ets
import { LengthMetrics } from '@kit.ArkUI';
import { ListDataSource } from './ListDataSource';

@Entry
@Component
struct ListExample {
  private arr: ListDataSource = new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
  scrollerForList: Scroller = new Scroller();

  build() {
    Column() {

      List({ space: 20, initialIndex: 0, scroller: this.scrollerForList }) {
        LazyForEach(this.arr, (item: number) => {
          ListItem() {
            Text('' + item)
              .width('100%')
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor(0xFFFFFF)
          }
        }, (item: number) => item.toString())
      }
      .fadingEdge(true, { fadingEdgeLength: LengthMetrics.vp(80) })
    }
    .width('100%')
    .height('100%')
    .backgroundColor(0xDCDCDC)
    .padding({ top: 5 })
  }
}

fadingEdge_list

示例3（设置裁剪区域）

该示例通过设置clipContent属性，改变组件的内容层裁剪区域。

// xxx.ets
import { LengthMetrics } from '@kit.ArkUI';

@Entry
@Component
struct ScrollExample {
  scroller: Scroller = new Scroller();
  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
  @State clipContent: ContentClipMode | RectShape | undefined = undefined;

  build() {
    Column() {
      Scroll(this.scroller) {
        Column() {
          ForEach(this.arr, (item: number) => {
            Text(item.toString())
              .width(300)
              .height(80)
              .fontSize(20)
              .textAlign(TextAlign.Center)
              .backgroundColor(Color.Grey)
          }, (item: string) => item)
        }
      }
      .backgroundColor(Color.Blue)
      .clipContent(this.clipContent)
      .scrollBar(BarState.Off)
      .friction(0.6)
      .width(300)
      .height('50%')
      .padding(10)
      .safeAreaPadding(LengthMetrics.vp(10))
      .initialOffset({ yOffset: 80 })
      .margin({ top: 20 })

      Button('clipContent SAFE_AREA')
        .onClick(() => {
          this.clipContent = ContentClipMode.SAFE_AREA;
        }).margin({ top: 30 })

      Button('clipContent BOUNDARY')
        .onClick(() => {
          this.clipContent = ContentClipMode.BOUNDARY;
        }).margin({ top: 35 })

      Button('clipContent CONTENT_ONLY')
        .onClick(() => {
          this.clipContent = ContentClipMode.CONTENT_ONLY;
        }).margin({ top: 40 })
    }.width('100%').height('100%').backgroundColor(0xDCDCDC)
  }
}

clipContent_scroll

示例4（设置滚动条边距）

从API version 20开始，该示例通过设置scrollBarMargin属性，调整滚动组件的滚动条边距。

ListDataSource说明及完整代码参考示例1（添加滚动事件）。

// xxx.ets
import { ListDataSource } from './ListDataSource';
import { LengthMetrics } from '@kit.ArkUI';

@Entry
@Component
struct ListExample {
  arr: ListDataSource = new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
  @State scrollBarMargin: ScrollBarMargin = { start: LengthMetrics.vp(0), end: LengthMetrics.vp(0) };

  build() {
    Stack({ alignContent: Alignment.TopStart }) {
      Column() {
        List({ space: 20, initialIndex: 0 }) {
          LazyForEach(this.arr, (item: number, index?: number) => {
            ListItem() {
              Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) {
                Text('' + item)
                  .width('100%')
                  .height(80)
                  .fontSize(20)
                  .textAlign(TextAlign.Center)
                  .borderRadius(10)
                  .backgroundColor(Color.White)
                  .flexShrink(1)
              }
            }
          }, (item: number) => item.toString())
        }.width('90%')
        .friction(0.6)
        .scrollBar(BarState.On)
        .scrollBarMargin(this.scrollBarMargin)
      }.width('100%')

      Button('scrollBarMargin')
        .onClick(() => {
          this.scrollBarMargin = { start: LengthMetrics.vp(45), end: LengthMetrics.vp(70) };
        }).margin({ top: 5, left: 20 })

      Button('scrollBarMargin2')
        .onClick(() => {
          this.scrollBarMargin = { start: LengthMetrics.vp(15), end: LengthMetrics.vp(100) };
        }).margin({ top: 200, left: 20 })
    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
  }
}

scrollBarMargin_list

滚动组件通用接口

属性

scrollBar11+

scrollBarColor11+

scrollBarColor22+

scrollBarWidth11+

scrollBarWidth

edgeEffect11+

nestedScroll11+

enableScrollInteraction11+

friction11+

flingSpeedLimit11+

fadingEdge14+

clipContent14+

backToTop15+

scrollBarMargin20+

autoAdjustScrollBarMargin

digitalCrownSensitivity18+

contentStartOffset22+

contentEndOffset22+

enableScrollWithMouse

事件

onReachStart11+

onReachEnd11+

onScrollStart11+

onScrollStop11+

onWillScroll12+

onDidScroll12+

onScroll(deprecated)

onWillStartDragging21+

onWillStopDragging20+

onDidStopDragging21+

onWillStartFling21+

onDidStopFling21+

ItemDragInfo对象说明

NestedScrollOptions10+对象说明

EdgeEffectOptions11+对象说明

FadingEdgeOptions14+对象说明

EditModeOptions23+对象说明

EffectEdge18+枚举说明

ContentClipMode14+枚举说明

OnWillScrollCallback12+

OnScrollCallback12+

OnItemDragStartCallback23+

OnGetPreviewBadgeCallback23+

ScrollResult12+对象说明

ChildrenMainSize12+对象说明

constructor12+

childDefaultSize12+

splice12+

update12+

UIScrollableCommonEvent19+

setOnReachStart19+

setOnReachEnd19+

setOnScrollStart19+

setOnScrollStop19+

setOnScrollFrameBegin19+

OnWillStopDraggingCallback20+

OnDidStopDraggingCallback21+

OnVisibleIndexesChangeCallback

示例

示例1（支持滚动手势）

示例2（设置边缘渐隐）

示例3（设置裁剪区域）

示例4（设置滚动条边距）

scrollBar¹¹⁺

scrollBarColor¹¹⁺

scrollBarColor²²⁺

scrollBarWidth¹¹⁺

edgeEffect¹¹⁺

nestedScroll¹¹⁺

enableScrollInteraction¹¹⁺

friction¹¹⁺

flingSpeedLimit¹¹⁺

fadingEdge¹⁴⁺

clipContent¹⁴⁺

backToTop¹⁵⁺

scrollBarMargin²⁰⁺

digitalCrownSensitivity¹⁸⁺

contentStartOffset²²⁺

contentEndOffset²²⁺

onReachStart¹¹⁺

onReachEnd¹¹⁺

onScrollStart¹¹⁺

onScrollStop¹¹⁺

onWillScroll¹²⁺

onDidScroll¹²⁺

onScroll^(deprecated)

onWillStartDragging²¹⁺

onWillStopDragging²⁰⁺

onDidStopDragging²¹⁺

onWillStartFling²¹⁺

onDidStopFling²¹⁺

NestedScrollOptions¹⁰⁺对象说明

EdgeEffectOptions¹¹⁺对象说明

FadingEdgeOptions¹⁴⁺对象说明

EditModeOptions²³⁺对象说明

EffectEdge¹⁸⁺枚举说明

ContentClipMode¹⁴⁺枚举说明

OnWillScrollCallback¹²⁺

OnScrollCallback¹²⁺

OnItemDragStartCallback²³⁺

OnGetPreviewBadgeCallback²³⁺

ScrollResult¹²⁺对象说明

ChildrenMainSize¹²⁺对象说明

constructor¹²⁺

childDefaultSize¹²⁺

splice¹²⁺

update¹²⁺

UIScrollableCommonEvent¹⁹⁺

setOnReachStart¹⁹⁺

setOnReachEnd¹⁹⁺

setOnScrollStart¹⁹⁺

setOnScrollStop¹⁹⁺

setOnScrollFrameBegin¹⁹⁺

OnWillStopDraggingCallback²⁰⁺

OnDidStopDraggingCallback²¹⁺