HarmonyOS ArkUI 弹窗系统：Toast、Dialog、ActionSheet 完全指南

前言

用户完成操作后，需要及时的反馈——保存成功、网络错误、删除确认……这些交互场景都需要弹窗组件。本项目在GasStationPage.ets中就使用了getPromptAction().showToast()来提示"敬请期待"。

本篇覆盖 HarmonyOS ArkUI 的所有弹窗类型，从最简单的 Toast 到复杂的自定义 Dialog，带你掌握交互反馈的全套方案。

一、Toast：轻量级消息提示

1.1 基础用法

// 方式1：通过 UIContext 获取 PromptAction（推荐）this.getUIContext().getPromptAction().showToast({message:'操作成功！',duration:2000,// 显示时长（毫秒），默认1500ms，范围1500~10000ms});// 方式2：通过 promptAction 模块（需要 import）import{promptAction}from'@kit.ArkUI';promptAction.showToast({message:'Hello Toast!'});

1.2 本项目中的 Toast

// GasStationPage.ets.onClick(()=>{if(gasStation){this.openOrCloseMap(true);this.moveToGasStation(gasStation.latitude,gasStation.longitude);}else{// 数据为空时显示 Toastthis.getUIContext().getPromptAction().showToast({message:$r('app.string.Stay_tuned')// 使用资源字符串});}})

1.3 Toast 完整配置

this.getUIContext().getPromptAction().showToast({message:'这是一条提示信息',// 必填：提示内容duration:2000,// 显示时长（ms）bottom:'200px',// 距底部的距离（可选）showMode:promptAction.ToastShowMode.TOP_MOST,// 显示模式alignment:Alignment.Bottom,// 对齐方式offset:{dx:0,dy:-50}// 偏移量});

1.4 封装一个通用 Toast 工具

// ToastUtil.etsimport{promptAction}from'@kit.ArkUI';exportclassToastUtil{staticsuccess(message:string):void{promptAction.showToast({message:`✅${message}`,duration:2000});}staticerror(message:string):void{promptAction.showToast({message:`❌${message}`,duration:3000});}staticinfo(message:string):void{promptAction.showToast({message:`ℹ️${message}`,duration:2000});}staticwarning(message:string):void{promptAction.showToast({message:`⚠️${message}`,duration:2500});}}// 使用ToastUtil.success('保存成功');ToastUtil.error('网络连接失败，请重试');

二、AlertDialog：确认对话框

2.1 单按钮对话框

AlertDialog.show({title:'提示',message:'操作成功！',autoCancel:true,// 点击遮罩层是否关闭confirm:{value:'确定',action:()=>{console.log('用户点击了确定');}}});

2.2 双按钮（确认/取消）

AlertDialog.show({title:'删除确认',message:'确定要删除这条加油记录吗？此操作不可撤销。',autoCancel:false,// 点击遮罩不关闭（强制选择）primaryButton:{value:'取消',fontColor:'#666666',action:()=>{console.log('取消删除');}},secondaryButton:{value:'删除',fontColor:'#FF4D4F',// 危险操作用红色action:()=>{console.log('确认删除');this.deleteRecord();}}});

2.3 通过 PromptAction 的 showDialog

// 更灵活的方式：支持多个按钮this.getUIContext().getPromptAction().showDialog({title:'选择定位方式',message:'请选择获取位置的方式',buttons:[{text:'GPS高精度',color:'#1A6FF5'},{text:'网络定位',color:'#52C41A'},{text:'取消',color:'#999999'}]}).then(result=>{switch(result.index){case0:console.log('选择了GPS');break;case1:console.log('选择了网络定位');break;case2:console.log('取消');break;}});

三、自定义 Dialog（CustomDialog）

3.1 定义自定义弹窗

// 自定义加油站选择弹窗@CustomDialogstruct StationSelectDialog{controller:CustomDialogController=newCustomDialogController({builder:StationSelectDialog()});onSelect:(stationId:string)=>void=()=>{};privatestations=[{id:'001',name:'中国石化',icon:'⛽',discount:'立减0.1元/升'},{id:'002',name:'中国石油',icon:'⛽',discount:'积分翻倍'},{id:'003',name:'壳牌',icon:'⛽',discount:'无优惠'},];build(){Column({space:0}){// 标题区Row(){Text('选择品牌').fontSize(18).fontWeight(FontWeight.Bold).layoutWeight(1)Image($r('app.media.back')).width(24).height(24).onClick(()=>{this.controller.close();})}.padding({left:20,right:20,top:20,bottom:16})Divider().strokeWidth(0.5).color('#F0F0F0')// 列表区Column({space:0}){ForEach(this.stations,(station:Record<string,string>)=>{Row({space:12}){Text(station['icon']asstring).fontSize(28)Column({space:4}){Text(station['name']asstring).fontSize(16).fontWeight(FontWeight.Medium)Text(station['discount']asstring).fontSize(12).fontColor('#52C41A')}.alignItems(HorizontalAlign.Start).layoutWeight(1)Text('选择').fontSize(14).fontColor('#1A6FF5')}.padding({left:20,right:20,top:14,bottom:14}).width('100%').onClick(()=>{this.onSelect(station['id']asstring);this.controller.close();})Divider().strokeWidth(0.5).color('#F0F0F0').margin({left:20})})}// 取消按钮Text('取消').fontSize(16).fontColor('#999999').padding({top:16,bottom:24}).onClick(()=>{this.controller.close();})}.backgroundColor('#FFFFFF').borderRadius({topLeft:20,topRight:20,bottomLeft:0,bottomRight:0}).width('100%')}}// 使用自定义弹窗@Entry@Componentstruct CustomDialogDemoPage{@StateselectedBrand:string='未选择';privatedialogController:CustomDialogController=newCustomDialogController({builder:StationSelectDialog({onSelect:(id:string)=>{constmap:Record<string,string>={'001':'中国石化','002':'中国石油','003':'壳牌'};this.selectedBrand=map[id]||'未知';}}),alignment:DialogAlignment.Bottom,// 从底部弹出（sheet 风格）offset:{dx:0,dy:0},customStyle:true,// 使用自定义样式maskColor:'#80000000',// 遮罩颜色openAnimation:{duration:300,curve:Curve.EaseOut}});build(){Column({space:24}){Text('自定义弹窗示例').fontSize(20).fontWeight(FontWeight.Bold)Text(`已选品牌：${this.selectedBrand}`).fontSize(16).fontColor(this.selectedBrand==='未选择'?'#999999':'#1A6FF5')Button('选择加油品牌').onClick(()=>{this.dialogController.open();}).width('80%').height(48).backgroundColor('#1A6FF5').fontColor('#FFFFFF').borderRadius(24)}.width('100%').height('100%').justifyContent(FlexAlign.Center)}}

四、ActionSheet：底部操作菜单

ActionSheet.show({title:'选择操作',message:'请选择对该加油站的操作',autoCancel:true,confirm:{value:'取消',action:()=>{}},sheets:[{title:'查看地图路线',action:()=>{console.log('打开地图导航');}},{title:'收藏加油站',action:()=>{console.log('添加到收藏');}},{title:'分享给朋友',action:()=>{console.log('分享');}},{title:'举报问题',action:()=>{console.log('举报');}}]});

五、弹窗类型选择指南

总结

HarmonyOS 提供了丰富的弹窗体系：showToast适合轻量反馈、AlertDialog适合确认操作、ActionSheet适合多选项菜单、CustomDialog适合复杂自定义内容。本项目使用showToast+bindSheet的组合——Toast 提示轻量信息，bindSheet 展示加油站列表——是一种简洁而有效的 UI 设计方案。根据交互的权重选择合适的弹窗类型，是打磨产品体验的关键细节。