ts-container-scroll.md 9.2 KB
Newer Older
Z
zengyawen 已提交
1 2
# Scroll

H
geshi  
HelloCrease 已提交
3
>  **说明:**
L
luoying_ace_admin 已提交
4 5
> - 该组件从API version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
> - 该组件嵌套List子组件滚动时,若List不设置宽高,则默认全部加载,在对性能有要求的场景下建议指定List的宽高。
Z
zengyawen 已提交
6

Z
zengyawen 已提交
7 8 9

可滚动的容器组件,当子组件的布局尺寸超过父组件的视口时,内容可以滚动。

Z
zengyawen 已提交
10 11

## 权限列表
Z
zengyawen 已提交
12 13 14



Z
zengyawen 已提交
15 16

## 子组件
Z
zengyawen 已提交
17 18 19

支持单个子组件。

Z
zengyawen 已提交
20 21 22 23 24 25 26 27

## 接口

Scroll(scroller?: Scroller)


## 属性

H
HelloCrease 已提交
28 29 30 31 32 33
| 名称             | 参数类型                                     | 默认值                      | 描述        |
| -------------- | ---------------------------------------- | ------------------------ | --------- |
| scrollable     | ScrollDirection                          | ScrollDirection.Vertical | 设置滚动方法。   |
| scrollBar      | [BarState](ts-appendix-enums.md#barstate枚举说明) | ScrollDirection.Auto     | 设置滚动条状态。  |
| scrollBarColor | Color                                    | -                        | 设置滚动条的颜色。 |
| scrollBarWidth | Length                                   | -                        | 设置滚动条的宽度。 |
Z
zengyawen 已提交
34 35

- ScrollDirection枚举说明
H
HelloCrease 已提交
36 37 38 39 40
  | 名称         | 描述         |
  | ---------- | ---------- |
  | Horizontal | 仅支持水平方向滚动。 |
  | Vertical   | 仅支持竖直方向滚动。 |
  | None       | 不可滚动。      |
Z
zengyawen 已提交
41

42 43
## 事件

H
HelloCrease 已提交
44 45
| 名称                                       | 功能描述                          |
| ---------------------------------------- | ----------------------------- |
C
caocan 已提交
46
| onScrollBegin<sup>9+</sup>(dx: number, dy: number)&nbsp;=&gt;&nbsp;{ dxRemain: number, dyRemain: number } | 滚动开始事件回调。<br>参数:<br>- dx:即将发生的水平方向滚动量。<br>- dy:即将发生的竖向方向滚动量。<br>返回值:<br>- dxRemain:水平方向滚动剩余量。<br>- dyRemain:竖直方向滚动剩余量。 |
H
HelloCrease 已提交
47 48 49
| onScroll(xOffset:&nbsp;number,&nbsp;yOffset:&nbsp;number)&nbsp;=&gt;&nbsp;void | 滚动事件回调,&nbsp;返回滚动时水平、竖直方向偏移量。 |
| onScrollEdge(side:&nbsp;Edge)&nbsp;=&gt;&nbsp;void | 滚动到边缘事件回调。                    |
| onScrollEnd()&nbsp;=&gt;&nbsp;void       | 滚动停止事件回调。                     |
Z
zengyawen 已提交
50

C
caocan 已提交
51 52 53
>  **说明:**
> 若通过onScrollBegin事件和scrollBy方法实现容器嵌套滚动,需设置子滚动节点的EdgeEffect为None。如Scroll嵌套List滚动时,List组件的edgeEffect属性需设置为EdgeEffect.None。

Z
zengyawen 已提交
54
## Scroller
Z
zengyawen 已提交
55 56 57

可滚动容器组件的控制器,可以将此组件绑定至容器组件,然后通过它控制容器组件的滚动,目前支持绑定到List和Scroll组件上。

Z
zengyawen 已提交
58 59

### 导入对象
Z
zengyawen 已提交
60 61 62 63 64 65

```
scroller: Scroller = new Scroller()
```


66
### scrollTo
Z
zengyawen 已提交
67 68 69

scrollTo(value: { xOffset: number | string, yOffset: number | string, animation?: { duration: number, curve: Curve } }): void

Z
zengyawen 已提交
70 71 72

滑动到指定位置。

Z
zengyawen 已提交
73 74

- 参数
H
HelloCrease 已提交
75 76 77 78 79
  | 参数名       | 参数类型                                     | 必填   | 默认值  | 参数描述                                     |
  | --------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- |
  | xOffset   | Length                                   | 是    | -    | 水平滑动偏移。                                  |
  | yOffset   | Length                                   | 是    | -    | 竖直滑动偏移。                                  |
  | animation | {<br/>duration:&nbsp;number,<br/>curve:&nbsp;[Curve](ts-animatorproperty.md)&nbsp;\|<br/>CubicBezier&nbsp;\|<br/>SpringCurve<br/>} | 否    |      | 动画配置:<br/>-&nbsp;duration:&nbsp;滚动时长设置。<br/>-&nbsp;curve:&nbsp;滚动曲线设置。 |
Z
zengyawen 已提交
80 81


82
### scrollEdge
Z
zengyawen 已提交
83 84 85

scrollEdge(value: Edge): void

Z
zengyawen 已提交
86 87 88

滚动到容器边缘。

Z
zengyawen 已提交
89 90

- 参数
H
HelloCrease 已提交
91 92 93
  | 参数名   | 参数类型 | 必填   | 默认值  | 参数描述      |
  | ----- | ---- | ---- | ---- | --------- |
  | value | Edge | 是    | -    | 滚动到的边缘位置。 |
Z
zengyawen 已提交
94 95


96
### scrollPage
Z
zengyawen 已提交
97 98

scrollPage(value: { next: boolean, direction?: Axis }): void
Z
zengyawen 已提交
99 100

滚动到下一页或者上一页。
Z
zengyawen 已提交
101

Z
zengyawen 已提交
102
- 参数
H
HelloCrease 已提交
103 104 105 106
  | 参数名       | 参数类型    | 必填   | 默认值  | 参数描述                           |
  | --------- | ------- | ---- | ---- | ------------------------------ |
  | next      | boolean | 是    | -    | 是否向下翻页。true表示向下翻页,false表示向上翻页。 |
  | direction | Axis    | 否    | -    | 设置滚动方向为水平或竖直方向。                |
Z
zengyawen 已提交
107 108


109
### currentOffset
Z
zengyawen 已提交
110

C
caocan 已提交
111
currentOffset(): Object
Z
zengyawen 已提交
112

Z
zengyawen 已提交
113 114 115 116

返回当前的滚动偏移量。


Z
zengyawen 已提交
117
- 返回值
H
HelloCrease 已提交
118 119 120
  | 类型                                       | 描述                                       |
  | ---------------------------------------- | ---------------------------------------- |
  | {<br/>xOffset:&nbsp;number,<br/>yOffset:&nbsp;number<br/>} | xOffset:&nbsp;水平滑动偏移;<br/>yOffset:&nbsp;竖直滑动偏移。 |
Z
zengyawen 已提交
121

Z
zengyawen 已提交
122

123
### scrollToIndex
Z
zengyawen 已提交
124

C
caocan 已提交
125
scrollToIndex(value: number): void
Z
zengyawen 已提交
126 127 128 129


滑动到指定Index。

Z
zengyawen 已提交
130

H
geshi  
HelloCrease 已提交
131
>  **说明:**
Z
zengyawen 已提交
132 133 134 135
> 仅支持list组件。


- 参数
H
HelloCrease 已提交
136 137 138
  | 参数名   | 参数类型   | 必填   | 默认值  | 参数描述              |
  | ----- | ------ | ---- | ---- | ----------------- |
  | value | number | 是    | -    | 要滑动到的列表项在列表中的索引值。 |
Z
zengyawen 已提交
139 140


C
caocan 已提交
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
### scrollBy

scrollBy(dx: Length, dy: Length): void


滑动指定距离。


>  **说明:**
> 仅支持Scroll组件。


- 参数
  | 参数名   | 参数类型   | 必填   | 默认值  | 参数描述              |
  | ----- | ------ | ---- | ---- | ----------------- |
  | dx | Length | 是    | -    | 水平方向滚动距离。 |
  | dy | Length | 是    | -    | 竖直方向滚动距离。 |


Z
zengyawen 已提交
160
## 示例
Z
zengyawen 已提交
161

H
geshi  
HelloCrease 已提交
162 163
```ts
// xxx.ets
Z
zengyawen 已提交
164 165 166 167 168 169 170 171 172 173 174 175
@Entry
@Component
struct ScrollExample {
  scroller: Scroller = new Scroller()
  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

  build() {
    Stack({ alignContent: Alignment.TopStart }) {
      Scroll(this.scroller) {
        Column() {
          ForEach(this.arr, (item) => {
            Text(item.toString())
G
gmy 已提交
176 177 178 179 180 181
              .width('90%')
              .height(150)
              .backgroundColor(0xFFFFFF)
              .borderRadius(15)
              .fontSize(16)
              .textAlign(TextAlign.Center)
Z
zengyawen 已提交
182 183 184 185
              .margin({ top: 10 })
          }, item => item)
        }.width('100%')
      }
G
gmy 已提交
186 187 188 189
      .scrollable(ScrollDirection.Vertical)
      .scrollBar(BarState.On)
      .scrollBarColor(Color.Gray)
      .scrollBarWidth(30)
Z
zengyawen 已提交
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
      .onScroll((xOffset: number, yOffset: number) => {
        console.info(xOffset + ' ' + yOffset)
      })
      .onScrollEdge((side: Edge) => {
        console.info('To the edge')
      })
      .onScrollEnd(() => {
        console.info('Scroll Stop')
      })

      Button('scroll 100')
        .onClick(() => { // 点击后下滑100.0距离
          this.scroller.scrollTo({ xOffset: 0, yOffset: this.scroller.currentOffset().yOffset + 100 })
        })
        .margin({ top: 10, left: 20 })
      Button('back top')
        .onClick(() => { // 点击后回到顶部
          this.scroller.scrollEdge(Edge.Top)
        })
        .margin({ top: 60, left: 20 })
      Button('next page')
        .onClick(() => { // 点击后下滑到底部
          this.scroller.scrollPage({ next: true })
        })
        .margin({ top: 110, left: 20 })
    }.width('100%').height('100%').backgroundColor(0xDCDCDC)
  }
}
```

Z
zengyawen 已提交
220
![zh-cn_image_0000001174104386](figures/zh-cn_image_0000001174104386.gif)
C
caocan 已提交
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275


```ts
@Entry
@Component
struct NestedScroll {
  @State listPosition: number = 0 // 0代表滚动到List顶部,1代表中间值,2代表滚动到List底部。
  private arr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
  private scroller: Scroller = new Scroller()

  build() {
    Flex() {
      Scroll(this.scroller) {
        Column() {
          Text("Scroll Area")
            .width("100%").height("40%").backgroundColor(0X330000FF)
            .fontSize(16).textAlign(TextAlign.Center)

          List({ space: 20 }) {
            ForEach(this.arr, (item) => {
              ListItem() {
                Text("ListItem" + item)
                  .width("100%").height("100%").borderRadius(15)
                  .fontSize(16).textAlign(TextAlign.Center).backgroundColor(Color.White)
              }.width("100%").height(100)
            }, item => item)
          }
          .width("100%").height("50%").edgeEffect(EdgeEffect.None)
          .onReachStart(() => {
            this.listPosition = 0
          })
          .onReachEnd(() => {
            this.listPosition = 2
          })
          .onScrollBegin((dx: number, dy: number) => {
            if ((this.listPosition == 0 && dy >= 0) || (this.listPosition == 2 && dy <= 0)) {
              this.scroller.scrollBy(0, -dy)
              return { dxRemain: dx, dyRemain: 0 }
            }
            this.listPosition = 1;
            return { dxRemain: dx, dyRemain: dy }
          })

          Text("Scroll Area")
            .width("100%").height("40%").backgroundColor(0X330000FF)
            .fontSize(16).textAlign(TextAlign.Center)
        }
      }
      .width("100%").height("100%")
    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding(20)
  }
}
```

![NestedScroll](figures/NestedScroll.gif)