【HarmonyOS 6】使用说明功能：浮动按钮、弹窗与偏好设置

功能概述在热力图页面HeatmapPage中使用说明功能由三部分协同工作内嵌式使用说明面板— 首次进入或开启常驻时在网格上方展开的引导卡片浮动帮助按钮— 面板隐藏后出现在右上角的圆形悬浮按钮AlertDialog 弹窗— 点击?按钮后弹出的详细帮助对话框三者通过两个状态变量联动showGuide控制面板显隐和showGuideAlways控制是否常驻。同时利用 PreferencesManager 将用户选择持久化到本地。一、状态定义与初始化StateshowGuide:booleanfalse// 是否显示内嵌面板StateshowGuideAlways:booleanfalse// 是否常驻显示页面加载时调用loadGuidePreferences()从本地偏好读取设置asyncaboutToAppear():Promisevoid{awaitthis.loadData()awaitthis.loadGuidePreferences()// 加载使用说明偏好}privateasyncloadGuidePreferences():Promisevoid{consthasSeenGuideawaitthis.preferencesManager.hasSeenGuide()this.showGuideAlwaysawaitthis.preferencesManager.getShowGuideAlways()// 首次使用 或 设置了常驻显示 → 自动展示面板if(!hasSeenGuide||this.showGuideAlways){this.showGuidetrue// 首次查看后标记为已读下次不再自动弹出if(!hasSeenGuide){awaitthis.preferencesManager.markGuideAsSeen()}}}设计要点使用双条件判断首次用户必看老用户可选择常驻markGuideAsSeen()只在首次触发一次之后由showGuideAlways接管二、内嵌式使用说明面板当showGuide true时在网格内容上方渲染一个卡片// GridTimeline() Builder 中if(this.showGuide){Column(){// 标题栏标题 关闭按钮Row(){Text(使用说明).fontSize(this.fs(16)).fontWeight(FontWeight.Bold).fontColor($r(app.color.text_primary))Blank()Button(){Text(×)...}.backgroundColor(Color.Transparent).onClick(async(){this.showGuidefalse// 关闭时若开启了常驻则一并取消if(this.showGuideAlways){this.showGuideAlwaysfalseawaitthis.preferencesManager.setShowGuideAlways(false)}})}.width(100%).margin({bottom:8})// 引导条目列表Column(){Text(• 点击空白格子快速记录单个时间段)Text(• 长按并拖动选择多个连续时间段)Text(• 点击已记录格子编辑时间块)Text(• 左上角白点标识时间块的起始位置)Text(• 金色边框高质量时间专注度≥4 且 价值感≥4)Text(提示可通过右上角 ? 按钮随时查看帮助).fontStyle(FontStyle.Italic)}.alignItems(HorizontalAlign.Start)}.width(100%).padding(16).backgroundColor($r(app.color.card_background)).borderRadius(8).margin({left:8,right:8,bottom:12})}布局要点要素实现方式标题与关闭按钮同行RowBlank()占据中间空间关闭按钮样式背景透明、无 padding、仅显示×符号条目左对齐外层 Column 设置alignItems(HorizontalAlign.Start)底部提示区分级斜体 灰色 较小字号关闭逻辑的细节点击 × 时不仅设showGuide false还检查并同步取消常驻状态保证 UI 和持久化数据一致。三、浮动帮助按钮当内嵌面板隐藏时!this.showGuide在页面右上角显示一个圆形悬浮按钮// build() 方法中的 Stack 布局内if(!this.showGuide){Button(){Text(?).fontSize(this.fs(20)).fontWeight(FontWeight.Bold).fontColor(Color.White)}.width(48).height(48).borderRadius(24)// 正圆形.backgroundColor($r(app.color.primary_color)).position({x:100%,y:70})// 锚定右侧y70 是日期导航栏高度.translate({x:-68,y:20})// 向左偏移68向下偏移20.shadow({radius:12,color:$r(app.color.primary_shadow),offsetX:0,offsetY:4}).onClick((){this.showGuideDialog()})}定位原理整个页面使用Stack布局浮动按钮作为叠加层放置position({ x: 100%, y: 70 })将按钮锚定到容器右边缘垂直位置在日期导航栏下方translate({ x: -68, y: 20 })微调最终位置距离右边距 20px距离导航栏底部 20px48px按钮宽度 20px边距 68pxshadow属性赋予按钮浮起感互斥显示if (!this.showGuide)保证面板和按钮不会同时出现。四、AlertDialog 帮助弹窗点击?按钮后调用showGuideDialog()弹出系统对话框privateshowGuideDialog():void{AlertDialog.show({title:使用说明,message:• 点击空白格子快速记录单个时间段\n\n• 长按并拖动先长按某个格子再滑动选择多个连续时间段\n\n• 点击已记录格子编辑时间块\n\n• 左上角白点标识每个时间块的起始位置\n\n• 金色边框高质量时间专注度≥4 且 价值感≥4\n\n• 左侧时间标签显示每行的开始时间\n\n• 格子颜色整点格子较深半点格子较浅,primaryButton:{value:this.showGuideAlways?关闭常驻显示:开启常驻显示,action:async(){this.showGuideAlways!this.showGuideAlwaysawaitthis.preferencesManager.setShowGuideAlways(this.showGuideAlways)this.showGuidethis.showGuideAlways// 开启时常驻显示面板}},secondaryButton:{value:知道了,action:(){}// 仅关闭对话框},alignment:DialogAlignment.Center})}关键设计动态按钮文案主按钮文字根据当前状态切换——“开启常驻显示” ↔ “关闭常驻显示”双操作合一点击主按钮同时完成切换状态 → 持久化 → 控制showGuide开启时同步显示面板\n\n分段在 message 中使用双换行实现段落间距五、偏好设置持久化PreferencesManager 提供四个 API 管理使用说明状态// PreferencesManager.ets 中相关方法privatestaticreadonlyKEY_HAS_SEEN_GUIDE:stringhas_seen_guideprivatestaticreadonlyKEY_SHOW_GUIDE_ALWAYS:stringshow_guide_always// 检查是否首次查看asynchasSeenGuide():Promiseboolean{returnawaitthis.prefs.get(KEY_HAS_SEEN_GUIDE,false)asboolean}// 标记为已查看只执行一次asyncmarkGuideAsSeen():Promisevoid{awaitthis.prefs.put(KEY_HAS_SEEN_GUIDE,true)awaitthis.prefs.flush()}// 获取常驻显示设置asyncgetShowGuideAlways():Promiseboolean{returnawaitthis.prefs.get(KEY_SHOW_GUIDE_ALWAYS,false)asboolean}// 切换常驻显示asyncsetShowGuideAlways(show:boolean):Promisevoid{awaitthis.pfs.put(KEY_SHOW_GUIDE_ALWAYS,show)awaitthis.prefs.flush()}首次启动时在setDefaultPreferences()中写入默认值awaitthis.prefs.put(KEY_HAS_SEEN_GUIDE,false)// 默认未查看awaitthis.prefs.put(KEY_SHOW_GUIDE_ALWAYS,false)// 默认非常驻底层使用 HarmonyOS 的ohos.data.preferences轻量级 KV 存储flush()保证立即写入磁盘。