基础布局

间距、边框与圆角

布局属性决定组件自身占多大、和邻居隔多远。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)
  1. alignContent:所有子组件统一对齐,默认 Alignment.Center(居中堆叠)
  2. 一共 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 种方式)

  1. 子组件.align ():优先级高于 Stack 的 alignContent,单独修改这个子组件对齐
Stack({alignContent:Alignment.Center}){
  Text('居中')
  Text('我要放右下角')
    .align(Alignment.BottomEnd)
}
  1. offset({x,y}):相对于它本身对齐位置,偏移(相对偏移)
Text('角标')
  .offset({x:15,y:-15})
  1. 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 即可。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐