夜雨聆风做移动端 App 的都知道，新手引导页是用户第一次打开应用时看到的第一个界面。设计得好，能给用户留下专业、贴心的第一印象；设计得不好，可能直接劝退。
但说实话，写引导页挺烦的。要考虑多页滑动、卡片动画、跳过逻辑、本地存储记忆... 这些功能加起来，代码量不小。
最近我在开发一个 uni-app X 项目时，封装了一个引导页组件 ux-guide-page，把这些问题都解决了。今天分享出来，希望能帮到大家。
先看效果
这个组件支持：
✅ 多页滑动展示 ✅ 卡片动画 ✅ 自动记忆（用户看过一次就不再显示） ✅ 全平台支持（App、H5、微信小程序） ✅ 高度可定制
为什么要写这个组件
在写这个组件之前，我调研过市面上的一些引导页方案。大部分要么功能太简单，只能做基础的轮播图；要么太重，引入一堆用不到的依赖，最关键是没有前端适配。
我想要的引导页是这样的：
开箱即用：几行代码就能跑起来，不用自己处理滑动、动画这些底层逻辑 灵活配置：支持单卡片、多卡片、全自定义等多种模式 自动记忆：自动记录用户是否看过，不用自己写 storage 逻辑 动画流畅：卡片飞入效果要自然，不能太生硬 平台兼容：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，可以完全自定义：
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-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 个示例，从默认样式到完全自定义，覆盖了各种使用场景：
默认样式 - 开箱即用，无需额外配置 自定义页面 - 使用 slot 自定义整个页面内容 自定义卡片 - 只自定义卡片的图标和内容 Props 控制 - 通过 props 隐藏不需要的元素 完全自定义 - 使用所有 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
如果这篇文章对你有帮助，欢迎点赞收藏，也欢迎分享给有需要的朋友。
