BizGuide 新手引导

分步高亮引导：box-shadow 挖孔遮罩 + 主题色高亮环 + 贴目标说明卡片（空间不足自动翻转）。SaaS 开屏引导、新功能发布、复杂表单首次填写的标准件。目标按 CSS 选择器定位，元素不在视口时自动滚动居中后测量；目标缺失该步卡片居中展示。

基础用法

状态

steps 声明目标选择器与文案；v-model 控制开关（关闭自动重置第一步）。

<script setup lang="ts">
/** 基础用法：三步引导（搜索框 → 状态筛选 → 操作按钮） */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizGuide } from 'vue3-ep-biz-lib'
import type { BizGuideStep } from 'vue3-ep-biz-lib'

const active = ref(false)

const steps: BizGuideStep[] = [
  { target: '.demo-guide-search', title: '快速检索', content: '支持订单号 / 手机号 / 收货人模糊搜索，回车立即执行。' },
  { target: '.demo-guide-status', title: '状态筛选', content: '按订单状态过滤列表，支持多选组合。', placement: 'bottom' },
  { target: '.demo-guide-action', title: '批量操作', content: '勾选订单后可批量发货 / 导出。' },
]

const onClose = (reason: 'done' | 'skip' | 'mask'): void => {
  if (reason === 'done') ElMessage.success('引导完成')
}
</script>

<template>
  <div>
    <div class="toolbar">
      <ElInput class="demo-guide-search" placeholder="搜索订单" style="width: 200px" />
      <ElSelect class="demo-guide-status" placeholder="状态" style="width: 120px" />
      <ElButton class="demo-guide-action" type="primary">批量发货</ElButton>
    </div>
    <ElButton @click="active = true">开始引导</ElButton>
    <BizGuide v-model="active" :steps="steps" @close="onClose" />
  </div>
</template>

<style scoped>
.toolbar {
  display: flex;
  gap: 8px;
  align-items: center;
  margin-bottom: 16px;
  padding: 12px;
  border: 1px dashed var(--el-border-color);
  border-radius: var(--el-border-radius-base);
}
</style>

显示代码

自定义内容 · 居中开屏

快捷入口

八个常用功能格子（示意）

无 target 的步骤卡片居中（开屏欢迎页）；content 插槽按步骤自定义卡片内容。

<script setup lang="ts">
/** 进阶：content 插槽自定义卡片内容 + 无目标居中（开屏引导） */
import { ref } from 'vue'
import { BizGuide } from 'vue3-ep-biz-lib'
import type { BizGuideStep } from 'vue3-ep-biz-lib'

const active = ref(false)

const steps: BizGuideStep[] = [
  {
    title: '欢迎使用运营平台',
    content: '接下来用 20 秒带你熟悉核心功能，随时可跳过。',
  },
  { target: '.demo-guide-entry', title: '快捷入口', content: '常用功能一键直达，支持自定义。' },
]
</script>

<template>
  <div>
    <ElCard class="demo-guide-entry" shadow="never">
      <template #header>快捷入口</template>
      八个常用功能格子（示意）
    </ElCard>
    <ElButton style="margin-top: 12px" @click="active = true">开屏引导</ElButton>
    <BizGuide v-model="active" :steps="steps" done-text="开始使用">
      <template #content="{ index: i }">
        <div v-if="i === 0" style="margin-top: 8px; font-size: 12px; color: var(--el-text-color-secondary)">
          插槽自定义内容：第一条无 target，卡片居中展示
        </div>
      </template>
    </BizGuide>
  </div>
</template>

显示代码

表单五步引导

单据类型

差旅报销

金额

发生日期

发票附件

placement 四向覆盖（上/下/左/右贴边）；目标自动滚动进入视口后测量。

<script setup lang="ts">
/** 表单页五步引导：字段逐个高亮（placement 覆盖四向） */
import { ref } from 'vue'
import { BizGuide } from 'vue3-ep-biz-lib'
import type { BizGuideStep } from 'vue3-ep-biz-lib'

const active = ref(false)

const steps: BizGuideStep[] = [
  { target: '.demo-gf-type', title: '第 1 步 · 单据类型', content: '先选单据类型，后续字段随类型联动。', placement: 'bottom' },
  { target: '.demo-gf-amount', title: '第 2 步 · 报销金额', content: '含税金额，自动折算未税。', placement: 'right' },
  { target: '.demo-gf-date', title: '第 3 步 · 发生日期', content: '仅可选近 90 天。', placement: 'left' },
  { target: '.demo-gf-attach', title: '第 4 步 · 发票附件', content: '每张发票单独上传，支持批量。', placement: 'top' },
  { target: '.demo-gf-submit', title: '第 5 步 · 提交审批', content: '提交后进入财务审批流，可随时撤回。', placement: 'top' },
]
</script>

<template>
  <div>
    <div class="form">
      <div class="row"><span class="lab">单据类型</span><ElSelect class="demo-gf-type" style="width: 200px" placeholder="差旅报销" /></div>
      <div class="row"><span class="lab">金额</span><ElInputNumber class="demo-gf-amount" style="width: 200px" placeholder="0.00" /></div>
      <div class="row"><span class="lab">发生日期</span><ElDatePicker class="demo-gf-date" style="width: 200px" placeholder="2026-09-29" /></div>
      <div class="row"><span class="lab">发票附件</span><ElButton class="demo-gf-attach">上传发票</ElButton></div>
      <div class="row"><ElButton class="demo-gf-submit" type="primary">提交审批</ElButton></div>
    </div>
    <ElButton style="margin-top: 12px" @click="active = true">开始表单引导</ElButton>
    <BizGuide v-model="active" :steps="steps" />
  </div>
</template>

<style scoped>
.form {
  max-width: 380px;
  padding: 16px;
  border: 1px dashed var(--el-border-color);
  border-radius: var(--el-border-radius-base);
}
.row {
  display: flex;
  align-items: center;
  gap: 12px;
  margin-bottom: 14px;
}
.lab {
  width: 70px;
  font-size: 13px;
  color: var(--el-text-color-regular);
}
</style>

显示代码

轻引导（国际化文案）

mask-closable 点击遮罩即离开；按钮文案自定义（close 事件区分 done/skip/mask）。

<script setup lang="ts">
/** 轻引导：mask-closable 点击遮罩即走 + 自定义按钮文案 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizGuide } from 'vue3-ep-biz-lib'
import type { BizGuideStep } from 'vue3-ep-biz-lib'

const active = ref(false)
const steps: BizGuideStep[] = [
  { target: '.demo-lt-a', title: 'What’s New', content: 'Click the mask to leave at any time.' },
  { target: '.demo-lt-b', title: 'Done', content: 'That’s all. Enjoy!' },
]

const onClose = (reason: 'done' | 'skip' | 'mask'): void => {
  ElMessage.info(`closed by: ${reason}`)
}
</script>

<template>
  <div>
    <div style="display: flex; gap: 10px; margin-bottom: 12px">
      <ElButton class="demo-lt-a">Feature A</ElButton>
      <ElButton class="demo-lt-b">Feature B</ElButton>
    </div>
    <ElButton @click="active = true">Start light tour</ElButton>
    <BizGuide
      v-model="active"
      :steps="steps"
      mask-closable
      next-text="Next"
      prev-text="Back"
      done-text="Got it"
      skip-text="Skip"
      @close="onClose"
    />
  </div>
</template>

显示代码

条件目标兜底

先展开高级面板

关掉开关再引导：第 2 步目标缺失 → 卡片居中而不是报错

目标元素 v-if 不存在时该步卡片居中展示，引导流不断。

<script setup lang="ts">
/** 条件目标：目标元素 v-if 不存在时该步卡片居中兜底 */
import { ref } from 'vue'
import { BizGuide } from 'vue3-ep-biz-lib'
import type { BizGuideStep } from 'vue3-ep-biz-lib'

const active = ref(false)
const advancedOpen = ref(false)

const steps: BizGuideStep[] = [
  { target: '.demo-cd-basic', title: '基础查询', content: '日常用法在这里就够了。' },
  { target: '.demo-cd-advanced', title: '高级筛选', content: '若该面板未展开（目标不存在），本卡片自动居中兜底展示。' },
]
</script>

<template>
  <div>
    <div style="display: flex; gap: 10px; align-items: center; margin-bottom: 12px">
      <ElButton class="demo-cd-basic">基础查询</ElButton>
      <ElButton v-if="advancedOpen" class="demo-cd-advanced">高级筛选面板</ElButton>
      <ElSwitch v-model="advancedOpen" active-text="先展开高级面板" />
    </div>
    <ElButton @click="active = true">开始引导</ElButton>
    <BizGuide v-model="active" :steps="steps" />
    <div class="tip">关掉开关再引导：第 2 步目标缺失 → 卡片居中而不是报错</div>
  </div>
</template>

<style scoped>
.tip {
  margin-top: 10px;
  font-size: 13px;
  color: var(--el-text-color-secondary);
}
</style>

显示代码

不再提示

不再提示

未记忆

skip + localStorage 记忆，二次进入自动跳过（SaaS 常见交互）。

<script setup lang="ts">
/** 不再提示：localStorage 记忆 skip，二次进入自动跳过 */
import { onMounted, ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizGuide } from 'vue3-ep-biz-lib'
import type { BizGuideStep } from 'vue3-ep-biz-lib'

const KEY = 'biz-guide-demo-no-more'
const active = ref(false)
const remembered = ref(false)

const steps: BizGuideStep[] = [
  { target: '.demo-nm-entry', title: '新功能', content: '看完可勾选「不再提示」，下次进入不再弹出。' },
]

onMounted(() => {
  remembered.value = window.localStorage.getItem(KEY) === '1'
})

const onClose = (reason: 'done' | 'skip' | 'mask'): void => {
  if (reason === 'skip' && noMore.value) {
    window.localStorage.setItem(KEY, '1')
    remembered.value = true
    ElMessage.success('已记住，刷新后不再自动弹出')
  }
}

const noMore = ref(false)
const reset = (): void => {
  window.localStorage.removeItem(KEY)
  remembered.value = false
  ElMessage.info('已重置记忆')
}
</script>

<template>
  <div>
    <div style="display: flex; gap: 10px; align-items: center; margin-bottom: 12px">
      <ElButton class="demo-nm-entry" type="primary">新功能入口</ElButton>
      <ElCheckbox v-model="noMore">不再提示</ElCheckbox>
    </div>
    <div style="display: flex; gap: 8px">
      <ElButton @click="active = true">打开引导</ElButton>
      <ElButton v-if="remembered" text type="primary" @click="reset">重置「不再提示」记忆</ElButton>
    </div>
    <BizGuide v-model="active" :steps="steps" @close="onClose" />
    <div class="tip">{{ remembered ? '已记住跳过：真实项目在页面 onMounted 判断后不再 setActive' : '未记忆' }}</div>
  </div>
</template>

<style scoped>
.tip {
  margin-top: 10px;
  font-size: 13px;
  color: var(--el-text-color-secondary);
}
</style>

显示代码

Props

属性名	类型	默认值	说明
v-model	boolean	false	引导开关
steps	BizGuideStep[]	[]	步骤定义
skippable	boolean	true	显示跳过按钮
mask-closable	boolean	false	点击遮罩关闭
next-text / prev-text / done-text / skip-text	string	下一步/上一步/完成/跳过引导	按钮文案

BizGuideStep：target 选择器（缺省居中）、title、content、placement（top / bottom（默认）/ left / right，空间不足自动翻转）。

Events

事件名	参数	说明
update:model-value	(value: boolean)	开关变化
change	(index: number)	步骤切换
close	(reason: 'done' | 'skip' | 'mask')	引导结束（区分完成 / 跳过 / 点遮罩）

Slots

插槽名	说明
content	卡片补充内容（作用域：step、index）

Expose

属性/方法	说明
next / prev / goTo	编程式步进（goTo(index) 跳指定步）