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