uview-plus

# Guide 首屏引导

打开

Guide 组件用于首屏全屏引导场景，支持多页滑动、跳过/完成交互，以及本地存储的“仅展示一次”能力。

# 平台差异说明

App（vue） App（nvue） H5 小程序
√ √ √ √

# 基本使用

通过 v-model:show 控制显隐，list 传入引导页数据。

<template>
  <up-guide
    v-model:show="show"
    :list="list"
    storage-key="demo-up-guide-once"
  />
</template>

<script setup>
import { ref } from 'vue'

const show = ref(true)
const list = ref([
  {
    image: '/static/uview/common/logo.png',
    title: '欢迎使用 uview-plus',
    desc: '一套跨端可复用的高质量组件库。'
  },
  {
    image: '/static/uview/common/gray-logo.png',
    title: '引导页支持多页滑动',
    desc: '可配置跳过、下一步和立即体验。'
  },
  {
    image: '/static/uview/common/logo.jpg',
    title: '只显示一次',
    desc: '默认内置本地存储记忆能力。'
  }
])
</script>

<script>
export default {
  data() {
    return {
      show: true,
      list: [
        {
          image: '/static/uview/common/logo.png',
          title: '欢迎使用 uview-plus',
          desc: '一套跨端可复用的高质量组件库。'
        },
        {
          image: '/static/uview/common/gray-logo.png',
          title: '引导页支持多页滑动',
          desc: '可配置跳过、下一步和立即体验。'
        },
        {
          image: '/static/uview/common/logo.jpg',
          title: '只显示一次',
          desc: '默认内置本地存储记忆能力。'
        }
      ]
    }
  }
}
</script>

# 仅展示一次与重置

  • once 默认为 true，点击“跳过”或“立即体验”后会写入本地存储。
  • 通过 storageKey 区分不同业务引导。
  • 可通过 ref 调用 reset() 清理已读标记后重新展示。
<template>
  <up-guide
    ref="guideRef"
    v-model:show="show"
    :list="list"
    storage-key="demo-up-guide-once"
  />
  <up-button text="重置首次标记" @click="resetGuide"></up-button>
</template>

<script setup>
import { ref } from 'vue'

const show = ref(false)
const guideRef = ref(null)

function resetGuide() {
  guideRef.value?.reset?.()
  show.value = true
}
</script>

<script>
export default {
  data() {
    return {
      show: false
    }
  },
  methods: {
    resetGuide() {
      this.$refs.guideRef && this.$refs.guideRef.reset()
      this.show = true
    }
  }
}
</script>

# 监听事件

<up-guide
  v-model:show="show"
  :list="list"
  @change="onChange"
  @skip="onSkip"
  @finish="onFinish"
  @close="onClose"
/>

# 右侧演示页面源代码地址

点击以下链接以查看右侧演示页面的源码


 github  gitee

# API

# Props

参数 说明 类型 默认值 可选值
show 是否显示引导层（支持 v-model:show） Boolean false true
list 引导页数据 Array [] -
storageKey 本地存储 key String up-guide-default -
once 是否只展示一次 Boolean true false
showSkip 是否显示跳过按钮 Boolean true false
skipText 跳过按钮文案 String 跳过 -
nextText 非最后一页按钮文案 String 下一步 -
finishText 最后一页按钮文案 String 立即体验 -
indicator 是否显示页码指示器 Boolean true false
bgColor 页面默认背景色 String #111111 -
zIndex 组件层级 String | Number 10075 -

# list 数据项（GuideItem）

字段 说明 类型 默认值
image 引导图地址（建议必填） String -
title 标题 String -
desc 描述文案 String -
backgroundColor 当前页背景色（优先级高于 bgColor） String -

# Events

事件名 说明 回调参数
update:show 显隐变化时触发 show(Boolean)
change 切页时触发 { current }
skip 点击跳过时触发 -
finish 点击立即体验时触发 -
close 关闭引导层时触发 -

# Methods

通过 ref 调用。

方法名 说明 参数
open 打开引导层并回到第一页 -
close 关闭引导层 remember(Boolean，默认 true)
reset 清理一次性展示标记 -

← Popover 弹窗提示 →