dapaijizhang3/USER_GUIDE_README.md

# 新用户引导功能说明

## 功能概述

为首页添加了新用户引导功能，首次访问小程序时会自动显示，帮助用户快速了解核心功能。

---

## 技术实现

### 1. 引导组件 (`components/guide/guide`)

**核心特性**：
- ✅ 高亮遮罩层（打洞效果）
- ✅ 自适应位置计算
- ✅ 多步骤引导流程
- ✅ 进度指示器
- ✅ 平滑过渡动画
- ✅ 防止穿透交互

**文件结构**：
```
components/guide/
├── guide.wxml  # 模板（遮罩 + 高亮 + 提示卡片）
├── guide.wxss  # 样式（渐变背景 + 动画）
├── guide.js    # 逻辑（位置计算 + 步骤控制）
└── guide.json  # 配置
```

### 2. 引导步骤配置

在 [pages/index/index.js](pages/index/index.js) 中定义引导步骤：

```javascript
guideSteps: [
  {
    selector: '.guide-create-btn',     // 目标元素选择器
    title: '创建房间',                 // 标题
    description: '点击这里可以...',    // 说明文字
    position: 'bottom',                 // 提示框位置（top/bottom/left/right）
    padding: 12,                        // 高亮区域扩展边距
    borderRadius: 16                    // 高亮区域圆角
  },
  // ... 更多步骤
]
```

### 3. 首次访问检测

使用 `wx.getStorageSync('hasShownGuide')` 检测是否已显示过引导：

```javascript
checkAndShowGuide() {
  const hasShownGuide = wx.getStorageSync('hasShownGuide')
  if (!hasShownGuide) {
    // 延迟500ms显示，等待页面完全渲染
    setTimeout(() => {
      this.setData({ showGuide: true })
    }, 500)
  }
}
```

### 4. 目标元素标记

为需要引导的元素添加唯一的class：

```html
<!-- 创建房间按钮 -->
<view class="action-btn primary-btn guide-create-btn" bindtap="createRoom">
  <!-- ... -->
</view>

<!-- 加入房间按钮 -->
<view class="action-btn secondary-btn guide-join-btn" bindtap="joinRoom">
  <!-- ... -->
</view>

<!-- 扫码按钮 -->
<view class="scan-btn guide-scan-btn" bindtap="scanCode">
  <!-- ... -->
</view>
```

---

## 使用方式

### 在其他页面中使用

#### 1. 注册组件

在页面的 `xxx.json` 中：

```json
{
  "usingComponents": {
    "user-guide": "../../components/guide/guide"
  }
}
```

#### 2. 添加模板

在页面的 `xxx.wxml` 中：

```html
<user-guide
  show="{{showGuide}}"
  steps="{{guideSteps}}"
  bind:complete="onGuideComplete"
/>
```

#### 3. 配置步骤

在页面的 `xxx.js` 中：

```javascript
Page({
  data: {
    showGuide: false,
    guideSteps: [
      {
        selector: '.target-element',
        title: '功能标题',
        description: '功能说明文字',
        position: 'bottom',      // 可选：top/bottom/left/right
        padding: 12,             // 可选：高亮区域扩展边距（默认8）
        borderRadius: 16,        // 可选：圆角大小（默认16）
        showArrow: true          // 可选：是否显示箭头（默认true）
      }
      // ... 更多步骤
    ]
  },

  onReady() {
    // 检查是否需要显示引导
    const hasShown = wx.getStorageSync('hasShownGuide_pageName')
    if (!hasShown) {
      setTimeout(() => {
        this.setData({ showGuide: true })
      }, 500)
    }
  },

  onGuideComplete() {
    this.setData({ showGuide: false })
    wx.setStorageSync('hasShownGuide_pageName', true)
  }
})
```

---

## 测试方法

### 方法1：清除存储测试

在微信开发者工具的控制台中执行：

```javascript
// 清除引导标记
wx.removeStorageSync('hasShownGuide')

// 重新加载页面
wx.reLaunch({ url: '/pages/index/index' })
```

### 方法2：清除缓存测试

1. 微信开发者工具 → 清缓存 → 清除所有
2. 重新编译项目
3. 重新进入首页

### 方法3：手动触发测试

在 [pages/index/index.js](pages/index/index.js) 中临时修改：

```javascript
checkAndShowGuide() {
  // 注释掉检查逻辑，直接显示
  // const hasShownGuide = wx.getStorageSync('hasShownGuide')
  // if (!hasShownGuide) {
    setTimeout(() => {
      this.setData({ showGuide: true })
    }, 500)
  // }
}
```

---

## 自定义配置

### 修改引导步骤

编辑 [pages/index/index.js](pages/index/index.js) 中的 `guideSteps` 数组：

```javascript
guideSteps: [
  // 添加新的步骤
  {
    selector: '.my-element',
    title: '新功能',
    description: '这是一个新功能的说明',
    position: 'top',
    padding: 10,
    borderRadius: 12
  }
]
```

### 修改样式

编辑 [components/guide/guide.wxss](components/guide/guide.wxss)：

```css
/* 修改遮罩透明度 */
.guide-overlay {
  background: rgba(0, 0, 0, 0.75); /* 调整透明度 */
}

/* 修改提示卡片样式 */
.guide-text-wrapper {
  background: white;        /* 背景色 */
  border-radius: 16rpx;     /* 圆角 */
  padding: 32rpx 28rpx;     /* 内边距 */
}

/* 修改按钮样式 */
.guide-next {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
```

### 修改位置计算逻辑

编辑 [components/guide/guide.js](components/guide/guide.js) 中的 `calculateContentPosition` 方法。

---

## 功能特点

### 1. 智能位置计算

组件会自动计算最佳显示位置，避免超出屏幕边界：

- 优先使用指定位置（top/bottom/left/right）
- 空间不足时自动切换到对面
- 保持在屏幕可视范围内

### 2. 高亮打洞效果

使用 CSS `box-shadow` 实现高亮区域：

```css
.guide-spotlight {
  box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.75);
}
```

这样可以在遮罩层上"打洞"，突出显示目标元素。

### 3. 步骤进度指示

底部圆点显示当前进度：

- 灰色圆点：未完成的步骤
- 紫色长条：当前步骤
- 平滑过渡动画

### 4. 防止交互穿透

```javascript
// 阻止滚动
preventMove() {}

// 阻止点击穿透
catchtouchmove="preventMove"
```

---

## 注意事项

### 1. 选择器必须唯一

确保每个引导步骤的 `selector` 能唯一定位到目标元素：

```html
<!-- ✅ 正确：使用唯一的class -->
<view class="btn guide-create-btn"></view>

<!-- ❌ 错误：选择器不唯一 -->
<view class="btn"></view>
<view class="btn"></view>
```

### 2. 等待页面渲染

在 `onReady` 生命周期中显示引导，并使用延迟：

```javascript
onReady() {
  setTimeout(() => {
    this.setData({ showGuide: true })
  }, 500)  // 延迟500ms，确保页面完全渲染
}
```

### 3. 避免在隐藏元素上使用

不要在 `wx:if="{{false}}"` 或 `display: none` 的元素上使用引导，否则无法获取位置。

### 4. 不同页面使用不同标记

如果多个页面都有引导，使用不同的storage key：

```javascript
// 首页
wx.setStorageSync('hasShownGuide_index', true)

// 其他页面
wx.setStorageSync('hasShownGuide_detail', true)
```

---

## API参数

### 组件属性

| 属性 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| show | Boolean | 是 | false | 是否显示引导 |
| steps | Array | 是 | [] | 引导步骤配置 |

### 组件事件

| 事件 | 参数 | 说明 |
|------|------|------|
| complete | 无 | 引导完成时触发 |

### 步骤配置

| 字段 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| selector | String | 是 | - | 目标元素的CSS选择器 |
| title | String | 是 | - | 引导标题 |
| description | String | 是 | - | 引导说明文字 |
| position | String | 否 | 'bottom' | 提示框位置（top/bottom/left/right）|
| padding | Number | 否 | 8 | 高亮区域扩展边距（px）|
| borderRadius | Number | 否 | 16 | 高亮区域圆角大小（px）|
| showArrow | Boolean | 否 | true | 是否显示箭头 |

---

## 效果预览

### 步骤1：创建房间
- 高亮"创建房间"按钮
- 显示说明文字
- 进度指示：1/3

### 步骤2：加入房间
- 高亮"加入房间"按钮
- 显示说明文字
- 进度指示：2/3

### 步骤3：扫码进入
- 高亮"扫码"按钮
- 显示说明文字
- 进度指示：3/3
- 显示"知道了"按钮

---

## 常见问题

### Q: 引导没有显示？

A: 检查以下几点：
1. 是否已经显示过（清除 storage）
2. 选择器是否正确
3. 目标元素是否已渲染
4. 延迟时间是否足够

### Q: 位置显示不对？

A: 检查：
1. 目标元素是否被隐藏
2. 页面是否完全渲染
3. 增加 `setTimeout` 延迟时间

### Q: 如何调试？

A: 在组件的 `showStep` 方法中添加日志：

```javascript
showStep(stepIndex) {
  const step = this.data.steps[stepIndex]
  console.log('显示引导步骤:', stepIndex, step)
  // ...
}
```

### Q: 如何强制重新显示引导？

A: 控制台执行：

```javascript
wx.removeStorageSync('hasShownGuide')
getCurrentPages()[0].setData({ showGuide: true })
```

---

## 未来优化方向

1. **手势控制** - 支持滑动切换步骤
2. **视频教程** - 嵌入视频演示
3. **自定义主题** - 支持暗色模式
4. **动画增强** - 添加更多过渡动画
5. **智能触发** - 根据用户行为动态显示引导
6. **A/B测试** - 支持多种引导方案

---

## 开发者

如有问题或建议，请联系开发团队。