鸿蒙:ArkUI布局
基础布局
间距、边框与圆角
布局属性决定组件自身占多大、和邻居隔多远。padding 是内边距,拉开内容与组件边缘的距离;margin 是外边距,拉开两个组件之间的距离;border 画边框线;borderRadius 切圆角。四者都可以给一个数字(四个方向相同),也可以给对象单独指定方向。
[代码]
Text('文字')
.padding(20) // 四向相同
.padding({ top: 10, right: 20, bottom: 40, left: 30 })
.margin({ bottom: 10 })
边框属性接收一个对象,可同时指定宽度、颜色和样式。BorderStyle 有实线、虚线、点线三种;四个方向可以统一设置,也可以分别设置。
【代码】
Text('边框')
.width(100).height(48).textAlign(TextAlign.Center)
.border({ width: 1, color: '#999', style: BorderStyle.Solid })
// 四向不同
.border({
width: { left: 1, top: 3, right: 5, bottom: 7 },
color: { left: 'red', top: '#ffffee', right: '#ffee00', bottom: '#cccccc' },
style: { top: BorderStyle.Dashed, right: BorderStyle.Dotted }
})
圆角用 borderRadius,可以给统一数值,也可以用对象分别设置 topLeft、topRight、bottomLeft、bottomRight。卡片类界面通常给 8~12 的圆角。
1.背景属性
背景属性
|
属性 |
说明 |
|
backgroundColor |
背景色 |
|
backgroundImage |
背景图,第二个参数为平铺方式 ImageRepeat |
|
backgroundImageSize |
背景图缩放尺寸或缩放策略 |
|
backgroundImagePosition |
背景图在组件内的位置 |
背景图平铺方式有 NoRepeat(默认不平铺)、X(水平平铺)、Y(垂直平铺)、XY(双向平铺)。缩放可以给具体宽高,也可以用 ImageSize 的 Cover、Contain、Auto;只设置一边尺寸时,另一边按原图比例缩放。位置可以给坐标 { x, y },也可以用 Alignment 枚举,默认在左上角。
【代码】
Text('背景图')
.width(300).height(150)
.backgroundImage($r('app.media.flower'), ImageRepeat.NoRepeat)
.backgroundImageSize(ImageSize.Cover)
.backgroundImagePosition(Alignment.Center)
2.线性布局 Row 与 Column
线性布局是最常用的布局方式:Column 的子元素沿垂直方向排列,Row 的子元素沿水平方向排列。描述这类布局要分清主轴与交叉轴——主轴是布局方向的轴线,子元素默认沿主轴排列;交叉轴垂直于主轴。因此 Column 主轴纵向、交叉轴横向,Row 正好相反。
主轴方向的间距用 space 参数统一设置,比给每个子元素写 margin 更整齐。
【代码】
Row({ space: 20 }) {
Text('子元素1').width(100).height(48).backgroundColor(Color.Pink)
Text('子元素2').width(100).height(48).backgroundColor(Color.Orange)
}
.width('100%')
主轴对齐用 justifyContent,取值属于 FlexAlign。交叉轴对齐用 alignItems,Column 用 HorizontalAlign,Row 用 VerticalAlign。
表 7 justifyContent 常用取值
|
取值 |
效果 |
|
Start |
首端对齐 |
|
Center |
居中对齐 |
|
End |
尾部对齐 |
|
SpaceBetween |
两端对齐,子元素之间间距相等 |
|
SpaceAround |
子元素两侧间距相等,两端间距是中间间距的一半 |
|
SpaceEvenly |
所有间距都完全相等,包括首尾 |
注意:alignItems 要生效,容器在交叉轴方向必须有足够空间。Column 若不设高度,高度只包住内容,垂直方向就无从对齐;同理 Row 不设宽度时水平方向也不会真正居中。若只想调整某一个子元素,用 alignSelf,取值是 ItemAlign,其中 Stretch 会在交叉轴方向拉伸填满。
【代码】
Column({ space: 20 }) {
Text('A')
Text('B')
Text('C').alignSelf(ItemAlign.End) // 仅 C 靠交叉轴末端
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)
3.自适应缩放 layoutWeight
父容器主轴尺寸确定时,设置了 layoutWeight 的子元素会与兄弟元素按权重分配主轴剩余尺寸。它适合做“左边固定、右边自适应”的结构,也适合把一行等分成若干份。
【代码】
Row() {
Text('固定').width(60).height(40).backgroundColor('#ccc')
Text('自适应').height(40).backgroundColor('#ddd').layoutWeight(1)
}
.width('100%'
注意:layoutWeight 只作用于主轴,不加高度不会自动撑高;它分配的是剩余尺寸,前面兄弟元素已占满主轴时权重再大也没有可分的空间。
弹性布局 Flex
1.基本用法与布局方向
弹性布局 Flex 提供了更有效的排列、对齐和分配剩余空间的方式,常用于页面头部导航的均匀分布、页面框架搭建和多行数据排列。它同样有主轴与交叉轴,子元素默认沿主轴排列。
【代码】
Flex() {
Text('1').width('33%').height(30).backgroundColor(Color.Orange)
Text('2').width('33%').height(30).backgroundColor(Color.Pink)
}
.width('100%')
.height(200)
主轴方向由 direction 参数控制,取值属于 FlexDirection:Row 为水平、RowReverse 为水平反向、Column 为垂直、ColumnReverse 为垂直反向。默认是 Row。
2.对齐与换行
Flex 的主轴对齐仍是 justifyContent,取值与线性布局完全一致;交叉轴对齐是 alignItems,取值属于 ItemAlign,比线性布局多了 Stretch 和 Baseline 两个值,Stretch 表示在交叉轴方向拉伸填充,未设尺寸时会一直拉到容器尺寸。
【代码】
Flex({
justifyContent: FlexAlign.SpaceBetween,
alignItems: ItemAlign.Center
}) {
Text('1').width(30).height(30)
Text('2').width(30).height(30)
}
.width('100%')
换行由 wrap 参数控制,取值属于 FlexWrap:NoWrap 为单行(默认),Wrap 为多行,WrapReverse 为反向多行。单行时若子元素尺寸之和超过容器,子元素会被自动挤压变形,这正是标签网格出现“字被压扁”的原因,加 wrap 即可解决。
【代码】
Flex({ wrap: FlexWrap.Wrap }) {
Text('React.js').width('22%').height(36)
Text('Vue.js').width('22%').height(36)
// …其余若干项,超出一行自动换行
}
3.剩余空间分配与基准尺寸
flexGrow 设置父容器剩余空间的分配比例,参数是占几份。父容器的剩余空间会按各子元素的份数比例分给它们。flexBasis 则设置子元素在主轴方向的基准尺寸,在分配剩余空间之前先占住这个尺寸。
【代码】
Flex() {
Text('A').width(60).height(40)
Text('B').height(40).flexGrow(1).flexBasis(120)
Text('C').height(40).flexGrow(1)
}
.width('100%')
注意:flexGrow 只分配主轴方向的剩余空间,不控制高度;如果同时写了固定的 width 又想靠 flexGrow 撑开,两个规则会互相牵制,出现宽度或高度异常。规整网格不需要 flexGrow,只在“这一行没排满、想让最后一个元素铺满剩余位置”时才用。
层叠布局Stack
Stack 是堆叠容器,子组件按代码书写顺序入栈,后写的组件盖在上面,用来做图片上加文字、角标、悬浮按钮、卡片叠加、支付宝 banner 这种效果Harmo...。
对比:Column 垂直排、Row 水平排;Stack 是全部叠在同一个区域。
Stack({ alignContent: Alignment.BottomStart }) {
// 底层(先写)
Image($r('app.media.banner'))
// 上层(后写,盖在图片上)
Text('热卖')
}
.width('100%')
.height(200)
alignContent:所有子组件统一对齐,默认Alignment.Center(居中堆叠)- 一共 9 种对齐枚举:
TopStart左上、Top上中、TopEnd右上Start左中、Center正中、End右中BottomStart左下、Bottom下中、BottomEnd右下
控制层级(zIndex)
默认规则:写在后面的层级更高 想要手动改覆盖顺序,用 .zIndex(数字)
- 值越大,越靠上层,盖住 zIndex 小的组件
Stack(){
Text('底层')
.width(100).height(100).backgroundColor(Color.Red)
.zIndex(1)
Text('上层')
.width(60).height(60).backgroundColor(Color.Blue)
.zIndex(99) // 这个在上面
}
⚠️ 坑:zIndex 只在同一个 Stack 内部兄弟组件生效,跨 Stack 无效!
单独控制某个子组件位置(3 种方式)
- 子组件.align ():优先级高于 Stack 的 alignContent,单独修改这个子组件对齐
Stack({alignContent:Alignment.Center}){
Text('居中')
Text('我要放右下角')
.align(Alignment.BottomEnd)
}
- offset({x,y}):相对于它本身对齐位置,偏移(相对偏移)
Text('角标')
.offset({x:15,y:-15})
- position({x,y}):相对于 Stack 父容器左上角,绝对定位(固定坐标)Huawei Dev...
区分:offset = 挪一点;position = 直接固定坐标
部分易错点清单
ArkTS 与 ArkUI 常见易错点
|
现象 |
原因 |
处理 |
|
新建页面预览一片空白 |
文件缺少 @Entry 或 @Component,或 build 未实现 |
补全两个装饰器与 build 方法 |
|
报错“根节点必须是容器组件” |
build 的根直接写了 Image、Text 等基础组件 |
外层包一层 Column、Row、Stack 或 Flex |
|
图片不显示 |
media 目录误用 Image('xx.png'),或少了网络权限 |
media 用 $r('app.media.名') 不带后缀;网络图在 module.json5 加 INTERNET 权限 |
|
textOverflow 报类型错误 |
新版 API 要求传对象而不是枚举值 |
写 .textOverflow({ overflow: TextOverflow.Ellipsis }) 并配 maxLines |
|
标题始终居中,textAlign 无效 |
Column 默认交叉轴居中;textAlign 需要组件宽大于文字宽 |
容器加 .alignItems(HorizontalAlign.Start),Text 加 .width('100%') |
|
justifyContent 写了没反应 |
误写在子组件上,它是容器属性 |
移到容器上,并保证容器在主轴方向有确定尺寸 |
|
alignItems 没效果 |
交叉轴方向没有足够空间 |
给容器补 height('100%') 或固定宽度 |
|
Flex 子元素被压扁、不换行 |
默认 FlexWrap.NoWrap,单行强制挤压 |
加 wrap: FlexWrap.Wrap |
|
加了 flexGrow 后组件变矮或宽度错乱 |
flexGrow 只分配主轴剩余空间,与固定 width 冲突 |
规整网格删掉 flexGrow,或改为只给末端元素使用 |
|
设了 aspectRatio 高度却不对 |
宽高比优先,高度被反推覆盖 |
只保留 width 与 aspectRatio,删掉 height |
|
编译报 arkts-no-any-unknown |
ArkTS 禁止 any 与 unknown |
用 interface 约定结构或写显式类型 |
还有一类问题来自写法本身:组件属性必须紧跟在自己所属的组件后面,括号必须成对闭合。一次少写一个大括号,编译器往往会在几十行之后报“逗号缺失”“意外的标记”,并连带报出一串 any/unknown 错误——此时应先回到结构层级检查括号,而不是逐条改类型。
这段模板把几个高频属性一次写齐:Column 占满屏幕、内边距 20、子元素左对齐、整体靠上排列。需要垂直居中时,把 justifyContent 改成 FlexAlign.Center 即可。
更多推荐



所有评论(0)