super_video/src/components/Guide/README.md

引导组件使用说明

组件概述

基于你提供的背景图片设计，创建了一套完整的引导组件系统，包含导学小龙UI和步骤管理功能。

组件结构

src/components/guide/
├── GuideDragon.vue      # 导学小龙UI组件
├── GuideSteps.vue       # 步骤管理组件
├── index.ts            # 组件导出文件
└── README.md           # 使用说明

组件功能

1. GuideDragon 组件

功能特性：

• 基于1920*1080设计稿的等比例缩放
• 导学小龙UI区域（左侧）
• 小龙角色区域（右侧）
• 操作按钮区域（底部）
• 支持自定义内容插槽
• 响应式动画效果

Props：

interface Props {
  showSkip?: boolean // 是否显示跳过按钮
  nextButtonText?: string // 下一步按钮文本
  currentStep?: number // 当前步骤
  totalSteps?: number // 总步骤数
}

Events：

interface Emits {
  (e: 'next'): void // 下一步事件
  (e: 'skip'): void // 跳过事件
  (e: 'complete'): void // 完成事件
}

2. GuideSteps 组件

功能特性：

• 多步骤引导管理
• 自动步骤切换
• 自定义步骤内容
• 步骤跳转功能
• 引导重置功能

Props：

interface Props {
  steps: GuideStep[] // 引导步骤配置
  autoStart?: boolean // 是否自动开始
}

interface GuideStep {
  id: string // 步骤ID
  content: string // 步骤内容（支持HTML/()=>h()）
  nextText?: string // 下一步按钮文本
}

使用示例

基础使用

<template>
  <GuideDragon
    next-button-text="下一步"
    @next="handleNext"
  >
    <h3>欢迎使用短视频达人！</h3>
    <p>让我来为你介绍如何使用这个应用吧~</p>
  </GuideDragon>
</template>

<script setup lang="ts">
import { GuideDragon } from '@/components/guide'

const handleNext = () => {
  console.log('下一步')
}

const handleComplete = () => {
  console.log('完成')
}
</script>

多步骤引导

<template>
  <GuideSteps
    :steps="guideSteps"
    @complete="handleComplete"
  />
</template>

<script setup lang="ts">
import { GuideSteps } from '@/components/guide'

const guideSteps = [
  {
    id: 'welcome',
    content: '欢迎来到短视频达人应用！我是你的导学小龙...',
    nextText: '开始学习',
  },
  {
    id: 'features',
    content: '我们的应用包含以下核心功能...',
    nextText: '了解详情',
  },
]

const handleComplete = () => {
  console.log('引导完成')
}
</script>

灵活的写法

<template>
  <GuideSteps @complete="handleComplete">
    <GuideStepsItem>欢迎来到短视频达人应用！我是你的导学小龙</GuideStepsItem>
    <GuideStepsItem>
      <p>
        现在让我们一起走进
        <em class="text-red">Vlog</em>
        的世界。简单说，
        <em class="text-red">Vlog</em>
        就是用视频记录生活的一种方式--它像一本会动的日记能把我们身边的小事、瞬间的心情，通过镜头变得生动又具体。
      </p>
    </GuideStepsItem>
  </GuideSteps>
</template>

<script setup lang="ts">
import { GuideSteps, GuideStepsItem } from '@/components/guide'

const handleComplete = () => {
  console.log('引导完成')
}
</script>

高级用法

<template>
  <GuideSteps
    @complete="handleComplete"
    :keyboard-navigation="true"
    :auto-play-interval="3000"
  >
    <GuideStepsItem>欢迎来到短视频达人应用！</GuideStepsItem>
    <GuideStepsItem>这里是第二个步骤</GuideStepsItem>
    <GuideStepsItem>最后一步</GuideStepsItem>
  </GuideSteps>
</template>

<script setup lang="ts">
import { GuideSteps, GuideStepsItem } from '@/components/guide'

const handleComplete = () => {
  console.log('引导完成')
}

const handleSkip = () => {
  console.log('跳过引导')
}
</script>

组件特性

1. 双模式支持

• 配置模式: 通过 steps 属性传递步骤配置
• 插槽模式: 通过 <GuideStepsItem> 组件定义步骤内容

2. 键盘导航

• 支持方向键导航（左右箭头）
• 空格键前进，ESC键跳过
• 可配置是否启用键盘导航

3. 自动播放

• 支持自动播放模式
• 可配置播放间隔时间
• 自动播放时支持暂停和恢复

4. 智能按钮显示

• 自动在每页内容后添加"继续"按钮
• 最后一页不显示"继续"按钮
• 按钮与文字在同一行，不换行

5. 响应式设计

• 基于useScale hook的等比例缩放
• 适配不同屏幕尺寸
• 保持设计稿比例

6. 动画效果

• 淡入动画
• 小龙角色弹跳动画
• 平滑过渡效果

7. 视觉设计

• 渐变背景色
• 圆角边框设计
• 阴影效果
• 现代化UI风格

Props 说明

GuideSteps Props

属性名	类型	默认值	说明
steps	GuideStep[]	[]	引导步骤配置（插槽模式时可省略）
autoStart	boolean	true	是否自动开始
keyboardNavigation	boolean	true	是否启用键盘导航
autoPlayInterval	number	0	自动播放间隔时间（毫秒），0表示不自动播放

GuideStep 接口

interface GuideStep {
  id: string
  title?: string
  content: string
  nextText?: string
}

Events 说明

事件名	参数	说明
complete	-	引导完成时触发
skip	-	跳过引导时触发
step-change	(step: GuideStep | null, index: number)	步骤变更时触发

方法说明

通过 ref 可以调用以下方法：

方法名	参数	说明
goToStep	(index: number)	跳转到指定步骤
resetGuide	-	重置引导到第一步
startAutoPlay	-	开始自动播放
stopAutoPlay	-	停止自动播放

路由集成

引导页面已集成到路由系统中：

// 路由配置
{
  path: '/guide',
  name: 'Guide',
  component: () => import('@/views/guide/index.vue'),
  meta: {
    title: '使用引导'
  }
}

注意事项

1. 图片资源：需要将背景图片放置在 src/assets/images/guide/ 目录下
2. 样式兼容：组件使用Tailwind CSS，确保项目已正确配置
3. 响应式：组件会自动适配不同屏幕尺寸
4. 自定义内容：支持HTML格式的内容，注意XSS安全

扩展功能

• 可以添加更多动画效果
• 支持自定义小龙角色图片
• 可以集成音效和语音提示
• 支持引导进度保存和恢复