更新记录

1.0.2（2025-11-13） 下载此版本

• ✨ 新增首次显示功能
  • 新增 showOnlyOnce 配置项，支持只在首次进入时显示
  • 新增 storageKey 配置项，用于自定义存储标识
  • 新增 reset() 方法，支持重置显示状态
  • show() 方法支持 force 参数，可强制显示忽略首次限制
  • 自动使用页面路径作为默认存储标识
  • 完成或关闭指引后自动记录显示状态

1.0.1（2025-10-30） 下载此版本

• 自动判断上下方可用空间
  • 优先显示在高亮区域上方
  • 自动避让固定元素

1.0.0（2025-10-22） 下载此版本

• 初始版本发布
• 支持多步骤流程展示
• 支持高亮区域自动定位
• 支持对话框智能定位（自动避让）
• 支持自定义按钮文本
• 支持蒙版点击关闭配置
• 支持关闭按钮
• 兼容 H5 和微信小程序
• 提供 show、hide 等方法
• 提供 finish、close、step-change 等事件

平台兼容性

uni-app(4.83)

process-guide 流程指引蒙版组件

组件名：process-guide 版本：v1.0.0 作者：产权小程序团队

process-guide 是一个功能强大的流程指引蒙版组件，专为新手引导和操作指引场景设计。支持多步骤流程展示、智能滚动定位、高亮区域自动适配、固定元素避让等高级功能。

快速开始

安装

在 HBuilderX 中，点击右上角的 使用 HBuilderX 导入插件 按钮，或者下载插件 ZIP 包解压到项目的 uni_modules/process-guide 目录下。

使用

由于使用了 uni_modules 方式，组件会自动注册，无需手动引入，可以直接在页面中使用：

<template>
  <process-guide
    ref="processGuideRef"
    :steps="guideSteps"
    @finish="handleFinish"
  />
</template>

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

const guideSteps = ref([
  {
    title: '第一步',
    content: '这是第一步的说明',
    highlight: '#step1'
  }
]);

const handleFinish = () => {
  console.log('完成指引');
};
</script>

功能特性

• ✅ 多步骤流程展示 - 支持任意数量的引导步骤
• ✅ 高亮区域自动定位 - 精准定位目标元素并高亮显示
• ✅ 智能滚动定位 - 自动滚动到高亮元素，支持元素高度检测和智能对齐策略
• ✅ 固定元素适配 - 支持顶部/底部固定元素避让，确保高亮区域完全可见
• ✅ 禁止页面滚动 - 显示引导时自动禁止页面滚动，防止用户误操作
• ✅ 对话框智能定位 - 自动计算最佳位置，避免遮挡和超出屏幕
• ✅ 灵活的按钮配置 - 第一步/中间步骤/最后一步显示不同按钮组合
• ✅ 支持关闭操作 - 提供关闭按钮和蒙版点击关闭（可配置）
• ✅ 响应式设计 - 支持主题变量定制
• ✅ 完整的 API - 提供 show、hide 等方法和丰富的事件
• ✅ 跨平台兼容 - 完美兼容 H5 和微信小程序

平台兼容性

注: 所有平台均已测试通过，H5 和微信小程序经过深度优化

Props

Events

Methods

使用示例

基础使用

<template>
  <view>
    <!-- 流程指引组件 -->
    <process-guide
      ref="processGuideRef"
      :steps="guideSteps"
      :finalButtonText="'开始模拟'"
      @finish="handleFinish"
      @close="handleClose"
    />

    <!-- 页面内容 -->
    <view class="page-content">
      <view class="step1" id="step1">步骤1区域</view>
      <view class="step2" id="step2">步骤2区域</view>
      <view class="step3" id="step3">步骤3区域</view>
    </view>
  </view>
</template>

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

const processGuideRef = ref(null);

const guideSteps = ref([
  {
    title: '第一步',
    content: '这是第一步的说明内容',
    highlight: '#step1'  // 高亮区域的选择器
  },
  {
    title: '第二步',
    content: '这是第二步的说明内容',
    highlight: '#step2'
  },
  {
    title: '第三步',
    content: '这是第三步的说明内容',
    highlight: '#step3'
  }
]);

const handleFinish = () => {
  console.log('用户完成了流程指引');
  // 执行相关业务逻辑
};

const handleClose = () => {
  console.log('用户关闭了流程指引');
};
</script>

首次显示功能（推荐）

适用于新手引导场景，只在用户首次进入页面时显示，后续不再自动显示：

<template>
  <process-guide
    ref="processGuideRef"
    :steps="guideSteps"
    :finalButtonText="'我知道了'"
    :showOnlyOnce="true"
    storageKey="myPageGuide"
    @finish="handleFinish"
    @close="handleClose"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue';

const processGuideRef = ref(null);

onMounted(() => {
  // 页面加载完成后自动显示（首次进入才显示）
  setTimeout(() => {
    processGuideRef.value?.show();
  }, 500);
});

const handleFinish = () => {
  console.log('用户完成了流程指引');
};

const handleClose = () => {
  console.log('用户关闭了流程指引');
};

// 如果需要重新显示指引（例如：用户点击"查看教程"按钮）
const showGuideAgain = () => {
  // 强制显示，忽略 showOnlyOnce 限制
  processGuideRef.value?.show(true);
};

// 如果需要重置显示状态（例如：用于测试）
const resetGuide = () => {
  processGuideRef.value?.reset();
};
</script>

高级使用

<script setup>
// 手动显示指引
const showGuide = () => {
  processGuideRef.value?.show();
};

// 手动隐藏指引
const hideGuide = () => {
  processGuideRef.value?.hide();
};

// 监听步骤变化
const handleStepChange = (step) => {
  console.log(`当前步骤: ${step + 1}`);
};
</script>

<template>
  <process-guide
    ref="processGuideRef"
    :steps="guideSteps"
    :finalButtonText="'开始使用'"
    :maskClosable="true"
    :highlightPadding="15"
    :dialogOffset="30"
    @finish="handleFinish"
    @close="handleClose"
    @step-change="handleStepChange"
  />
</template>

数据结构

steps 数组格式

[
  {
    title: '步骤标题',           // 必需，显示在弹窗顶部
    content: '步骤内容说明',      // 必需，显示在标题下方
    highlight: '#element-id'    // 必需，高亮区域的选择器（支持 id、class 等）
  },
  // ... 更多步骤
]

样式定制

组件支持 CSS 变量定制：

// 使用主题变量
--light-primary: #0098ff  // 按钮颜色

注意事项

1. 高亮选择器 - highlight 属性需要指定一个有效的 CSS 选择器，如 #id、.class 等
2. 步骤数据 - steps 数组中每项必须包含 title、content 和 highlight 属性
3. 自动显示 - 组件会在 onMounted 时自动显示，如需手动控制请使用 show() 方法
4. H5 适配 - 组件已针对 H5 平台的导航栏高度（44px）进行了适配
5. 固定元素 - 如果页面有固定定位元素，务必配置 fixedTopHeight 或 fixedBottomHeight
6. 元素渲染 - 确保高亮元素在组件显示前已经渲染到页面上
7. 代码优化 - 组件代码已优化到 463 行，保持简洁高效

核心功能详解

1. 智能滚动定位 ⭐

组件内置了强大的智能滚动功能，完美解决长页面中高亮元素不在可视区域的问题：

工作原理：

1. 智能判断 - 自动检测高亮元素是否在可视区域内（屏幕的 20%-80% 区域）
2. 元素高度检测 - 自动判断元素高度是否超过可用视口，采用不同对齐策略
   • 元素过高：采用顶部对齐策略，确保元素顶部可见
   • 元素正常：采用居中对齐策略，获得最佳视觉效果
3. 按需滚动 - 如果元素不在合适位置，自动滚动到最佳位置
4. 平滑动画 - H5 使用 smooth 滚动，小程序使用 300ms 动画，体验流畅
5. 稳定显示 - 滚动完成后等待页面稳定再显示高亮和对话框

特点：

• ✅ 零配置 - 自动工作，无需任何配置
• ✅ 智能优化 - 元素已在合适位置时不触发滚动
• ✅ 容错处理 - 滚动失败不影响引导流程
• ✅ 跨平台 - H5 和微信小程序完美兼容

2. 固定元素适配 ⭐

当页面存在固定定位的元素（如固定顶部导航栏、固定底部按钮栏）时，组件会智能处理，确保高亮元素不被遮挡：

工作原理：

1. 配置固定元素高度 - 通过 fixedTopHeight 和 fixedBottomHeight 属性告知组件固定元素的高度（单位：rpx）
2. 智能计算可视区域 - 自动排除固定元素占用的空间，计算实际可用的视口高度
3. 优化滚动位置 - 滚动时确保高亮元素完全显示在可用区域内，不被固定元素遮挡
4. 对话框避让 - 对话框定位时也会考虑固定元素，避免被遮挡

使用示例：

<template>
  <!-- 底部有固定按钮栏，高度为 128rpx -->
  <process-guide
    :steps="guideSteps"
    :fixedBottomHeight="128"
    @finish="handleFinish"
  />

  <!-- 底部固定按钮栏 -->
  <view class="fixed-bottom-bar">
    <!-- 按钮内容 -->
  </view>
</template>

<style>
.fixed-bottom-bar {
  position: fixed;
  bottom: 0;
  height: 128rpx; /* 与 fixedBottomHeight 保持一致 */
}
</style>

特点：

• ✅ 精确适配 - 支持同时配置顶部和底部固定元素
• ✅ 自动转换 - 自动将 rpx 转换为 px，无需手动计算
• ✅ 完全可见 - 确保高亮元素完全显示，不被遮挡
• ✅ 向后兼容 - 默认值为 0，不影响现有代码

3. 禁止页面滚动 ⭐

为了提升用户体验，组件在显示引导蒙层时会自动禁止页面滚动，防止用户误操作：

工作原理：

1. 显示时禁止 - 组件显示时自动禁止页面滚动，防止用户隔着蒙层滚动页面
2. 保存位置 - 自动保存当前页面滚动位置
3. 临时解锁 - 切换步骤时临时解锁滚动，允许组件自动滚动到目标元素
4. 再次锁定 - 滚动完成后再次锁定，防止用户手动滚动
5. 关闭时恢复 - 组件关闭或完成时，自动恢复页面滚动并恢复到原来的位置

平台实现：

• H5 端 - 通过设置 body 的 overflow: hidden 和 position: fixed 实现
• 小程序端 - 通过蒙层阻止触摸事件传递（@touchmove.stop.prevent）实现

特点：

• ✅ 零配置 - 自动管理，无需手动处理
• ✅ 位置保持 - 关闭引导后自动恢复到原来的滚动位置
• ✅ 安全清理 - 组件销毁时自动恢复页面滚动，避免页面卡死
• ✅ 智能协调 - 与自动滚动功能完美配合，不会冲突

常见场景

场景1: 在线多轮竞价页面

const guideSteps = ref([
  { 
    title: '竞价倒计时', 
    content: '请关注此处倒计时，把握竞价时机',
    highlight: '#countdown'
  },
  { 
    title: '出价规则', 
    content: '每次出价必须高于当前价格',
    highlight: '#price-input'
  },
  { 
    title: '出价方式', 
    content: '可选择手动出价或自动出价',
    highlight: '#bid-buttons'
  },
  { 
    title: '成交确认', 
    content: '竞价结束后，最高出价者成交',
    highlight: '#result-area'
  }
]);

场景2: 表单填写指引

const guideSteps = ref([
  { 
    title: '填写基本信息', 
    content: '请先填写您的基本信息',
    highlight: '#basic-info'
  },
  { 
    title: '上传证件', 
    content: '上传身份证正反面照片',
    highlight: '#upload-area'
  },
  { 
    title: '提交审核', 
    content: '确认信息无误后点击提交',
    highlight: '#submit-btn'
  }
]);

更新日志

v1.0.0 (2025-01-30)

• 🎉 初始版本发布
• ✅ 支持多步骤流程展示
• ✅ 支持高亮区域自动定位
• ✅ 支持智能滚动定位（元素高度检测、智能对齐策略）
• ✅ 支持固定元素适配（顶部/底部固定元素避让）
• ✅ 支持禁止页面滚动（H5 和小程序跨平台实现）
• ✅ 支持对话框智能定位（自动避让、空间判断）
• ✅ 支持自定义按钮文本
• ✅ 完美兼容 H5 和微信小程序
• ✅ 代码优化到 463 行，简洁高效

许可证

MIT License

联系方式

如有问题或建议，欢迎反馈。