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>  - For the **\<TextInput>** component, the **auto** option of **width** means to adapt to the text width.
32>  
33>  - For the **\<AlphabetIndexer>** component, the **auto** option of **width** means to adapt 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>  For the **\<Row>**, **\<Column>**, and **\<RelativeContainer>** components, the **auto** option of **width** and **height** means to adapt to 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>**, **\<Column>**, or **\<Flex>** 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## layoutWeight
120
121layoutWeight(value: number | string)
122
123Sets the weight of the component during layout.
124
125**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
126
127**Atomic service API**: This API can be used in atomic services since API version 11.
128
129**System capability**: SystemCapability.ArkUI.ArkUI.Full
130
131**Parameters**
132
133| Name  | Type                        | Mandatory     | Description                                      |
134| ----- | -------------------------- | ------- | ---------------------------------------- |
135| value | number \| string | Yes| Weight of the component during layout. When the container size is determined, the container space is allocated along the main axis among the component and sibling components based on the layout weight, and the component size setting is ignored.<br>Default value: **0**<br>**NOTE**<br>This attribute is valid only for the **\<Row>**, **\<Column>**, and **\<Flex>** layouts.<br>The value can be a number greater than or equal to 0 or a string that can be converted to a number.|
136
137## constraintSize
138
139constraintSize(value: ConstraintSizeOptions)
140
141Sets the constraint size of the component, which is used to limit the size range during component layout.
142
143Since API version 10, this API supports the calc calculation feature.
144
145**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
146
147**Atomic service API**: This API can be used in atomic services since API version 11.
148
149**System capability**: SystemCapability.ArkUI.ArkUI.Full
150
151**Parameters**
152
153| Name  | Type                                      | Mandatory  | Description                                      |
154| ----- | ---------------------------------------- | ---- | ---------------------------------------- |
155| 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>|
156
157**Impact of constraintSize on width/height**
158
159| Default Value                                     | Result                                      |
160| ---------------------------------------- | ---------------------------------------- |
161| /                                        | max(minWidth/minHeight, min(maxWidth/maxHeight, width/height)) |
162| maxWidth/maxHeight                       | max(minWidth/minHeight, width/height)    |
163| minWidth/minHeight                       | min(maxWidth/maxHeight, width/height)    |
164| width/height                             | In the case of maxWidth/maxHeight > minWidth/minHeight, the layout logic of the component is used,<br>and the result is between maxWidth/maxHeight and minWidth/minHeight.<br> In other cases, the result is max(minWidth/minHeight, maxWidth/maxHeight).|
165| maxWidth/maxHeight && width/height       | minWidth/minHeight                       |
166| minWidth/minHeight && width/height       | The layout logic of the component is used. The final result does not exceed maxWidth/maxHeight.    |
167| maxWidth/maxHeight && minWidth/minHeight | Width/Height, which may be stretched or compressed based on other layout attributes.          |
168| maxWidth/maxHeight && minWidth/minHeight && width/height | The layout restrictions passed by the parent container are used for layout.                       |
169
170## SizeOptions
171
172**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
173
174**Atomic service API**: This API can be used in atomic services since API version 11.
175
176| Name  | Type                                      | Mandatory  | Description                                      |
177| ----- | ---------------------------------------- | ---- | ---------------------------------------- |
178| width  | [Length](ts-types.md#length) | No| Component width.|
179| height | [Length](ts-types.md#length) | No| Component height.|
180
181## ConstraintSizeOptions
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| Name  | Type                                      | Mandatory  | Description                                      |
188| ----- | ---------------------------------------- | ---- | ---------------------------------------- |
189| minWidth  | [Length](ts-types.md#length) | No| Minimum width of the component.|
190| maxWidth  | [Length](ts-types.md#length) | No| Maximum width of the component.|
191| minHeight | [Length](ts-types.md#length) | No| Minimum height of the component.|
192| maxHeight | [Length](ts-types.md#length) | No| Maximum height of the component.|
193
194>  **NOTE**
195>
196>  For the **\<Row>**, **\<Column>**, and **\<RelativeContainer>** components, the **auto** option of **width** and **height** means to adapt to their child components. For the **\<TextInput>** component, the **auto** option of **width** means to adapt to the text width.
197
198## Example
199### Example 1
200
201```ts
202// xxx.ets
203@Entry
204@Component
205struct SizeExample {
206  build() {
207    Column({ space: 10 }) {
208      Text('margin and padding:').fontSize(12).fontColor(0xCCCCCC).width('90%')
209      Row() {
210        // Width: 80; height: 80; margin: 20 (blue area); top, bottom, left, and right paddings: 5, 15, 10, and 20 (white area)
211        Row() {
212          Row().size({ width: '100%', height: '100%' }).backgroundColor(Color.Yellow)
213        }
214        .width(80)
215        .height(80)
216        .padding({ top: 5, left: 10, bottom: 15, right: 20 })
217        .margin(20)
218        .backgroundColor(Color.White)
219      }.backgroundColor(Color.Blue)
220
221      Text('constraintSize').fontSize(12).fontColor(0xCCCCCC).width('90%')
222      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')
223        .width('90%')
224        .constraintSize({ maxWidth: 200 })
225
226      Text('layoutWeight').fontSize(12).fontColor(0xCCCCCC).width('90%')
227      // 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.
228      Row() {
229        // Weight 1: The component occupies 1/3 of the remaining space along the main axis.
230        Text('layoutWeight(1)')
231          .size({ width: '30%', height: 110 }).backgroundColor(0xFFEFD5).textAlign(TextAlign.Center)
232          .layoutWeight(1)
233        // Weight 2: The component occupies 2/3 of the remaining space along the main axis.
234        Text('layoutWeight(2)')
235          .size({ width: '30%', height: 110 }).backgroundColor(0xF5DEB3).textAlign(TextAlign.Center)
236          .layoutWeight(2)
237        // If layoutWeight is not set, the component is rendered based on its own size setting.
238        Text('no layoutWeight')
239          .size({ width: '30%', height: 110 }).backgroundColor(0xD2B48C).textAlign(TextAlign.Center)
240      }.size({ width: '90%', height: 140 }).backgroundColor(0xAFEEEE)
241      // calc calculation feature
242      Text('calc:').fontSize(12).fontColor(0xCCCCCC).width('90%')
243      Text('calc test')
244        .fontSize(50)
245        .fontWeight(FontWeight.Bold)
246        .backgroundColor(0xFFFAF0)
247        .textAlign(TextAlign.Center)
248        .margin('calc(25vp*2)')
249        // If width or height is set to a percentage, the width or height of the parent container are used as the basic value.
250        .size({ width: 'calc(90%)', height: 'calc(50vp + 10%)' })
251    }.width('100%').margin({ top: 5 })
252  }
253}
254```
255
256![size](figures/size.png)
257
258### Example 2
259```ts
260// xxx.ets
261// In the following, the padding and margin attributes are of the LocalizedPadding and LocalizedMargin types, respectively.
262
263import { LengthMetrics } from '@kit.ArkUI'
264
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        // 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).
273        Row() {
274          Row().size({ width: '100%', height: '100%' }).backgroundColor(Color.Yellow)
275        }
276        .width(80)
277        .height(80)
278        .padding({
279          top: LengthMetrics.vp(5),
280          bottom: LengthMetrics.vp(15),
281          start: LengthMetrics.vp(10),
282          end: LengthMetrics.vp(20)
283        })
284        .margin({
285          top: LengthMetrics.vp(40),
286          bottom: LengthMetrics.vp(20),
287          start: LengthMetrics.vp(30),
288          end: LengthMetrics.vp(10)
289        })
290        .backgroundColor(Color.White)
291      }.backgroundColor(Color.Blue)
292    }.width('100%').margin({ top: 5 })
293  }
294}
295```
296
297The following shows how the example is represented with left-to-right scripts.
298
299![size](figures/size-ltr.png)
300
301The following shows how the example is represented with right-to-left scripts.
302
303![size](figures/size-rtl.png)
304