Files

richarjiang 8a7599f630 feat: 新增目标页面引导功能及相关组件

- 在目标页面中集成用户引导功能，帮助用户了解页面各项功能
- 创建 GoalsPageGuide 组件，支持多步骤引导和动态高亮功能区域
- 实现引导状态的检查、标记和重置功能，确保用户体验
- 添加开发测试按钮，方便开发者重置引导状态
- 更新相关文档，详细描述引导功能的实现和使用方法

2025-08-23 13:53:18 +08:00

3.7 KiB

Raw Blame History

用户引导功能实现文档

功能概述

用户引导功能用于在用户首次进入特定页面时，提供功能说明和操作指导，帮助用户更好地理解和使用应用功能。

已实现的引导

1. Goals页面 - 全面功能引导

位置: app/(tabs)/goals.tsx

引导内容:

欢迎介绍：介绍目标页面的整体功能
任务进度统计：说明任务进度卡片显示当天任务的完成情况
目标管理：说明如何查看和管理目标
创建新目标：说明如何快速创建新目标
任务筛选：说明如何使用标签筛选任务
任务列表：说明任务列表的功能和操作

组件: GoalsPageGuide

技术实现

核心组件

GoalsPageGuide (components/GoalsPageGuide.tsx)
- 引导弹窗组件
- 支持多步骤引导
- 动态高亮不同功能区域
- 平滑动画效果
- 回顾功能支持
引导状态管理 (utils/guideHelpers.ts)
- 使用AsyncStorage存储引导完成状态
- 提供检查、标记、重置功能

引导状态键

const GUIDE_KEYS = {
  GOALS_PAGE: '@guide_goals_page_completed',
} as const;

使用方法

在页面中集成引导

导入必要组件和工具:

import { GoalsPageGuide } from '@/components/GoalsPageGuide';
import { checkGuideCompleted, markGuideCompleted } from '@/utils/guideHelpers';

添加状态管理:

const [showGuide, setShowGuide] = useState(false);

检查引导状态:

const checkAndShowGuide = async () => {
  try {
    const hasCompletedGuide = await checkGuideCompleted('GOALS_PAGE');
    if (!hasCompletedGuide) {
      setTimeout(() => {
        setShowGuide(true);
      }, 1000);
    }
  } catch (error) {
    console.error('检查引导状态失败:', error);
  }
};

处理引导完成:

const handleGuideComplete = async () => {
  try {
    await markGuideCompleted('GOALS_PAGE');
    setShowGuide(false);
  } catch (error) {
    console.error('保存引导状态失败:', error);
    setShowGuide(false);
  }
};

在页面中渲染组件:

<GoalsPageGuide
  visible={showGuide}
  onComplete={handleGuideComplete}
/>

开发测试

测试按钮

在开发模式下，Goals页面右上角会显示"重置引导"按钮，用于测试引导功能。

手动重置引导状态

import { resetGuideStates } from '@/utils/devTools';

// 重置所有引导状态
await resetGuideStates();

检查引导状态

import { getAllGuideStatus } from '@/utils/guideHelpers';

// 获取所有引导状态
const status = await getAllGuideStatus();
console.log('引导状态:', status);

添加新的引导

1. 创建引导组件

参考 TaskProgressCardGuide 的结构创建新的引导组件。

2. 添加状态键

在 utils/guideHelpers.ts 中添加新的引导键：

const GUIDE_KEYS = {
  GOALS_PAGE: '@guide_goals_page_completed',
  NEW_GUIDE: '@guide_new_guide_completed', // 新增
} as const;

3. 在页面中集成

按照上述使用方法在目标页面中集成引导功能。

设计原则

用户友好: 引导内容简洁明了，避免信息过载
可跳过: 用户可以选择跳过引导
可回顾: 用户可以回顾之前的步骤
一次性: 引导只显示一次，避免重复打扰
响应式: 引导内容适应不同屏幕尺寸
可测试: 提供开发测试工具

注意事项

引导应该在页面完全加载后显示，避免布局问题
引导状态应该持久化存储，避免重复显示
引导内容应该与页面功能紧密相关
测试时注意重置引导状态，确保功能正常

3.7 KiB Raw Blame History Unescape Escape