forked from zhongyidian/super_video
feat: 添加 Husky 和 commit 限制配置
This commit is contained in:
zhongyidian committed
commit
27e0c23b3f
125 files changed
+5760
No files matched your search
@@ -0,0 +1,309 @@
|
||||
# 引导组件使用说明
|
||||
|
||||
## 组件概述
|
||||
|
||||
基于你提供的背景图片设计，创建了一套完整的引导组件系统，包含导学小龙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
|
||||
:show-skip="true"
|
||||
next-button-text="下一步"
|
||||
@next="handleNext"
|
||||
@skip="handleSkip"
|
||||
@complete="handleComplete"
|
||||
>
|
||||
<h3>欢迎使用短视频达人！</h3>
|
||||
<p>让我来为你介绍如何使用这个应用吧~</p>
|
||||
</GuideDragon>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { GuideDragon } from '@/components/guide'
|
||||
|
||||
const handleNext = () => {
|
||||
console.log('下一步')
|
||||
}
|
||||
|
||||
const handleSkip = () => {
|
||||
console.log('跳过')
|
||||
}
|
||||
|
||||
const handleComplete = () => {
|
||||
console.log('完成')
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### 多步骤引导
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<GuideSteps :steps="guideSteps" @complete="handleComplete" @skip="handleSkip" />
|
||||
</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" @skip="handleSkip">
|
||||
<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"
|
||||
@skip="handleSkip"
|
||||
: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安全
|
||||
|
||||
## 扩展功能
|
||||
|
||||
- 可以添加更多动画效果
|
||||
- 支持自定义小龙角色图片
|
||||
- 可以集成音效和语音提示
|
||||
- 支持引导进度保存和恢复
|
||||
Reference in new issue
Block a user