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