还在为鸿蒙应用的新手引导头疼？还在手写 Canvas 遮罩、计算气泡位置、处理边缘避让？harmony_noviceguide V2.0 来了——一句代码启动引导，零布局侵入。

为什么需要新手引导？

每个应用都有"第一次"。用户打开你的 App，面对陌生的界面，最常见的反应是——关掉。

一个好的新手引导能在 30 秒内告诉用户：这里能干什么、那里怎么操作。它是留存率的第一道防线。

但在 HarmonyOS 生态中，做一个像样的新手引导并不轻松：

• 遮罩层怎么挖孔？Canvas 手动画
• 气泡位置怎么算？屏幕边缘怎么避让？
• 多步骤怎么管理？动画怎么过渡？
• 适配折叠屏？横竖屏切换？

这些，harmony_noviceguide 都帮你做好了。

先看效果

一句代码，就这么简单

import { NoviceGuideKit } from 'harmony_noviceguide';

NoviceGuideKit.show(this.getUIContext(), {
  steps: [
    { targetId: 'btn_start', tipData: '点击这里开始' },
    { targetId: 'btn_settings', tipData: '这里是设置' }
  ]
});

不需要创建控制器。不需要修改页面布局。不需要套 Stack。

这是 V2.0 最大的变化：新增 NoviceGuideKit 一句代码 API。对比一下 V1.0 的写法：

// V1.0：需要 3 步
// 1. 声明控制器
@Local guideController: GuideController = new GuideController();

// 2. 改布局，套 Stack + NoviceGuide 组件
build() {
  Stack() {
    Column() { /* 你的页面 */ }
    NoviceGuide({ controller: this.guideController })  // 必须加
  }
}

// 3. 调用 Builder 启动
new GuideBuilder().addStep({...}).show(this.guideController);

V2.0 把这三步压缩成了一行。

V2.0 新增了什么？

1. 仅首次显示（持久化）

新手引导只需要显示一次。V2.0 内置了持久化：

// 传入 guideId，自动判断是否已展示过
await NoviceGuideKit.showOnce(this.getUIContext(), 'onboarding_v1', {
  steps: [...]
});

// 用户需要重新看？重置记录
await NoviceGuideKit.resetGuide(this.getUIContext(), 'onboarding_v1');

不再需要自己读写 Preferences。

2. 步骤进度指示器

默认提示框自动显示 1/5 进度，用户知道"还有几步"，心理预期更好。通过 showStepIndicator: false 可关闭。

3. 脉冲高亮动效

静态高亮不够吸引眼球？加一行配置：

{
  targetId: 'important_btn',
  tipData: '快看这里！',
  highlightEffect: 'pulse'  // 呼吸脉冲
}

高亮区域会产生白色呼吸环，自然地引导用户视线。

4. 智能避让全面升级

V1.0 的避让有时会把气泡推出屏幕。V2.0 重写了算法：

• 溢出面积评分：不再盲选第一个能放下的方位，而是遍历所有候选，选溢出最小的
• 双向溢出居中：提示框比屏幕宽？自动居中
• 防振荡冷却：解决了气泡在两个方位间反复跳动的问题

5. MVVM 架构重构

V2.0 把 984 行的巨型 View 组件拆分为：

Model（数据）→ ViewModel（业务逻辑）→ View（纯渲染）

• GuideViewModel：承载全部布局计算、动画编排、传感器管理
• NoviceGuide：瘦身到 ~350 行，只负责 Canvas 绘制和动画播放
• GuideController：新增 goTo()、isFirstStep()、isLastStep()、progress 等计算属性

6. GuideBuilder 链式回调

V1.0 的 Builder 不支持注册回调，需要单独操作 Controller。V2.0 全链式：

new GuideBuilder()
  .addStep({ targetId: 'btn1', tipData: '步骤1' })
  .addStep({ targetId: 'btn2', tipData: '步骤2' })
  .onStepChange((index, step) => { /* 步骤变化 */ })
  .onStepWillChange((from, to) => {
    if (!taskDone) return false;  // 阻止跳转
    return true;
  })
  .onFinish(() => { /* 完成 */ })
  .show(controller);  // 返回 controller

7. 无障碍适配

每步自动生成屏幕朗读文本 "引导步骤 1，共 3 步"，也支持自定义：

{ targetId: 'btn1', accessibilityLabel: '请点击开始按钮' }

三种 API，按需选择

方式	适用场景	需要改布局？
NoviceGuideKit.show()	快速集成	否
GuideBuilder 链式	需要回调/拦截	是
GuideController 手动	完全自定义	是

90% 的场景用 NoviceGuideKit 就够了。

安装

ohpm install harmony_noviceguide

环境要求：

• DevEco Studio 5.0.0+
• HarmonyOS API 12+

完整功能列表

功能	说明
一句代码调用	NoviceGuideKit.show() 零侵入启动
仅首次显示	showOnce() 持久化，重复调用自动跳过
步骤进度指示器	默认显示 1/5 进度
脉冲高亮	highlightEffect: 'pulse' 呼吸动效
智能避让	溢出评分 + 防振荡 + 双向居中
形变动画	步骤间高亮区域平滑插值过渡
多种高亮形状	Circle / Rect / RoundRect
自定义气泡	WrappedBuilder 完全自定义 UI
自定义连接线	同上，支持全局和单步覆盖
自动播放	autoPlay: true + 可配间隔
滚动定位	绑定 Scroller，自动滚动到目标
毛玻璃背景	enableBlur: true
链式回调	Builder 支持 onStepChange/onFinish
步骤拦截	onStepWillChange 返回 false 阻止
跳转任意步	controller.goTo(index)
折叠屏适配	监听 foldStatus + windowSize
无障碍	动态 accessibilityText
MVVM 架构	Model → ViewModel → View 分层

和 iOS/Android 对标

对比了 iOS 的 MaterialShowcase、Instructions，Android 的 TapTargetView、Spotlight 等主流库，harmony_noviceguide 在以下方面领先：

• 形变动画：步骤间高亮区域平滑过渡，竞品大多只有淡入淡出
• 三层 API：Kit / Builder / Controller 三种粒度，比任何竞品都灵活
• 折叠屏感知：HarmonyOS 独有，监听折叠状态和窗口尺寸变化
• 自动滚动定位：内置 Scroller 支持，竞品需手动处理

开源信息

• 协议：Apache 2.0（商用友好）
• 仓库：https://gitee.com/qq1963861722/HarmonyNoviceGuideGit
• 安装：ohpm install harmony_noviceguide

欢迎 Star、提 Issue、贡献代码。

---

如果这个库帮到了你，请给个 Star 支持一下。有问题或功能建议，直接在仓库提 Issue，我会尽快回复。