9.0 KiB

Raw Permalink Blame History

新用户引导功能说明

功能概述

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

技术实现

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

核心特性：

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

文件结构：

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

2. 引导步骤配置

在 pages/index/index.js 中定义引导步骤：

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

3. 首次访问检测

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

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

4. 目标元素标记

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

<!-- 创建房间按钮 -->
<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 中：

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

2. 添加模板

在页面的 xxx.wxml 中：

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

3. 配置步骤

在页面的 xxx.js 中：

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：清除存储测试

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

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

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

方法2：清除缓存测试

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

方法3：手动触发测试

在 pages/index/index.js 中临时修改：

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

自定义配置

修改引导步骤

编辑 pages/index/index.js 中的 guideSteps 数组：

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

修改样式

编辑 components/guide/guide.wxss：

/* 修改遮罩透明度 */
.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 中的 calculateContentPosition 方法。

功能特点

1. 智能位置计算

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

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

2. 高亮打洞效果

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

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

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

3. 步骤进度指示

底部圆点显示当前进度：

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

4. 防止交互穿透

// 阻止滚动
preventMove() {}

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

注意事项

1. 选择器必须唯一

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

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

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

2. 等待页面渲染

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

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

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

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

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

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

// 首页
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: 检查以下几点：

是否已经显示过（清除 storage）
选择器是否正确
目标元素是否已渲染
延迟时间是否足够

Q: 位置显示不对？

A: 检查：

目标元素是否被隐藏
页面是否完全渲染
增加 setTimeout 延迟时间

Q: 如何调试？

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

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

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

A: 控制台执行：

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

未来优化方向

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

开发者

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

9.0 KiB Raw Permalink Blame History Unescape Escape