HarmonyOS ArkTS Stack 实战：做一个“悬浮按钮 + 遮罩弹层 + 底部菜单”的完整小项目

HarmonyOS ArkTS Stack 实战：做一个"悬浮按钮 + 遮罩弹层 + 底部菜单"的完整小项目

鸿蒙第四期开发者活动

你学 Stack 的时候，最容易卡在一句话： "Stack 就是叠在一起。"------听懂了，但真写页面时还是不知道怎么落地。

我这次直接用一个小项目把 Stack 的典型用法串起来：背景叠字、角标、悬浮按钮、遮罩、防穿透、底部弹出菜单，全都在一个页面里。你跑起来后，基本就能把 Stack 用顺手。

---

1）这个 Demo 最终长什么样

页面结构大概是这样（你可以脑补成三层）：

• 第 1 层：页面内容 顶部封面图 + 渐变遮罩 + 标题；中间是"叠层卡片"
• 第 2 层：遮罩 点击 FAB 后出现的半透明黑色遮罩，点一下就关闭
• 第 3 层：弹层 一个底部弹出菜单（像很多 App 的"快捷操作"那种）

右下角有个 悬浮按钮（FAB） ，永远浮在最上面。

---

2）为什么这个 Demo 一定要用 Stack？

因为它同时包含了 Stack 的 3 种"高频真实用途"：

0. 背景 + 前景（叠字） 比如封面图上叠标题、叠渐变遮罩
1. 覆盖层（遮罩 / 弹窗 / 菜单） 这是 Stack 的老本行
2. 层级控制（zIndex） 不管你写得多漂亮，层级没控制好就是"按钮点不到 / 菜单被盖住"

---

3）项目结构（建议这么放）

 entry/src/main/ets/
   entryability/EntryAbility.ets
   pages/StackDemoPage.ets
   components/FabMenu.ets
   components/StackCards.ets

你也可以不拆文件，但拆开后更像真实项目： 页面负责组合，组件负责细节。

---

4）入口：EntryAbility.ets（确保能打开 StackDemoPage）

你如果是默认工程，有可能已经在这里 loadContent 了。 只要确保打开的是 pages/StackDemoPage 就行。

 // entry/src/main/ets/entryability/EntryAbility.ets
 import UIAbility from '@ohos.app.ability.UIAbility';
 import window from '@ohos.window';
 ​
 export default class EntryAbility extends UIAbility {
   onWindowStageCreate(windowStage: window.WindowStage) {
     windowStage.loadContent('pages/StackDemoPage', (err) => {
       if (err) {
         console.error('loadContent failed: ' + JSON.stringify(err));
       }
     });
   }
 }

---

5）主页面：StackDemoPage.ets（核心就在这里）

我习惯把页面写成一个"大 Stack"，原因很简单： 我想把整个页面当成一个舞台 ------ 内容、遮罩、弹层、悬浮按钮都在一个舞台里叠起来。

主页面代码

 // entry/src/main/ets/pages/StackDemoPage.ets
 import { FabMenu } from '../components/FabMenu';
 import { StackCards } from '../components/StackCards';
 ​
 @Entry
 @Component
 struct StackDemoPage {
   @State private menuOpen: boolean = false;
 ​
   build() {
     // 整个页面：一个大 Stack 负责"叠图层"
     Stack({ alignContent: Alignment.TopStart }) {
 ​
       // ========== A. 第 1 层：页面内容 ==========
       Column() {
         // 顶部：封面图 + 渐变遮罩 + 标题（这块就是 Stack 的经典用法）
         Stack({ alignContent: Alignment.BottomStart }) {
           // 1）封面图
           Image($r('app.media.icon'))
             .width('100%')
             .height(220)
             .objectFit(ImageFit.Cover);
 ​
           // 2）渐变遮罩（让白字在图上更清楚）
           Rect()
             .width('100%')
             .height(220)
             .fill(Color.Transparent)
             .linearGradient({
               angle: 180,
               colors: [[0x00000000, 0.0], [0xAA000000, 1.0]]
             });
 ​
           // 3）标题文字
           Column({ space: 6 }) {
             Text('Stack 实战：浮层 + 菜单 + 徽标')
               .fontSize(22)
               .fontColor(Color.White)
               .fontWeight(FontWeight.Bold);
             Text('点击右下角按钮，体验遮罩与弹出面板')
               .fontSize(13)
               .fontColor(0xE6FFFFFF);
           }
           .padding({ left: 16, right: 16, bottom: 16 });
         }
 ​
         // 中间内容：叠层卡片
         Column({ space: 14 }) {
           Text('层叠卡片示例')
             .fontSize(16)
             .fontWeight(FontWeight.Medium)
             .padding({ left: 16, top: 12 });
 ​
           StackCards()
 ​
           Text('Stack 更像"图层容器"：背景、遮罩、角标、弹窗都靠它。')
             .fontSize(13)
             .fontColor(0x99000000)
             .padding({ left: 16, right: 16, top: 10 });
 ​
           // 留一点底部空间，让 FAB 不挡内容
           Blank().height(120);
         }
         .width('100%');
       }
       .width('100%')
       .height('100%')
       .backgroundColor(0xFFF5F6F8);
 ​
       // ========== B. 第 2 层：遮罩（只在打开菜单时出现） ==========
       if (this.menuOpen) {
         // 遮罩一定要覆盖全屏，而且要能点击关闭
         Rect()
           .width('100%')
           .height('100%')
           .fill(0x66000000)
           .onClick(() => this.menuOpen = false)
           .zIndex(10);
       }
 ​
       // ========== C. 第 3 层：底部弹出菜单 ==========
       FabMenu({
         open: this.menuOpen,
         onClose: () => (this.menuOpen = false),
         onAction: (name: string) => {
           console.info('action: ' + name);
           this.menuOpen = false;
         }
       })
         .zIndex(20);
 ​
       // ========== D. 永远在最上层：悬浮按钮（FAB） ==========
       Stack({ alignContent: Alignment.Center }) {
         // 外圈：白底 + 阴影（看起来更"浮"）
         Circle()
           .width(58)
           .height(58)
           .fill(0xFFFFFFFF)
           .shadow({ radius: 18, color: 0x33000000, offsetX: 0, offsetY: 6 });
 ​
         // 内圈：主色
         Circle()
           .width(50)
           .height(50)
           .fill(0xFF1677FF);
 ​
         Text('+')
           .fontSize(26)
           .fontColor(Color.White)
           .fontWeight(FontWeight.Bold);
       }
       // position：把它钉到右下角附近
       .position({ x: '82%', y: '84%' })
       .onClick(() => this.menuOpen = !this.menuOpen)
       .zIndex(30);
     }
     .width('100%')
     .height('100%');
   }
 }

---

6）叠层卡片：StackCards.ets（用 translate + zIndex 做"层次感"）

这一块我想表达的是： Stack 不只是"盖住"，它还能做视觉层次（卡片叠层、影子叠层）。

写法要点：

• 底层卡：略往下偏移一点
• 中间卡：再往上一点
• 顶层卡：最完整，还带一个角标（角标就是 Stack 叠出来的）

 // entry/src/main/ets/components/StackCards.ets
 @Component
 export struct StackCards {
   build() {
     Stack({ alignContent: Alignment.Center }) {
 ​
       this.card('基础层：背景卡片', 0xFFE9EEF7)
         .translate({ x: 0, y: 14 })
         .zIndex(1);
 ​
       this.card('中间层：信息卡片', 0xFFFFFFFF)
         .translate({ x: 0, y: 6 })
         .zIndex(2);
 ​
       // 顶层卡：再套一层 Stack 用来叠角标
       Stack({ alignContent: Alignment.TopEnd }) {
         this.card('顶层：带角标 / 徽标', 0xFFFFFFFF);
 ​
         Row({ space: 6 }) {
           Circle().width(8).height(8).fill(0xFFFF3B30);
           Text('NEW')
             .fontSize(12)
             .fontColor(Color.White)
             .fontWeight(FontWeight.Medium);
         }
         .padding({ left: 10, right: 10, top: 6, bottom: 6 })
         .backgroundColor(0xFFFF3B30)
         .borderRadius(999)
         .margin({ top: 10, right: 10 });
       }
       .zIndex(3);
     }
     .height(210)
     .padding({ left: 16, right: 16 });
   }
 ​
   private card(title: string, bg: number) {
     return Column({ space: 10 }) {
       Text(title).fontSize(15).fontWeight(FontWeight.Medium);
       Text('这张卡片用 Stack 叠在其他卡片上，通过 translate 做出层次感。')
         .fontSize(12)
         .fontColor(0x99000000)
         .maxLines(2);
 ​
       Row({ space: 10 }) {
         this.tag('Stack');
         this.tag('zIndex');
         this.tag('translate');
       }
     }
     .padding(16)
     .width('100%')
     .height(160)
     .backgroundColor(bg)
     .borderRadius(16)
     .shadow({ radius: 14, color: 0x22000000, offsetX: 0, offsetY: 6 });
   }
 ​
   private tag(text: string) {
     return Text(text)
       .fontSize(11)
       .fontColor(0xFF1677FF)
       .padding({ left: 10, right: 10, top: 4, bottom: 4 })
       .backgroundColor(0xFFEAF2FF)
       .borderRadius(999);
   }
 }

---

7）底部弹出菜单：FabMenu.ets（弹层本质就是"在最上面叠一个面板"）

这里我写得比较"项目味"一点：

• 菜单是一个 Column 卡片
• 位置在底部（用 Stack 的 Alignment.BottomCenter）
• 每个菜单项都是 Row
• 点击菜单项回调给页面
• 点击"关闭"或点遮罩关闭

 // entry/src/main/ets/components/FabMenu.ets
 @Component
 export struct FabMenu {
   open: boolean = false;
   onClose?: () => void;
   onAction?: (name: string) => void;
 ​
   build() {
     Stack({ alignContent: Alignment.BottomCenter }) {
       if (this.open) {
         Column({ space: 12 }) {
           Row() {
             Text('快捷操作').fontSize(16).fontWeight(FontWeight.Medium);
             Blank();
             Text('关闭')
               .fontSize(13)
               .fontColor(0xFF1677FF)
               .onClick(() => this.onClose?.());
           }
           .width('100%');
 ​
           this.actionItem('新建笔记', 'create_note');
           this.actionItem('扫描二维码', 'scan_qr');
           this.actionItem('分享当前页', 'share');
 ​
           Divider().strokeWidth(1).color(0x11000000).margin({ top: 4, bottom: 2 });
 ​
           this.actionItem('设置', 'settings');
         }
         .width('92%')
         .padding(16)
         .backgroundColor(0xFFFFFFFF)
         .borderRadius(18)
         .shadow({ radius: 24, color: 0x22000000, offsetX: 0, offsetY: 8 })
         .margin({ bottom: 18 });
       }
     }
     .width('100%')
     .height('100%');
   }
 ​
   private actionItem(title: string, name: string) {
     return Row({ space: 12 }) {
       Circle().width(34).height(34).fill(0xFFEAF2FF);
       Text(title).fontSize(14);
       Blank();
       Text('>').fontSize(14).fontColor(0x66000000);
     }
     .width('100%')
     .padding({ top: 10, bottom: 10, left: 8, right: 8 })
     .borderRadius(12)
     .backgroundColor(0xFFF8FAFF)
     .onClick(() => this.onAction?.(name));
   }
 }

---

8）我写 Stack 弹层时最在意的 3 个细节（很容易踩坑）

① 层级要清楚：遮罩、弹层、FAB 谁在上？

我一般会固定一个习惯：

• 遮罩 zIndex(10)
• 弹层 zIndex(20)
• FAB zIndex(30)

这样你永远不会遇到"按钮被盖住点不到"的问题。

② 遮罩要"吃掉点击"

你不吃掉点击，用户点在遮罩上就会穿透点到下面页面（体验很糟）。 所以遮罩必须 onClick(()=>close)。

③ 弹层不要写死位置太死

我这里用 BottomCenter + margin(bottom)，比用绝对坐标稳一点。 你要做多设备适配时会省很多事。

---

9）你可以怎么把这个 Demo 改成你的项目组件

• 把 FabMenu 做成通用组件：传入 items 数组就能渲染菜单
• 把 FAB 的 position 改成"跟随屏幕尺寸计算"，适配更好
• 把弹层换成"半屏卡片 + 拖拽下滑关闭"（更像系统交互）