# 新用户引导功能说明
## 功能概述
为首页添加了新用户引导功能，首次访问小程序时会自动显示，帮助用户快速了解核心功能。
---
## 技术实现
### 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
```
---
## 使用方式
### 在其他页面中使用
#### 1. 注册组件
在页面的 `xxx.json` 中：
```json
{
"usingComponents": {
"user-guide": "../../components/guide/guide"
}
}
```
#### 2. 添加模板
在页面的 `xxx.wxml` 中：
```html
```
#### 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
```
### 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测试** - 支持多种引导方案
---
## 开发者
如有问题或建议，请联系开发团队。