CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

模块概述

这是一个新手引导与引导浮层组件模块，用于为Android应用提供用户引导功能。该模块支持高亮特定View、显示引导内容、管理引导页面的生命周期等功能。

核心架构

主要组件

BaseGuide - 引导的抽象基类
- 管理Activity/Fragment/Dialog的引导注册
- 提供引导显示/隐藏的生命周期管理
- 子类需要实现 buildGuide(), interceptGuide(), guideType() 方法
GuideCenter - 引导管理中心
- 全局引导注册管理器
- 支持引导类型标识和缓存机制
- 提供激活/取消激活引导的统一接口
GuideController - 引导控制器
- 管理引导页面的显示逻辑
- 支持多页引导的顺序播放
- 处理引导页面的生命周期回调
GuidePage - 引导页面模型
- 定义单个引导页的配置
- 支持高亮区域、背景色、交互行为等设置
- 包含自动消失、标签管理等功能
NewbieGuide - 引导构建器
- 提供链式调用API构建引导
- 支持Activity/Fragment/Dialog三种容器
- Builder模式创建GuideController实例

高亮系统

HighLight - 高亮区域抽象类
HighLightView - 基于View标签的高亮实现
HighLightOptions - 高亮区域配置选项
RelativeGuide - 相对于高亮区域的引导内容布局

持久化机制

GuideLabel - 引导状态管理
- 使用SharedPreferences持久化引导完成状态
- 支持标签化管理，避免重复显示引导

常用开发命令

# 编译模块
./gradlew :frame:guide:assemble

# 运行单元测试
./gradlew :frame:guide:test

# 运行Android测试
./gradlew :frame:guide:connectedAndroidTest

# 检查代码风格
./gradlew :frame:guide:ktlintCheck

架构设计模式

遵循项目标准的接口-工厂-初始化模式：

// 1. 继承BaseGuide实现具体引导类
class MyGuide : BaseGuide() {
    override fun buildGuide(): GuideController? {
        return NewbieGuide.with(activity)
            .addGuidePage(/* 引导页配置 */)
            .build()
    }
    
    override fun interceptGuide(): Boolean = false
    override fun guideType(): String = "my_guide"
}

// 2. 注册引导
val guide = MyGuide()
guide.register(activity)

// 3. 激活引导显示
GuideCenter.activeGuide("my_guide")

关键实现细节

高亮区域查找机制

通过View标签(@StringRes viewTag)定位目标View
支持圆形和圆角矩形两种高亮形状
可设置内边距和圆角半径

引导页面显示逻辑

GuideLayout使用PorterDuff.Mode.CLEAR绘制透明高亮区域
支持点击高亮区域或任意位置消失
可配置延迟自动消失

状态管理

每个引导页可设置唯一label标识
显示后自动标记为完成状态，下次不再显示
支持组标签(groupLabel)控制整组引导的显示

生命周期管理

Activity/Fragment/Dialog销毁时自动清理引导资源
支持引导页面的刷新(refresh)机制
提供显示和消失的回调监听

依赖关系

依赖 frame:base 基础框架
依赖 frame:util 工具类
依赖 frame:log 日志框架
可选依赖 frame:zero 零配置工具

CLAUDE.md 3.3 KB Permalink Verlauf Originalformat