# HarmonyNoviceGuideGit

**Repository Path**: harmonyos4me/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**: 1
- **Created**: 2025-12-20
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 功能介绍

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

主要功能清单如下：

- **👆 交互穿透 (Interactive Pass-through)**：独创的挖孔响应机制，允许用户直接点击高亮区域内的组件（如点击按钮），实现“边引导，边操作”的沉浸式体验。
- **🧠 智能定位与避让**：内置几何算法，当目标靠近屏幕边缘时，气泡自动调整方向（Auto Flip）或偏移，防止遮挡。
- **🎨 自由定制提示框UI**：支持通过 `WrappedBuilder` 传入自定义的 **气泡 (Tip)** 和 **连接线 (Connector)**，不受预设样式限制。
- **📐 多种形状支持**：内置圆形 (Circle)、矩形 (Rect)、圆角矩形 (RoundRect)
  的高亮区域，并在步骤切换时支持平滑的形状变换动画 (Morphing)。
- **⚡️ ArkUI V2 架构**：全链路采用 V2 状态管理，状态管理更高效。

## 环境要求

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

## 快速入门

1. 安装组件

   在项目根目录下执行以下命令：

   ```
   ohpm install @org/novice-guide
   ```

2. 引入组件

   在需要使用的页面文件中引入核心类：

   ```
   import { 
     NoviceGuide, 
     GuideController, 
     GuideBuilder 
   } from '@org/novice-guide';
   ```

3. 页面布局

   将 NoviceGuide 组件放置在页面根容器 Stack 的 最底层（代码层面的最后一行，使其渲染在最上层）。

   ```
   @Entry
   @ComponentV2
   struct Index {
     // 1. 创建控制器
     @Local guideController: GuideController = new GuideController();
   
     build() {
       Stack() {
         // ... 您的业务 UI ...
         Button('目标按钮').id('target_btn_1')
   
         // 2. 添加引导组件 (必须在 Stack 的最上方)
         NoviceGuide({ controller: this.guideController })
       }
     }
   }
   ```

## 使用样例

通过 `GuideBuilder` 构建引导步骤并启动：

```
// 在页面加载完成(onPageShow)或点击事件中调用
startGuide() {
  new GuideBuilder()
    // 全局配置
    .setConfig({
      maskColor: 'rgba(0, 0, 0, 0.6)',
      clickMaskToNext: true, // 点击遮罩跳转下一步
      enableBlur: true       // 开启毛玻璃
    })
    // 步骤 1：基础用法
    .addStep({
      targetId: 'target_btn_1', // 对应组件的 .id()
      tipData: { title: '基础功能', content: '这是一个普通的高亮引导' },
      placement: 'bottom',      // 气泡在下方
      shape: 'roundRect'        // 圆角矩形
    })
    // 步骤 2：交互穿透
    .addStep({
      targetId: 'target_btn_2',
      tipData: { title: '交互模式', content: '您可以直接点击这个按钮触发业务逻辑' },
      placement: 'top',
      allowTargetClick: true    // 核心功能：允许点击高亮区
    })
    // 启动引导
    .show(this.guideController);
}
```

## 示例效果

![SVID_20251218_175739_1](https://communityfile-drcn.op.hicloud.com/FileServer/getFile/cmtyPrivatetemp/20251218/cmtyPrivate/144/890/357/0070086000144890357.20251218192028.35265316725131358367418399603869:20251218202028:2800:E8D409454265F69E7979B9A40CC163FBD94DED84C70F7326E317A5266AF2F6D3.gif)

## API说明

### 1. NoviceGuide (组件)

| **参数**             | **类型**            | **必填** | **说明**              |
|--------------------|-------------------|--------|---------------------|
| `controller`       | `GuideController` | 是      | 核心控制器，用于控制显示/隐藏     |
| `tipContent`       | `WrappedBuilder`  | 否      | 自定义气泡 UI 构建器 (全局默认) |
| `connectorBuilder` | `WrappedBuilder`  | 否      | 自定义连接线构建器 (全局默认)    |
| `enableLog`        | `boolean`         | 否      | 是否开启内部调试日志          |
| `customGuideId`    | `string`          | 否      | 自定义组件 ID，用于多实例场景    |

### 2. GuideController (控制器)

| **方法**                             | **说明**               |
|------------------------------------|----------------------|
| `start(steps, config?, onFinish?)` | 启动引导流程               |
| `next()`                           | 跳转下一步                |
| `prev()`                           | 返回上一步                |
| `stop()`                           | 停止并关闭引导              |
| `onStepChange(callback)`           | 监听步骤切换               |
| `onStepWillChange(callback)`       | 拦截步骤切换（返回 false 可阻止） |

### 3. GuideStepOptions (步骤配置)

| **属性**             | **类型**           | **说明**                                   |
|--------------------|------------------|------------------------------------------|
| `targetId`         | `string`         | 目标组件的 ID (需在 UI 中设置 `.id()`)             |
| `tipData`          | `Object`         | 提示数据 (默认包含 title, content，无泛型)           |
| `placement`        | `GuidePlacement` | 气泡方位 (`top`/`bottom`/`left`/`right` 等)   |
| `shape`            | `'circle'        | 'rect'                                   | 'roundRect'` | 高亮形状                                           |
| `allowTargetClick` | `boolean`        | 是否允许点击高亮区域 (穿透)                          |
| `zoneConfig`       | `ZoneConfig`     | 高亮区的内边距 (`padding`) 和圆角 (`borderRadius`) |
| `stepBuilder`      | `WrappedBuilder` | 单步完全自定义气泡 UI                             |
| `connectorBuilder` | `WrappedBuilder` | 单步自定义连接线 UI                              |
| `scroller`         | `Scroller`       | 绑定的滚动控制器，用于自动定位                          |
| `scrollIndex`      | `number`         | 滚动目标的索引                                  |

## 配置说明

通过 `GuideBuilder.setConfig()` 或直接实例化 `GuideGlobalConfig` 进行配置：

| **属性**             | **默认值**                | **说明**        |
|--------------------|------------------------|---------------|
| `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] 下载源码。