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 插件市场导入：

插件地址：https://ext.dcloud.net.cn/plugin?name=ux-guide-page

最简单的用法

5 行代码就能跑起来：

<template><ux-guide-pagev-model:show="showGuide":slides="slides"storage-key="app_guide_shown"        @complete="onComplete"    /></template><scriptsetuplang="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: ['实时同步', '数据分析', '云端存储']            }        ]    }])functiononComplete() {// 引导完成，跳转到首页    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-pagestorage-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-pagev-model:show="showGuide":slides="slides"    @change="onChange"    @complete="onComplete"    @skip="onSkip"/>

functiononChange(index: number) {console.log('切换到第', index + 1, '页')// 可以在这里做埋点统计，看用户看了哪些页面}functiononComplete() {console.log('引导完成')// 引导完成后跳转到首页    uni.switchTab({ url: '/pages/index/index' })}functiononSkip() {console.log('用户跳过了引导')// 跳过引导也跳转到首页    uni.switchTab({ url: '/pages/index/index' })}

手动控制页面跳转

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

<template><ux-guide-pageref="guideRef"v-model:show="showGuide":slides="slides" /><button @click="goToPage(2)">跳转到第3页</button></template><scriptsetuplang="uts">import { ref } from'vue'const guideRef = ref()functiongoToPage(index: number) {    guideRef.value?.goToSlide(index)}</script>

组件暴露的方法：

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

控制显示元素

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

<!-- 隐藏跳过按钮和指示器 --><ux-guide-pagev-model:show="showGuide":slides="slides":show-skip="false":show-dots="false"/><!-- 隐藏头部和操作按钮 --><ux-guide-pagev-model:show="showGuide":slides="slides":show-header="false":show-actions="false"/>

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

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

高度可定制

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

1. 自定义背景

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

2. 自定义跳过按钮

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

3. 自定义操作按钮

<ux-guide-pagev-model:show="showGuide":slides="slides"><template #actions="{ isFirst, isLast, onPrev, onNext, onComplete }"><viewclass="custom-actions"><buttonv-if="!isFirst" @click="onPrev">上一步</button><buttonv-if="!isLast" @click="onNext">下一步</button><buttonv-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. 自定义页面 - 使用 slot 自定义整个页面内容
3. 自定义卡片 - 只自定义卡片的图标和内容
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、微信小程序，基本覆盖了大部分使用场景。

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

插件地址：https://ext.dcloud.net.cn/plugin?name=ux-guide-page

官方文档：https://uviewpro.cn/zh/ext/guidePage

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