【共创季稿事节】鸿蒙原生 ArkTS 布局深度解析：Stack 实现圆角头像与角标

鸿蒙原生 ArkTS 布局深度解析：Stack 实现圆角头像与角标

一、前言

在移动应用开发中，圆形头像 + 在线状态角标是社交类、即时通讯类 App 中最常见的 UI 模式之一。微信、Telegram、Discord 等主流应用无一例外地采用了这一视觉范式。对于鸿蒙原生开发者而言，如何在 HarmonyOS NEXT 上使用 ArkTS 高效、优雅地实现这一布局，是掌握鸿蒙 UI 开发的第一道关卡。

本文将从一个完整的可运行示例出发，深入剖析Stack布局容器在圆角头像与角标场景下的三种实现方案，并详细讲解.borderRadius切圆、Badge组件内置角标、Circle手绘状态指示器、@Component子组件封装等核心技术。全文配以完整源码和中文注释，力求让读者「看得懂、学得会、用得顺」。

二、环境与工程配置

2.1 开发环境要求

2.2 工程结构

app6211/ ├── AppScope/ # 应用级配置 ├── entry/ │ └── src/main/ets/ │ ├── entryability/ # Ability 生命周期 │ └── pages/ │ └── Index.ets # ★ 核心页面（本文分析对象） ├── build-profile.json5 # 应用级构建配置 └── hvigor/ # 构建系统

在build-profile.json5中，我们配置了 SDK 版本为 API 24：

{ "app": { "products": [ { "targetSdkVersion": "6.2.0(24)", "compatibleSdkVersion": "6.2.0(24)", "runtimeOS": "HarmonyOS" } ] } }

三、核心布局组件概览

3.1 Stack — 层叠布局容器

Stack是 ArkUI 提供的层叠布局容器，其核心特点是：子组件按照在代码中的书写顺序从底向上依次堆叠，后声明的组件在 Z 轴上覆盖先声明的组件。

Z 轴方向（从上往下看） ┌─────────────────────┐ │ 顶层子组件（最后声明） │ ← Z-index 最高 ├─────────────────────┤ │ 中间层子组件 │ ├─────────────────────┤ │ 底层子组件（最先声明） │ ← Z-index 最低 └─────────────────────┘

Stack不限制子组件的数量，每个子组件可以通过以下方式定位：

• .position({ x, y })：相对于 Stack 左上角的绝对偏移
• .align(Alignment.xxx)：相对于 Stack 容器的对齐方式
• 默认居中：如果子组件未指定任何位置属性，默认在 Stack 中心

3.2 Badge — 系统内置角标组件

Badge是 HarmonyOS NEXT 内置的角标容器，专门用于在子元素右上角（或其他位置）显示小圆点或数字标记。它的构造参数如下：

3.3 Circle — 形状绘制组件

Circle()是 ArkUI 提供的原生形状组件，用于绘制圆形。与Image不同，它不依赖图片资源，完全由属性驱动渲染：

Circle().width(24)// 圆直径.height(24)// 圆直径.fill('#4CAF50')// 填充色.stroke('#FFFFFF')// 描边色.strokeWidth(3)// 描边宽度

这一特性使得Circle天然适合作为状态指示器 —— 轻量、高效、无网络请求。

四、三种实现方案详解

我们的示例代码Index.ets演示了三种递进式实现方案，覆盖从「开箱即用」到「完全自定义」的全场景需求。

方案一：Badge 组件内置角标（推荐）

适用场景：标准圆形头像 + 简单状态指示，追求开发效率。

Badge({value:'',// 空串 → 纯色圆点position:BadgePosition.RightTop,// 右上角style:{badgeSize:18,// 角标直径 18vpbadgeColor:'#4CAF50'// 在线绿色}}){Image($r('app.media.startIcon')).width(80).height(80).borderRadius(40)// 切圆：宽高的一半.objectFit(ImageFit.Cover).border({width:2,color:'#FFFFFF'})}

关键要点：

1. Badge作为容器包裹头像，自动在右上角叠加角标
2. .borderRadius(40)将 80×80 的正方形图片裁切成正圆 ——半径 = 宽/2
3. .objectFit(ImageFit.Cover)确保图片内容按比例填充，不留黑边
4. 白色描边.border({ width: 2, color: '#FFFFFF' })增加视觉层次感

扩展用法 —— 数字角标：

当value传入非空字符串（如'3'）时，Badge 自动切换为数字角标样式，适合展示未读消息数：

Badge({value:'3',// 显示数字position:BadgePosition.RightTop,style:{badgeSize:20,badgeColor:'#FF5722',// 红色 = 提醒fontSize:11,fontWeight:FontWeight.Bold}}){Image($r('app.media.startIcon')).width(64).height(64).borderRadius(32)}

方案二：纯 Stack 手动叠加角标（灵活控制）

适用场景：需要将角标放在任意位置（左上、左下、右下），或状态圆点有特殊样式需求。

Stack(){// 第1层（底层）：圆形头像Image($r('app.media.startIcon')).width(96).height(96).borderRadius(48).objectFit(ImageFit.Cover).border({width:2,color:'#FFFFFF'})// 第2层（顶层右下角）：在线状态圆点Circle().width(24).height(24).fill('#4CAF50').stroke('#FFFFFF').strokeWidth(3).position({x:72,y:72})// 96-24=72，右下角对齐}.width(96).height(96)

定位计算口诀：

position.x = 头像宽 - 圆点宽 position.y = 头像高 - 圆点高

将此公式推广到四个角落：

多状态演示：

在示例代码中，我们通过封装StatusAvatar子组件，一行代码即可展示不同状态：

Row({space:24}){StatusAvatar({avatarSize:56,statusColor:'#FFC107',dotSize:14,posX:0,posY:0})// 离开-黄StatusAvatar({avatarSize:56,statusColor:'#4CAF50',dotSize:14,posX:42,posY:0})// 在线-绿StatusAvatar({avatarSize:56,statusColor:'#9E9E9E',dotSize:14,posX:42,posY:42})// 离线-灰StatusAvatar({avatarSize:56,statusColor:'#F44336',dotSize:14,posX:0,posY:42})// 忙碌-红}

这种「颜色语义化」的设计模式，让代码意图一目了然，也便于后期维护和扩展。

方案三：大尺寸用户卡片（综合应用）

适用场景：个人主页、用户详情页，需要展示大尺寸头像 + 状态 + 姓名标签的综合信息卡片。

Stack(){// 底层：圆形头像 120×120Image($r('app.media.startIcon')).width(120).height(120).borderRadius(60).border({width:3,color:'#FFFFFF'})// 顶层右下角：状态圆点Circle().width(30).height(30).fill('#4CAF50').stroke('#FFFFFF').strokeWidth(4).position({x:90,y:90})// 顶层底部居中：半透明姓名标签Row(){Text('张三').fontSize(14).fontColor('#FFFFFF').fontWeight(FontWeight.Bold)}.width('100%').height(32).backgroundColor('#66000000')// 半透明黑底.justifyContent(FlexAlign.Center).align(Alignment.Bottom)// 贴在 Stack 底部}.width(120).height(120).borderRadius(12)

方案三的亮点：

1. 三层叠加：头像 → 状态圆点 → 姓名标签，全部在一个 Stack 内完成
2. 混合定位：状态圆点用.position()绝对定位，姓名标签用.align(Alignment.Bottom)相对定位
3. 半透明遮罩：#66000000是 40% 透明度的黑色，文字清晰可读

五、子组件封装与复用

为了提升代码的可维护性，示例将三个可复用 UI 单元抽取为独立的@Component：

5.1 TitleBar — 顶部标题栏

@Componentstruct TitleBar{build(){Row(){Text('📱 圆角头像 & 角标').fontSize(20).fontWeight(FontWeight.Bold).fontColor('#FFFFFF')}.width('100%').height(56).backgroundColor('#3F51B5').padding({left:20})}}

5.2 SectionTitle — 区块标题

@Componentstruct SectionTitle{@Proptitle:string='';@Propdesc:string='';build(){Column({space:4}){Text(this.title).fontSize(15).fontWeight(FontWeight.Bold).fontColor('#333')Text(this.desc).fontSize(12).fontColor('#999')}.alignItems(HorizontalAlign.Start).width('100%').margin({top:8})}}

5.3 StatusAvatar — 可复用头像+角标（核心组件）

@Componentstruct StatusAvatar{@PropavatarSize:number=56;@PropstatusColor:string='#4CAF50';@PropdotSize:number=14;@PropposX:number=42;@PropposY:number=42;build(){Stack(){Image($r('app.media.startIcon')).width(this.avatarSize).height(this.avatarSize).borderRadius(this.avatarSize/2)// 动态切圆.objectFit(ImageFit.Cover).border({width:2,color:'#FFFFFF'})Circle().width(this.dotSize).height(this.dotSize).fill(this.statusColor).stroke('#FFFFFF').strokeWidth(2).position({x:this.posX,y:this.posY})}.width(this.avatarSize).height(this.avatarSize)}}

封装价值：

• 一次定义，多处复用 —— 仅需一行<StatusAvatar {...} />即可创建完整的头像组件
• 参数化驱动 ——avatarSize、statusColor、dotSize、posX、posY五个参数覆盖所有常见变体
• 零外部依赖 —— 不依赖任何图片资源以外的外部模块，可直接放入任何项目使用

六、布局要点总结

回顾整个实现过程，以下是经过实战检验的五点核心经验：

6.1 Stack 是层叠容器，子组件从底向上堆叠

Stack的行为可以理解为「后入者在 Z 轴上越靠前」。这一特性让它在实现「叠加效果」时无需任何 z-index 或 elevation 设置，天然适合头像+角标、卡片+遮罩、图片+文字标签等场景。

6.2 .borderRadius 切圆的数学公式

将正方形图片切成正圆，半径公式非常简单：

.borderRadius(图片宽度 / 2)

对于 80×80 的图片 →.borderRadius(40)
对于 96×96 的图片 →.borderRadius(48)
对于 120×120 的图片 →.borderRadius(60)

6.3 Badge 组件适合标准场景

如果角标只需要在右上角展示纯色圆点或数字，优先使用Badge组件。它是系统级实现，经过充分优化，代码量最少，无需手动计算偏移。

6.4 Stack + .position 手动定位适合复杂场景

当角标需要在任意位置出现（左上、左下、右下、甚至中心），或状态圆点有自定义动画、渐变等特殊需求时，使用Stack + Circle + .position方案更灵活。

6.5 Circle 是轻量级状态指示器

Circle()不涉及图片加载、解码、缓存，性能远优于同等尺寸的Image。配合.fill和.stroke，可以绘制出任意颜色、任意描边效果的圆点，非常适合作为在线/离开/离线/忙碌等状态指示器。

七、性能优化建议

7.1 图片资源管理

• 头像图片建议使用WebP格式，体积比 PNG 小 25%~35%
• 在Image上设置.objectFit(ImageFit.Cover)可以避免图片变形
• 对于列表中的大量头像，考虑使用LazyForEach+ 内存缓存

7.2 避免不必要的重绘

• 角标颜色、位置等属性应使用@Prop而非@State传入子组件，减少状态管理开销
• 如果角标状态频繁变化（如在线/离线切换），使用@Watch监听状态变化而非每秒重建 UI

7.3 Stack 的嵌套深度

• 避免 Stack 多层嵌套（超过 5 层），过深的嵌套会影响布局计算性能
• 本示例中每个头像的 Stack 深度仅为 2 层（外层 Stack + 头像/圆点），这是最优深度

八、适用场景扩展

本文所介绍的技术不局限于头像角标，以下场景同样适用：

九、完整源码

完整的Index.ets源码已上传至项目entry/src/main/ets/pages/目录。核心代码约 273 行，包含：

• 1 个主页面@Component
• 3 个可复用子组件
• 3 套布局方案
• 详尽的中文注释

使用 DevEco Studio 打开项目后直接运行即可看到效果。页面支持滚动浏览全部三种方案及布局要点总结。

十、结语

通过本文的深入剖析，我们从「Stack 层叠布局」出发，逐步深入到 Badge 组件、Circle 形状绘制、@Component 组件化封装等 HarmonyOS NEXT 原生 ArkTS 核心技术。这不仅仅是关于「如何画一个圆角头像」的教程，更是一次关于鸿蒙原生声明式 UI 设计哲学的实践。

在鸿蒙生态快速发展的今天，掌握这些基础但强大的布局能力，是每一位鸿蒙开发者构建高品质用户体验的基石。希望本文能为你的鸿蒙开发之旅提供实实在在的帮助。