更新记录

1.0.0（2025-01-09） 下载此版本

无

平台兼容性

智能分步引导组件

一个功能强大的智能分步引导组件，用于新手引导、功能介绍等场景。支持多步骤引导、动态适配、交互式教学等特性。

特性

• 🎯 多步骤引导：支持多个步骤的引导，每个步骤高亮不同的页面元素
• 📱 动态适配：自动检测目标元素的位置和大小，确保引导框正确显示
• 🎨 主题定制：支持浅色/深色主题切换
• 🔍 交互式教学：支持验证用户操作是否正确，提供实时反馈
• 🚀 易于使用：简单的API，丰富的配置选项
• 💫 动画效果：平滑的过渡动画和高亮效果
• 🎨 自适应布局：自动调整引导框位置，避免超出屏幕

安装

1. 在插件市场搜索"智能分步引导组件"
2. 点击安装到项目
3. 导入组件：

// pages.json中注册组件
{
  "easycom": {
    "custom": {
      "^smart-step-guide": "@/uni_modules/smart-step-guide/components/smart-step-guide/smart-step-guide.uvue"
    }
  }
}

使用示例

<template>
  <view class="content">
    <!-- 目标元素 -->
    <view class="guide-step1">第一步引导的目标</view>
    <view class="guide-step2">第二步引导的目标</view>

    <!-- 引导组件 -->
    <smart-step-guide
      ref="guide"
      :steps="steps"
      :theme="theme"
      :skip-enabled="true"
      @complete="onGuideComplete"
      @skip="onGuideSkip"
    />
  </view>
</template>

<script lang="uts">
export default {
  data() {
    return {
      theme: 'light',
      steps: [
        {
          target: '.guide-step1',
          title: '第一步',
          content: '这是第一步的引导说明',
          position: 'bottom'
        },
        {
          target: '.guide-step2',
          title: '第二步',
          content: '这是第二步的引导说明',
          position: 'right'
        }
      ]
    }
  },

  onReady() {
    // 页面加载完成后启动引导
    setTimeout(() => {
      this.startGuide()
    }, 1000)
  },

  methods: {
    startGuide() {
      const guide = this.$refs.guide as any
      if (guide) {
        guide.start()
      }
    },

    onGuideComplete() {
      uni.showToast({
        title: '引导完成！',
        icon: 'success'
      })
    },

    onGuideSkip() {
      uni.showToast({
        title: '已跳过引导',
        icon: 'none'
      })
    }
  }
}
</script>

<style>
.content {
  padding: 20px;
}
</style>

API

Props

步骤配置

每个步骤的配置对象包含以下属性：

interface Step {
  target: string;      // 目标元素选择器（使用class选择器，如 '.guide-step1'）
  title: string;       // 步骤标题
  content: string;     // 步骤说明内容
  position?: 'top' | 'bottom' | 'left' | 'right';  // 引导框位置
  validate?: () => boolean;  // 验证函数（可选）
}

Events

Methods

样式定制

主题切换

组件提供了 light 和 dark 两种主题，可以通过 theme 属性切换：

<smart-step-guide :theme="theme" />

自定义样式

可以通过CSS覆盖默认样式：

/* 修改遮罩层颜色 */
.mask-top,
.mask-right,
.mask-bottom,
.mask-left {
  background-color: rgba(0, 0, 0, 0.8);
}

/* 修改高亮边框样式 */
.highlight-border {
  border: 2px solid #ff6b00;
  box-shadow: 0 0 8px rgba(255, 107, 0, 0.6);
}

/* 修改引导框样式 */
.guide-box {
  background-color: #f8f8f8;
  border-radius: 12px;
}

最佳实践

1. 元素选择器

   • 推荐使用class选择器（如 .guide-step1）而不是id选择器
   • 确保选择器唯一且稳定，避免使用动态生成的选择器

2. 启动时机

   • 在 onReady 生命周期中启动引导
   • 对于动态加载的内容，确保内容加载完成后再启动
   • 建议添加适当的延时，确保页面完全渲染

3. 步骤设计

   • 控制步骤数量，建议不超过6-7步
   • 提供清晰简洁的说明文字
   • 合理设置引导框位置，避免遮挡重要内容

4. 交互设计

   • 提供跳过选项，不强制用户完成引导
   • 适当使用验证函数，确保用户理解操作
   • 在合适的时机触发引导（如首次访问、新功能上线）

常见问题

Q: 引导框位置不准确？

A:

• 确保目标元素已完全加载和渲染
• 检查元素选择器是否正确
• 适当延长启动延时
• 避免在元素动画过程中启动引导

Q: 如何处理动态内容？

A:

• 监听内容加载状态
• 在内容加载完成后再启动引导
• 使用 nextTick 或 setTimeout 确保渲染完成

Q: 如何实现条件引导？

A:

• 动态构建steps数组
• 使用本地存储记录引导状态
• 根据业务逻辑控制引导显示

更新日志

v1.0.0 (2024-01-20)

• 首次发布
• 支持基础引导功能
• 支持主题切换
• 支持多平台
• 实现自适应布局
• 添加动画效果