# 引导组件使用说明

## 组件概述

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

## 组件结构

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

## 组件功能

### 1. GuideDragon 组件

**功能特性：**

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

**Props：**

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

**Events：**

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

### 2. GuideSteps 组件

**功能特性：**

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

**Props：**

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

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

## 使用示例

### 基础使用

```vue
<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>
```

### 多步骤引导

```vue
<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>
```

### 灵活的写法

```vue
<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>
```

### 高级用法

```vue
<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 接口

```typescript
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  | -               | 停止自动播放     |

## 路由集成

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

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

## 注意事项

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

## 扩展功能

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