1# Scroll 2 3可滚动的容器组件，当子组件的布局尺寸超过父组件的尺寸时，内容可以滚动。 4 5> **说明：** 6> - 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 7> - 该组件嵌套List子组件滚动时，若List不设置宽高，则默认全部加载，在对性能有要求的场景下建议指定List的宽高。 8> - 该组件滚动的前提是主轴方向大小小于内容大小。 9> - 该组件回弹的前提是要有滚动。内容小于一屏时，没有回弹效果。 10 11 12## 子组件 13 14支持单个子组件。 15 16 17## 接口 18 19Scroll(scroller?: Scroller) 20 21## 属性 22 23除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 24 25| 名称 | 参数类型 | 描述 | 26| -------------- | ---------------------------------------- | ---------------------------------------- | 27| scrollable | [ScrollDirection](#scrolldirection枚举说明) | 设置滚动方向。<br/>默认值：ScrollDirection.Vertical | 28| scrollBar | [BarState](ts-appendix-enums.md#barstate) | 设置滚动条状态。<br/>默认值：BarState.Auto | 29| scrollBarColor | string \| number \| [Color](ts-appendix-enums.md#color) | 设置滚动条的颜色。 | 30| scrollBarWidth | string \| number | 设置滚动条的宽度。 | 31| edgeEffect | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 设置滑动效果，目前支持的滑动效果参见EdgeEffect的枚举说明。<br/>默认值：EdgeEffect.None | 32 33## ScrollDirection枚举说明 34| 名称 | 描述 | 35| ---------------------------- | ----------------------------------- | 36| Horizontal | 仅支持水平方向滚动。 | 37| Vertical | 仅支持竖直方向滚动。 | 38| None | 不可滚动。 | 39| Free<sup>(deprecated) </sup> | 支持竖直或水平方向滚动<br/> 从API version 9开始废弃 | 40 41## 事件 42 43| 名称 | 功能描述 | 44| ---------------------------------------- | ---------------------------------------- | 45| onScrollBegin<sup>9+</sup>(event: (dx: number, dy: number) => { dxRemain: number, dyRemain: number }) | 滚动开始事件回调。<br>参数：<br>- dx：即将发生的水平方向滚动量。<br>- dy：即将发生的竖直方向滚动量。<br>返回值：<br>- dxRemain：水平方向滚动剩余量。<br>- dyRemain：竖直方向滚动剩余量。 | 46| onScroll(event: (xOffset: number, yOffset: number) => void) | 滚动事件回调, 返回滚动时水平、竖直方向偏移量。 | 47| onScrollEdge(event: (side: Edge) => void) | 滚动到边缘事件回调。 | 48| onScrollEnd(event: () => void) | 滚动停止事件回调。 | 49 50> **说明：** 51> 52> 若通过onScrollBegin事件和scrollBy方法实现容器嵌套滚动，需设置子滚动节点的EdgeEffect为None。如Scroll嵌套List滚动时，List组件的edgeEffect属性需设置为EdgeEffect.None。 53 54## Scroller 55 56可滚动容器组件的控制器，可以将此组件绑定至容器组件，然后通过它控制容器组件的滚动，同一个控制器不可以控制多个容器组件，目前支持绑定到List、Scroll、ScrollBar上。 57 58 59### 导入对象 60 61``` 62scroller: Scroller = new Scroller() 63``` 64 65 66### scrollTo 67 68scrollTo(value: { xOffset: number | string, yOffset: number | string, animation?: { duration: number, curve: Curve } }): void 69 70 71滑动到指定位置。 72 73**参数：** 74 75| 参数名 | 参数类型 | 必填 | 参数描述 | 76| --------- | ---------------------------------------- | ---- | ---------------------------------------- | 77| xOffset | Length | 是 | 水平滑动偏移。 | 78| yOffset | Length | 是 | 竖直滑动偏移。 | 79| animation | {<br/>duration: number,<br/>curve: [Curve](ts-animatorproperty.md)<br/>} | 否 | 动画配置：<br/>- duration: 滚动时长设置。<br/>- curve: 滚动曲线设置。 | 80 81 82### scrollEdge 83 84scrollEdge(value: Edge): void 85 86 87滚动到容器边缘。 88 89**参数：** 90 91| 参数名 | 参数类型 | 必填 | 参数描述 | 92| ----- | --------------------------------- | ---- | --------- | 93| value | [Edge](ts-appendix-enums.md#edge) | 是 | 滚动到的边缘位置。 | 94 95 96### scrollPage 97 98scrollPage(value: { next: boolean, direction?: Axis }): void 99 100滚动到下一页或者上一页。 101 102**参数：** 103 104| 参数名 | 参数类型 | 必填 | 参数描述 | 105| --------------------------------- | --------------------------------- | ---- | --------------------------------------- | 106| next | boolean | 是 | 是否向下翻页。true表示向下翻页，false表示向上翻页。 | 107| direction<sup>(deprecated) </sup> | [Axis](ts-appendix-enums.md#axis) | 否 | 设置滚动方向为水平或竖直方向。<br/> 从API version 9开始废弃 | 108 109 110### currentOffset 111 112currentOffset() 113 114 115返回当前的滚动偏移量。 116 117**返回值** 118 119| 类型 | 描述 | 120| ---------------------------------------- | ---------------------------------------- | 121| {<br/>xOffset: number,<br/>yOffset: number<br/>} | xOffset: 水平滑动偏移;<br/>yOffset: 竖直滑动偏移。 | 122 123 124### scrollToIndex 125 126scrollToIndex(value: number): void 127 128 129滑动到指定Index。 130 131 132> **说明：** 133> 134> 仅支持list组件。 135 136**参数：** 137 138| 参数名 | 参数类型 | 必填 | 参数描述 | 139| ----- | ------ | ---- | ----------------- | 140| value | number | 是 | 要滑动到的列表项在列表中的索引值。 | 141 142 143### scrollBy<sup>9+</sup> 144 145scrollBy(dx: Length, dy: Length): void 146 147 148滑动指定距离。 149 150 151> **说明：** 152> 153> 仅支持Scroll组件。 154 155**参数：** 156 157| 参数名 | 参数类型 | 必填 | 参数描述 | 158| ---- | ------ | ---- | ------------------ | 159| dx | Length | 是 | 水平方向滚动距离，不支持百分比形式。 | 160| dy | Length | 是 | 竖直方向滚动距离，不支持百分比形式。 | 161 162 163## 示例 164### 示例1 165 166```ts 167// xxx.ets 168@Entry 169@Component 170struct ScrollExample { 171 scroller: Scroller = new Scroller(); 172 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; 173 174 build() { 175 Stack({ alignContent: Alignment.TopStart }) { 176 Scroll(this.scroller) { 177 Column() { 178 ForEach(this.arr, (item) => { 179 Text(item.toString()) 180 .width('90%') 181 .height(150) 182 .backgroundColor(0xFFFFFF) 183 .borderRadius(15) 184 .fontSize(16) 185 .textAlign(TextAlign.Center) 186 .margin({ top: 10 }) 187 }, item => item) 188 }.width('100%') 189 } 190 .scrollable(ScrollDirection.Vertical) // 滚动方向纵向 191 .scrollBar(BarState.On) // 滚动条常驻显示 192 .scrollBarColor(Color.Gray) // 滚动条颜色 193 .scrollBarWidth(30) // 滚动条宽度 194 .edgeEffect(EdgeEffect.None) 195 .onScroll((xOffset: number, yOffset: number) => { 196 console.info(xOffset + ' ' + yOffset); 197 }) 198 .onScrollEdge((side: Edge) => { 199 console.info('To the edge'); 200 }) 201 .onScrollEnd(() => { 202 console.info('Scroll Stop'); 203 }) 204 205 Button('scroll 150') 206 .onClick(() => { // 点击后下滑指定距离150.0vp 207 this.scroller.scrollBy(0,150); 208 }) 209 .margin({ top: 10, left: 20 }) 210 Button('scroll 100') 211 .onClick(() => { // 点击后滑动到指定位置，即下滑100.0vp的距离 212 this.scroller.scrollTo({ xOffset: 0, yOffset: this.scroller.currentOffset().yOffset + 100 }); 213 }) 214 .margin({ top: 60, left: 20 }) 215 Button('back top') 216 .onClick(() => { // 点击后回到顶部 217 this.scroller.scrollEdge(Edge.Top); 218 }) 219 .margin({ top: 110, left: 20 }) 220 Button('next page') 221 .onClick(() => { // 点击后滑到下一页 222 this.scroller.scrollPage({ next: true }); 223 }) 224 .margin({ top: 170, left: 20 }) 225 }.width('100%').height('100%').backgroundColor(0xDCDCDC) 226 } 227} 228``` 229 230 231 232### 示例2 233```ts 234@Entry 235@Component 236struct NestedScroll { 237 @State listPosition: number = 0; // 0代表滚动到List顶部，1代表中间值，2代表滚动到List底部。 238 private arr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; 239 private scroller: Scroller = new Scroller(); 240 241 build() { 242 Flex() { 243 Scroll(this.scroller) { 244 Column() { 245 Text("Scroll Area") 246 .width("100%").height("40%").backgroundColor(0X330000FF) 247 .fontSize(16).textAlign(TextAlign.Center) 248 249 List({ space: 20 }) { 250 ForEach(this.arr, (item) => { 251 ListItem() { 252 Text("ListItem" + item) 253 .width("100%").height("100%").borderRadius(15) 254 .fontSize(16).textAlign(TextAlign.Center).backgroundColor(Color.White) 255 }.width("100%").height(100) 256 }, item => item) 257 } 258 .width("100%").height("50%").edgeEffect(EdgeEffect.None) 259 .onReachStart(() => { 260 this.listPosition = 0; 261 }) 262 .onReachEnd(() => { 263 this.listPosition = 2; 264 }) 265 .onScrollBegin((dx: number, dy: number) => { 266 if ((this.listPosition == 0 && dy >= 0) || (this.listPosition == 2 && dy <= 0)) { 267 this.scroller.scrollBy(0, -dy); 268 return { dxRemain: dx, dyRemain: 0 }; 269 } 270 this.listPosition = 1; 271 return { dxRemain: dx, dyRemain: dy }; 272 }) 273 274 Text("Scroll Area") 275 .width("100%").height("40%").backgroundColor(0X330000FF) 276 .fontSize(16).textAlign(TextAlign.Center) 277 } 278 } 279 .width("100%").height("100%") 280 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20) 281 } 282} 283``` 284 285
