引导管理器

多步骤引导流程的核心控制器，支持跳转、状态保持、异步加载等复杂场景

介绍#

mk.GuideManage 是一个功能完整的引导流程管理器，专为多步骤、多状态、可中断的引导场景设计。适用于游戏新手引导、应用功能教学等需要分步交互的场景。

创建管理器#

通过构造函数创建引导管理器实例：

const guideManager = new mk.GuideManage({
    currentStepNum: 1, // 初始步骤编号
    endStepNum: 10, // 结束步骤编号
    nameStr: '新手引导', // 引导名称（用于日志）
    operateTab: XXXGuideOperate.tab, // 操作单元表
    stepUpdateCallbackFunc: (stepNum) => {
        /* 步骤更新回调 */
    },
});

初始化配置说明#

注意：

• 若未提供 currentStepNum，默认从 0 开始。
• stepUpdateCallbackFunc 返回 null 或 undefined 会中断引导。

属性说明#

公共属性#

方法详解#

注册步骤#

regis(step_: MKGuideStepBase | MKGuideStepBase[]): void

注册一个或多个步骤实例。

参数：

• step_：单个或数组形式的步骤实例

说明：

• 注册后，步骤实例的 guideManage 属性会被自动设置为当前管理器
• 步骤会被存储到 stepMap 中，以 stepNum 为 key

运行引导#

run(): Promise<void>

运行当前步骤，自动取消暂停状态并更新视图

用户通常不需要手动调用此接口，除非在暂停状态下恢复当前步骤运行。

执行流程：

1. 通过任务管线（MKTaskPipeline）保证执行顺序
2. 检查是否已到达结束步骤
3. 处理场景切换（根据 sceneStr）
4. 加载操作单元（operateStrList）
5. 执行步骤 preLoad、load、unload 生命周期
6. 触发完整生命周期事件

注意：仅当 isPause === false 时才会执行完整流程。

设置步骤#

setStep(stepNum_: number, initData_?: any): Promise<void>

更新当前步骤，并在 isPause 为 false 的情况下自动执行 run()

参数：

• stepNum_：目标步骤编号
• initData_：可选的初始化数据（传递给步骤的 initData）

行为：

• 正常状态下: 执行完整步骤切换流程
• 暂停状态下: 仅更新步骤数据，不执行生命周期
• 完成状态下: 重置完成状态（isFinish）为 false，重新执行引导
• 切换前触发 beforeSwitch 事件
• 到达 endStepNum 时自动调用 finish()

提示：可通过 this._next() 在步骤内部调用此方法。

获取当前步骤#

getStep(): number

获取当前步骤编号。

返回值：

• 当前步骤编号（即 this._stepNum）

完成引导#

finish(): void

手动完成引导，如果初始化参数传递了结束步骤（endStepNum）且当前步骤不为结束步骤则会跳转到结束步骤

行为：

• 设置 isPause 和 isFinish 为 true
• 触发 finish 事件

适用场景：强制结束引导，如用户跳过、超时等。

暂停/恢复#

通过 isPause 属性控制引导状态：

guideManager.isPause = true; // 暂停，触发 pause 事件
guideManager.isPause = false; // 恢复，触发 resume 事件

说明：

• 暂停状态下仍可切换步骤，只会更新步骤数据，但不会执行步骤生命周期
• isPause = false 仅为恢复暂停但不会执行当前步骤的生命周期，如果你想要执行当前步骤生命周期并恢复暂停状态可以使用 run();

事件系统#

通过 event 属性监听引导生命周期事件：

guideManager.event.on(guideManager.event.key.loadingStep, () => {
    // 步骤加载开始
});

可用事件列表#

提示：使用 guideManager.event.key.xxx 可避免拼写错误。

使用示例#

完整流程示例#

// 1. 创建管理器
const guide = new mk.GuideManage({
    nameStr: '测试引导',
    endStepNum: 999,
    operateTab: {
        tip: {
            load: () => showTip(),
            unload: () => hideTip(),
        },
    },
});

// 2. 注册步骤
guide.regis([new FirstStep(1), new SecondStep(2)]);

// 3. 监听事件
guide.event.on(guide.event.key.finish, () => {
    console.log('✅ 引导完成');
});

// 4. 开始引导
guide.setStep(1);

// 5. 结束引导，跳转到 endStepNum 步骤或调用 finish 函数
guide.setStep(999); // guide.finish();

常见问题（FAQ）#

Q：如何中断引导？

1. 在 stepUpdateCallbackFunc 中返回 null 或 undefined，代表步骤数据不存在中断引导，触发 break 事件
2. 调用 finish() 提前结束引导
3. 设置 isPause = true 暂停引导生命周期，但是 setStep 仍然可以更新步骤数据

Q：如何预加载资源？

在步骤的 preLoad() 方法中加载资源，管理器会根据步骤脚本的 nextStepNumList 自动调用

Q：如何实现分支引导？

设置 nextStepNumList = [2, 3]，表示多路径，然后在步骤中根据条件手动调用 setStep(2) 或 setStep(3)

Q：如何跨场景引导？

在步骤中设置 bundle 和 scene 名，例如 sceneStr = "resources.lobby"，管理器会自动切换到 resources Bundle 中的 lobby 场景

参考资料#

• 操作表概念详解