1# 图片边框设置 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @liyujie43--> 5<!--Designer: @weixin_52725220--> 6<!--Tester: @xiong0104--> 7<!--Adviser: @HelloCrease--> 8 9设置组件的图片边框样式。 10 11> **说明：** 12> 13> 从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## borderImage 16 17borderImage(value: BorderImageOption): T 18 19设置组件的图片边框。 20 21**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 22 23**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 24 25**系统能力：** SystemCapability.ArkUI.ArkUI.Full 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ----------- | ----------------------------------------------- | ---- | -------------------------------- | 31| value | [BorderImageOption](#borderimageoption对象说明) | 是 | 图片边框或者渐变色边框设置接口。 | 32 33**返回值：** 34 35| 类型 | 说明 | 36| ------ | ------------------------ | 37| T | 返回当前组件。 | 38 39## BorderImageOption对象说明 40 41**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 42 43**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | ------------------------------------------------------------ | 49| source | string \| [Resource](ts-types.md#resource) \| [LinearGradient](#lineargradient) | 否 | 是 | 边框图源或者渐变色设置。参数类型为string类型时，用于设置边框图源，引用方式请参考[加载图片资源](../../../ui/arkts-graphics-display.md#加载图片资源)。<br/>**说明：**<br>边框图源仅适用于容器组件，如[Row](ts-container-row.md)、[Column](ts-container-column.md)、[Flex](ts-container-flex.md)，在非容器组件上使用会失效。 | 50| slice | [Length](ts-types.md#length) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#localizededgewidths12)<sup>12+</sup>| 否 | 是 | 设置边框图片左上角、右上角、左下角以及右下角的切割宽度。<br/>默认值：0<br/>**说明：**<br/>设置负数时取默认值。<br/>参数类型为[Length](ts-types.md#length)时，统一设置四个角的宽高。<br/>参数类型为[EdgeWidths](ts-types.md#edgewidths9)时：<br/>- Top：设置图片左上角或者右上角被切割的高。<br/>- Bottom：设置图片左下角或者右下角被切割的高。<br/>- Left：设置图片左上角或者左下角被切割的宽。<br/>- Right：设置图片右上角或者右下角被切割的宽。 <br/>参数类型为[LocalizedEdgeWidths](ts-types.md#localizededgewidths12)<sup>12+</sup>时：<br/>- Top：设置图片左上角或者右上角被切割的高。<br/>- Bottom：设置图片左下角或者右下角被切割的高。<br/>- Start：设置图片左上角或者左下角被切割的宽。<br />从右至左显示语言模式下为设置图片右上角或者右下角被切割的宽。<br/>- End：设置图片右上角或者右下角被切割的宽。 从右至左显示语言模式下为设置图片左上角或者左下角被切割的宽。| 51| width | [Length](ts-types.md#length) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#localizededgewidths12)<sup>12+</sup> | 否 | 是 | 设置图片边框宽度。<br/>默认值：0<br/>**说明：**<br/>参数类型为[Length](ts-types.md#length)时，统一设置四个角的宽高，设置负数时取默认值。<br/>参数类型为[EdgeWidths](ts-types.md#edgewidths9)时：<br/>- Top：设置图片边框上边框的宽。<br/>- Bottom：设置图片边框下边框的宽。<br/>- Left：设置图片边框左边框的宽。<br/>- Right：设置图片边框右边框宽。<br/>参数类型为[LocalizedEdgeWidths](ts-types.md#localizededgewidths12)<sup>12+</sup>时：<br/>- Top：设置图片边框上边框的宽。<br/>- Bottom：设置图片边框下边框的宽。<br/>- Start：设置图片边框左边框的宽。<br />从右至左显示语言模式下为设置图片边框右边框宽。<br/>- End：设置图片边框右边框宽。<br />从右至左显示语言模式下为设置图片边框左边框的宽。<br/>设置负数时值取1。 | 52| outset | [Length](ts-types.md#length) \| [EdgeWidths](ts-types.md#edgewidths9) \| [LocalizedEdgeWidths](ts-types.md#localizededgewidths12)<sup>12+</sup> | 否 | 是 | 设置边框图片向外延伸距离。<br/>默认值：0<br/>**说明：**<br/>设置负数时取默认值。<br/>参数类型为[Length](ts-types.md#length)时，统一设置四个角的宽高。<br/>参数类型为[EdgeWidths](ts-types.md#edgewidths9)时：<br/>- Top：设置边框图片上边框向外延伸的距离。<br/>- Bottom：设置边框图片下边框向外延伸的距离。<br/>- Left：设置边框图片左边框向外延伸的距离。<br/>- Right：设置边框图片右边框向外延伸的距离。<br/>参数类型为[LocalizedEdgeWidths](ts-types.md#localizededgewidths12)<sup>12+</sup>时：<br/>- Top：设置边框图片上边框向外延伸的距离。<br/>- Bottom：设置边框图片下边框向外延伸的距离。<br/>- Start：设置边框图片左边框向外延伸的距离。<br/>从右至左显示语言模式下为设置边框图片右边框向外延伸的距离。<br/>- End：设置边框图片右边框向外延伸的距离。<br/>从右至左显示语言模式下为设置边框图片左边框向外延伸的距离。 | 53| repeat | [RepeatMode](#repeatmode枚举说明) | 否 | 是 | 设置被切割的图片在边框上的重复方式。<br/>默认值：RepeatMode.Stretch | 54| fill | boolean | 否 | 是 | 设置边框图片是否中心填充。true表示中心填充，false表示非中心填充。<br/>默认值：false | 55 56## RepeatMode枚举说明 57 58**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 59 60**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 61 62**系统能力：** SystemCapability.ArkUI.ArkUI.Full 63 64| 名称 | 值 | 说明 | 65| ------- | ----------------------------------- | ----------------------------------- | 66| Repeat | - | 被切割的图片会重复铺平在图片边框上，超出部分会被剪裁。 | 67| Stretch | - | 被切割的图片会以拉伸填充的方式铺满图片边框。 | 68| Round | - | 被切割的图片会以整数次平铺在图片边框上，无法以整数次平铺时会压缩图片。 | 69| Space | - | 被切割的图片会以整数次平铺在图片边框上，无法以整数次平铺时会以空白填充。 | 70 71## LinearGradient 72 73**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 74 75**系统能力：** SystemCapability.ArkUI.ArkUI.Full 76 77| 名称 | 类型 | 必填 | 说明 | 78| --------------- | ------ | ---- | ------------------------- | 79| angle | number \| string | 否 | 线性渐变的起始角度。0点方向顺时针旋转为正向角度。<br/>默认值：180<br/>角度为字符串时仅支持类型'deg'，'grad'，'rad'，'turn'。 | 80| direction | [GradientDirection](ts-appendix-enums.md#gradientdirection) | 否 | 线性渐变的方向，设置angle后不生效。<br/>默认值：GradientDirection.Bottom | 81| colors | Array<[[ResourceColor](ts-types.md#resourcecolor), number]> | 是 | 指定渐变色颜色和其对应的百分比位置的数组，设置非法颜色直接跳过。 | 82| repeating | boolean | 否 | 为渐变的颜色重复着色。<br/>默认值：false<br>true：允许为渐变的颜色重复着色。<br>false：不允许为渐变的颜色重复着色。 | 83 84## 示例 85 86### 示例1（设置渐变色边框） 87 88通过borderImage接口为组件设置渐变色边框。 89 90```ts 91// xxx.ets 92@Entry 93@Component 94struct Index { 95 build() { 96 Row() { 97 Column() { 98 Text('This is gradient color.').textAlign(TextAlign.Center).height(50).width(200) 99 .borderImage({ 100 source: { 101 angle: 90, 102 direction: GradientDirection.Left, 103 colors: [[0xAEE1E1, 0.0], [0xD3E0DC, 0.3], [0xFCD1D1, 1.0]] 104 }, 105 slice: { top: 10, bottom: 10, left: 10, right: 10 }, 106 width: { top: "10px", bottom: "10px", left: "10px", right: "10px" }, 107 repeat: RepeatMode.Stretch, 108 fill: false 109 }) 110 } 111 .width('100%') 112 } 113 .height('100%') 114 } 115} 116``` 117 118 119 120### 示例2（动态调整属性值） 121 122通过[slider](../../apis-arkui/arkui-js/js-components-basic-slider.md)接口动态调整borderImage接口中属性值。 123 124```ts 125// xxx.ets 126@Entry 127@Component 128struct BorderImage { 129 @State WidthValue: number = 0 130 @State SliceValue: number = 0 131 @State OutSetValue: number = 0 132 @State RepeatValue: RepeatMode[] = [RepeatMode.Repeat, RepeatMode.Stretch, RepeatMode.Round, RepeatMode.Space] 133 @State SelectIndex: number = 0 134 @State SelectText: string = 'Repeat' 135 @State FillValue: boolean = false 136 137 build() { 138 Row() { 139 Column({ space: 20 }) { 140 Row() { 141 Text('This is borderImage.').textAlign(TextAlign.Center).fontSize(50) 142 } 143 .borderImage({ 144 source: $r('app.media.icon'), 145 slice: this.SliceValue, 146 width: this.WidthValue, 147 outset: this.OutSetValue, 148 repeat: this.RepeatValue[this.SelectIndex], 149 fill: this.FillValue 150 }) 151 152 Column() { 153 Text(`borderImageSlice = ${this.SliceValue}px`) 154 Slider({ 155 value: this.SliceValue, 156 min: 0, 157 max: 100, 158 style: SliderStyle.OutSet 159 }) 160 .onChange((value: number, mode: SliderChangeMode) => { 161 this.SliceValue = value 162 }) 163 } 164 165 Column() { 166 Text(`borderImageWidth = ${this.WidthValue}px`) 167 Slider({ 168 value: this.WidthValue, 169 min: 0, 170 max: 100, 171 style: SliderStyle.OutSet 172 }) 173 .onChange((value: number, mode: SliderChangeMode) => { 174 this.WidthValue = value 175 }) 176 } 177 178 Column() { 179 Text(`borderImageOutSet = ${this.OutSetValue}px`) 180 Slider({ 181 value: this.OutSetValue, 182 min: 0, 183 max: 100, 184 style: SliderStyle.OutSet 185 }) 186 .onChange((value: number, mode: SliderChangeMode) => { 187 this.OutSetValue = value 188 }) 189 } 190 191 Row() { 192 Text('borderImageRepeat: ') 193 Select([{ value: 'Repeat' }, { value: 'Stretch' }, { value: 'Round' }, { value: 'Space' }]) 194 .value(this.SelectText) 195 .selected(this.SelectIndex) 196 .onSelect((index: number, value?: string) => { 197 this.SelectIndex = index 198 this.SelectText = value as string 199 }) 200 } 201 202 Row() { 203 Text(`borderImageFill: ${this.FillValue} `) 204 Toggle({ type: ToggleType.Switch, isOn: this.FillValue }) 205 .onChange((isOn: boolean) => { 206 this.FillValue = isOn 207 }) 208 } 209 210 } 211 .width('100%') 212 } 213 .height('100%') 214 } 215} 216``` 217 218 219 220### 示例3（使用LocalizedEdgeWidths类型值） 221 222borderImage接口中的slice、width和outset属性值使用[LocalizedEdgeWidths](ts-types.md#localizededgewidths12)类型。 223 224```ts 225// xxx.ets 226import { LengthMetrics } from '@kit.ArkUI' 227 228@Entry 229@Component 230struct BorderImage { 231 @State WidthStartValue: number = 0 232 @State WidthEndValue: number = 0 233 @State SliceStartValue: number = 0 234 @State SliceEndValue: number = 0 235 @State OutSetStartValue: number = 0 236 @State OutSetEndValue: number = 0 237 @State RepeatValue: RepeatMode[] = [RepeatMode.Repeat, RepeatMode.Stretch, RepeatMode.Round, RepeatMode.Space] 238 @State SelectIndex: number = 0 239 @State SelectText: string = 'Repeat' 240 @State FillValue: boolean = false 241 242 build() { 243 Row() { 244 Column({ space: 20 }) { 245 Row() { 246 Text('This is borderImage.').textAlign(TextAlign.Center).fontSize(50) 247 } 248 .borderImage({ 249 source: $r('app.media.icon'), 250 slice: { 251 top: LengthMetrics.px(10), 252 bottom: LengthMetrics.px(10), 253 start: LengthMetrics.px(this.SliceStartValue), 254 end: LengthMetrics.px(this.SliceEndValue) }, 255 width: { 256 top: LengthMetrics.px(10), 257 bottom: LengthMetrics.px(10), 258 start: LengthMetrics.px(this.WidthStartValue), 259 end: LengthMetrics.px(this.WidthEndValue) 260 }, 261 outset: { 262 top: LengthMetrics.px(10), 263 bottom: LengthMetrics.px(10), 264 start: LengthMetrics.px(this.OutSetStartValue), 265 end: LengthMetrics.px(this.OutSetEndValue) 266 }, 267 repeat: this.RepeatValue[this.SelectIndex], 268 fill: this.FillValue 269 }) 270 271 Column() { 272 Text(`borderImageSliceStart = ${this.SliceStartValue}px`) 273 Slider({ 274 value: this.SliceStartValue, 275 min: 0, 276 max: 100, 277 style: SliderStyle.OutSet 278 }) 279 .onChange((value: number, mode: SliderChangeMode) => { 280 this.SliceStartValue = value 281 }) 282 } 283 284 Column() { 285 Text(`borderImageEndSliceStart = ${this.SliceEndValue}px`) 286 Slider({ 287 value: this.SliceEndValue, 288 min: 0, 289 max: 100, 290 style: SliderStyle.OutSet 291 }) 292 .onChange((value: number, mode: SliderChangeMode) => { 293 this.SliceEndValue = value 294 }) 295 } 296 297 Column() { 298 Text(`borderImageWidthStart = ${this.WidthStartValue}px`) 299 Slider({ 300 value: this.WidthStartValue, 301 min: 0, 302 max: 100, 303 style: SliderStyle.OutSet 304 }) 305 .onChange((value: number, mode: SliderChangeMode) => { 306 this.WidthStartValue = value 307 }) 308 } 309 310 Column() { 311 Text(`borderImageWidthEnd = ${this.WidthEndValue}px`) 312 Slider({ 313 value: this.WidthEndValue, 314 min: 0, 315 max: 100, 316 style: SliderStyle.OutSet 317 }) 318 .onChange((value: number, mode: SliderChangeMode) => { 319 this.WidthEndValue = value 320 }) 321 } 322 323 Column() { 324 Text(`borderImageOutSetStart = ${this.OutSetStartValue}px`) 325 Slider({ 326 value: this.OutSetStartValue, 327 min: 0, 328 max: 100, 329 style: SliderStyle.OutSet 330 }) 331 .onChange((value: number, mode: SliderChangeMode) => { 332 this.OutSetStartValue = value 333 }) 334 } 335 336 Column() { 337 Text(`borderImageOutSetEnd = ${this.OutSetEndValue}px`) 338 Slider({ 339 value: this.OutSetEndValue, 340 min: 0, 341 max: 100, 342 style: SliderStyle.OutSet 343 }) 344 .onChange((value: number, mode: SliderChangeMode) => { 345 this.OutSetEndValue = value 346 }) 347 } 348 349 Row() { 350 Text('borderImageRepeat: ') 351 Select([{ value: 'Repeat' }, { value: 'Stretch' }, { value: 'Round' }, { value: 'Space' }]) 352 .value(this.SelectText) 353 .selected(this.SelectIndex) 354 .onSelect((index: number, value?: string) => { 355 this.SelectIndex = index 356 this.SelectText = value as string 357 }) 358 } 359 360 Row() { 361 Text(`borderImageFill: ${this.FillValue} `) 362 Toggle({ type: ToggleType.Switch, isOn: this.FillValue }) 363 .onChange((isOn: boolean) => { 364 this.FillValue = isOn 365 }) 366 } 367 368 } 369 .width('100%') 370 } 371 .height('100%') 372 } 373} 374``` 375 376从左至右显示语言示例图 377 378 379 380从右至左显示语言示例图 381 382 383
