更新记录

1.0.4（2026-05-11） 下载此版本

• fix：首屏在布局与测量完成前整体透明（bootstrapping），避免气泡暂存于左上角、遮罩与高亮不同步的闪动

1.0.3（2026-01-16） 下载此版本

--

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

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

平台兼容性

uni-app(4.83)

其他

process-guide

多步骤流程指引蒙层：高亮目标节点、气泡说明、自动滚动与 H5 禁止滚动。适用于 H5、微信小程序（其他小程序需自行验证）。

当前版本：1.0.4 · 更新说明见同目录 changelog.md。

安装

将本插件置于项目 uni_modules/process-guide。若未通过 easycom 自动解析，可在 pages.json 的 easycom.custom 中增加：

"process-guide": "@/uni_modules/process-guide/components/process-guide/process-guide.vue"

快速使用

页面内需存在与 highlight 对应的真实节点（如带 id 的区块）。组件挂载后默认自动打开指引（受 showOnlyOnce 等配置影响）。

<template>
    <view>
        <view id="step-a">第一步区域</view>
        <view id="step-b">第二步区域</view>
        <process-guide
            ref="guideRef"
            :steps="steps"
            finalButtonText="完成"
            :showOnlyOnce="true"
            storageKey="myPage"
            @finish="onFinish"
        />
    </view>
</template>

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

const guideRef = ref(null);

const steps = ref([
    { title: '第一步', content: '说明文案', highlight: '#step-a' },
    { title: '第二步', content: '说明文案', highlight: '#step-b' }
]);

const onFinish = () => {
    console.log('finish');
};

// 再次展示：guideRef.value?.show(true)
// 清除「只显一次」记录：guideRef.value?.reset()
</script>

Props

Events

Methods（ref）

注意事项

• 高亮目标须在测量前已渲染；长列表或异步内容请先保证节点存在。
• H5 已对常见导航栏高度做偏移适配；固定头尾请配置 fixedTopHeight / fixedBottomHeight（与页面实际 rpx 一致）。
• 主题色可使用工程内 CSS 变量 --light-primary 覆盖主按钮色。

许可证

MIT License（见 LICENSE）。