# 尺寸设置 设置组件的宽高、边距。 > **说明:** > > 从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。 > > 如果组件的尺寸通过百分比进行设置, 在计算组件尺寸的百分比大小时,参考最近设置了固定大小的祖先节点的尺寸。 ## width width(value: Length): T 设置组件自身的宽度,缺省时使用元素自身内容需要的宽度。若子组件的宽大于父组件的宽,则会画出父组件的范围。 从API version 10开始,该接口支持calc计算特性。 **卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------- | ---- | ------------------- | | value | [Length](ts-types.md#length) | 是 | 要设置的组件宽度。
单位:vp | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | > **说明:** > > - 在[TextInput](./ts-basic-components-textinput.md)组件中,width设置auto表示自适应文本宽度。 > > - 在[AlphabetIndexer](./ts-container-alphabet-indexer.md)组件中,width设置auto表示自适应宽度最大索引项的宽度。 ## height height(value: Length): T 设置组件自身的高度,缺省时使用元素自身内容需要的高度。若子组件的高大于父组件的高,则会画出父组件的范围。 从API version 10开始,该接口支持calc计算特性。 **卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------- | ---- | ------------------- | | value | [Length](ts-types.md#length) | 是 | 要设置的组件高度。
单位:vp | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | > **说明:** > > 在[Row](./ts-container-row.md)、[Column](./ts-container-column.md)、[RelativeContainer](./ts-container-relativecontainer.md)组件中,width、height设置auto表示自适应子组件。 ## width15+ width(widthValue: Length | LayoutPolicy): T 设置组件自身的宽度或水平方向布局策略,缺省时使用元素自身内容需要的宽度。若子组件的宽大于父组件的宽,则会画出父组件的范围。 **卡片能力:** 从API version 15开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 15开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------- | ---- | ------------------- | | widthValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-universal-attributes-size.md#layoutpolicy15) | 是 | 要设置的组件宽度。
单位:vp | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | ## height15+ height(heightValue: Length | LayoutPolicy): T 设置组件自身的高度或垂直方向布局策略,缺省时使用元素自身内容需要的高度。若子组件的高大于父组件的高,则会画出父组件的范围。 **卡片能力:** 从API version 15开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 15开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------- | ---- | ------------------- | | heightValue | [Length](ts-types.md#length) \| [LayoutPolicy](ts-universal-attributes-size.md#layoutpolicy15) | 是 | 要设置的组件高度。
单位:vp | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | ## size size(value: SizeOptions): T 设置组件自身的宽高尺寸。 从API version 10开始,该接口支持calc计算特性。 **卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | ------------------------------- | ---- | ----------------- | | value | [SizeOptions](ts-types.md#sizeoptions) | 是 | 设置宽高尺寸。
异常值:参数为undefined时,属性设置不生效;其它异常值时,size属性恢复到不配置时的默认行为。
单位:vp | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | ## padding padding(value: Padding | Length | LocalizedPadding): T 设置组件的内边距属性。 从API version 10开始,该接口支持calc计算特性。 **卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ---------------------------------------- | | value | [Padding](ts-types.md#padding) \| [Length](ts-types.md#length) \| [LocalizedPadding](ts-types.md#localizedpadding12)12+| 是 | 设置组件的内边距。
参数为Length类型时,四个方向内边距同时生效。
默认值:0
单位:vp
padding设置百分比时,上下左右内边距均以父容器的width作为基础值。 | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | ## margin margin(value: Margin | Length | LocalizedMargin): T 设置组件的外边距属性。在计算位置时外边距视为组件大小的一部分,从而影响组件位置。 从API version 10开始,该接口支持calc计算特性。 **卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | | value | [Margin](ts-types.md#margin) \| [Length](ts-types.md#length) \| [LocalizedMargin](ts-types.md#localizedmargin12)12+ |  是 | 设置组件的外边距。
参数为Length类型时,四个方向外边距同时生效。
默认值:0
单位:vp
margin设置百分比时,上下左右外边距均以父容器的width作为基础值。在[Row](./ts-container-row.md)、[Column](./ts-container-column.md)、[Flex](./ts-container-flex.md)交叉轴上布局时,子组件交叉轴的大小与margin的和为整体。
例如Column容器宽100,其中子组件宽50,margin left为10,right为20,子组件水平方向偏移10。 | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | ## safeAreaPadding14+ safeAreaPadding(paddingValue: Padding | LengthMetrics | LocalizedPadding): T 设置安全区边距属性。允许容器向自身添加组件级安全区域,供子组件延伸,支持[attributeModifier](ts-universal-attributes-attribute-modifier.md#attributemodifier)动态设置属性方法。 **卡片能力:** 从API version 14开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 14开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ---------------------------------------- | | paddingValue | [Padding](ts-types.md#padding) \| [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) \| [LocalizedPadding](ts-types.md#localizedpadding12)| 是 | 设置组件的安全区边距。
默认值:0
单位:vp | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | > **说明:** > > 当父辈和祖先容器设置了组件级安全区域时,子组件可以感知并利用该区域,称该区域为累计安全区延伸(accumulatedSafeAreaExpand,下文简称SAE),表示子组件在四个方向上各可延伸的长度。当祖辈与更上一级祖辈的safeAreaPadding相邻接(即未被margin、border、padding分隔)时,SAE将递归地向外累积,直至不存在相邻的更外层safeAreaPadding或递归至页面容器外。系统级避让区域(如状态栏、导航条、挖孔区等,详情参见[expandSafeArea](./ts-universal-attributes-expand-safe-area.md)中的说明)可视为页面容器特有的safeAreaPadding,同样参与该延伸范围的计算。 > >通过与其他属性配合使用,可对上述计算得到的组件级安全区区域加以利用。例如,对子组件设置[ignoreLayoutSafeArea](./ts-universal-attributes-expand-safe-area.md#ignorelayoutsafearea20)属性,即可利用SAE延伸组件的布局范围。 ## layoutWeight layoutWeight(value: number | string): T 设置组件的布局权重,使组件在父容器([Row](./ts-container-row.md)/[Column](./ts-container-column.md)/[Flex](./ts-container-flex.md))的主轴方向按照权重分配尺寸。 **卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | -------------------------- | ------- | ---------------------------------------- | | value | number \| string |  是 | 父容器尺寸确定时,不设置layoutWeight属性或者layoutWeight属性生效值为0的元素优先占位,这些元素占位后在主轴留下的空间称为主轴剩余空间。设置了layoutWeight属性且layoutWeight属性生效值大于0的子元素会从主轴剩余空间中按照各自所设置的权重占比分配尺寸,分配时会忽略元素本身的尺寸设置。
默认值:0
**说明:**
仅在[Row](./ts-container-row.md)/[Column](./ts-container-column.md)/[Flex](./ts-container-flex.md)布局中生效。
可选值为大于等于0的数字,或者可以转换为数字的字符串。
如果容器中有子元素设置了layoutWeight属性,且设置的属性值大于0,则所有子元素不会再基于flexShrink和flexGrow布局。 | **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | ## constraintSize constraintSize(value: ConstraintSizeOptions): T 设置约束尺寸,组件布局时,进行尺寸范围限制。 从API version 10开始,该接口支持calc计算特性。 **卡片能力:** 从API version 9开始,该接口支持在ArkTS卡片中使用。 **原子化服务API:** 从API version 11开始,该接口支持在原子化服务中使用。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full **参数:** | 参数名 | 类型 | 必填 | 说明 | | ----- | ---------------------------------------- | ---- | ---------------------------------------- | | value | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 是 | 设置约束尺寸。constraintSize的优先级高于Width和Height。取值结果参考constraintSize取值对width/height影响。
默认值:
{
minWidth: 0,
maxWidth: Infinity,
minHeight: 0,
maxHeight: Infinity
}
异常值:数值开头的字符串仅解析出数字部分,非数值开头的字符串解析为0;其它异常值时,constraintSize属性恢复到不配置时的默认行为。
单位:vp
| **返回值:** | 类型 | 说明 | | --- | --- | | T | 返回当前组件。 | **constraintSize(minWidth/maxWidth/minHeight/maxHeight)取值对width/height影响:** | 缺省值 | 结果 | | ---------------------------------------- | ---------------------------------------- | | \ | width=MAX(minWidth,MIN(maxWidth,width))
height=MAX(minHeight,MIN(maxHeight,height)) | | maxWidth、maxHeight | width=MAX(minWidth,width)
height=MAX(minHeight,height) | | minWidth、minHeight | width=MIN(maxWidth,width)
height=MIN(maxHeight,height) | | width、height | 若minWidth若minHeightheight=minHeight | | width与minWidth、height与minHeight | 组件自身布局逻辑生效,width取值约束为不大于maxWidth。
组件自身布局逻辑生效,height取值约束为不大于maxHeight。 | | minWidth与maxWidth、minHeight与maxHeight | width以所设值为基础,根据其他布局属性发生可能的拉伸或者压缩。
height以所设值为基础,根据其他布局属性发生可能的拉伸或者压缩。| | width与minWidth与maxWidth | 使用父容器传递的布局限制进行布局。 | | height与minHeight与maxHeight | 使用父容器传递的布局限制进行布局。 | ## LayoutPolicy15+ 用于组件宽度和高度的布局策略。 **系统能力:** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 只读 | 可选 | 说明 | | --------- | ------ | ---- | ---- |---------- | | matchParent | [LayoutPolicy](ts-universal-attributes-size.md#layoutpolicy15) | 是 | 否 | 当前组件自适应父组件布局时,其大小与父组件内容区相等,不包括padding,border和safeAreaPadding。
**卡片能力:** 从API version 15开始,该接口支持在ArkTS卡片中使用。
**原子化服务API:** 从API version 15开始,该接口支持在原子化服务中使用。| | wrapContent20+ | [LayoutPolicy](ts-universal-attributes-size.md#layoutpolicy15) | 是 | 否 | 当前组件自适应子组件(内容)时,其大小与子组件(内容)相等,并且其大小受父组件内容区大小约束。
**卡片能力:** 从API version 20开始,该接口支持在ArkTS卡片中使用。
**原子化服务API:** 从API version 20开始,该接口支持在原子化服务中使用。| | fixAtIdealSize20+ | [LayoutPolicy](ts-universal-attributes-size.md#layoutpolicy15) | 是 | 否 | 当前组件自适应子组件(内容)时,其大小与子组件(内容)相等,并且其大小不受父组件内容区大小约束。
**卡片能力:** 从API version 20开始,该接口支持在ArkTS卡片中使用。
**原子化服务API:** 从API version 20开始,该接口支持在原子化服务中使用。| > **说明:** > > - LayoutPolicy支持设置三种布局策略:matchParent(自适应父组件布局)、wrapContent(根据内容自适应但不超过父组件尺寸的布局)和fixAtIdealSize(根据内容自适应,可能超过父组件尺寸的布局)。具体示例代码参见[设置布局策略](./ts-universal-attributes-size.md#示例5设置布局策略)。 > > - wrapContent和fixAtIdealSize场景,组件无法通过内容确定大小时,如果组件大小有默认值,则按照默认值进行测算;如果没有默认值,则按照宽高(0,0)进行测算。 > > - 容器设置wrapContent,并且有子组件设置matchParent时,容器先由确定大小的子组件撑大,设置matchParent的子组件再匹配容器大小;如果没有确定大小的子组件,容器和子组件大小均为0。 > > - LayoutPolicy优先级低于constraintSize。 ## 示例 ### 示例1(设置组件的宽高和边距) 设置组件的宽度、高度、内边距及外边距。 ```ts // xxx.ets @Entry @Component struct SizeExample { build() { Column({ space: 10 }) { Text('margin and padding:').fontSize(12).fontColor(0xCCCCCC).width('90%') Row() { // 宽度80 ,高度80 ,外边距20(蓝色区域),上下左右的内边距分别为5、15、10、20(白色区域) Row() { Row() .size({ width: '100%', height: '100%' }) .backgroundColor(Color.Yellow) } .width(80) .height(80) .padding({ top: 5, left: 10, bottom: 15, right: 20 }) .margin(20) .backgroundColor(Color.White) }.backgroundColor(Color.Blue) Text('constraintSize') .fontSize(12) .fontColor(0xCCCCCC) .width('90%') 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') .width('90%') .constraintSize({ maxWidth: 200 }) Text('layoutWeight') .fontSize(12) .fontColor(0xCCCCCC) .width('90%') // 父容器尺寸确定时,设置了layoutWeight的子元素在主轴布局尺寸按照权重进行分配,忽略本身尺寸设置。 Row() { // 权重1,占主轴剩余空间1/3 Text('layoutWeight(1)') .size({ width: '30%', height: 110 }).backgroundColor(0xFFEFD5).textAlign(TextAlign.Center) .layoutWeight(1) // 权重2,占主轴剩余空间2/3 Text('layoutWeight(2)') .size({ width: '30%', height: 110 }).backgroundColor(0xF5DEB3).textAlign(TextAlign.Center) .layoutWeight(2) // 未设置layoutWeight属性,组件按照自身尺寸渲染 Text('no layoutWeight') .size({ width: '30%', height: 110 }).backgroundColor(0xD2B48C).textAlign(TextAlign.Center) } .size({ width: '90%', height: 140 }) .backgroundColor(0xAFEEEE) // calc计算特性 Text('calc:') .fontSize(12) .fontColor(0xCCCCCC) .width('90%') Text('calc test') .fontSize(50) .fontWeight(FontWeight.Bold) .backgroundColor(0xFFFAF0) .textAlign(TextAlign.Center) .margin('calc(25vp*2)') // width和height设置百分比时,以父容器的width和height作为基础值。 .size({ width: 'calc(90%)', height: 'calc(50vp + 10%)' }) } .width('100%') .margin({ top: 5 }) } } ``` ![size](figures/size.png) ### 示例2(LocalizedPadding和LocalizedMargin类型的使用) 使用LocalizedPadding类型和LocalizedMargin类型定义padding和margin属性。 ```ts // xxx.ets import { LengthMetrics } from '@kit.ArkUI' @Entry @Component struct SizeExample { build() { Column({ space: 10 }) { Text('margin and padding:') .fontSize(12) .fontColor(0xCCCCCC) .width('90%') Row() { // 宽度80 ,高度80 ,上下开始结束的外边距40、20、30、10(蓝色区域),上下开始结束的内边距分别为5、15、10、20(白色区域) Row() { Row() .size({ width: '100%', height: '100%' }) .backgroundColor(Color.Yellow) } .width(80) .height(80) .padding({ top: LengthMetrics.vp(5), bottom: LengthMetrics.vp(15), start: LengthMetrics.vp(10), end: LengthMetrics.vp(20) }) .margin({ top: LengthMetrics.vp(40), bottom: LengthMetrics.vp(20), start: LengthMetrics.vp(30), end: LengthMetrics.vp(10) }) .backgroundColor(Color.White) } .backgroundColor(Color.Blue) } .width('100%') .margin({ top: 5 }) } } ``` 从左至右显示语言示例图 ![size](figures/size-ltr.png) 从右至左显示语言示例图 ![size](figures/size-rtl.png) ### 示例3(设置安全区) 对容器设置组件级安全区。 ```ts // xxx.ets import { LengthMetrics } from '@kit.ArkUI'; @Entry @Component struct SafeAreaPaddingExample { build() { Column() { Column() { Column() .width("100%") .height("100%") .backgroundColor(Color.Pink) } .width(200) .height(200) .backgroundColor(Color.Yellow) .borderWidth(10) .padding(10) .safeAreaPadding(LengthMetrics.vp(40)) } .height('100%') .width('100%') } } ``` ![safeAreaPaddingExample](figures/safeAreaPaddingExample.png) ### 示例4(使用attributeModifier动态设置安全区) 使用attributeModifier对容器设置组件级安全区。 ```ts // xxx.ets class MyModifier implements AttributeModifier { applyNormalAttribute(instance: CommonAttribute): void { instance.safeAreaPadding({ left: 10, top: 20, right: 30, bottom: 40 }) } } @Entry @Component struct SafeAreaPaddingExample { @State modifier: MyModifier = new MyModifier() build() { Column() { Column() { Column() .width("100%") .height("100%") .backgroundColor(Color.Pink) } .width(200) .height(200) .backgroundColor(Color.Yellow) .borderWidth(10) .padding(10) .attributeModifier(this.modifier) } .height('100%') .width('100%') } } ``` ![safeAreaPaddingModifierExample](figures/safeAreaPaddingModifierExample.png) ### 示例5(设置布局策略) 对容器大小设置布局策略。 ```ts // xxx.ets @Entry @Component struct LayoutPolicyExample { build() { Column() { Column() { // matchParent生效时,当前组件会与其父组件内容区大小(180vp * 180vp)相等,同时依旧受自身constraintSize(150vp * 150vp)约束,因此当前组件大小为150vp * 150vp Text("matchParent") Flex() .backgroundColor('rgb(0, 74, 175)') .width(LayoutPolicy.matchParent) .height(LayoutPolicy.matchParent) .constraintSize({ maxWidth: 150, maxHeight: 150 }) // wrapContent生效时,当前组件会与其子组件大小(300vp * 300vp)相等,但不能超过父组件内容大小(180vp * 180vp)且会受自身constraintSize(250vp * 250vp)约束,因此当前组件大小为180vp * 180vp Text("wrapContent") Row() { Flex() .width(300) .height(300) } .backgroundColor('rgb(39, 135, 217)') .width(LayoutPolicy.wrapContent) .height(LayoutPolicy.wrapContent) .constraintSize({ maxWidth: 250, maxHeight: 250 }) // 从API version 20开始,layoutPolicy支持wrapContent和fixAtIdealSize。fixAtIdealSize生效时,当前组件会与其子组件大小(300vp * 300vp)相等,可以超过父组件内容大小(180vp * 180vp)但会受自身constraintSize(250vp * 250vp)约束,因此当前组件大小为250vp * 250vp Text("fixAtIdealSize") Row() { Flex() .width(300) .height(300) } .backgroundColor('rgb(240, 250, 255)') .width(LayoutPolicy.fixAtIdealSize) .height(LayoutPolicy.fixAtIdealSize) .constraintSize({ maxWidth: 250, maxHeight: 250 }) } .width(200) .height(200) .padding(10) } .width("100%") .height("100%") } } ``` ![layoutPolicyExample](figures/layoutPolicy_demo.jpg)