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## size
60
61size(value: SizeOptions)
62
63Sets the size of the component.
64
65Since API version 10, this API supports the calc calculation feature.
66
67**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
68
69**Atomic service API**: This API can be used in atomic services since API version 11.
70
71**System capability**: SystemCapability.ArkUI.ArkUI.Full
72
73**Parameters**
74
75| Name  | Type                             | Mandatory  | Description               |
76| ----- | ------------------------------- | ---- | ----------------- |
77| value | [SizeOptions](#sizeoptions) | Yes   | Size of the component to set.<br>Unit: vp|
78
79## padding
80
81padding(value: Padding | Length | LocalizedPadding)
82
83Sets the padding of the component.
84
85Since API version 10, this API supports the calc calculation feature.
86
87**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
88
89**Atomic service API**: This API can be used in atomic services since API version 11.
90
91**System capability**: SystemCapability.ArkUI.ArkUI.Full
92
93**Parameters**
94
95| Name  | Type                                      | Mandatory  | Description                                      |
96| ----- | ---------------------------------------- | ---- | ---------------------------------------- |
97| 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.|
98
99## margin
100
101margin(value: Margin | Length | LocalizedMargin)
102
103Sets the margin 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  | [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.|
118
119## safeAreaPadding<sup>14+</sup>
120
121safeAreaPadding(value: Padding | LengthMetrics | LocalizedPadding)
122
123Sets the safe area padding. It enables a container to add a component-level safe area for child components to expand into.
124
125**Widget capability**: This API can be used in ArkTS widgets since API version 14.
126
127**Atomic service API**: This API can be used in atomic services since API version 14.
128
129**System capability**: SystemCapability.ArkUI.ArkUI.Full
130
131**Parameters**
132
133| Name  | Type                                      | Mandatory  | Description                                      |
134| ----- | ---------------------------------------- | ---- | ---------------------------------------- |
135| 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|
136
137## layoutWeight
138
139layoutWeight(value: number | string)
140
141Sets 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.
142
143**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
144
145**Atomic service API**: This API can be used in atomic services since API version 11.
146
147**System capability**: SystemCapability.ArkUI.ArkUI.Full
148
149**Parameters**
150
151| Name  | Type                        | Mandatory     | Description                                      |
152| ----- | -------------------------- | ------- | ---------------------------------------- |
153| 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**.|
154
155## constraintSize
156
157constraintSize(value: ConstraintSizeOptions)
158
159Sets the constraint size of the component, which is used to limit the size range during component layout.
160
161Since API version 10, this API supports the calc calculation feature.
162
163**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
164
165**Atomic service API**: This API can be used in atomic services since API version 11.
166
167**System capability**: SystemCapability.ArkUI.ArkUI.Full
168
169**Parameters**
170
171| Name  | Type                                      | Mandatory  | Description                                      |
172| ----- | ---------------------------------------- | ---- | ---------------------------------------- |
173| 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>|
174
175**Impact of constraintSize(minWidth/maxWidth/minHeight/maxHeight) on width/height**
176
177| Default Value                                     | Result                                      |
178| ---------------------------------------- | ---------------------------------------- |
179| \ | width=MAX(minWidth,MIN(maxWidth,width))<br>height=MAX(minHeight,MIN(maxHeight,height)) |
180| maxWidth, maxHeight| width=MAX(minWidth,width)<br>height=MAX(minHeight,height) |
181| minWidth, minHeight| width=MIN(maxWidth,width)<br>height=MIN(maxHeight,height) |
182| 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).|
183| width and maxWidth; height and maxHeight| width = minWidth<br>height = minHeight |
184| 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**.|
185| 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.|
186| width, minWidth, and maxWidth| The layout restrictions passed by the parent container are used for layout.|
187| height, minHeight, and maxHeight| The layout restrictions passed by the parent container are used for layout.|
188
189## SizeOptions
190
191**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
192
193**Atomic service API**: This API can be used in atomic services since API version 11.
194
195| Name  | Type                                      | Mandatory  | Description                                      |
196| ----- | ---------------------------------------- | ---- | ---------------------------------------- |
197| width  | [Length](ts-types.md#length) | No| Component width.|
198| height | [Length](ts-types.md#length) | No| Component height.|
199
200## ConstraintSizeOptions
201
202**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
203
204**Atomic service API**: This API can be used in atomic services since API version 11.
205
206| Name  | Type                                      | Mandatory  | Description                                      |
207| ----- | ---------------------------------------- | ---- | ---------------------------------------- |
208| minWidth  | [Length](ts-types.md#length) | No| Minimum width of the component.|
209| maxWidth  | [Length](ts-types.md#length) | No| Maximum width of the component.|
210| minHeight | [Length](ts-types.md#length) | No| Minimum height of the component.|
211| maxHeight | [Length](ts-types.md#length) | No| Maximum height of the component.|
212
213>  **NOTE**
214>
215>  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.
216
217## Example
218### Example 1
219
220```ts
221// xxx.ets
222@Entry
223@Component
224struct SizeExample {
225  build() {
226    Column({ space: 10 }) {
227      Text('margin and padding:').fontSize(12).fontColor(0xCCCCCC).width('90%')
228      Row() {
229        // Width: 80; height: 80; margin: 20 (blue area); top, bottom, left, and right paddings: 5, 15, 10, and 20 (white area)
230        Row() {
231          Row().size({ width: '100%', height: '100%' }).backgroundColor(Color.Yellow)
232        }
233        .width(80)
234        .height(80)
235        .padding({ top: 5, left: 10, bottom: 15, right: 20 })
236        .margin(20)
237        .backgroundColor(Color.White)
238      }.backgroundColor(Color.Blue)
239
240      Text('constraintSize').fontSize(12).fontColor(0xCCCCCC).width('90%')
241      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')
242        .width('90%')
243        .constraintSize({ maxWidth: 200 })
244
245      Text('layoutWeight').fontSize(12).fontColor(0xCCCCCC).width('90%')
246      // 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.
247      Row() {
248        // Weight 1: The component occupies 1/3 of the remaining space along the main axis.
249        Text('layoutWeight(1)')
250          .size({ width: '30%', height: 110 }).backgroundColor(0xFFEFD5).textAlign(TextAlign.Center)
251          .layoutWeight(1)
252        // Weight 2: The component occupies 2/3 of the remaining space along the main axis.
253        Text('layoutWeight(2)')
254          .size({ width: '30%', height: 110 }).backgroundColor(0xF5DEB3).textAlign(TextAlign.Center)
255          .layoutWeight(2)
256        // If layoutWeight is not set, the component is rendered based on its own size setting.
257        Text('no layoutWeight')
258          .size({ width: '30%', height: 110 }).backgroundColor(0xD2B48C).textAlign(TextAlign.Center)
259      }.size({ width: '90%', height: 140 }).backgroundColor(0xAFEEEE)
260      // calc calculation feature
261      Text('calc:').fontSize(12).fontColor(0xCCCCCC).width('90%')
262      Text('calc test')
263        .fontSize(50)
264        .fontWeight(FontWeight.Bold)
265        .backgroundColor(0xFFFAF0)
266        .textAlign(TextAlign.Center)
267        .margin('calc(25vp*2)')
268        // If width or height is set to a percentage, the width or height of the parent container are used as the basic value.
269        .size({ width: 'calc(90%)', height: 'calc(50vp + 10%)' })
270    }.width('100%').margin({ top: 5 })
271  }
272}
273```
274
275![size](figures/size.png)
276
277### Example 2
278This example demonstrates how to use the **padding** and **margin** attributes of the LocalizedPadding and LocalizedMargin types, respectively.
279```ts
280// xxx.ets
281import { LengthMetrics } from '@kit.ArkUI'
282
283@Entry
284@Component
285struct SizeExample {
286  build() {
287    Column({ space: 10 }) {
288      Text('margin and padding:').fontSize(12).fontColor(0xCCCCCC).width('90%')
289      Row() {
290        // 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).
291        Row() {
292          Row().size({ width: '100%', height: '100%' }).backgroundColor(Color.Yellow)
293        }
294        .width(80)
295        .height(80)
296        .padding({
297          top: LengthMetrics.vp(5),
298          bottom: LengthMetrics.vp(15),
299          start: LengthMetrics.vp(10),
300          end: LengthMetrics.vp(20)
301        })
302        .margin({
303          top: LengthMetrics.vp(40),
304          bottom: LengthMetrics.vp(20),
305          start: LengthMetrics.vp(30),
306          end: LengthMetrics.vp(10)
307        })
308        .backgroundColor(Color.White)
309      }.backgroundColor(Color.Blue)
310    }.width('100%').margin({ top: 5 })
311  }
312}
313```
314
315The following shows how the example is represented with left-to-right scripts.
316
317![size](figures/size-ltr.png)
318
319The following shows how the example is represented with right-to-left scripts.
320
321![size](figures/size-rtl.png)
322
323### Example 3
324This example sets a component-level safe area for a container.
325```ts
326// xxx.ets
327import { LengthMetrics } from '@kit.ArkUI';
328
329@Entry
330@Component
331struct SafeAreaPaddingExample {
332  build() {
333    Column() {
334      Column() {
335        Column()
336          .width("100%")
337          .height("100%")
338          .backgroundColor(Color.Pink)
339      }
340      .width(200)
341      .height(200)
342      .backgroundColor(Color.Yellow)
343      .borderWidth(10)
344      .padding(10)
345      .safeAreaPadding(LengthMetrics.vp(40))
346    }
347    .height('100%')
348    .width('100%')
349  }
350}
351```
352
353![safeAreaPaddingExample](figures/safeAreaPaddingExample.png)
354