Shepherd.js 用户引导库：快速构建应用内引导式导航的完整指南

Shepherd.js 用户引导库：快速构建应用内引导式导航的完整指南

【免费下载链接】shepherdGuide your users through a tour of your app项目地址: https://gitcode.com/gh_mirrors/sh/shepherd

产品上线后，新用户常常不知道从哪里点起。Shepherd.js 是一个开源的用户引导库，能把应用里的按钮、面板逐一高亮，配上文字说明做成一步步的引导式导航，帮用户快速熟悉功能。它由 Ship Shape 团队维护，纯 JavaScript 和主流前端框架都能用，体积轻、定制空间大。

一句话说清：它是什么，为谁解决什么问题

Shepherd.js 的名字来自牧羊犬：应用是草地，用户是羊，这个库就是那只带路的狗。它解决的核心痛点是——功能开发完了，用户却不会用。你把关键界面元素一个个圈出来，在旁边弹出带说明的提示框，用户点"下一步"就走一步，走完全程就完成一次导览。全程不跳页、不自己写弹窗逻辑，靠配置就能跑起来。

核心能力

步骤化导览

创建一个 Tour，用addStep逐步添加；每步指定挂载到哪个页面元素、朝哪个方向（上/下/左/右），提示框会借助内置的 floating-ui 自动贴合定位，换布局也不乱。

高亮遮罩与自动滚动

开启useModalOverlay后整页变暗，只留目标元素亮着，像打了一束追光；还可以配置自动滚动，保证用户始终看得见当前步骤。

事件系统

库暴露on、off、once方法，步骤完成、导览结束等节点都能挂事件，方便你接入埋点或做"上一步/下一步"的自定义按钮。

兼容面

支持 IE/Edge、Firefox、Chrome、Safari 的主流版本；纯 JS、ES Modules 直接可用，React、Vue、Angular、Ember 均有对应封装。

快速上手与框架集成

安装走 npm：npm install shepherd.js，再引入配套的样式文件即可。主要用法就三步：创建 Tour 实例 →addStep添加步骤（每步填目标元素、方位、文案和按钮）→ 调用start()开跑。框架项目不必从零接，React 官方封装就在这个仓库的 packages/react/ 里，另有 vue-shepherd、angular-shepherd、ember-shepherd 三个社区封装可对照选用。安装方式细节可看 docs-src/src/content/docs/guides/install.mdx。

用户引导的 3 个典型用例

• 新用户入门：SaaS 工具用 SimplePlanner 的做法，带新注册用户过一遍协作排期界面，降低上手门槛。
• 首次配置向导：LogSeq 用它引导用户完成初始化设置，避免用户对着空白页发呆。
• 功能更新与站点导览：Drupal 用它给核心模块做站点内导览，发新版时把老用户引到新功能处。

小结

一句话：配置驱动的轻量引导库，把"带用户逛一遍应用"这件麻烦事变成几行声明式代码。适合需要新用户引导、功能导览或更新提示的前端项目，尤其是有 React/Vue 等框架背景的团队。

资源

• 使用文档：docs-src/src/content/docs/guides/usage.md
• 样式定制：docs-src/src/content/docs/guides/styling.md
• 核心源码：shepherd.js/src/
• React 封装：packages/react/

【免费下载链接】shepherdGuide your users through a tour of your app项目地址: https://gitcode.com/gh_mirrors/sh/shepherd