一文就可搞清楚的 HarmonyOS NEXT 解锁模态页面的“真香”操作

2025-06-05
北京
本文字数：2212 字
阅读完需：约 7 分钟

0.前言

最近在搞考试 App 的 HarmonyOS NEXT 原生开发，卡在考试功能的答题卡显示上。一开始用弹框做答题卡，效果堪称“买家秀 vs 卖家秀”——丑到想给产品经理递辞职信（不是）。痛定思痛后，我发现了模态页面这个“神器”，简直打开新世界大门！今天就来和大家聊聊这玩意儿怎么玩～

1.模态页面：弹窗界的“变形金刚”🤖

想象一下：你正在打游戏（当前上下文），突然弹出一个任务面板（模态页面），既不挡住游戏画面，又能让你专注处理任务——这就是模态页面的魅力！

它是个“大面板交互式弹窗”，和普通弹窗最大的区别是内容全靠自定义，想塞多少东西塞多少（比如你的考试答题卡）。ArkUI 提供了两种形态：

半模态：非全屏弹窗，允许底层页面“露个脸”，适合做轻量级操作（比如选日期、填备注）。
全模态：霸道总裁式全屏覆盖，必须侧滑才能退出，适合需要沉浸式操作的场景（比如看超长答题卡）。

划重点：半模态支持侧滑、点蒙层、点关闭按钮退出，全模态默认只能侧滑——专治手残党误触！

2.半模态页面：温柔的“侧边小助手”👨💻

半模态就像你的贴心小秘书，不遮挡主界面，却能帮你快速完成任务。比如做个“纪念日管理”功能，选日期、写备注一气呵成～

生命周期：弹窗的“心跳记录”📅

半模态的一生很简单：

诞生前（onWillAppear）→ 登场（onAppear）→ 消失前（onWillDisappear）→ 退场（onDisappear）

就像舞台上的演员，每个阶段都有专属 BGM（回调函数），方便你随时“操控”它的状态～

代码实现：手把手教你搭一个“纪念日小助手”🚀

@Entry@Componentstruct Index {  // 定义页面是否显示的状态（是不是很像开关？）  @State isShow:boolean=false;  // 选中的日期：默认今天，防止用户选“明天考试”这种魔幻操作  @State selectedDate:Date=new Date();  // 备注信息：留空，等用户吐槽用  @State remark:string="";
  // 创建半模态页面的方法：就像搭积木，把组件堆起来  @Builder  createSheet() {    Column({ space: 10 }) { // 列布局，组件上下排，间距10px      Row({ space: 10 }) { // 行布局，组件左右排，间距10px        Text("纪念日：") // 标签，告诉用户这是选日期的地方        // 日历选择器：右边对齐，字体颜色骚气红，点击能选日期        CalendarPicker({ hintRadius: 10, selected: this.selectedDate })          .edgeAlign(CalendarAlign.END)          .textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } })          .margin(10)          .onChange((value) => { // 选完日期打印日志，方便debug            console.info("CalendarPicker onChange:" + JSON.stringify(value))          })      }      .margin({ top: 30 }) // 上边距30px，和上面的组件隔开      .width("90%") // 宽度占父容器90%，防止撑破屏幕
      Row() { // 备注输入框区域        Text("备注：") // 标签        TextInput({ placeholder: "请输入备注信息" }) // 输入框，提示用户“快写点什么”          .onChange(v => { // 输入内容实时更新到remark变量            this.remark = v          })      }      .width("90%") // 同样占90%宽度
      // 确认保存按钮：点击后弹Toast，关闭弹窗      Button("确认保存")        .width("80%") // 按钮窄一点，显得精致        .onClick(() => {          this.getUIContext().getPromptAction().showToast({            message: "纪念日：" + this.selectedDate.toDateString() + " 备注：" + this.remark          })          this.isShow = false; // 关闭弹窗，世界清净        })    }    .width("90%") // 整个半模态内容区占90%宽度    .padding(20) // 内边距20px，防止内容挤成一团  }
  // 主页面布局：一个按钮，点击打开半模态  build() {    Column({space:20}){      Text("半模态页面") // 标题，简单粗暴      Button("打开半模态页面") // 按钮，点击触发“开关”        .bindSheet($$this.isShow,this.createSheet,          {mode:SheetMode.EMBEDDED, detents: [SheetSize.MEDIUM, SheetSize.LARGE, 300]})        .onClick(()=>{ // 点击时把“开关”打开（isShow设为true）          this.isShow=true;        })    }    .height('100%') // 撑满屏幕高度    .width('100%') // 撑满屏幕宽度  }}