产品简介

newbie-guide-cj 是一款聚焦式新手引导组件，通过明暗对比的高亮区域与遮罩背景，帮助用户精准定位核心功能，快速上手应用基础操作。

核心功能

• 提供完整的新手引导页面功能
• 支持多页引导设计，每页可配置多个高亮区域
• 具备引导页显示/隐藏、返回上页、跳转指定页功能
• 支持透明度渐变动画效果
• 可设置引导页最大展示次数

源码结构说明

├─AppScope
├─doc            # API文档和使用手册存放目录                   
├─entry          # 示例代码文件夹                  
├─highlightguide # highlightguide 库源目录                  
│  └─src
│      └─main
│          ├─cangjie
│          │  └─src                                     
│          │      ├─core                         # 高亮引导页组件控制器及通用配置构造类
│          │      ├─model                        # 用于构建高亮引导页组件的数据模型,引导页组件的高亮区域点击事件监听、显示/移除监听、页面切换监听、高亮区域重绘监听
│          │      ├─highlight_guide_component.cj # 高亮引导页组件
│          └─resources
├─hvigor     # 构建工具目录
├─README.md  # newbie-guide-cj 介绍及使用说明

Interface Description

For details on main classes and function interfaces, please refer to API.

Usage Instructions

1. Import via module

   1. Clone and download the project.
   2. Copy the highlightguide module to your application project.
   3. Modify the oh-package.json5 file under your application's entry directory. Add "highlightguide": "file:../highlightguide" to the dependencies field.

      {  
         "name": "entry",  
         "version": "1.0.0",  
         "description": "Please describe the basic information.",  
         "main": "",  
         "author": "",  
         "license": "",  
         "dependencies": {  
            "highlightguide": "file:../highlightguide"  
         }  
      }  
      

   4. Modify the cjpm.toml file under your application's entry/src/main/cangjie directory. Add the following under the [dependencies] field:

      [dependencies]  
          highlightguide = {path = "../../../../highlightguide/src/main/cangjie", version = "1.0.0"}  
      

      Or:

      [dependencies]  
           [dependencies.highlightguide]  
               path = "../../../../highlightguide/src/main/cangjie"  
               version = "1.0.0"  
      

   5. Use import highlightguide.* in your project to reference the highlightguide module.

      import highlightguide.*  
      

2. Import newbie-guide-cj as a third-party dependency

   1. Add the newbie-guide-cj dependency library as a git submodule in the target project.

      > cd $PROJECT_ROOT  
      > mkdir third-party  
      > cd third-party  
      > git submodule add "https://gitcode.com/Cangjie-TPC/newbie-guide-cj.git"  
      

   2. Modify the cjpm.toml file under your application's entry/src/main/cangjie directory. Add the dependency:

      [dependencies]  
          highlightguide = {path = "../../../../third-party/newbie-guide-cj/highlightguide/src/main/cangjie", version = "1.0.0"}  
      

      Or:

      [dependencies]  
          [dependencies.highlightguide]  
              path = "../../../../third-party/newbie-guide-cj/highlightguide/src/main/cangjie"  
              version = "1.0.0"  
      

   3. Use the highlightguide component in your project.

      import highlightguide.*  
      

Feature Examples

For details, refer to entry.

Highlight Guide Component Example

import highlightguide.*
import highlightguide.model.*
import ohos.router.*
import highlightguide.core.HighLightGuideBuilder
import highlightguide.core.Controller
import ohos.base.*
import ohos.component.*
import ohos.state_manage.*
import ohos.state_macro_manage.*
import ohos.hilog.Hilog

@Entry
@Component
class EntryView {
    private var builder: ?HighLightGuideBuilder = Option<HighLightGuideBuilder>.None
    private var controller: ?Controller = Option<Controller>.None

    protected override func aboutToAppear() {
        this.builder = HighLightGuideBuilder().setLabel("guide1").alwaysShow(true).addGuidePage(
            GuidePage.newInstance().addHighLight('Simple').addHighLight(
            RectF(0.0, top: 310.0, right: 200.0, bottom: 360.0))
        .setHighLightIndicator(this.SimpleIndicator))
    }

    func build() {
        Column {
            Stack() {
                HighLightGuideComponent(
                    highLightContainer: this.HighLightComponent,
                    currentHLIndicator: unsafe {zeroValue<(CustomView) -> ViewBuilder>()},
                    builder: this.builder,
                    globalContext: globalAbilityContext,
                    onReady: {
                        controller: Controller => this.controller = controller
                    }
                )
            }
        }.width(100.percent)
    }

    @Builder
    private func HighLightComponent() {
        Column() {
            Column() {
                Row() {
                    Button("简单使用").onClick(
                        {
                        => if (let Some(controller) <- this.controller) {
                            controller.show()
                        }
                    }).id("Simple")
                }.margin(top: 10)
            }.alignItems(HorizontalAlign.Start).width(100.percent).height(40.percent)

            Column(10) {
                Button("指定RectF高亮").onClick({
                    => Router.push(url: "Second")
                })
            }.position(x: 0.percent, y: 40.percent)
        }.alignItems(HorizontalAlign.Start).width(100.percent).height(100.percent)
    }

    @Builder
    private func SimpleIndicator() {
        Text("提示：下一步点击 指示 RectF 高亮").fontColor(0xffffff).position(x: 0, y: 50)
        Image(@r(app.media.icon)).width(300.px).height(300.px).position(x: 40, y: 100)
    }
}

Note: The globalAbilityContext in the use case is defined and assigned within the application's own entry\src\main\cangjie\main_ability.cj.

//1.引包
internal import ohos.ability.AbilityContext

//2.定义变量 globalAbilityContext
public var globalAbilityContext: Option<AbilityContext> = Option<AbilityContext>.None

class MainAbility <: Ability {
    public init() {
        super()
        registerSelf()
    }

    public override func onCreate(want: Want, launchParam: LaunchParam): Unit {
        AppLog.info("MainAbility OnCreated.${want.abilityName}")
        //3. 变量 globalAbilityContext 赋值
        globalAbilityContext = Option<AbilityContext>.Some(this.context)
        match (launchParam.launchReason) {
            case LaunchReason.START_ABILITY => AppLog.info("START_ABILITY")
            case _ => ()
        }
    }

    public override func onWindowStageCreate(windowStage: WindowStage): Unit {
        AppLog.info("MainAbility onWindowStageCreate.")
        windowStage.loadContent("Mains")
    }
}

效果图如下：

约束与限制

已在以下版本验证通过：

DevEco Studio 5.0.13.200
Cangjie Support Plugin 5.0.13.200

开源协议

本项目采用 Apache License 2.0 协议，欢迎自由使用与参与开源协作。

参与贡献

我们诚挚欢迎您：

• 提交 Pull Request（PR）
• 报告 Issue
• 以任何形式参与项目贡献