richarjiang
8a7599f630
- 在目标页面中集成用户引导功能，帮助用户了解页面各项功能 - 创建 GoalsPageGuide 组件，支持多步骤引导和动态高亮功能区域 - 实现引导状态的检查、标记和重置功能，确保用户体验 - 添加开发测试按钮，方便开发者重置引导状态 - 更新相关文档，详细描述引导功能的实现和使用方法
159 lines
3.7 KiB
Markdown
159 lines
3.7 KiB
Markdown
# 用户引导功能实现文档
|
||
|
||
## 功能概述
|
||
|
||
用户引导功能用于在用户首次进入特定页面时，提供功能说明和操作指导，帮助用户更好地理解和使用应用功能。
|
||
|
||
## 已实现的引导
|
||
|
||
### 1. Goals页面 - 全面功能引导
|
||
|
||
**位置**: `app/(tabs)/goals.tsx`
|
||
|
||
**引导内容**:
|
||
- 欢迎介绍：介绍目标页面的整体功能
|
||
- 任务进度统计：说明任务进度卡片显示当天任务的完成情况
|
||
- 目标管理：说明如何查看和管理目标
|
||
- 创建新目标：说明如何快速创建新目标
|
||
- 任务筛选：说明如何使用标签筛选任务
|
||
- 任务列表：说明任务列表的功能和操作
|
||
|
||
**组件**: `GoalsPageGuide`
|
||
|
||
## 技术实现
|
||
|
||
### 核心组件
|
||
|
||
1. **GoalsPageGuide** (`components/GoalsPageGuide.tsx`)
|
||
- 引导弹窗组件
|
||
- 支持多步骤引导
|
||
- 动态高亮不同功能区域
|
||
- 平滑动画效果
|
||
- 回顾功能支持
|
||
|
||
2. **引导状态管理** (`utils/guideHelpers.ts`)
|
||
- 使用AsyncStorage存储引导完成状态
|
||
- 提供检查、标记、重置功能
|
||
|
||
### 引导状态键
|
||
|
||
```typescript
|
||
const GUIDE_KEYS = {
|
||
GOALS_PAGE: '@guide_goals_page_completed',
|
||
} as const;
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 在页面中集成引导
|
||
|
||
1. **导入必要组件和工具**:
|
||
```typescript
|
||
import { GoalsPageGuide } from '@/components/GoalsPageGuide';
|
||
import { checkGuideCompleted, markGuideCompleted } from '@/utils/guideHelpers';
|
||
```
|
||
|
||
2. **添加状态管理**:
|
||
```typescript
|
||
const [showGuide, setShowGuide] = useState(false);
|
||
```
|
||
|
||
3. **检查引导状态**:
|
||
```typescript
|
||
const checkAndShowGuide = async () => {
|
||
try {
|
||
const hasCompletedGuide = await checkGuideCompleted('GOALS_PAGE');
|
||
if (!hasCompletedGuide) {
|
||
setTimeout(() => {
|
||
setShowGuide(true);
|
||
}, 1000);
|
||
}
|
||
} catch (error) {
|
||
console.error('检查引导状态失败:', error);
|
||
}
|
||
};
|
||
```
|
||
|
||
4. **处理引导完成**:
|
||
```typescript
|
||
const handleGuideComplete = async () => {
|
||
try {
|
||
await markGuideCompleted('GOALS_PAGE');
|
||
setShowGuide(false);
|
||
} catch (error) {
|
||
console.error('保存引导状态失败:', error);
|
||
setShowGuide(false);
|
||
}
|
||
};
|
||
```
|
||
|
||
5. **在页面中渲染组件**:
|
||
```typescript
|
||
<GoalsPageGuide
|
||
visible={showGuide}
|
||
onComplete={handleGuideComplete}
|
||
/>
|
||
```
|
||
|
||
## 开发测试
|
||
|
||
### 测试按钮
|
||
|
||
在开发模式下，Goals页面右上角会显示"重置引导"按钮，用于测试引导功能。
|
||
|
||
### 手动重置引导状态
|
||
|
||
```typescript
|
||
import { resetGuideStates } from '@/utils/devTools';
|
||
|
||
// 重置所有引导状态
|
||
await resetGuideStates();
|
||
```
|
||
|
||
### 检查引导状态
|
||
|
||
```typescript
|
||
import { getAllGuideStatus } from '@/utils/guideHelpers';
|
||
|
||
// 获取所有引导状态
|
||
const status = await getAllGuideStatus();
|
||
console.log('引导状态:', status);
|
||
```
|
||
|
||
## 添加新的引导
|
||
|
||
### 1. 创建引导组件
|
||
|
||
参考 `TaskProgressCardGuide` 的结构创建新的引导组件。
|
||
|
||
### 2. 添加状态键
|
||
|
||
在 `utils/guideHelpers.ts` 中添加新的引导键：
|
||
|
||
```typescript
|
||
const GUIDE_KEYS = {
|
||
GOALS_PAGE: '@guide_goals_page_completed',
|
||
NEW_GUIDE: '@guide_new_guide_completed', // 新增
|
||
} as const;
|
||
```
|
||
|
||
### 3. 在页面中集成
|
||
|
||
按照上述使用方法在目标页面中集成引导功能。
|
||
|
||
## 设计原则
|
||
|
||
1. **用户友好**: 引导内容简洁明了，避免信息过载
|
||
2. **可跳过**: 用户可以选择跳过引导
|
||
3. **可回顾**: 用户可以回顾之前的步骤
|
||
4. **一次性**: 引导只显示一次，避免重复打扰
|
||
5. **响应式**: 引导内容适应不同屏幕尺寸
|
||
6. **可测试**: 提供开发测试工具
|
||
|
||
## 注意事项
|
||
|
||
1. 引导应该在页面完全加载后显示，避免布局问题
|
||
2. 引导状态应该持久化存储，避免重复显示
|
||
3. 引导内容应该与页面功能紧密相关
|
||
4. 测试时注意重置引导状态，确保功能正常
|