鸿蒙 ArkTS 实战全解：从基础布局到完整页面，核心组件与样式一篇通

本文为鸿蒙 ArkTS 入门系列第二篇，承接上篇《鸿蒙 ArkTS 学习入门》，从基础页面结构进阶到可落地的页面开发，覆盖鸿蒙开发中 90% 高频场景的核心组件、样式属性与布局技巧，新手友好，看完就能独立写出完整的基础交互页面。

开发环境：DevEco Studio，API 10 及以上

前置要求：了解 ArkTS 基础页面结构即可

前言

在上一篇入门教程里，我们带大家认识了 ArkTS 的标准页面结构、@Component/@Entry 装饰器、@State 响应式状态，以及最简单的 Text、Button 组件，很多同学看完之后反馈：

知道了基础的页面框架，但是不知道怎么写出好看、能用的页面？

图片怎么加载？样式怎么调？输入框怎么和数据绑定？

各种布局属性、样式属性太多了，不知道哪些是高频必学的？

这篇文章就专门解决这些问题，我们把鸿蒙 ArkUI 开发中核心高频的组件、布局技巧、样式属性全部梳理清楚，从容器布局到内容组件，从基础样式到进阶效果，附完整可运行的代码示例，还有新手最容易踩的坑，帮你从只会写 Hello World，进阶到能独立完成基础页面开发。

一、页面骨架：Column/Row 容器布局进阶

ArkUI 中，所有的页面内容都需要放在容器组件里排列，入门阶段我们已经认识了最核心的两个布局容器：

• Column：垂直布局，子组件从上到下依次排列
• Row：水平布局，子组件从左到右依次排列

这一节我们就把这两个容器的高频实用技巧全部讲透，掌握这些就能搞定绝大多数页面的排版需求。

1.1 快速设置子组件间距：space 属性

新手最常用的给组件加间距的方式，是给每个子组件加 margin，其实有更简洁高效的方式：直接在容器的括号里传入space参数，就能给所有子组件设置统一的间距，代码更整洁，维护更方便。

示例代码：

import { Column, Text, FlexAlign } from '@kit.ArkUI';

@Entry
@Component
struct SpaceDemo {
  build() {
    Column() {
      Text("垂直布局第一项")
      Text("垂直布局第二项")
      Text("垂直布局第三项")
    }
    .width('100%')
    .height(300)
    // 给所有子组件设置15vp的统一间距
    .space(15)
    .justifyContent(FlexAlign.Center)
  }
}

space属性同样适用于 Row 容器，仅需把 Column 换成 Row 即可。

1.2 子组件对齐与分布：justifyContent 属性

justifyContent是控制子组件在容器主轴方向的对齐与分布方式的核心属性，Column 的主轴是垂直方向，Row 的主轴是水平方向。

它接收FlexAlign类型的参数，常用值全解析：

属性值	效果说明	适用场景
FlexAlign.Start	左对齐 / 顶部对齐（默认值）	常规列表内容从上到下排列
FlexAlign.Center	水平居中 / 垂直居中	页面标题、登录表单居中展示
FlexAlign.End	右对齐 / 底部对齐	页面底部的操作按钮、右下角的悬浮按钮
FlexAlign.SpaceBetween	两端对齐，子组件之间间距均分	页面顶部的导航栏、左右分布的标题与操作按钮
FlexAlign.SpaceAround	子组件两侧间距相等，相邻组件间距叠加	均匀分布的卡片列表
FlexAlign.SpaceEvenly	所有间距完全相等，包括两端与组件之间	等距分布的图标按钮组

示例代码（最常用的居中 + 两端对齐）：

import { Column, Row, Text, Button, FlexAlign, FontWeight, Color } from '@kit.ArkUI';

@Entry
@Component
struct JustifyDemo {
  build() {
    Column() {
      // 两端对齐：标题在左，按钮在右
      Row() {
        Text("个人中心")
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
        Text("编辑资料")
          .fontSize(14)
          .fontColor(Color.Blue)
      }
      .width('90%')
      .justifyContent(FlexAlign.SpaceBetween)

      // 居中展示的按钮组
      Row() {
        Button("取消")
        Button("确认")
      }
      .width('90%')
      .space(20)
      .justifyContent(FlexAlign.Center)
      .margin({ top: 30 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .space(30)
  }
}

二、页面内容：三大核心基础组件全解析

搞定了页面的骨架，接下来就是填充内容的核心组件，这一节我们把开发中最高频的文本、图片、交互组件的全用法讲透，覆盖绝大多数场景的需求。

2.1 Text 文本组件：不止是显示文字

Text 是页面中最基础的文本展示组件，除了入门阶段的基础用法，我们还可以通过丰富的样式属性，实现各种文本效果，满足不同的业务需求。

高频样式属性全解析：

import { Column, Text, Color, FontWeight, TextOverflow, FlexAlign } from '@kit.ArkUI';

@Entry
@Component
struct TextDemo {
  build() {
    Column() {
      // 基础文本样式
      Text("ArkTS进阶实战")
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.Blue)
        .margin({ bottom: 20 })

      // 十六进制颜色+行高设置
      Text("这是一段设置了行高和自定义颜色的文本，适合用于页面的正文内容展示，提升阅读体验。")
        .fontSize(16)
        .fontColor('#ff333333')
        .lineHeight(28)
        .margin({ bottom: 20 })
        .width('90%')

      // 长文本溢出省略号效果
      Text("这是一段很长的文本，当文本内容超出了设置的最大行数时，就会自动显示省略号，非常适合用于列表项的标题、简介等场景。")
        .fontSize(16)
        .width('90%')
        .maxLines(2)
        .textOverflow({ overflow: TextOverflow.Ellipsis })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .space(15)
  }
}

新手避坑：textOverflow省略号效果必须配合maxLines属性一起使用，否则不会生效。

2.2 Image 图片组件：三种加载方式全覆盖

Image 是页面中用于展示图片的核心组件，支持本地资源、网络图片、SVG 图标三种加载方式，覆盖所有图片使用场景。

2.2.1 本地图片加载

这是最常用的加载方式，用于展示 App 内的固定图片、图标等资源。

• 资源存放路径：entry/src/main/resources/base/media 目录下
• 引用写法：Image($r('app.media.图片名'))
• 注意事项：图片名不能包含特殊字符、中文，不需要写文件后缀名

示例代码：

// 加载本地media目录下的avatar.png图片
Image($r('app.media.avatar'))
  .width(80)
  .height(80)
  .borderRadius(40)

2.2.2 网络图片加载

用于展示服务端返回的线上图片，直接传入图片的网络地址即可。

示例代码：

// 加载网络图片
Image('https://example.com/avatar.jpg')
  .width(80)
  .height(80)
  .borderRadius(40)

注意：加载网络图片需要在项目中配置网络权限，否则无法加载。

2.2.3 SVG 图标加载

SVG 图标是开发中非常推荐使用的图标格式，优势明显：任意放大缩小不会失真、可以修改颜色、文件体积更小。

• 来源：可以让设计师提供，也可以直接从华为官方图标库中选取（官方地址：https://developer.huawei.com/consumer/cn/design/harmonyos-icon/）
• 用法：和本地图片一致，放在 media 目录下，直接引用即可

2.3 交互组件：TextInput 输入框与 Button 按钮

入门阶段我们已经接触了基础的交互组件，这一节我们补充更多实用的进阶用法，满足表单、用户输入的需求。

2.3.1 TextInput 输入框

用于接收用户的文本输入，支持占位提示、输入类型限制、输入内容监听等功能，搭配 @State 可以实现数据双向同步。

示例代码：

import { Column, TextInput, Text, FlexAlign, InputType } from '@kit.ArkUI';

@Entry
@Component
struct InputDemo {
  @State inputValue: string = ""

  build() {
    Column() {
      TextInput({ placeholder: "请输入手机号" })
        .width('90%')
        .height(50)
        .borderRadius(8)
        .backgroundColor('#F5F5F5')
        .type(InputType.PhoneNumber)
        .onChange((value) => {
          this.inputValue = value
        })

      Text("您输入的内容：" + this.inputValue)
        .margin({ top: 20 })
        .fontSize(16)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .space(20)
  }
}

常用的输入类型InputType还有：Normal（普通文本）、Password（密码，隐藏输入内容）、Number（纯数字）等。

2.3.2 Button 按钮

按钮是页面中触发用户操作的核心入口，搭配onClick点击事件，就能实现各种业务逻辑，和 @State 配合可以实现页面状态的更新，基础用法在上一篇入门教程中已有详细讲解，这里不再赘述。

三、样式进阶：新手必学的高频样式属性

学会了组件的基础用法，接下来就是通过样式属性，把页面调得更美观、更符合设计规范，这一节我们把开发中最高频的样式属性全部梳理清楚，每个都附实用示例。

3.1 间距控制：padding 内边距与 margin 外边距

padding 和 margin 是控制组件间距的核心属性，很多新手会搞混两者的区别，这里一次性讲清楚：

• padding：组件的内边距，控制组件边框和内部内容之间的距离
• margin：组件的外边距，控制组件和其他组件之间的距离

两种常用写法：

1. 统一设置：padding(20)，给四个方向设置相同的间距
2. 分方向设置：padding({top: 10, right: 20, bottom: 10, left: 20})，给不同方向设置不同的间距

示例代码：

Text("带内边距的文本")
  .fontSize(16)
  .backgroundColor('#F5F5F5')
  .padding({ left: 15, right: 15, top: 8, bottom: 8 })
  .margin({ top: 20, bottom: 20 })

3.2 边框与圆角：border 与 borderRadius

边框和圆角是美化组件最常用的属性，能让页面的元素更有层次感，实现各种好看的效果。

3.2.1 border 边框属性

可以给组件设置边框的宽度、颜色、样式，支持统一设置和分方向设置。

示例代码：

Text("带边框的文本")
  .fontSize(16)
  .padding(15)
  .border({
    width: 1,
    color: '#E5E5E5',
    style: BorderStyle.Solid
  })
  .borderRadius(8)

3.2.2 borderRadius 圆角属性

用于设置组件四个角的圆润度，数值越大，角越圆。

• 实用技巧：当圆角数值设置为组件短边宽度的一半时，就能实现半圆 / 圆形效果。

示例代码：

// 圆形头像
Image($r('app.media.avatar'))
  .width(80)
  .height(80)
  .borderRadius(40)

// 两端半圆的圆角按钮
Button("圆角按钮")
  .width(200)
  .height(50)
  .borderRadius(25)

3.3 背景进阶：backgroundImage 背景图

除了纯色背景，我们还可以给组件设置背景图片，实现更丰富的视觉效果，支持设置背景图的位置、缩放、平铺方式。

示例代码：

Column() {
  Text("带背景图的容器")
    .fontSize(20)
    .fontColor(Color.White)
    .fontWeight(FontWeight.Bold)
}
.width('100%')
.height(200)
.backgroundImage($r('app.media.bg'), ImageRepeat.NoRepeat)
.backgroundImagePosition(Alignment.Center)
.backgroundImageSize(ImageSize.Cover)
.justifyContent(FlexAlign.Center)

常用的背景图缩放模式：

• ImageSize.Contain：图片完整显示，碰到容器边缘就停止缩放，不会裁剪图片
• ImageSize.Cover：图片全覆盖容器，保证容器被填满，多余部分会被裁剪，是背景图最常用的模式

四、新手避坑指南：这些错误 90% 的人都踩过

结合学习和开发经验，整理了新手在使用这些组件和样式时，最容易踩的坑，帮你少走弯路：

1. 本地图片加载失败？

   检查这三点：① 图片是否放在entry/src/main/resources/base/media目录下；② 图片名是否包含中文、特殊字符，是否正确书写（不需要加后缀）；③ 引用格式是否正确，必须是$r('app.media.文件名')

2. 文字溢出省略号不生效？

   必须同时设置两个属性：maxLines（限制最大行数）和textOverflow({ overflow: TextOverflow.Ellipsis })，缺一不可；同时要给 Text 组件设置固定宽度或百分比宽度，否则文本会无限撑开。

3. 圆角不生效 / 无法实现圆形？

   想要实现圆形，borderRadius的数值必须等于组件宽高的一半（宽高必须相等）；如果是矩形想要实现两端半圆，圆角数值等于组件高度的一半即可。

4. 颜色设置报错？

   使用Color.xxx枚举写法时，必须先从@kit.ArkUI中导入 Color；使用十六进制颜色时，必须用单引号 / 双引号包裹，格式为#ffxxxxxx（前两位是透明度，后六位是色值），也可以简写为#xxxxxx（默认不透明）。

5. 网络图片无法加载？

   必须在项目的module.json5文件中配置网络权限，同时确保设备 / 模拟器可以正常访问网络。

五、综合实战：个人信息卡片页面

接下来我们把前面学到的所有知识点整合起来，写一个完整的个人信息卡片页面，包含头像、用户信息、输入框、操作按钮，所有代码可直接复制运行。

完整代码：

import { Column, Row, Text, Image, TextInput, Button, Color, FontWeight, FlexAlign, HorizontalAlign } from '@kit.ArkUI';

@Entry
@Component
struct ProfileDemo {
  @State nickName: string = ""
  @State signature: string = ""

  build() {
    Column() {
      // 页面标题
      Text("个人信息")
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 40 })

      // 头像与用户名区域
      Row() {
        // 圆形头像
        Image($r('app.media.avatar'))
          .width(80)
          .height(80)
          .borderRadius(40)

        Column() {
          Text("请设置您的昵称")
            .fontSize(18)
            .fontWeight(FontWeight.Medium)
          Text("完善个人信息，获得更好的体验")
            .fontSize(14)
            .fontColor('#999999')
            .margin({ top: 5 })
        }
        .alignItems(HorizontalAlign.Start)
        .margin({ left: 20 })
      }
      .width('90%')
      .justifyContent(FlexAlign.Start)
      .margin({ bottom: 30 })

      // 昵称输入框
      TextInput({ placeholder: "请输入您的昵称" })
        .width('90%')
        .height(50)
        .borderRadius(8)
        .backgroundColor('#F5F5F5')
        .padding({ left: 15 })
        .onChange((value) => {
          this.nickName = value
        })

      // 个性签名输入框
      TextInput({ placeholder: "请输入您的个性签名" })
        .width('90%')
        .height(50)
        .borderRadius(8)
        .backgroundColor('#F5F5F5')
        .padding({ left: 15 })
        .margin({ top: 20 })
        .onChange((value) => {
          this.signature = value
        })

      // 保存按钮
      Button("保存信息")
        .width('90%')
        .height(50)
        .backgroundColor(Color.Blue)
        .borderRadius(25)
        .margin({ top: 40 })
        .onClick(() => {
          console.log("昵称：" + this.nickName + "，个性签名：" + this.signature)
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Start)
    .padding({ top: 50 })
    .space(15)
  }
}

六、学习总结

这篇文章我们从基础的容器布局，到核心的内容组件，再到高频的样式属性，完整覆盖了鸿蒙 ArkTS 开发中基础页面开发的所有核心知识点，相比入门篇，我们完成了全面的进阶拓展：

• 掌握了 Column/Row 容器的space、justifyContent进阶布局技巧，能实现复杂的页面排版
• 吃透了 Image 图片组件的三种加载方式，覆盖所有图片使用场景
• 学会了 Text 文本组件的进阶样式，包括行高、溢出省略号等高频实用效果
• 补充了 TextInput 输入框的输入类型限制、内容监听等进阶用法，能实现基础表单功能
• 掌握了边框、圆角、背景图、间距控制等高频样式属性，能写出符合设计规范的美观页面
• 整理了新手最容易踩的坑，帮你避开开发中的常见问题

掌握以上这些内容，你已经可以独立完成绝大多数鸿蒙基础页面的开发，从只会写 Hello World，进阶到能写出完整、美观、带交互的业务页面。

后续我们会继续更新 ArkTS 的进阶内容，包括列表组件、高级状态管理、路由跳转、网络请求等，带你一步步从鸿蒙新手，进阶到能独立完成完整 App 的开发。