【共创季稿事节】鸿蒙原生 ArkTS 布局方式入门：Stack 堆叠布局 — 层叠式排列的核心概念

鸿蒙原生 ArkTS 布局方式入门Stack 堆叠布局 — 层叠式排列的核心概念一、引言在鸿蒙原生应用开发中布局是 UI 最核心的能力。ArkUI 的Column、Row、Flex、RelativeContainer各有所长而本文的主角Stack堆叠布局是其中唯一天然支持Z 轴层叠的容器。Stack 在 Android 对应FrameLayout在 Flutter 对应Stack在 Web 对应position: absoluterelative。它的核心思想极简子组件按添加顺序从下往上依次叠放——先添加的在底层Z 值小后添加的在上层Z 值大。应用场景非常广泛头像右上角叠加未读红点、商品图片左上角显示热卖标签、卡片底部叠加半透明遮罩、多个头像部分重叠形成群组、页面顶层覆盖加载动画屏蔽层。没有掌握 Stack就不算真正掌握了鸿蒙 UI 开发。二、Stack 布局核心概念2.1 什么是 StackStack是 ArkUI 内置容器组件无需 import可直接使用。它让子组件在Z 轴方向上层叠排列。与Column纵向和Row横向不同Stack 的所有子组件占据同一平面空间通过前后叠放构建 UI 层次。布局容器排列方向生活类比ColumnY 轴垂直书架上的书从上到下RowX 轴水平餐桌上的餐具从左到右StackZ 轴深度桌面上叠放的纸张2.2 Z 轴层叠机制Stack 的规则极其简单先添加的在底层后添加的在上层。Z 轴方向越往上越靠前 ↑ ┌────────────────────┐ ← 第3层Text最上层 │ Z3顶层 │ └────────────────────┘ ┌────────────────────┐ ← 第2层绿色矩形中层 │ Z2中层 │ └────────────────────┘ ┌────────────────────┐ ← 第1层蓝色矩形底层 │ Z1底层 │ └────────────────────┘这个顺序不可逆——无法在运行时动态调整某个子项的 Z 轴顺序除非重新排列代码中的添加顺序。因此编码时建议按底层 → 中层 → 顶层顺序编写子组件。2.3 API 24 的注意事项对齐枚举统一为AlignmentStackAlign已废弃使用Alignment枚举性能优化子组件超过 10 个时布局计算性能提升约 30%嵌套稳定性多层 Stack 嵌套的尺寸溢出问题已修复三、Stack 基本用法3.1 最简单的 StackEntryComponentstruct SimpleStack{build(){Stack(){// 子组件在此层叠}.width(100%).height(100%)}}Stack是 ArkUI 的全局内置类型无需 import 声明。3.2 alignContent 参数构造函数接受可选的alignContent控制所有子组件的默认对齐方式Stack({alignContent:Alignment.Center}){// 所有子组件默认居中对齐}不指定时默认值为Alignment.Center。Alignment共 9 个取值对齐值说明TopStart/Top/TopEnd左上 / 顶部居中 / 右上Start/Center/End左中 / 居中 / 右中BottomStart/Bottom/BottomEnd左下 / 底部居中 / 右下3.3 尺寸行为要点无子组件时 Stack 尺寸为 0×0子组件全部固定尺寸时Stack 自适应到最大子组件的尺寸子组件使用百分比如width(100%)时Stack必须有固定尺寸最佳实践始终为 Stack 显式设置width和height四、alignContent 动态切换使用State动态切换 9 种对齐方式直观感受每种模式的效果StatecurrentAlignIndex:number0;privatealignOptions:Alignment[][Alignment.TopStart,Alignment.Top,Alignment.TopEnd,Alignment.Start,Alignment.Center,Alignment.End,Alignment.BottomStart,Alignment.Bottom,Alignment.BottomEnd,];Stack({alignContent:this.alignOptions[this.currentAlignIndex]}){Rect().fill(#22000000).width(100%).height(100%);Rect().width(60).height(60).fill(#FFE74C3C);Rect().width(50).height(50).fill(#FF3498DB);Rect().width(40).height(40).fill(#FF2ECC71);}观察要点TopStart时三方块吸到左上角Center时叠在正中间BottomEnd时移向右下角。alignContent是全局设置同时影响所有子组件。如需单独控制某个子项用.position()或.margin()。五、实战示例详解5.1 Z 轴层叠顺序演示三个不同颜色、尺寸的矩形从下往上叠放直观展示 Z 轴层级Stack({alignContent:Alignment.Center}){// 第1层最底层蓝色最大矩形Rect().width(240).height(200).fill(#FF4A90D9).radiusWidth(12);// 第2层中层绿色中等矩形Rect().width(180).height(150).fill(#FF50C878).radiusWidth(12);// 第3层最顶层白色文字Text(Z3 (最顶层)).fontSize(14).fontColor(Color.White);}.width(240).height(200);效果三层矩形层层嵌套蓝色边缘露出约 30px绿色露出约 15px。底层尺寸决定容器尺寸中层和顶层只需关注自身尺寸。若三层尺寸相同则完全覆盖需要用opacity才能看到下层。5.2 角标/徽标叠加Badge这是 Stack 最经典的应用——在图标右上角叠加红色未读数Stack({alignContent:Alignment.TopStart}){// 底层消息图标Circle().width(80).height(80).fill(#FFEEEEEE).stroke(#FFCCCCCC).strokeWidth(2);// 信封符号Text(✉).fontSize(32).fontColor(#FF666666).alignRules({center:{anchor:__container__,align:VerticalAlign.Center},middle:{anchor:__container__,align:HorizontalAlign.Center}});// 顶层红色角标Stack({alignContent:Alignment.Center}){Circle().width(26).height(26).fill(#FFE74C3C);Text(3).fontSize(12).fontColor(Color.White).fontWeight(FontWeight.Bold);}.position({x:58,y:-6});// ★ 绝对定位到右上角}.width(80).height(80);原理这是一个二级 Stack 嵌套。外层 Stack 为TopStart对齐内层角标通过.position({ x: 58, y: -6 })偏移到右上角。X 偏移 图标宽(80) - 角标宽(26) 露出量(4) 58。若需角标在左下角将外层改为BottomStart并调整坐标即可。5.3 头像堆叠排列群组场景多个头像部分重叠形成群组效果常用于xxx 等 N 人赞了Stack({alignContent:Alignment.Start}){// 头像 1 — 最左侧Circle().width(48).height(48).fill(#FFE74C3C).stroke(Color.White).strokeWidth(3);// 头像 2 — 右移 30px重叠 18pxCircle().width(48).height(48).fill(#FF3498DB).stroke(Color.White).strokeWidth(3).margin({left:30});// 头像 3 — 右移 60pxCircle().width(48).height(48).fill(#FF2ECC71).stroke(Color.White).strokeWidth(3).margin({left:60});// N 提示Circle().width(48).height(48).fill(#FF999999).stroke(Color.White).strokeWidth(3).margin({left:90});Text(3).fontSize(14).fontColor(Color.White).fontWeight(FontWeight.Bold).margin({left:90});}.width(100%).height(56).padding({left:10});技巧使用Alignment.Start左对齐通过递增的.margin({ left: N })让每个头像逐步偏移。重叠量 18px约头像宽度的 37.5%在视觉上最舒适。实际项目中可用ForEach循环渲染并用index * overlapOffset计算偏移量。5.4 卡片阴影叠加层通过 Stack 叠加一个偏移的阴影层实现比.shadow()更丰富的视觉效果Stack({alignContent:Alignment.Center}){// 阴影层半透明黑色 向右下偏移Rect().width(260).height(100).fill(#22000000).radiusWidth(12).translate({x:4,y:4});// 主卡片白色 系统阴影Rect().width(260).height(100).fill(Color.White).radiusWidth(12).shadow({radius:8,color:#33000000,offsetY:4});// 卡片内容Column({space:4}){Text(卡片标题).fontSize(16).fontWeight(FontWeight.Bold);Text(卡片正文内容展示 Stack 布局的典型应用场景。).fontSize(13).fontColor(#FF888888);}.alignItems(HorizontalAlign.Start).padding({left:16,right:16});}.width(260).height(100);两层阴影原理底层半透明矩形用translate偏移 4px 模拟投影上层主卡片用shadow提供柔和边缘阴影。调整translate方向即可控制阴影出现在右下、正下或左下。5.5 加载遮罩层页面加载时在内容上方显示遮罩 加载动画Stack(){// 底层页面内容Column(){/* 列表、卡片等 */}.width(100%).height(100%);// 顶层遮罩 加载动画通过状态变量控制显示if(this.isLoading){Column(){LoadingProgress().width(40).height(40).color(Color.White);Text(加载中...).fontSize(14).fontColor(Color.White).margin({top:12});}.width(100%).height(100%).backgroundColor(#66000000)// 40% 透明度黑色遮罩.justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center);}}要点用if条件渲染控制遮罩显示/隐藏40% 透明度黑色既能屏蔽操作又能让下层隐约可见。六、子组件定位方式对比Stack 提供四种定位方式方式作用域适用场景alignContent全局所有子组件统一对齐如全部居中.margin()单个子组件头像堆叠等逐个偏移.position()单个子组件角标等精确定位.alignRules()单个子组件锚点对齐类似 RelativeContainer七、最佳实践与避坑指南7.1 适合 vs 不适合✅ 适合角标 / 头像堆叠 / 卡片阴影 / 加载遮罩 / 图片标签 / FAB 按钮 / 全屏加载动画❌ 不适合列表布局用 List/ 简单纵向排列用 Column/ 简单横向排列用 Row/ 自适应换行用 FlexWrap7.2 常见错误错误原因解决子组件显示不全Stack 尺寸太小显式设置 width/height百分比尺寸无效Stack 无固定尺寸给 Stack 设固定尺寸角标位置不对对齐方式不符预期检查外层 alignContent子组件全不可见尺寸均为 0至少一个子组件设固定尺寸import Stack 报错误以为需 importStack 是内置组件无需 import7.3 性能建议单个 Stack 子组件建议不超过 10 个嵌套不超过 3 层非永久显示的组件用if条件渲染替代.visibility()优先用.margin()而不是.position()八、Stack 与其他布局对比特性StackColumnRowRelativeContainer排列方向Z 轴层叠Y 轴垂直X 轴水平锚点相对子组件重叠✅ 是❌ 否❌ 否✅ 是position 定位✅⚠️ 有限⚠️ 有限❌ 不支持alignRules✅❌❌✅ 原生支持层叠效果✅ 最佳❌❌⚠️ 可实现选择建议90% 场景用ColumnRow需层叠用Stack需精细锚点用RelativeContainer需弹性布局用Flex。九、总结本文从 Stack 布局的核心——Z 轴层叠机制出发通过 5 个实战示例全面讲解了 Stack 在鸿蒙原生 ArkTS 开发中的用法。核心要点Z 轴层叠子组件按添加顺序从下往上叠放先添加的在底层对齐控制alignContent共 9 种取值Alignment枚举全局控制定位方式全局alignContent、子级.margin()、子级.position()、锚点alignRules()实战场景角标叠加、头像堆叠、阴影层、遮罩层——覆盖 90% 的 Stack 使用场景API 24使用Alignment枚举Stack 为内置组件无需 importStack 是 ArkUI 布局体系中四两拨千斤的存在——语法极简应用极广。掌握 Stack你的鸿蒙应用 UI 表达能力将提升一个台阶。