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

E
ester.zhou 已提交
3
>  **NOTE**
E
esterzhou 已提交
4 5 6
>  - This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
>  - When nesting a **\<List>** within this component, specify the width and height for the **\<List>** under scenarios where consistently high performance is required. If the width and height are not specified, this component will load all content of the **\<List>**.
>  - This component can produce a bounce effect only when there is more than one screen of content.
Z
zengyawen 已提交
7

Z
zengyawen 已提交
8

E
ester.zhou 已提交
9
The **\<Scroll>** component scrolls the content when the layout size of a component exceeds the viewport of its parent component.
Z
zengyawen 已提交
10 11 12


## Required Permissions
Z
zengyawen 已提交
13

E
ester.zhou 已提交
14
None.
Z
zengyawen 已提交
15

Z
zengyawen 已提交
16 17

## Child Components
Z
zengyawen 已提交
18 19 20

This component supports only one child component.

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

## APIs

Scroll(scroller?: Scroller)


## Attributes

E
ester.zhou 已提交
29 30 31
| Name            | Type                                    | Default Value                     | Description       |
| -------------- | ---------------------------------------- | ------------------------ | --------- |
| scrollable     | ScrollDirection                          | ScrollDirection.Vertical | Scroll method.  |
E
esterzhou 已提交
32 33
| scrollBar      | [BarState](ts-appendix-enums.md#barstate) | BarState.Off     | Scrollbar status. |
| scrollBarColor | string&nbsp;\|&nbsp;number&nbsp;\|&nbsp;Color   | -                  | Color of the scrollbar.|
E
ester.zhou 已提交
34
| scrollBarWidth | Length                                   | -                        | Width of the scrollbar.|
E
esterzhou 已提交
35
| edgeEffect     | EdgeEffect                               | EdgeEffect.Spring | Scroll effect. For details, see **EdgeEffect**.|
Z
zengyawen 已提交
36

E
esterzhou 已提交
37
## ScrollDirection enums
E
ester.zhou 已提交
38 39 40 41 42
  | Name        | Description        |
  | ---------- | ---------- |
  | Horizontal | Only horizontal scrolling is supported.|
  | Vertical   | Only vertical scrolling is supported.|
  | None       | Scrolling is disabled.     |
Z
zengyawen 已提交
43

E
esterzhou 已提交
44 45 46 47 48 49 50 51
## EdgeEffect

| Name    | Description                                      |
| ------ | ---------------------------------------- |
| Spring | Spring effect. When at one of the edges, the component can move beyond the bounds through touches, and produces a bounce effect when the user releases their finger.|
| Fade   | Fade effect. When at one of the edges, the component produces a fade effect.         |
| None   | No effect when the component is at one of the edges.                              |

52 53
## Events

E
ester.zhou 已提交
54 55 56
| Name                                      | Description                         |
| ---------------------------------------- | ----------------------------- |
| onScrollBegin<sup>9+</sup>(dx: number, dy: number)&nbsp;=&gt;&nbsp;{ dxRemain: number, dyRemain: number } | Invoked when scrolling starts.<br>Parameters:<br>- **dx**: amount to scroll by in the horizontal direction.<br>- **dy**: amount to scroll by in the vertical direction.<br>Return value:<br>- **dxRemain**: remaining amount to scroll by in the horizontal direction.<br>- **dyRemain**: remaining amount to scroll by in the vertical direction.|
E
esterzhou 已提交
57 58 59
| onScroll(event: (xOffset: number, yOffset: number) => void) | Invoked to return the horizontal and vertical offsets during scrolling when the specified scroll event occurs.|
| onScrollEdge(event: (side: Edge) => void) | Invoked when scrolling reaches the edge.                   |
| onScrollEnd(event: () => void)      | Invoked when scrolling stops.                    |
60 61

>  **NOTE**
E
ester.zhou 已提交
62
> If the **onScrollBegin** event and **scrollBy** API are used to implement nested scrolling, you must set **edgeEffect** of the scrolling child node to **None**. For example, if a **\<List>** is nested in the **\<Scroll>** component, the **edgeEffect** attribute of the **\<List>** must be set to **EdgeEffect.None**.
Z
zengyawen 已提交
63 64 65

## Scroller

E
esterzhou 已提交
66
Implements a controller for a scrollable container component. You can bind this component to a container component and use it to control the scrolling of that component. Currently, this component can be bound to the **\<Scroll>** and **\<ScrollBar>** components.
Z
zengyawen 已提交
67 68 69 70


### Objects to Import

Z
zengyawen 已提交
71 72 73 74 75
```
scroller: Scroller = new Scroller()
```


76
### scrollTo
Z
zengyawen 已提交
77 78 79

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

Z
zengyawen 已提交
80 81 82

Scrolls to the specified position.

Z
zengyawen 已提交
83 84

- Parameters
E
ester.zhou 已提交
85 86 87 88 89
  | Name      | Type                                    | Mandatory  | Default Value | Description                                    |
  | --------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- |
  | xOffset   | Length                                   | Yes   | -    | Horizontal scrolling offset.                                 |
  | yOffset   | Length                                   | Yes   | -    | Vertical scrolling offset.                                 |
  | animation | {<br>duration:&nbsp;number,<br>curve:&nbsp;[Curve](ts-animatorproperty.md)&nbsp;\|<br>CubicBezier&nbsp;\|<br>SpringCurve<br>} | No   |      | Animation configuration, which includes the following:<br>- **duration**: scrolling duration.<br>- **curve**: scrolling curve.|
Z
zengyawen 已提交
90 91


92
### scrollEdge
Z
zengyawen 已提交
93 94 95

scrollEdge(value: Edge): void

Z
zengyawen 已提交
96 97 98

Scrolls to the edge of the container.

Z
zengyawen 已提交
99 100

- Parameters
E
ester.zhou 已提交
101 102
  | Name  | Type| Mandatory  | Default Value | Description     |
  | ----- | ---- | ---- | ---- | --------- |
E
esterzhou 已提交
103
  | value | [Edge](ts-appendix-enums.md#edge) | Yes   | -    | Edge position to scroll to.|
E
ester.zhou 已提交
104

Z
zengyawen 已提交
105

E
ester.zhou 已提交
106
  
Z
zengyawen 已提交
107

108
### scrollPage
Z
zengyawen 已提交
109 110

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

Scrolls to the next or previous page.
Z
zengyawen 已提交
113

Z
zengyawen 已提交
114
- Parameters
E
ester.zhou 已提交
115 116 117
  | Name      | Type   | Mandatory  | Default Value | Description                          |
  | --------- | ------- | ---- | ---- | ------------------------------ |
  | next      | boolean | Yes   | -    | Whether to turn to the next page. The value **true** means to scroll to the next page, and **false** means to scroll to the previous page.|
E
esterzhou 已提交
118
  | direction | [Axis](ts-appendix-enums.md#axis)    | No   | -    | Scrolling direction: horizontal or vertical.               |
Z
zengyawen 已提交
119 120


121
### currentOffset
Z
zengyawen 已提交
122

E
ester.zhou 已提交
123
currentOffset(): Object
Z
zengyawen 已提交
124

Z
zengyawen 已提交
125 126 127 128

Obtains the scrolling offset.


E
ester.zhou 已提交
129
- Return value
E
esterzhou 已提交
130 131 132
  | Type                                      | Description                                      |
  | ---------------------------------------- | ---------------------------------------- |
  | {<br>xOffset:&nbsp;number,<br>yOffset:&nbsp;number<br>} | **xOffset**: horizontal scrolling offset.<br>**yOffset**: vertical scrolling offset.|
Z
zengyawen 已提交
133

Z
zengyawen 已提交
134

E
ester.zhou 已提交
135
### scrollToIndex
Z
zengyawen 已提交
136

E
ester.zhou 已提交
137
scrollToIndex(value: number): void
Z
zengyawen 已提交
138 139


E
ester.zhou 已提交
140
Scrolls to the item with the specified index.
Z
zengyawen 已提交
141

Z
zengyawen 已提交
142

E
ester.zhou 已提交
143
>  **NOTE**
144
> Only the **\<List>** component is supported.
Z
zengyawen 已提交
145 146 147


- Parameters
E
ester.zhou 已提交
148 149 150
  | Name  | Type  | Mandatory  | Default Value | Description             |
  | ----- | ------ | ---- | ---- | ----------------- |
  | value | number | Yes   | -    | Index of the item to be scrolled to in the list.|
Z
zengyawen 已提交
151 152


153
### scrollBy
Z
zengyawen 已提交
154

155
scrollBy(dx: Length, dy: Length): void
Z
zengyawen 已提交
156 157


158
Scrolls by the specified amount.
Z
zengyawen 已提交
159

Z
zengyawen 已提交
160

161
>  **NOTE**
E
ester.zhou 已提交
162
> Only the **\<Scroll>** component is supported.
163 164 165 166 167 168 169 170 171 172 173 174 175


- Parameters
  | Name  | Type  | Mandatory  | Default Value | Description             |
  | ----- | ------ | ---- | ---- | ----------------- |
  | dx | Length | Yes   | -    | Amount to scroll by in the horizontal direction.|
  | dy | Length | Yes   | -    | Amount to scroll by in the vertical direction.|


## Example

```ts
// xxx.ets
Z
zengyawen 已提交
176 177 178 179 180 181 182 183 184 185 186 187
@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())
188 189 190 191 192 193
              .width('90%')
              .height(150)
              .backgroundColor(0xFFFFFF)
              .borderRadius(15)
              .fontSize(16)
              .textAlign(TextAlign.Center)
Z
zengyawen 已提交
194 195 196 197
              .margin({ top: 10 })
          }, item => item)
        }.width('100%')
      }
198 199 200 201
      .scrollable(ScrollDirection.Vertical)
      .scrollBar(BarState.On)
      .scrollBarColor(Color.Gray)
      .scrollBarWidth(30)
Z
zengyawen 已提交
202 203 204 205 206 207 208 209 210 211 212
      .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')
E
ester.zhou 已提交
213
        .onClick(() => { // Click to scroll down 100.0.
Z
zengyawen 已提交
214 215 216 217
          this.scroller.scrollTo({ xOffset: 0, yOffset: this.scroller.currentOffset().yOffset + 100 })
        })
        .margin({ top: 10, left: 20 })
      Button('back top')
E
ester.zhou 已提交
218
        .onClick(() => { // Click to go back to the top.
Z
zengyawen 已提交
219 220 221 222
          this.scroller.scrollEdge(Edge.Top)
        })
        .margin({ top: 60, left: 20 })
      Button('next page')
E
ester.zhou 已提交
223
        .onClick(() => { // Click to scroll down to the bottom.
Z
zengyawen 已提交
224 225 226 227 228 229 230 231
          this.scroller.scrollPage({ next: true })
        })
        .margin({ top: 110, left: 20 })
    }.width('100%').height('100%').backgroundColor(0xDCDCDC)
  }
}
```

Z
zengyawen 已提交
232
![en-us_image_0000001256978363](figures/en-us_image_0000001256978363.gif)
E
ester.zhou 已提交
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 276 277 278 279 280 281 282 283 284 285 286 287
```ts
@Entry
@Component
struct NestedScroll {
  @State listPosition: number = 0 // 0 indicates scrolling to the top of the list, 1 indicates scrolling to the center of the list, and 2 indicates scrolling to the bottom of the 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)
新手
引导
客服 返回
顶部