# HarmonyNoviceGuideGit

**Repository Path**: mickey_2/HarmonyNoviceGuideGit

## Basic Information

- **Project Name**: HarmonyNoviceGuideGit
- **Description**: 新手引导组件仓库
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 功能介绍

**harmony_noviceguide** 是一款专为 **HarmonyOS (ArkUI)** 打造的高性能、高可定制的新手引导组件库。它基于最新的 **ArkTS V2
状态管理架构
(`@ComponentV2`, `@ObservedV2`) 开发，旨在为鸿蒙应用提供原生级、沉浸式的新手引导体验。

主要功能清单如下：

- **🧠 智能定位与避让**：内置几何算法，当目标靠近屏幕边缘时，气泡自动调整方向（Auto Flip）或偏移，防止遮挡。
- **🎨 自由定制提示框UI**：支持通过 `WrappedBuilder` 传入自定义的 **气泡 (Tip)** 和 **连接线 (Connector)**，不受预设样式限制。
- **📐 多种形状支持**：内置圆形 (Circle)、矩形 (Rect)、圆角矩形 (RoundRect)的高亮区域，并在步骤切换时支持平滑的形状变换动画 (
  Morphing)。
- **⚡️ ArkUI V2 架构**：全链路采用 V2 状态管理（MVVM），状态管理更高效。
- **🚀 一句代码调用**：通过 `NoviceGuideKit.show()` 一行代码启动引导，无需修改页面布局。

## 示例效果

![NoviceGuide 演示](https://gitee.com/qq1963861722/HarmonyNoviceGuideGit/raw/master/AppScope/resources/base/media/SVID_20260330_094833_1.gif)

## 环境要求

- **IDE 版本**：DevEco Studio 5.0.0 Release 及以上
- **SDK 版本**：HarmonyOS API 12 及以上
- **编程语言**：ArkTS、ArkUI

## 快速入门

1. 安装组件

   ```
   ohpm install harmony_noviceguide
   ```

2. 一句代码启动引导（推荐）

   ```typescript
   import { NoviceGuideKit } from 'harmony_noviceguide';

   // 在按钮点击或页面加载后调用
   NoviceGuideKit.show(this.getUIContext(), {
     steps: [
       { targetId: 'btn_start', tipData: '点击这里开始' },
       { targetId: 'btn_settings', tipData: '这里是设置' }
     ]
   });
   ```

   无需创建控制器、无需修改布局，一行搞定。

## 三种使用方式

根据场景复杂度选择适合的方式：

| 方式                      | 适用场景      |        需要修改布局？         |
|-------------------------|-----------|:----------------------:|
| `NoviceGuideKit.show()` | 快速集成、简单引导 |           否            |
| `GuideBuilder` 链式调用     | 需要回调/拦截器  | 是（Stack + NoviceGuide） |
| `GuideController` 手动控制  | 完全自定义流程   | 是（Stack + NoviceGuide） |

### 方式一：NoviceGuideKit（推荐）

```typescript
import { NoviceGuideKit } from 'harmony_noviceguide';

// 极简模式
NoviceGuideKit.show(this.getUIContext(), {
  steps: [
    { targetId: 'btn1', tipData: '这是按钮1' },
    {
      targetId: 'btn2',
      tipData: '这是按钮2',
      placement: 'top',
      shape: 'circle'
    }
  ]
});

// 完整模式
NoviceGuideKit.show(this.getUIContext(), {
  steps: [
    { targetId: 'btn1', tipData: new MyTipData('标题', '内容'), shape: 'roundRect' }
  ],
  config: { enableBlur: true, animDuration: 500 },
  onStepChange: (index, step) => {
    console.info(`第 ${index} 步`);
  },
  onFinish: () => {
    console.info('引导结束');
  }
});

// 关闭
NoviceGuideKit.dismiss();
```

### 方式二：GuideBuilder 链式调用

```typescript
import { NoviceGuide, GuideController, GuideBuilder, ZoneConfig } from 'harmony_noviceguide';

@Entry
@ComponentV2
struct MyPage {
  @Local controller: GuideController = new GuideController();

  build() {
    Stack() {
      Column() {
        Button('开始').id('btn_start')
        Button('设置').id('btn_settings')
      }
      NoviceGuide({ controller: this.controller })
    }
  }

  startGuide() {
    new GuideBuilder()
      .setConfig({ enableBlur: true })
      .addStep({ targetId: 'btn_start', tipData: '点击开始', placement: 'bottom' })
      .addStep({ targetId: 'btn_settings', tipData: '这是设置', placement: 'top' })
      .onStepChange((index, step) => { /* 步骤变化 */ })
      .onFinish(() => { /* 引导结束 */ })
      .show(this.controller);
  }
}
```

### 方式三：GuideController 手动控制

```typescript
const controller = new GuideController();
controller.onStepChange((index, step) => { ... });
controller.onStepWillChange((from, to) => {
  if (from === 0 && !taskDone) return false; // 阻止跳转
  return true;
});
controller.start(steps, config, onFinish);

// 手动导航
controller.next();
controller.prev();
controller.goTo(2); // 跳到第 3 步
controller.stop();
```

## API 说明

### NoviceGuideKit（一句代码调用）

| **方法**                     | **说明**                    |
|----------------------------|---------------------------|
| `show(uiContext, options)` | 启动引导，返回 `GuideController` |
| `dismiss()`                | 关闭当前引导                    |
| `getController()`          | 获取当前活跃控制器                 |

**NoviceGuideKitOptions：**

| **属性**             | **类型**                     | **必填** | **说明**   |
|--------------------|----------------------------|:------:|----------|
| `steps`            | `GuideStepOptions[]`       |   是    | 引导步骤     |
| `config`           | `GuideGlobalConfigOptions` |   否    | 全局配置     |
| `onFinish`         | `() => void`               |   否    | 引导结束回调   |
| `onStepChange`     | `(index, step) => void`    |   否    | 步骤切换后回调  |
| `onStepWillChange` | `(from, to) => boolean`    |   否    | 步骤切换前拦截器 |
| `tipBuilder`       | `WrappedBuilder`           |   否    | 全局自定义提示框 |
| `connectorBuilder` | `WrappedBuilder`           |   否    | 全局自定义连接线 |

### GuideController（控制器）

| **方法**                             | **说明**  |
|------------------------------------|---------|
| `start(steps, config?, onFinish?)` | 启动引导    |
| `next()`                           | 下一步     |
| `prev()`                           | 上一步     |
| `goTo(index)`                      | 跳转到指定步骤 |
| `stop()`                           | 停止引导    |
| `getCurrentStep()`                 | 获取当前步骤  |
| `isFirstStep()`                    | 是否第一步   |
| `isLastStep()`                     | 是否最后一步  |
| `onStepChange(callback)`           | 监听步骤切换  |
| `onStepWillChange(callback)`       | 拦截步骤切换  |

### GuideStepOptions（步骤配置）

| **属性**              | **类型**                              | **说明**                             |
|---------------------|-------------------------------------|------------------------------------|
| `targetId`          | `string`                            | 目标组件 ID（与 `.id()` 对应）              |
| `targetRect`        | `TargetRect`                        | 手动指定目标区域（与 targetId 二选一）           |
| `tipData`           | `Object`                            | 提示数据（字符串或 `{ title, content }` 对象） |
| `placement`         | `GuidePlacement`                    | 气泡方位，默认 `'bottom'`                 |
| `shape`             | `'circle' \| 'rect' \| 'roundRect'` | 高亮形状，默认 `'roundRect'`              |
| `zoneConfig`        | `ZoneConfig`                        | 高亮区内边距和圆角                          |
| `enableAutoFlip`    | `boolean`                           | 是否启用智能避让（覆盖全局配置）                   |
| `stepBuilder`       | `WrappedBuilder`                    | 单步自定义提示框                           |
| `connectorBuilder`  | `WrappedBuilder`                    | 单步自定义连接线                           |
| `scroller`          | `Scroller`                          | 绑定滚动控制器（用于自动滚动定位）                  |
| `scrollIndex`       | `number`                            | 滚动目标索引                             |
| `offsetX / offsetY` | `number`                            | 提示框偏移量                             |

### 全局配置

| **属性**             | **默认值**                | **说明**        |
|--------------------|------------------------|---------------|
| `maskColor`        | `'rgba(0, 0, 0, 0.6)'` | 遮罩层颜色         |
| `animDuration`     | `350`                  | 形状变换动画时长 (ms) |
| `clickMaskToNext`  | `true`                 | 点击遮罩是否下一步     |
| `enableBlur`       | `false`                | 是否开启背景模糊      |
| `autoPlay`         | `false`                | 是否自动播放        |
| `autoPlayInterval` | `3000`                 | 自动播放间隔 (ms)   |
| `enableAutoFlip`   | `true`                 | 空间不足时是否自动翻转   |
| `safePadding`      | `16`                   | 屏幕边缘安全距离      |

## 权限要求

本组件为纯 UI 组件，**不需要**申请任何系统权限。

## 技术支持

如果您在使用过程中遇到问题，或有功能建议，欢迎通过以下方式联系：

- **Issues**: 请在代码仓库提交 Issue

## 开源许可协议

该代码经过 [Apache 2.0 授权许可](http://www.apache.org/licenses/LICENSE-2.0)。

## 获取方式

可以通过 OHPM 中心仓获取，或访问 [https://gitee.com/qq1963861722/HarmonyNoviceGuideGit.git] 下载源码。