鸿蒙 ArkUI 布局与基础语法综合总结

Wmh_1231

43人浏览 · 2026-06-22 15:26:21

Wmh_1231 · 2026-06-22 15:26:21 发布

一、ArkUI 三大核心装饰器（页面基础三要素）

这是所有页面、组件的编写前提，所有 UI 代码都必须遵循该结构。

@Entry 页面入口装饰器，标记当前自定义组件为独立运行的页面，等同于程序main入口，单个页面仅允许一个@Entry。
@Component 自定义 UI 组件装饰器，被修饰的struct结构体具备 UI 构建能力，是创建组件的基础标识。
@build 组件专属 UI 构建方法，所有布局、组件、样式代码必须写在该方法内部，是界面渲染的唯一入口。

标准基础模板

ets

@Entry // 页面入口
@Component // 定义组件
struct DemoPage {
  // 1. 数据区域（普通变量/状态变量）
  name: string = "鸿蒙学习者"
  // 2. UI构建区域
  build() {
    // 布局容器 + 基础组件
    Column() {
      Text(this.name)
    }
  }
}

@Entry
@Component
struct  ArkTsDemo{
  //1.arkTS数据层,定义了页面所需要的数据
  userName:string='鸿蒙应用开发学习者';
  major:string='计算机应用技术';
  studyYear:number = 2024;
  build() {
    Column({space:20}){
          //写所有的UI组件、界面元素
      Text('ArkUI框架上门案例')
        .fontSize(30)
        .padding( {top:20})
        . fontColor(Color. Black)
        .fontWeight(FontWeight. Bold)

      Text(`学习者姓名:${this.userName}`)
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.Red)

      Text(`学习者专业:${this.major}`)
        .fontSize(21)
      Text(`入学年份:${this.studyYear}`)
        .fontSize(20)
    }
    .width('100%')
    .height('100%')
    .backgroundColor(0xF4f4f4)
    .justifyContent(FlexAlign.Center)
  }
}

补充：支持数据动态渲染，可在组件内定义普通变量，通过${this.变量名}将数据绑定到 Text 等组件，实现数据与视图联动。

二、七大核心布局容器（分类、规则、属性、场景）

布局容器用于承载、排列子组件，是页面排版的核心，下文按使用频率从高到低整理，包含排列规则、核心属性、典型场景与代码特征。

1. Column 垂直线性布局

排列规则：子组件从上到下垂直排列；主轴为垂直方向，交叉轴为水平方向。
核心属性
- space：统一设置子组件间距（官方推荐，替代重复margin）；
- justifyContent：主轴（垂直） 对齐（顶部、居中、底部、均分）；
- alignItems：交叉轴（水平） 对齐（左、中、右）；
- width/height：容器尺寸，全屏页面建议设为100%；
- backgroundColor：设置容器背景色。
典型场景：表单、个人信息列表、垂直导航、页面主体内容。
特点：结构简单、性能最优，是最常用的基础布局。

实例：

@Entry
@Component
struct ColAndRow {
  build() {
    // 根布局：Column，垂直排列三部分
    Column() {
      // 第一部分：顶部红色通栏
      Column()
        .height('33.3%')
        .width('100%')
        .backgroundColor(Color.Red)

      // 第二部分：中间Row，左右两个等分块
      Row() {
        // 左侧粉色块
        Row() {
          Text('你好')
            .fontSize(30) // 放大文字
            .textAlign(TextAlign.Center) // 文字在Text内居中
        }
        .width('50%')
        .height('100%')
        .backgroundColor(Color.Pink)

        // 右侧橙色块
        Row()
          .width('50%')
          .height('100%')
          .backgroundColor(Color.Orange)
      }
      .height('33.3%')
      .width('100%')

      // 第三部分：底部绿色通栏
      Column()
        .height('33.3%')
        .width('100%')
        .backgroundColor(Color.Green)
    }
    .width('100%')
    .height('100%')
  }
}

@Entry
@Component
struct ColuPerson{
  build() {
    Column({space:30}){
      Text('个人信息中心')
        .fontSize(40)
        .fontWeight(FontWeight.Bolder)
        .margin(10)

      Text('姓名：张三').fontSize(22)
      Text('专业：计算机应用技术').fontSize(22)
      Text('年纪：2025级').fontSize(22)
      Text('学号：208325464').fontSize(22)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#00f5f5')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

2. Row 水平线性布局

排列规则：子组件从左到右水平排列；主轴为水平方向，交叉轴为垂直方向。
核心属性：与Column一致，space控制水平间距，justifyContent控制水平对齐，alignItems控制垂直对齐。
典型场景：按钮组、工具栏、顶部导航、横向标签、并排控件。
补充：默认单行排列，子组件超出容器不会自动换行。

实例：

@Entry
@Component
struct RowDemo {
  build() {
    Row({ space: 35 }) {
      Text('space: 35')
        .fontSize(15)
        .fontColor(Color.Gray)

      Row()
        .width('10%')
        .height(150)
        .backgroundColor(0xF5DEB3)

      Row()
        .width('10%')
        .height(150)
        .backgroundColor(0xD2B48C)

      Row()
        .width('10%')
        .height(150)
        .backgroundColor(0xF5DEB3)
    }
    .width('90%')
  }
}

3. Flex 弹性布局

排列规则：增强版线性布局，支持水平 / 垂直切换，子组件超出容器可自动换行，适配多尺寸屏幕。
核心属性
- wrap: FlexWrap.Wrap：开启自动换行（核心功能）；
- space：统一子组件间距；
- justifyContent/alignItems：控制对齐方式。
典型场景：标签流、分类菜单、自适应卡片、不规则多元素排列。
特点：主打屏幕自适应，移动端多标签场景首选。

实例：

@Entry
@Component
struct FlexDemo{
  build() {
    Flex({ direction: FlexDirection.Row }) {
      Text('1')
        .width('33%')
        .height(50)
        .backgroundColor('#F5DEB3')

      Text('2')
        .width('53%')
        .height(50)
        .backgroundColor('#D2B48C')

      Text('3')
        .width('53%')
        .height(50)
        .backgroundColor('#F5DEB3')
    }
    .height(70)
    .width('90%')
    .padding(10)
    .backgroundColor('#AFEEEE')
  }
}

4. Stack 层叠布局

排列规则：子组件沿 Z 轴层叠叠加，后编写的组件覆盖在先编写的组件之上，无固定横竖顺序。
典型场景：图片 + 文字叠加、头像角标、悬浮按钮、页面水印、弹窗、轮播图底层容器。

实战案例：头像叠加 VIP 标签、背景图添加文字说明。

@Entry
@Component
struct ColStack{
  build() {
    Column({space:50}){
      Text('这是我的个人主页')
        .fontSize(35)
        .fontWeight(FontWeight.Normal)
        .fontColor(Color.Orange)

      Stack(){
        Text('')
          .width(220)
          .height(220)
          .backgroundColor(0x925312)
          .borderRadius(30)

        Text('你好')
          .fontSize(40)
          .fontColor(Color.Red)
          .width(120)
          .height(120)
          .backgroundColor(0x596613)
          .borderRadius(30)
          .padding({left:15,right:0,top:0,bottom:0})
      }

      Text('欢迎来到鸿蒙开发')
        .fontSize(35)
        .fontWeight(FontWeight.Bolder)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
    .backgroundColor(Color.Yellow)
  }
}

5. RelativeContainer 相对布局

排列规则：通过锚点定位实现自由布局。给每个子组件设置唯一id，再通过alignRules指定参照物（父容器__container__或其他组件 id）和对齐方式，组件位置相互绑定。
核心语法
1. 子组件：.id("自定义标识")；
2. 对齐规则：.alignRules({ 对齐方向: { anchor: "参照物id", align: 对齐方式 } })。
典型场景：复杂不规则页面、多组件精准定位、仪表盘、自定义功能面板。
特点：定位灵活，组件相对位置不会随屏幕尺寸变化错乱，适合复杂布局。

实例：

@Entry
@Component
struct RealtiveDemo1{
  build() {
    RelativeContainer(){
      // 1.标题文本
      Text('相对布局页面设计')
        .fontSize(40)
        .fontWeight(FontWeight.Bold)
        .id('title')
        .alignRules({
          top: { anchor: '__container__', align: VerticalAlign.Top },
          left: { anchor: '__container__', align: HorizontalAlign.Start }
        })
        .margin(15)
        .backgroundColor(Color.Red)

      // 2.上方单个按钮
      Button('基础按钮')
        .width(150)
        .height(80)
        .fontSize(25)
        .id('buttonid')
        .alignRules({
          top:{anchor:'title',align:VerticalAlign.Bottom},
          middle:{anchor:'title',align:HorizontalAlign.Center}
        })
        .margin(30)

      // 3.红色提示文字
      Text('这个组件依赖于button')
        .fontSize(26)
        .fontColor(Color.Red)
        .id('textid')
        .alignRules({
          top:{anchor:'buttonid',align:VerticalAlign.Bottom},
          middle:{anchor:'buttonid',align:HorizontalAlign.Center}
        })
        .margin(20)

      // 4.底部左侧按钮
      Button('基础按钮')
        .width(120)
        .height(60)
        .fontSize(20)
        .id('btn_left')
        .alignRules({
          top:{anchor:'textid',align:VerticalAlign.Bottom},
          right:{anchor:'textid',align:HorizontalAlign.End}
        })
        .margin({top:30, right:120})

      // 5.底部右侧按钮
      Button('基础按钮')
        .width(120)
        .height(60)
        .fontSize(20)
        .id('btn_right')
        .alignRules({
          top:{anchor:'textid',align:VerticalAlign.Bottom},
          left:{anchor:'btn_left',align:HorizontalAlign.End}
        })
        .margin({top:30,left:20})

    }
    .width('100%')
    .height('100%')
    .backgroundColor(Color.Gray)
  }
}

6. Swiper 轮播布局

排列规则：容器内子组件左右滑动切换，支持自动播放、无限循环、分页指示器。
核心属性
- autoPlay(true)：开启自动轮播；
- interval(数值)：轮播切换间隔（单位：毫秒）；
- loop(true)：开启无限循环；
- 配合ForEach可批量渲染多张图片 / 内容。
典型场景：首页 Banner、宣传图轮播、图片展示。
注意：引用图片资源时，文件名禁止空格、括号、特殊符号，仅支持字母、数字、下划线。

实例：

@Entry
@Component
struct SwiperDemo{
  build() {
    Column(){
      Swiper(){
        Text('0')
          .backgroundColor(Color.Gray)
          .fontSize(30)
        Text('1')
          .backgroundColor(Color.Green)
          .fontSize(30)
        Text('2')
          .backgroundColor(Color.Orange)
          .fontSize(30)
        Text('3')
          .backgroundColor(Color.Pink)
          .fontSize(30)
      }
      .width('100%')
      .height('30%')
      .autoPlay(true)    // 开启自动播放
      .interval(2000)     // 自动切换间隔2000毫秒(2秒)
      .loop(true)         // 开启无限循环轮播
    }
  }
}

7. Tabs 标签页布局

排列规则：多页面切换容器，由Tabs（根容器）+ TabContent（单个标签页）组成，点击标签切换对应页面内容Huawei Developer。
核心属性
- barPosition(BarPosition.Start/End)：标签栏位置（Start顶部、End底部）；
- .tabBar("文字")：设置标签栏显示文字（低版本 SDK 建议直接传字符串，避免重载报错）。
典型场景：APP 顶部 / 底部导航（首页、分类、个人中心）、多模块内容切换。
组合用法：每个TabContent内部可嵌套Column/Row/Swiper等布局，实现复杂分页。

实例：

@Entry
@Component
struct TabBase1{
  build() {
    Tabs(){
      TabContent(){
        Text('首页页面')
          .fontSize(24)
      }
      .tabBar('首页')

      TabContent(){
        Text('分类页面')
          .fontSize(24)
      }
      .tabBar('分类')

      TabContent(){
        Text('个人中心页面')
          .fontSize(24)
      }
      .tabBar('个人中心')

      TabContent(){
        Text('关于我们页面')
          .fontSize(24)
      }
      .tabBar('关于我们')
    }
    .barPosition(BarPosition.Start)
  }
}

三、布局组合实战规则（文档案例提炼）

实际开发中单一布局无法满足需求，多采用布局嵌套，总结高频组合方案：

基础页面通用结构 外层Column（垂直排布整体内容）→ 内层嵌套Row（实现局部横向控件），适用于 90% 常规页面（信息页、表单页）。
头像 / 资料卡片 Row（左右排布）嵌套Stack（头像 + 角标）+ Column（文字信息），实现图文组合卡片。
标签页 + 轮播 Tabs作为根布局，每个TabContent内部嵌套Column + Swiper，实现 “多分页 + 每页轮播图”（如学校简介、系部简介页面）。
不规则复杂页面 根容器使用RelativeContainer，通过锚点精准摆放标题、按钮、图片等所有组件。
多标签流式布局 直接使用Flex并开启自动换行，快速实现标签、分类等自适应效果。

四、高频踩坑与规范总结

（一）语法规范

所有 UI 代码必须写在build()方法内，@Entry、@Component成对使用。
样式采用链式调用，属性可连续叠加（如Text().fontSize().fontColor()）。
动态数据渲染使用 `${this.变量名}` 语法，绑定组件内普通变量。

（二）资源引用规范

图片资源存放于 resources/base/media，引用格式：$r('app.media.文件名')，不带文件后缀；文件名仅允许字母、数字、下划线。

（三）布局报错规避

Tabs 的.tabBar：低版本 SDK 优先传入纯字符串，避免Text组件嵌套导致重载报错。
颜色设置：若Color.浅色系枚举失效，改用十六进制色值字符串（如#ADD8E6）。
RelativeContainer：每个子组件id必须唯一，alignRules的参照物 id 不能写错。

（四）布局选型速查表

需求场景	优先选择布局
上下排列文本、表单	Column
左右排列按钮、图标	Row
标签、分类（自动换行）	Flex
图片叠加文字、角标	Stack
组件精准自由定位	RelativeContainer
图片自动滑动播放	Swiper
多页面切换导航	Tabs

五、整体学习脉络梳理

入门阶段：掌握三大装饰器 + Column/Row 线性布局，完成基础文本、按钮排版；
进阶阶段：学习Flex/Stack，实现自适应、层叠效果，练习布局嵌套；
实战阶段：掌握RelativeContainer、Swiper、Tabs，开发轮播、标签导航、复杂不规则页面；
优化阶段：规范资源命名、规避语法报错，结合数据绑定完成完整业务页面。

人工智能6S服务平台

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

更多推荐

cover

【共创季稿事节】鸿蒙原生 ArkTS 布局深度解析：Stack + Transition 层叠元素入场动画实战

人工智能6S服务平台

cover

【共创季稿事节】鸿蒙原生ArkTS布局 — Grid网格布局入门

人工智能6S服务平台

cover

鸿蒙应用开发：ForEach 循环渲染用法详解

人工智能6S服务平台

所有评论(0)

查看更多评论

Wmh_1231

已为社区贡献3条内容