• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ScrollBar
2
3滚动条组件ScrollBar，用于配合可滚动组件使用，如[ArcList](ts-container-arclist.md)、[List](ts-container-list.md)、[Grid](ts-container-grid.md)、[Scroll](ts-container-scroll.md)、[WaterFlow](ts-container-waterflow.md)。
4
5>  **说明：**
6>
7>  - 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
8>  - ScrollBar主轴方向不设置大小时，采用父组件[布局约束](../js-apis-arkui-frameNode.md#layoutconstraint12)中的maxSize作为主轴方向大小。如果ScrollBar的父组件存在可滚动组件，如[ArcList](ts-container-arclist.md)、[List](ts-container-list.md)、[Grid](ts-container-grid.md)、[Scroll](ts-container-scroll.md)、[WaterFlow](ts-container-waterflow.md)，建议设置ScrollBar主轴方向大小，否则ScrollBar主轴方向大小可能为无穷大。
9
10
11## 子组件
12
13可以包含单个子组件。
14
15
16## 接口
17
18ScrollBar(value: ScrollBarOptions)
19
20创建滚动条组件。
21
22**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
23
24**系统能力：** SystemCapability.ArkUI.ArkUI.Full
25
26**参数：**
27
28| 参数名 | 类型 | 必填 | 说明 |
29| -------- | -------- | -------- | -------- |
30| value |  [ScrollBarOptions](#scrollbaroptions对象说明)| 是 | 滚动条组件参数。 |
31
32## 属性
33
34除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性：
35
36### enableNestedScroll<sup>14+</sup>
37
38enableNestedScroll(enabled: Optional\<boolean>)
39
40设置滚动条是否嵌套滚动。
41
42**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。
43
44**系统能力：** SystemCapability.ArkUI.ArkUI.Full
45
46**参数：**
47
48| 参数名 | 类型    | 必填 | 说明                                  |
49| ------ | ------- | ---- | ------------------------------------- |
50| enabled  | Optional\<boolean> | 是   | 是否执行嵌套滚动。设置为true执行嵌套滚动，设置为false不嵌套滚动。 <br/>默认值：false |
51
52>  **说明：**
53>
54> 滚动条使能嵌套滚动时，滚动条的滚动偏移量会先发给绑定的内层滚动组件，内层滚动组件再根据设置的嵌套滚动优先级依次传递给外层父滚动组件。
55>
56> WaterFlow组件的布局模式为移动窗口式（SLIDING_WINDOW）时，不支持嵌套滚动。
57>
58> 设置嵌套滚动模式为PARALLEL时，父子组件同时滚动，需要开发者在onScrollFrameBegin中按照所需逻辑，自行设置父子组件滚动顺序。
59
60## ScrollBarOptions对象说明
61
62滚动条组件参数。
63
64**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
65
66**系统能力：** SystemCapability.ArkUI.ArkUI.Full
67
68| 名称 | 类型 | 必填 | 说明 |
69| -------- | -------- | -------- | -------- |
70| scroller | [Scroller](ts-container-scroll.md#scroller) | 是 | 可滚动组件的控制器。用于与可滚动组件进行绑定。 |
71| direction | [ScrollBarDirection](#scrollbardirection枚举说明) | 否 | 滚动条的方向，控制可滚动组件对应方向的滚动。<br/>默认值：ScrollBarDirection.Vertical |
72| state | [BarState](ts-appendix-enums.md#barstate) | 否 | 滚动条状态。<br/>默认值：BarState.Auto |
73
74>  **说明：**
75>
76> ScrollBar组件负责定义可滚动区域的行为样式，ScrollBar的子节点负责定义滚动条的行为样式。
77>
78> 滚动条组件与可滚动组件通过Scroller进行绑定，且只有当两者方向相同时，才能联动，ScrollBar与可滚动组件仅支持一对一绑定。
79>
80> 从API version 12开始，ScrollBar组件没有子节点时，支持显示默认样式的滚动条。
81
82## ScrollBarDirection枚举说明
83
84滚动条方向枚举。
85
86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
87
88**系统能力：** SystemCapability.ArkUI.ArkUI.Full
89
90| 名称 | 说明 |
91| -------- | -------- |
92| Vertical | 纵向滚动条。 |
93| Horizontal | 横向滚动条。 |
94
95
96## 示例1（设置子节点）
97
98该示例为ScrollBar组件有子节点时的滚动条样式。
99
100```ts
101// xxx.ets
102@Entry
103@Component
104struct ScrollBarExample {
105  private scroller: Scroller = new Scroller()
106  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
107
108  build() {
109    Column() {
110      Stack({ alignContent: Alignment.End }) {
111        Scroll(this.scroller) {
112          Flex({ direction: FlexDirection.Column }) {
113            ForEach(this.arr, (item: number) => {
114              Row() {
115                Text(item.toString())
116                  .width('80%')
117                  .height(60)
118                  .backgroundColor('#3366CC')
119                  .borderRadius(15)
120                  .fontSize(16)
121                  .textAlign(TextAlign.Center)
122                  .margin({ top: 5 })
123              }
124            }, (item:number) => item.toString())
125          }.margin({ right: 15 })
126        }
127        .width('90%')
128        .scrollBar(BarState.Off)
129        .scrollable(ScrollDirection.Vertical)
130        ScrollBar({ scroller: this.scroller, direction: ScrollBarDirection.Vertical,state: BarState.Auto }) {
131          Text()
132            .width(20)
133            .height(100)
134            .borderRadius(10)
135            .backgroundColor('#C0C0C0')
136        }.width(20).backgroundColor('#ededed')
137      }
138    }
139  }
140}
141```
142
143
144![zh-cn_image_0000001232775585](figures/zh-cn_image_0000001232775585.gif)
145
146## 示例2（不设置子节点）
147
148该示例为ScrollBar组件没有子节点时的滚动条样式。
149
150```ts
151@Entry
152@Component
153struct ScrollBarExample {
154  private scroller: Scroller = new Scroller()
155  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
156
157  build() {
158    Column() {
159      Stack({ alignContent: Alignment.End }) {
160        Scroll(this.scroller) {
161          Flex({ direction: FlexDirection.Column }) {
162            ForEach(this.arr, (item: number) => {
163              Row() {
164                Text(item.toString())
165                  .width('80%')
166                  .height(60)
167                  .backgroundColor('#3366CC')
168                  .borderRadius(15)
169                  .fontSize(16)
170                  .textAlign(TextAlign.Center)
171                  .margin({ top: 5 })
172              }
173            }, (item:number) => item.toString())
174          }.margin({ right: 15 })
175        }
176        .width('90%')
177        .scrollBar(BarState.Off)
178        .scrollable(ScrollDirection.Vertical)
179        ScrollBar({ scroller: this.scroller, direction: ScrollBarDirection.Vertical,state: BarState.Auto })
180      }
181    }
182  }
183}
184```
185
186
187![zh-cn_image_scrollbar](figures/zh-cn_image_scrollbar.gif)
188
189## 示例3（支持嵌套滚动）
190
191该示例通过enableNestedScroll属性使ScrollBar组件支持嵌套滚动。
192```ts
193@Entry
194@Component
195struct StickyNestedScroll {
196  listScroller: Scroller = new Scroller();
197  @State array: number[] = []
198
199  @Styles
200  listCard() {
201    .backgroundColor(Color.White)
202    .height(72)
203    .width("100%")
204    .borderRadius(12)
205  }
206
207  build() {
208    Stack() {
209      Scroll() {
210        Column() {
211          Text('Scroll Area')
212            .width("100%")
213            .height("40%")
214            .backgroundColor('#0080DC')
215            .textAlign(TextAlign.Center)
216          List({ space: 10, scroller: this.listScroller }) {
217            ForEach(this.array, (item: number) => {
218              ListItem() {
219                Text('item' + item)
220                  .fontSize(16)
221              }
222              .listCard()
223            }, (item: string) => item)
224          }
225          .scrollBar(BarState.Off)
226          .nestedScroll({
227            scrollForward: NestedScrollMode.PARENT_FIRST,
228            scrollBackward: NestedScrollMode.SELF_FIRST
229          })
230          .height("100%")
231        }
232        .width("100%")
233      }
234      .edgeEffect(EdgeEffect.Spring)
235      .backgroundColor('#DCDCDC')
236      .scrollBar(BarState.Off)
237      .width('100%')
238      .height('100%')
239      ScrollBar({ scroller: this.listScroller})
240        .position({right:0})
241        .enableNestedScroll(true)
242    }
243  }
244
245  aboutToAppear() {
246    for (let i = 0; i < 15; i++) {
247      this.array.push(i)
248    }
249  }
250}
251```
252![EnableNestedScroll](figures/EnableNestedScroll.gif)