uni-app X 全屏引导页组件，一套支持 App、H5、小程序多端引导

做移动端 App 的都知道，新手引导页是用户第一次打开应用时看到的第一个界面。设计得好，能给用户留下专业、贴心的第一印象；设计得不好，可能直接劝退。

但说实话，写引导页挺烦的。要考虑多页滑动、卡片动画、跳过逻辑、本地存储记忆... 这些功能加起来，代码量不小。

最近我在开发一个 uni-app X 项目时，封装了一个引导页组件 ux-guide-page，把这些问题都解决了。今天分享出来，希望能帮到大家。

先看效果

这个组件支持：

• ✅ 多页滑动展示
• ✅ 卡片动画
• ✅ 自动记忆（用户看过一次就不再显示）
• ✅ 全平台支持（App、H5、微信小程序）
• ✅ 高度可定制

为什么要写这个组件

在写这个组件之前，我调研过市面上的一些引导页方案。大部分要么功能太简单，只能做基础的轮播图；要么太重，引入一堆用不到的依赖，最关键是没有前端适配。

我想要的引导页是这样的：

1. 开箱即用：几行代码就能跑起来，不用自己处理滑动、动画这些底层逻辑
2. 灵活配置：支持单卡片、多卡片、全自定义等多种模式
3. 自动记忆：自动记录用户是否看过，不用自己写 storage 逻辑
4. 动画流畅：卡片飞入效果要自然，不能太生硬
5. 平台兼容：App、H5、小程序都要能跑

基于这些需求，我封装了 ux-guide-page。

安装

直接在 DCloud 插件市场导入：

插件地址 ：ext.dcloud.net.cn/plugin?name...

最简单的用法

5 行代码就能跑起来：

<template>
    <ux-guide-page 
        v-model:show="showGuide" 
        :slides="slides"
        storage-key="app_guide_shown"
        @complete="onComplete"
    />
</template>

<script setup lang="uts">
import { ref } from 'vue'

const showGuide = ref(true)

const slides = ref([
    {
        cards: [
            {
                icon: '🚀',
                title: '快速上手',
                desc: '简单几步即可开始使用',
                position: 'center',
                features: ['一键登录', '智能推荐', '个性定制']
            }
        ]
    },
    {
        cards: [
            {
                icon: '💡',
                title: '核心功能',
                desc: '探索应用的强大功能',
                position: 'center',
                features: ['实时同步', '数据分析', '云端存储']
            }
        ]
    }
])

function onComplete() {
    // 引导完成，跳转到首页
    uni.switchTab({ url: '/pages/index/index' })
}
</script>

就这么简单，一个带滑动、动画、自动记忆的引导页就做好了。

数据结构说明

使用组件前，先了解一下 slides 的数据结构：

type OnboardingCard = {
    icon: string              // 卡片图标，可以是 emoji 或图片 URL
    title: string             // 卡片标题
    desc: string              // 卡片描述
    position: 'top-left' | 'top-right' | 'center' | 'bottom-left' | 'bottom-right'
    features?: string[]       // 特性列表（可选）
    size?: 'small' | 'medium' | 'large'  // 卡片大小（可选，默认 medium）
    delay?: number            // 动画延迟时间，单位毫秒（可选）
}

type OnboardingSlide = {
    cards: OnboardingCard[]   // 该页面的卡片数组
}

• position 控制卡片位置，支持左上、右上、居中、左下、右下五个位置
• size 控制卡片大小，small 占 40%，medium 占 44%，large 占 48%
• delay 可以自定义卡片动画延迟，如果不设置会按顺序自动计算（每个卡片间隔 150ms）

多卡片布局

除了单卡片居中，还支持一页放多个卡片，分别放在左上、右上、左下、右下四个位置：

const multiCardSlides = ref([
    {
        cards: [
            {
                icon: '🎉',
                title: '功能介绍',
                desc: '了解我们的核心功能，探索更多可能性',
                position: 'center',
                size: 'medium',
                features: ['智能推荐', '数据分析', '多端同步', '云端存储']
            }
        ]
    },
    {
        cards: [
            {
                icon: '⚡',
                title: '快速开始',
                desc: '三步即可上手，轻松开启高效之旅',
                position: 'center',
                size: 'medium',
                features: ['一键安装', '自动配置', '即时使用', '在线帮助']
            }
        ]
    },
    {
        cards: [
            {
                icon: '🛡️',
                title: '安全保障',
                desc: '企业级安全防护，守护您的数据资产',
                position: 'center',
                size: 'medium',
                features: ['数据加密', '权限管理', '操作审计', '备份恢复']
            }
        ]
    },
    {
        cards: [
            {
                icon: '🚀',
                title: '持续升级',
                desc: '定期更新迭代，为您提供更好的体验',
                position: 'center',
                size: 'medium',
                features: ['功能更新', '性能优化', 'Bug修复', '新特性']
            }
        ]
    }
])

每个卡片会依次进入，动画效果很流畅。你可以通过 delay 参数控制每个卡片的入场时机，制造更丰富的视觉效果。

自动记忆功能

这个功能很实用。通过 storage-key 参数，组件会自动把"用户是否看过引导页"这个状态存到本地。

<ux-guide-page 
    storage-key="app_guide_shown"
    ...
/>

下次用户打开 App，如果已经看过引导页，就不会再次显示了。

更贴心的是，组件还会自动拼接应用版本号。比如你的应用版本是 1.2.0，实际存储的键名是 app_guide_shown_1.2.0。这样升级应用后，可以重新展示新版本的引导页，让用户了解新功能。

如果你想强制显示引导页（比如测试时），可以手动清除存储：

// 清除引导页记录
uni.removeStorageSync('app_guide_shown')
// 或者清除特定版本的记录
uni.removeStorageSync('app_guide_shown_1.2.0')

事件监听

组件提供了三个事件，方便你做业务处理：

<ux-guide-page 
    v-model:show="showGuide" 
    :slides="slides"
    @change="onChange"
    @complete="onComplete"
    @skip="onSkip"
/>

function onChange(index: number) {
    console.log('切换到第', index + 1, '页')
    // 可以在这里做埋点统计，看用户看了哪些页面
}

function onComplete() {
    console.log('引导完成')
    // 引导完成后跳转到首页
    uni.switchTab({ url: '/pages/index/index' })
}

function onSkip() {
    console.log('用户跳过了引导')
    // 跳过引导也跳转到首页
    uni.switchTab({ url: '/pages/index/index' })
}

手动控制页面跳转

有时候你可能需要在引导页里做一些交互，比如点击某个卡片跳转到特定页面。这时候可以通过 ref 获取组件实例，手动控制页面跳转：

<template>
    <ux-guide-page ref="guideRef" v-model:show="showGuide" :slides="slides" />
    <button @click="goToPage(2)">跳转到第3页</button>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const guideRef = ref()

function goToPage(index: number) {
    guideRef.value?.goToSlide(index)
}
</script>

组件暴露的方法：

• goToSlide(index) - 跳转到指定页面
• handleNext() - 切换到下一页
• handlePrev() - 切换到上一页
• handleComplete() - 完成引导

控制显示元素

如果你不需要某些默认元素，可以通过 props 隐藏它们：

<!-- 隐藏跳过按钮和指示器 -->
<ux-guide-page 
    v-model:show="showGuide" 
    :slides="slides"
    :show-skip="false"
    :show-dots="false"
/>

<!-- 隐藏头部和操作按钮 -->
<ux-guide-page 
    v-model:show="showGuide" 
    :slides="slides"
    :show-header="false"
    :show-actions="false"
/>

还可以禁用滑动切换，让用户只能通过按钮操作：

<ux-guide-page 
    v-model:show="showGuide" 
    :slides="slides"
    :enable-swipe="false"
/>

高度可定制

如果默认样式不满足需求，组件提供了 7 个 slot，可以完全自定义：

Slot 名称	用途	作用域参数
background	自定义背景	-
skip	自定义跳过按钮	{ onSkip }
header	自定义头部	{ current, total }
slide	自定义页面内容	{ slide, index, isActive }
card-icon	自定义卡片图标	{ card, index, cIndex }
card-content	自定义卡片内容	{ card, index, cIndex }
dots	自定义指示器	{ current, total }
actions	自定义操作按钮	{ isFirst, isLast, onPrev, onNext, onComplete }

1. 自定义背景

<ux-guide-page v-model:show="showGuide" :slides="slides">
    <template #background>
        <view class="custom-bg">
            <view class="gradient-circle"></view>
        </view>
    </template>
</ux-guide-page>

2. 自定义跳过按钮

<ux-guide-page v-model:show="showGuide" :slides="slides">
    <template #skip="{ onSkip }">
        <view class="custom-skip" @click="onSkip">
            <text>SKIP</text>
        </view>
    </template>
</ux-guide-page>

3. 自定义操作按钮

<ux-guide-page v-model:show="showGuide" :slides="slides">
    <template #actions="{ isFirst, isLast, onPrev, onNext, onComplete }">
        <view class="custom-actions">
            <button v-if="!isFirst" @click="onPrev">上一步</button>
            <button v-if="!isLast" @click="onNext">下一步</button>
            <button v-if="isLast" @click="onComplete">开始使用</button>
        </view>
    </template>
</ux-guide-page>

平台适配注意事项

开发过程中踩过几个坑，这里分享一下：

1. 渐变背景要三个色值

如果你要设置渐变背景色，App 端 linear-gradient 需要三个色值才能生效：

/* ✅ 正确 */
.custom-bg {
    background: linear-gradient(180deg, #667eea 0%, #764ba2 50%, #764ba2 100%);
}

/* ❌ 错误 - 两个色值在 App 端不生效 */
.custom-bg {
    background: linear-gradient(180deg, #667eea 0%, #764ba2 100%);
}

2. 动画要用 transition

App 端不支持 @keyframes，请使用 transition：

/* ✅ 正确 */
.card {
    opacity: 0;
    transform: translateY(30rpx);
    transition: all 0.4s ease;
}
.card-visible {
    opacity: 1;
    transform: translateY(0);
}

/* ❌ 错误 - App 端不支持 */
@keyframes fadeIn {
    from { opacity: 0; }
    to { opacity: 1; }
}

3. 注意 rpx 单位

uni-app X 中推荐使用 rpx 作为尺寸单位，可以自动适配不同屏幕：

.card {
    width: 300rpx;      /* ✅ 推荐 */
    padding: 20rpx;
    border-radius: 16rpx;
}

完整示例代码

我准备了 5 个示例，从默认样式到完全自定义，覆盖了各种使用场景：

1. 多卡片样式 - 开箱即用，无需额外配置即可实现多卡片引导
2. 自定义卡片 - 只自定义卡片的图标和内容
3. 自定义页面 - 使用 slot 自定义整个页面内容
4. Props 控制 - 通过 props 隐藏不需要的元素
5. 完全自定义 - 使用所有 slot + props 实现完全定制

你可以在文档页下载完整示例代码，直接复制到你的项目中使用。

实际应用案例

下面是一个电商 App 的引导页配置示例：

const ecommerceSlides = ref([
    {
        cards: [
            {
                icon: '🛍️',
                title: '海量商品',
                desc: '精选百万优质商品，满足你的各种需求',
                position: 'center',
                features: ['品质保证', '七天无理由', '极速发货']
            }
        ]
    },
    {
        cards: [
            {
                icon: '💰',
                title: '优惠多多',
                desc: '新人专享大礼包，首单立减 50 元',
                position: 'center',
                features: ['新人礼包', '每日签到', '积分抵现']
            }
        ]
    },
    {
        cards: [
            {
                icon: '🚚',
                title: '极速配送',
                desc: '全国 300+ 城市次日达',
                position: 'center',
                features: ['次日达', '实时追踪', '送货上门']
            }
        ]
    }
])

最后

这个组件是基于 uni-app X 开发的，所以仅支持 uni-app X 项目。如果你还在用 uni-app Vue2/Vue3，可能需要做一些适配。

目前组件已经支持 App（安卓、iOS、鸿蒙）、H5、微信小程序，基本覆盖了大部分使用场景。

如果你正好需要做一个引导页，可以试试这个组件。有问题欢迎在插件评论区留言，我会及时回复。

插件地址 ：ext.dcloud.net.cn/plugin?name...

官方文档 ：uviewpro.cn/zh/ext/guid...

如果这篇文章对你有帮助，欢迎点赞收藏，也欢迎分享给有需要的朋友。