1# Rect 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @zjsxstar--> 5<!--Designer: @sunbees--> 6<!--Tester: @liuli0427--> 7<!--Adviser: @HelloCrease--> 8 9矩形绘制组件。 10 11> **说明：** 12> 13> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14> 15> 该组件从API version 20开始支持使用[AttributeUpdater](../js-apis-arkui-AttributeUpdater.md)类的[updateConstructorParams](../js-apis-arkui-AttributeUpdater.md#updateconstructorparams)接口更新构造参数。 16 17 18## 子组件 19 20无 21 22 23## 接口 24 25Rect(options?: RectOptions | RoundedRectOptions) 26 27**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 28 29**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 30 31**系统能力：** SystemCapability.ArkUI.ArkUI.Full 32 33**参数：** 34 35| 参数名 | 类型 | 必填 | 说明 | 36| -------- | -------- | -------- | -------- | 37| options | [RectOptions](ts-drawing-components-rect.md#rectoptions18对象说明) \| [RoundedRectOptions](ts-drawing-components-rect.md#roundedrectoptions18对象说明) | 否 | Rect绘制属性。 | 38 39## RectOptions<sup>18+</sup>对象说明 40 41用于描述Rect组件绘制属性。 42 43> **说明：** 44> 45> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 46 47**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 48 49**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 50 51**系统能力：** SystemCapability.ArkUI.ArkUI.Full 52 53| 名称 | 类型 | 只读 | 可选 | 说明 | 54| -------- | -------- | -------- | -------- | -------- | 55| width<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 宽度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 56| height<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 高度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 57| radius<sup>7+</sup> | [Length](ts-types.md#length) \| Array<any> | 否 | 是 | 圆角半径，支持分别设置四个角的圆角度数，取值范围≥0。<br/>该属性和radiusWidth/radiusHeight属性效果类似，在组合使用时优先于radiusWidth/radiusHeight生效。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 58 59## RoundedRectOptions<sup>18+</sup>对象说明 60用于描述Rect绘制属性。 61 62> **说明：** 63> 64> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 65 66**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 67 68**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 69 70**系统能力：** SystemCapability.ArkUI.ArkUI.Full 71 72| 名称 | 类型 | 只读 | 可选 | 说明 | 73| -------- | -------- | -------- | -------- | -------- | 74| width<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 宽度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 75| height<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 高度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 76| radiusWidth<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 圆角宽度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 77| radiusHeight<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 是 | 圆角高度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp<br/>异常值按照默认值处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 78 79## 属性 80 81除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 82 83### radiusWidth 84 85radiusWidth(value: Length) 86 87设置圆角的宽度，仅设置宽时宽高一致，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 异常值按照默认值处理。 88 89**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 90 91**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 92 93**系统能力：** SystemCapability.ArkUI.ArkUI.Full 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | -------------------------- | ---- | -------------------------- | 99| value | [Length](ts-types.md#length) | 是 | 圆角的宽度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp | 100 101### radiusHeight 102 103radiusHeight(value: Length) 104 105设置圆角的高度，仅设置高时宽高一致，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 异常值按照默认值处理。 106 107**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 108 109**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 110 111**系统能力：** SystemCapability.ArkUI.ArkUI.Full 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| ------ | -------------------------- | ---- | -------------------------- | 117| value | [Length](ts-types.md#length) | 是 | 圆角的高度，取值范围≥0。<br/>默认值：0<br/>默认单位：vp | 118 119### radius 120 121radius(value: Length | Array<any>) 122 123设置圆角半径大小，取值范围≥0，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。异常值按照默认值处理。 124 125**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 126 127**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| ------ | ------------------------------------------------------------ | ---- | ---------------------------- | 135| value | [Length](ts-types.md#length) \| Array<any> | 是 | 圆角半径大小。<br/>默认值：0<br/>默认单位：vp | 136 137### fill 138 139fill(value: ResourceColor) 140 141设置填充区域的颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，异常值按照默认值处理。与通用属性foregroundColor同时设置时，后设置的属性生效。 142 143**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 144 145**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 146 147**系统能力：** SystemCapability.ArkUI.ArkUI.Full 148 149**参数：** 150 151| 参数名 | 类型 | 必填 | 说明 | 152| ------ | ------------------------------------------ | ---- | -------------------------------------- | 153| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 填充区域颜色。<br/>默认值：Color.Black | 154 155### fillOpacity 156 157fillOpacity(value: number | string | Resource) 158 159设置填充区域透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 160 161**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 162 163**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 164 165**系统能力：** SystemCapability.ArkUI.ArkUI.Full 166 167**参数：** 168 169| 参数名 | 类型 | 必填 | 说明 | 170| ------ | ------------------------------------------------------------ | ---- | ------------------------------ | 171| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 填充区域透明度。<br/>**说明：**<br/>number格式取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理。<br/>string格式支持number格式取值的字符串形式，取值范围与number格式相同。<br/>Resource格式支持系统资源或者应用资源中的字符串，取值范围和number格式相同。<br/>默认值：1 | 172 173### stroke 174 175stroke(value: ResourceColor) 176 177设置边框颜色，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法，不设置时，默认边框透明度为0，即无边框。异常值不会绘制边框。 178 179**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 180 181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ------ | ------------------------------------------ | ---- | ---------- | 189| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 边框颜色。 | 190 191### strokeDashArray 192 193strokeDashArray(value: Array<any>) 194 195设置边框间隙，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。取值范围≥0。异常值将按默认值处理。 196 197**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 198 199**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 200 201**系统能力：** SystemCapability.ArkUI.ArkUI.Full 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| ------ | ---------------- | ---- | ------------------------- | 207| value | Array<any> | 是 | 边框间隙。<br/>默认值：[]（空数组）<br/>默认单位：vp | 208 209### strokeDashOffset 210 211strokeDashOffset(value: number | string) 212 213设置边框绘制起点的偏移量，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。异常值按照默认值处理。 214 215**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 216 217**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 218 219**系统能力：** SystemCapability.ArkUI.ArkUI.Full 220 221**参数：** 222 223| 参数名 | 类型 | 必填 | 说明 | 224| ------ | -------------------------- | ---- | ------------------------------------ | 225| value | number \| string | 是 | 边框绘制起点的偏移量。<br/>默认值：0<br/>默认单位：vp | 226 227### strokeLineCap 228 229strokeLineCap(value: LineCapStyle) 230 231设置边框端点绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 232 233**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 234 235**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 236 237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 238 239**参数：** 240 241| 参数名 | 类型 | 必填 | 说明 | 242| ------ | ------------------------------------------------- | ---- | ------------------------------------------------ | 243| value | [LineCapStyle](ts-appendix-enums.md#linecapstyle) | 是 | 边框端点绘制样式。<br/>默认值：LineCapStyle.Butt | 244 245### strokeLineJoin 246 247strokeLineJoin(value: LineJoinStyle) 248 249设置边框拐角绘制样式，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 250 251**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 252 253**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 254 255**系统能力：** SystemCapability.ArkUI.ArkUI.Full 256 257**参数：** 258 259| 参数名 | 类型 | 必填 | 说明 | 260| ------ | --------------------------------------------------- | ---- | -------------------------------------------------- | 261| value | [LineJoinStyle](ts-appendix-enums.md#linejoinstyle) | 是 | 边框拐角绘制样式。<br/>默认值：LineJoinStyle.Miter | 262 263### strokeMiterLimit 264 265strokeMiterLimit(value: number | string) 266 267设置斜接长度与边框宽度比值的极限值，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。斜接长度表示外边框外边交点到内边交点的距离，边框宽度即strokeWidth属性的值。该属性取值需在strokeLineJoin属性取值LineJoinStyle.Miter时生效。 268 269该属性的合法值范围应当大于等于1.0，当取值范围在[0,1)时按1.0处理，其余异常值按默认值处理。 270 271**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 272 273**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 274 275**系统能力：** SystemCapability.ArkUI.ArkUI.Full 276 277**参数：** 278 279| 参数名 | 类型 | 必填 | 说明 | 280| ------ | -------------------------- | ---- | ---------------------------------------------- | 281| value | number \| string | 是 | 斜接长度与边框宽度比值的极限值。<br/>默认值：4 | 282 283### strokeOpacity 284 285strokeOpacity(value: number | string | Resource) 286 287设置边框透明度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性的取值范围是[0.0, 1.0]，若给定值小于0.0，则取值为0.0；若给定值大于1.0，则取值为1.0，其余异常值按1.0处理。 288 289**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 290 291**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 292 293**系统能力：** SystemCapability.ArkUI.ArkUI.Full 294 295**参数：** 296 297| 参数名 | 类型 | 必填 | 说明 | 298| ------ | ------------------------------------------------------------ | ---- | -------------------------- | 299| value | number \| string \| [Resource](ts-types.md#resource) | 是 | 边框透明度。<br/>默认值：[stroke](#stroke)接口设置的透明度。 | 300 301### strokeWidth 302 303strokeWidth(value: Length) 304 305设置边框宽度，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。该属性若为string类型，暂不支持百分比，百分比按照1px处理。 306 307**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 308 309**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 310 311**系统能力：** SystemCapability.ArkUI.ArkUI.Full 312 313**参数：** 314 315| 参数名 | 类型 | 必填 | 说明 | 316| ------ | ---------------------------- | ---- | ------------------------ | 317| value | [Length](ts-types.md#length) | 是 | 边框宽度，取值范围≥0。<br/>默认值：1<br/>默认单位：vp<br/>异常值按照默认值处理。 | 318 319### antiAlias 320 321antiAlias(value: boolean) 322 323设置是否开启抗锯齿效果，支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 324 325**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 326 327**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 328 329**系统能力：** SystemCapability.ArkUI.ArkUI.Full 330 331**参数：** 332 333| 参数名 | 类型 | 必填 | 说明 | 334| ------ | ------- | ---- | ------------------------------------- | 335| value | boolean | 是 | 是否开启抗锯齿效果。<br/>true：开启抗锯齿；false：关闭抗锯齿。<br/>默认值：true | 336 337## 示例 338 339### 示例1（组件属性绘制） 340 341使用fill、fillOpacity、stroke、radius属性分别绘制矩形的填充颜色、透明度、边框颜色、圆角。 342 343```ts 344// xxx.ets 345@Entry 346@Component 347struct RectExample { 348 build() { 349 Column({ space: 10 }) { 350 Text('normal').fontSize(11).fontColor(0xCCCCCC).width('90%') 351 // 绘制90% * 50的矩形 352 Column({ space: 5 }) { 353 Text('normal').fontSize(9).fontColor(0xCCCCCC).width('90%') 354 // 绘制90% * 50矩形 355 Rect({ width: '90%', height: 50 }) 356 .fill(Color.Pink) 357 // 绘制90% * 50的矩形框 358 Rect() 359 .width('90%') 360 .height(50) 361 .fillOpacity(0) 362 .stroke(Color.Red) 363 .strokeWidth(3) 364 365 Text('with rounded corners').fontSize(11).fontColor(0xCCCCCC).width('90%') 366 // 绘制90% * 80的矩形, 圆角宽高分别为40、20 367 Rect({ width: '90%', height: 80 }) 368 .radiusHeight(20) 369 .radiusWidth(40) 370 .fill(Color.Pink) 371 // 绘制90% * 80的矩形, 圆角宽高为20 372 Rect({ width: '90%', height: 80 }) 373 .radius(20) 374 .fill(Color.Pink) 375 .stroke(Color.Transparent) 376 }.width('100%').margin({ top: 10 }) 377 378 // 绘制90% * 50矩形, 左上圆角宽高40,右上圆角宽高20,右下圆角宽高40,左下圆角宽高20 379 Rect({ width: '90%', height: 80 }) 380 .radius([[40, 40], [20, 20], [40, 40], [20, 20]]) 381 .fill(Color.Pink) 382 }.width('100%').margin({ top: 5 }) 383 } 384} 385``` 386 387 388 389### 示例2（绘制渐变色矩形） 390 391通过通用属性linearGradient、clipShape分别绘制渐变色的矩形。 392 393```ts 394// xxx.ets 395@Entry 396@Component 397struct RectExample { 398 build() { 399 Column({ space: 10 }) { 400 Column() 401 .width(100) 402 .height(100) 403 .linearGradient({ 404 direction: GradientDirection.Right, 405 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]] 406 }) 407 .clipShape(new Rect({ width: 100, height: 100, radius: 40 })) 408 Rect() 409 .width(100) 410 .height(100) 411 // 设置矩形填充，如果需要显示背景的渐变色，请设置区域透明度.fillOpacity(0.0) 412 .fill(Color.Pink) 413 // 设置倒角为40 414 .radius(40) 415 .stroke(Color.Black) 416 // 设置渐变色，仅100*100的矩形区域生效，渐变色的边界不包含倒角 417 .linearGradient({ 418 direction: GradientDirection.Right, 419 colors: [[0xff0000, 0.0], [0x0000ff, 0.3], [0xffff00, 1.0]] 420 }) 421 } 422 } 423} 424``` 425 426 427 428### 示例3（使用不同参数类型绘制矩形） 429 430width、height、radius、radiusWidth、radiusHeight等属性分别使用不同的长度类型绘制图形。 431 432```ts 433// xxx.ets 434@Entry 435@Component 436struct RectExample { 437 build() { 438 Column({ space: 10 }) { 439 // 绘制90% * 50矩形，圆角半径为5 440 Rect({ width: '90%', height: '50', radius: '5' })//使用string类型 441 .fill(Color.Green) 442 // 绘制200 * 50的矩形框，圆角半径为5 443 Rect({ width: 200, height: 50, radius: 5 })//使用number类型 444 .fillOpacity(0) 445 .stroke(Color.Red) 446 .strokeWidth(3) 447 // 绘制200 * 50矩形, 圆角宽80, 圆角高20 448 Rect({ 449 width: $r('app.string.RectWidth'), //使用Resource类型，需用户自定义 450 height: $r('app.string.RectHeight'), 451 radius: $r('app.string.RectRadius') 452 }) 453 .radiusWidth($r('app.string.RectRadiusWidth')) 454 .radiusHeight($r('app.string.RectRadiusHeight')) 455 .fill(Color.Green) 456 }.width('100%').margin({ top: 5 }) 457 } 458} 459``` 460 461 462 463### 示例4（使用attributeModifier动态设置Rect组件的属性） 464 465以下示例展示了如何使用attributeModifier动态设置Rect组件的fill、fillOpacity、stroke、strokeDashArray、strokeDashOffset、strokeLineCap、strokeLineJoin、strokeMiterLimit、strokeOpacity、strokeWidth和antiAlias属性。 466 467```ts 468// xxx.ets 469class MyRectModifier implements AttributeModifier<RectAttribute> { 470 applyNormalAttribute(instance: RectAttribute): void { 471 // 填充颜色#707070，填充透明度0.5，边框颜色#2787D9，边框间隙[20]，向左偏移15，线条两端样式为半圆，拐角样式使用尖角连接路径段，斜接长度与边框宽度比值的极限值为5，边框透明度0.5，边框宽度10，抗锯齿开启 472 instance.fill("#707070") 473 instance.fillOpacity(0.5) 474 instance.stroke("#2787D9") 475 instance.strokeDashArray([20]) 476 instance.strokeDashOffset("15") 477 instance.strokeLineCap(LineCapStyle.Round) 478 instance.strokeLineJoin(LineJoinStyle.Miter) 479 instance.strokeMiterLimit(5) 480 instance.strokeOpacity(0.5) 481 instance.strokeWidth(10) 482 instance.antiAlias(true) 483 } 484} 485 486@Entry 487@Component 488struct RectModifierDemo { 489 @State modifier: MyRectModifier = new MyRectModifier() 490 491 build() { 492 Column() { 493 Rect() 494 .width(200) 495 .height(200) 496 .attributeModifier(this.modifier) 497 .offset({ x: 20, y: 20 }) 498 } 499 } 500} 501``` 502 503
