1# Size 2 3The size attributes set the width, height, and margin of a component. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9## width 10 11width(value: Length) 12 13Sets the width of the component. By default, the width required to fully hold the component content is used. If the width of the component is greater than that of the parent container, the component will be drawn beyond the parent container scope. 14 15Since API version 10, this API supports the calc calculation feature. 16 17**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name | Type | Mandatory | Description | 26| ----- | ---------------------------- | ---- | ------------------- | 27| value | [Length](ts-types.md#length) | Yes | Width of the component to set.<br>Unit: vp| 28 29> **NOTE** 30> 31> - In the [TextInput](./ts-basic-components-textinput.md) component, setting **width** to **auto** means that the width adapts to the width of the text content. 32> 33> - In the [AlphabetIndexer](./ts-container-alphabet-indexer.md) component, setting **width** to **auto** means that the width adapts to the maximum width of index entries. 34 35## height 36 37height(value: Length) 38 39Sets the height of the component. By default, the height required to fully hold the component content is used. If the height of the component is greater than that of the parent container, the component will be drawn beyond the parent container scope. 40 41Since API version 10, this API supports the calc calculation feature. 42 43**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 44 45**Atomic service API**: This API can be used in atomic services since API version 11. 46 47**System capability**: SystemCapability.ArkUI.ArkUI.Full 48 49**Parameters** 50 51| Name | Type | Mandatory | Description | 52| ----- | ---------------------------- | ---- | ------------------- | 53| value | [Length](ts-types.md#length) | Yes | Height of the component to set.<br>Unit: vp| 54 55> **NOTE** 56> 57> In the [Row](./ts-container-row.md), [Column](./ts-container-column.md), and [RelativeContainer](./ts-container-relativecontainer.md) components, setting **width** and **height** to **auto** means that the size adapts to the size of their child components. 58 59## width<sup>15+</sup> 60 61width(widthValue: Length | LayoutPolicy) 62 63Sets the width of the component or its horizontal layout policy. By default, the component uses the width required for its content. If the width of the component is greater than that of the parent container, the component will be drawn beyond the parent container scope. 64 65**Widget capability**: This API can be used in ArkTS widgets since API version 15. 66 67**Atomic service API**: This API can be used in atomic services since API version 15. 68 69**System capability**: SystemCapability.ArkUI.ArkUI.Full 70 71**Parameters** 72 73| Name | Type | Mandatory | Description | 74| ----- | ---------------------------- | ---- | ------------------- | 75| widthValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-types.md#layoutpolicy15) | Yes | Width of the component to set.<br>Unit: vp| 76 77## height<sup>15+</sup> 78 79height(heightValue: Length | LayoutPolicy) 80 81Sets the height of the component or its vertical layout policy. By default, the component uses the height required for its content. If the height of the component is greater than that of the parent container, the component will be drawn beyond the parent container scope. 82 83**Widget capability**: This API can be used in ArkTS widgets since API version 15. 84 85**Atomic service API**: This API can be used in atomic services since API version 15. 86 87**System capability**: SystemCapability.ArkUI.ArkUI.Full 88 89**Parameters** 90 91| Name | Type | Mandatory | Description | 92| ----- | ---------------------------- | ---- | ------------------- | 93| heightValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-types.md#layoutpolicy15) | Yes | Height of the component to set.<br>Unit: vp| 94 95> **NOTE** 96> 97> In the [Row](./ts-container-row.md) and [Column](./ts-container-column.md) components, **width** and **height** can be set to parameters of the [LayoutPolicy](ts-types.md#layoutpolicy15) type. 98 99## size 100 101size(value: SizeOptions) 102 103Sets the size of the component. 104 105Since API version 10, this API supports the calc calculation feature. 106 107**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 108 109**Atomic service API**: This API can be used in atomic services since API version 11. 110 111**System capability**: SystemCapability.ArkUI.ArkUI.Full 112 113**Parameters** 114 115| Name | Type | Mandatory | Description | 116| ----- | ------------------------------- | ---- | ----------------- | 117| value | [SizeOptions](#sizeoptions) | Yes | Size of the component to set.<br>Unit: vp| 118 119## padding 120 121padding(value: Padding | Length | LocalizedPadding) 122 123Sets the padding of the component. 124 125Since API version 10, this API supports the calc calculation feature. 126 127**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 128 129**Atomic service API**: This API can be used in atomic services since API version 11. 130 131**System capability**: SystemCapability.ArkUI.ArkUI.Full 132 133**Parameters** 134 135| Name | Type | Mandatory | Description | 136| ----- | ---------------------------------------- | ---- | ---------------------------------------- | 137| value | [Padding](ts-types.md#padding) \| [Length](ts-types.md#length) \| [LocalizedPadding](ts-types.md#localizedpadding12)<sup>12+</sup>| Yes | Padding of the component to set.<br>When the parameter is of the **Length** type, the four paddings take effect.<br>Default value: **0**<br>Unit: vp<br>When **padding** is set to a percentage, the width of the parent container is used as the basic value.| 138 139## margin 140 141margin(value: Margin | Length | LocalizedMargin) 142 143Sets the margin of the component. 144 145Since API version 10, this API supports the calc calculation feature. 146 147**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 148 149**Atomic service API**: This API can be used in atomic services since API version 11. 150 151**System capability**: SystemCapability.ArkUI.ArkUI.Full 152 153**Parameters** 154 155| Name| Type | Mandatory | Description | 156| ------ | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 157| value | [Margin](ts-types.md#margin) \| [Length](ts-types.md#length) \| [LocalizedMargin](ts-types.md#localizedmargin12)<sup>12+</sup> | Yes| Margin of the component to set.<br>When the parameter is of the **Length** type, the four margins take effect.<br>Default value: **0**<br>Unit: vp<br>When **margin** is set to a percentage, the width of the parent container is used as the basic value. When child components are laid out along the cross axis of the [Row](./ts-container-row.md), [Column](./ts-container-column.md), or [Flex](./ts-container-flex.md) container, the cross axis size of the child components and the margins add up to the total size of the container.<br>For example, if the width of the **Column** container is 100, the width of the child component is 50, the left margin is 10, and the right margin is 20, then the actual horizontal offset of the child component is 10.| 158 159## safeAreaPadding<sup>14+</sup> 160 161safeAreaPadding(value: Padding | LengthMetrics | LocalizedPadding) 162 163Sets the safe area padding. It enables a container to add a component-level safe area for child components to expand into. 164 165**Widget capability**: This API can be used in ArkTS widgets since API version 14. 166 167**Atomic service API**: This API can be used in atomic services since API version 14. 168 169**System capability**: SystemCapability.ArkUI.ArkUI.Full 170 171**Parameters** 172 173| Name | Type | Mandatory | Description | 174| ----- | ---------------------------------------- | ---- | ---------------------------------------- | 175| paddingValue | [Padding](ts-types.md#padding) \| [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) \| [LocalizedPadding](ts-types.md#localizedpadding12)| Yes | Safe area padding.<br>Default value: **0**<br>Unit: vp| 176 177## layoutWeight 178 179layoutWeight(value: number | string) 180 181Sets the weight of the component during layout. A component with this attribute is allocated space along the main axis of its parent container ([Row](./ts-container-row.md), [Column](./ts-container-column.md), or [Flex](./ts-container-flex.md)) based on its specified weight. 182 183**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 184 185**Atomic service API**: This API can be used in atomic services since API version 11. 186 187**System capability**: SystemCapability.ArkUI.ArkUI.Full 188 189**Parameters** 190 191| Name | Type | Mandatory | Description | 192| ----- | -------------------------- | ------- | ---------------------------------------- | 193| value | number \| string | Yes| Weight of the component during layout. When the size of the parent container is determined, the container space is allocated along the main axis among the component and its sibling components based on their respective weights, ignoring their own size settings.<br>Default value: **0**<br>**NOTE**<br>This parameter is only effective in [Row](./ts-container-row.md), [Column](./ts-container-column.md), and [Flex](./ts-container-flex.md) container components.<br>The value can be a number greater than or equal to 0 or a string that can be converted to a number.<br>If any child component in a container has the **layoutWeight** attribute set to a value greater than 0, then child components will no longer be laid out based on **flexShrink** and **flexGrow**.| 194 195## constraintSize 196 197constraintSize(value: ConstraintSizeOptions) 198 199Sets the constraint size of the component, which is used to limit the size range during component layout. 200 201Since API version 10, this API supports the calc calculation feature. 202 203**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 204 205**Atomic service API**: This API can be used in atomic services since API version 11. 206 207**System capability**: SystemCapability.ArkUI.ArkUI.Full 208 209**Parameters** 210 211| Name | Type | Mandatory | Description | 212| ----- | ---------------------------------------- | ---- | ---------------------------------------- | 213| value | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | Yes | Constraint size of the component to set. **constraintSize** takes precedence over **width** and **height**. See **Impact of constraintSize on width/height**.<br>Default value:<br>{<br>minWidth: 0,<br>maxWidth: Infinity,<br>minHeight: 0,<br>maxHeight: Infinity<br>}<br>Unit: vp<br>| 214 215**Impact of constraintSize(minWidth/maxWidth/minHeight/maxHeight) on width/height** 216 217| Default Value | Result | 218| ---------------------------------------- | ---------------------------------------- | 219| \ | width=MAX(minWidth,MIN(maxWidth,width))<br>height=MAX(minHeight,MIN(maxHeight,height)) | 220| maxWidth, maxHeight| width=MAX(minWidth,width)<br>height=MAX(minHeight,height) | 221| minWidth, minHeight| width=MIN(maxWidth,width)<br>height=MIN(maxHeight,height) | 222| width, height| If minWidth < maxWidth, the layout logic of the component takes effect, and the value range of **width** is [minWidth, maxWidth]. Otherwise, width = MAX(minWidth, maxWidth).<br>If minHeight < maxHeight, the layout logic of the component takes effect, and the value range of **height** is [minHeight, maxHeight]. Otherwise, height = MAX (minHeight, maxHeight).| 223| width and maxWidth; height and maxHeight| width = minWidth<br>height = minHeight | 224| width and minWidth; and height and minHeight| The layout logic of the component takes effect, and the value of **width** cannot be greater than that of **maxWidth**.<br>The layout logic of the component takes effect, and the value of **height** cannot be greater than that of **maxHeight**.| 225| minWidth and maxWidth; minHeight and maxHeight| The width of the component is initially determined by the value of **width**, and it may be adjusted based on other layout attributes.<br>The height of the component is initially determined by the value of **height**, and it may be adjusted based on other layout attributes.| 226| width, minWidth, and maxWidth| The layout restrictions passed by the parent container are used for layout.| 227| height, minHeight, and maxHeight| The layout restrictions passed by the parent container are used for layout.| 228 229## SizeOptions 230 231**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 232 233**Atomic service API**: This API can be used in atomic services since API version 11. 234 235| Name | Type | Mandatory | Description | 236| ----- | ---------------------------------------- | ---- | ---------------------------------------- | 237| width | [Length](ts-types.md#length) | No| Component width.| 238| height | [Length](ts-types.md#length) | No| Component height.| 239 240## ConstraintSizeOptions 241 242**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 243 244**Atomic service API**: This API can be used in atomic services since API version 11. 245 246| Name | Type | Mandatory | Description | 247| ----- | ---------------------------------------- | ---- | ---------------------------------------- | 248| minWidth | [Length](ts-types.md#length) | No| Minimum width of the component.| 249| maxWidth | [Length](ts-types.md#length) | No| Maximum width of the component.| 250| minHeight | [Length](ts-types.md#length) | No| Minimum height of the component.| 251| maxHeight | [Length](ts-types.md#length) | No| Maximum height of the component.| 252 253> **NOTE** 254> 255> In the [Row](./ts-container-row.md), [Column](./ts-container-column.md), and [RelativeContainer](./ts-container-relativecontainer.md) components, setting **width** and **height** to **auto** means that the size adapts to the size of their child components. In the [TextInput](./ts-basic-components-textinput.md) component, setting **width** to **auto** means that the width adapts to the width of the text content. 256 257## Example 258 259### Example 1: Setting the Component Width, Height, Margin, and Padding 260 261This example demonstrates how to set the width, height, margin, and padding of a component. 262 263```ts 264// xxx.ets 265@Entry 266@Component 267struct SizeExample { 268 build() { 269 Column({ space: 10 }) { 270 Text('margin and padding:').fontSize(12).fontColor(0xCCCCCC).width('90%') 271 Row() { 272 // Width: 80; height: 80; margin: 20 (blue area); top, bottom, left, and right paddings: 5, 15, 10, and 20 (white area) 273 Row() { 274 Row().size({ width: '100%', height: '100%' }).backgroundColor(Color.Yellow) 275 } 276 .width(80) 277 .height(80) 278 .padding({ top: 5, left: 10, bottom: 15, right: 20 }) 279 .margin(20) 280 .backgroundColor(Color.White) 281 }.backgroundColor(Color.Blue) 282 283 Text('constraintSize').fontSize(12).fontColor(0xCCCCCC).width('90%') 284 Text('this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text.this is a Text') 285 .width('90%') 286 .constraintSize({ maxWidth: 200 }) 287 288 Text('layoutWeight').fontSize(12).fontColor(0xCCCCCC).width('90%') 289 // When the container size is determined, the component occupies the space along the main axis based on the layout weight, and the component size setting is ignored. 290 Row() { 291 // Weight 1: The component occupies 1/3 of the remaining space along the main axis. 292 Text('layoutWeight(1)') 293 .size({ width: '30%', height: 110 }).backgroundColor(0xFFEFD5).textAlign(TextAlign.Center) 294 .layoutWeight(1) 295 // Weight 2: The component occupies 2/3 of the remaining space along the main axis. 296 Text('layoutWeight(2)') 297 .size({ width: '30%', height: 110 }).backgroundColor(0xF5DEB3).textAlign(TextAlign.Center) 298 .layoutWeight(2) 299 // If layoutWeight is not set, the component is rendered based on its own size setting. 300 Text('no layoutWeight') 301 .size({ width: '30%', height: 110 }).backgroundColor(0xD2B48C).textAlign(TextAlign.Center) 302 }.size({ width: '90%', height: 140 }).backgroundColor(0xAFEEEE) 303 // calc calculation feature 304 Text('calc:').fontSize(12).fontColor(0xCCCCCC).width('90%') 305 Text('calc test') 306 .fontSize(50) 307 .fontWeight(FontWeight.Bold) 308 .backgroundColor(0xFFFAF0) 309 .textAlign(TextAlign.Center) 310 .margin('calc(25vp*2)') 311 // If width or height is set to a percentage, the width or height of the parent container are used as the basic value. 312 .size({ width: 'calc(90%)', height: 'calc(50vp + 10%)' }) 313 }.width('100%').margin({ top: 5 }) 314 } 315} 316``` 317 318 319 320### Example 2: Using LocalizedPadding and LocalizedMargin Types 321 322This example demonstrates how to use **LocalizedPadding** and **LocalizedMargin** types to set the padding and margin. 323 324```ts 325// xxx.ets 326import { LengthMetrics } from '@kit.ArkUI' 327 328@Entry 329@Component 330struct SizeExample { 331 build() { 332 Column({ space: 10 }) { 333 Text('margin and padding:').fontSize(12).fontColor(0xCCCCCC).width('90%') 334 Row() { 335 // Set the width to 80, height to 80, top, bottom, start, and end paddings to 40, 20, 30, and 10, respectively (blue area), and top, bottom, start, and end margins to 5, 15, 10, and 20, respectively (white area). 336 Row() { 337 Row().size({ width: '100%', height: '100%' }).backgroundColor(Color.Yellow) 338 } 339 .width(80) 340 .height(80) 341 .padding({ 342 top: LengthMetrics.vp(5), 343 bottom: LengthMetrics.vp(15), 344 start: LengthMetrics.vp(10), 345 end: LengthMetrics.vp(20) 346 }) 347 .margin({ 348 top: LengthMetrics.vp(40), 349 bottom: LengthMetrics.vp(20), 350 start: LengthMetrics.vp(30), 351 end: LengthMetrics.vp(10) 352 }) 353 .backgroundColor(Color.White) 354 }.backgroundColor(Color.Blue) 355 }.width('100%').margin({ top: 5 }) 356 } 357} 358``` 359 360The following shows how the example is represented with left-to-right scripts. 361 362 363 364The following shows how the example is represented with right-to-left scripts. 365 366 367 368### Example 3: Setting Safe Area 369 370This example demonstrates how to set a component-level safe area for a container. 371 372```ts 373// xxx.ets 374import { LengthMetrics } from '@kit.ArkUI'; 375 376@Entry 377@Component 378struct SafeAreaPaddingExample { 379 build() { 380 Column() { 381 Column() { 382 Column() 383 .width("100%") 384 .height("100%") 385 .backgroundColor(Color.Pink) 386 } 387 .width(200) 388 .height(200) 389 .backgroundColor(Color.Yellow) 390 .borderWidth(10) 391 .padding(10) 392 .safeAreaPadding(LengthMetrics.vp(40)) 393 } 394 .height('100%') 395 .width('100%') 396 } 397} 398``` 399 400 401
