鸿蒙 ArkUI 布局与基础语法综合总结-深圳市維司達科技有限公司

一、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