如何在JavaScript中使用Shepherd构建用户导览

如何在JavaScript中使用Shepherd构建用户导览第1张

介绍

不管我们尝试如何简单地制作我们的 Web 应用程序，引导新用户完成他们的第一次体验通常是有帮助的。视觉游览可能是最简单的方法。

起初，我考虑自己构建它，但后来我找到了一个开源选项，Shepherd。

在今天的教程中，我将向您介绍使用Shepherd构建可视化用户导览。使用 Shepherd 相对简单，我将回顾一些我自己用来简化创作过程的代码。

Shepherd 是集客营销服务HubSpot的开源产品。感谢他们提供了一个具有良好文档的强大库。

我确实参与了下面的评论线程，所以请随时提出问题并分享您的反馈。我特别想了解您对其他视觉导游解决方案的体验。您也可以在 Twitter @lookahead_io上与我联系。

牧羊人如何工作

让我们来看看 Shepherd 的一个简单场景。

将带有 Shepherd 的基本游览集成到您的应用程序中非常简单。首先，您选择一个主题文件并像这样集成他们的javascript：

<link rel="stylesheet" href="shepherd-theme- arrows.css " />
<script src="tether.min.js"></script><script src="shepherd.min.js">
</script>

您可以从Shepherd GitHub 页面下载文件。我正在使用shepherd-theme-arrows.css上面的，但您可以从下面的任何默认值中进行选择并自定义它们：

如何在JavaScript中使用Shepherd构建用户导览第2张

接下来，您创建一个游览对象：

var tour;
 
tour = new Shepherd.Tour({
  defaults: {
    classes: 'shepherd-theme-arrows',
    scrollTo: true
  }
});

创建游览时，可以为所有步骤定义默认值。这些类是指您使用的主题定义，例如shepherd-theme-arrows. 并scrollTo 有助于确保所有步骤都出现在可见视口中。

然后，您将各个步骤添加到游览中：

tour.addStep('example-step', {
  text: 'This step is attached to the bottom of the <code>.
         example-css-selector</code> element.',
  attachTo: '.example-css-selector bottom',
  classes: 'example-step-extra-class',
  buttons: [
    {
      text: 'Next',
      action: tour.next
    }
  ]
});

这text是出现在视觉游览正文中的内容。attachTo 指向您希望在此步骤中巡回弹出窗口指向的项目的 CSS 选择器。buttons 允许您定义一个或多个按钮及其操作，例如Next。

最后，您开始游览：

tour.start();

Shepherd 基于另一个HubSpot开源产品 Tether 构建，它有助于将元素定位到页面上的其他元素。Tether 确保您的步数永远不会溢出屏幕或被裁剪。

虽然我对 Tether 没有任何问题，但我确实发现 Shepherd 无法在某些元素上正确显示箭头的问题。这是随机发生的，我不是唯一一个遇到这个问题的人。HubSpot 团队在两周后没有回复我的任何 GitHub 请求，这有点令人失望。尽管如此，Shepherd 总体上还是一个很棒的 JavaScript 库。

将 Tether 集成到您自己的应用程序中

如何在JavaScript中使用Shepherd构建用户导览第3张

当我开始尝试使用 Shepherd 时，我很快发现编写包含许多步骤的指南可能会变得相当冗长。这是我在自己的实现中解决的问题。

我不想使用需要随着时间的推移维护的冗长的 javaScript 代码包来编写游览。相反，我选择创建一个数组，并根据用户是在游览开始还是结束时对按钮进行编程自定义。

例如，我创建了一个steps[]数组并通过填充数组来定义游览：

var tour;
var steps =[];
steps.push(['.nav-tabs top','Welcome','Allow me to show you how to plan a '+title+'. <p>If you prefer, you can <a href="javascript::return false;" onclick="turnOffGuide();">turn off this guide</a>.<br /><br />']);
steps.push(['#headingWho top','Who would you like to invite?','You can add one person or a group of people to your '+title+'. <p>Click the person button to add participants.</p>']);
steps.push(['#invitation-url bottom','Inviting by email','Alternately, you can email the meeting link to your participant(s)']);
steps.push(['#headingWhat bottom','What is your meeting about?','You can customize the subject of your '+title+'. We\'ll use it for the invitation and reminder emails.<p>Click the pencil button to edit the subject.</p>']);
if ($('#headingActivity').length>0) {
  steps.push(['#headingActivity top','What do you want to do?','You can suggest one or more activity ideas. With multiple ideas, your participants can help you select their favorite. <p>Click the plus button to suggest activities.</p>']);
}
steps.push(['#headingWhen top','When do you want to meet?','Suggest one or more dates and times for your '+title+'. With more than one, your participants can help you choose. <p>Click the + button to add them.</p>']);
steps.push(['#headingWhere top','Where do you want to meet?','Suggest one or more places for your '+title+'. With multiple places, your participants can help you choose. <p>We use Google Places to simplify adding them. Click the + button to begin.</p>']);
steps.push(['.virtualThing top','Is this a virtual meeting?','Switch between <em>in person</em> and <em>virtual</em> '+title+'s such as phone calls or online conferences.']);
steps.push(['#actionSend top','Sending invitations','Scheduling is collaborative. After you add times and places, you can <strong>Invite</strong> participants to select their favorites. <em>A place isn\'t necessary for virtual '+title+'\s.</em>']);
steps.push(['#actionFinalize right','Finalizing the plan','Once you choose a time and place, you can <strong>Complete</strong> the plan. We\'ll email the invitations and setup reminders.']);
steps.push(['#tourDiscussion left','Share messages with participants ','You can write back and forth with participants on the <strong>Messages</strong> tab. <p>Messages are delivered via email.</p>']);    
steps.push(['.container ','Ask a question','Need help? <a href="'+$('#url_prefix').val()+'/ticket/create">Ask a question</a> and we\'ll respond as quickly as we can. <p>If you prefer, you can <a href="'+$('#url_prefix').val()+'/user-setting?tab=guide">turn off the guide</a> in settings.</p>']);

我添加的每个数组元素都包含三个项目：

此步骤指向的 CSS 视觉元素和位置，例如 '#headingWho top'
标题的文本，例如 'When do you want to meet?'
说明文字

对我来说，维护这个数组比为教程的每个步骤定义按钮要简单得多。但是，这意味着我需要在将步骤加载到游览中时以编程方式定义按钮。

我编写了这段代码来正确添加和响应游览的按钮。每一步，它都会创建一个button数组，否则我必须手动定义：

for (i = 0; i < steps.length; i++) {
  buttons=[];
  // no back button at the start
  if (i>0) {
    buttons.push({
      text: 'Back',
      classes: 'shepherd-button-secondary',
      action: function() {
        return tour.back();
      }
    });
  }
  // no next button on last step
  if (i!=(steps.length-1)) {
    buttons.push({
      text: 'Next',
      classes: 'shepherd-button-primary',
      action: function() {
        return tour.next();
      }
    });
  } else {
    buttons.push({
      text: 'Close',
      classes: 'shepherd-button-primary',
      action: function() {
        return tour.hide();
      }
    });
  }

例如，第一步没有返回按钮，最后一步没有下一步按钮。但最后一步确实有一个关闭按钮。

然后，我的数组中的每个步骤和每个按钮数组都被添加到游览中。

tour.addStep('step_'+i,{
    text: steps[i][2],
    title: steps[i][1],
    attachTo: steps[i][0],
    //classes: 'shepherd shepherd-open shepherd-theme-arrows shepherd-transparent-text',
    buttons: buttons,
  });

使用这种方法，我不必为教程的每一步重复重新定义相同的按钮。它还提供了一些编程能力，可以为未来动态定制游览。

使用我选择的 php 编程框架 Yii，我将必要的包含文件添加到我的资产文件中。这会加载到需要游览的特定页面上。就我而言，会议安排页面：

<?php
namespace frontend\assets;
use yii\web\AssetBundle;

class MeetingAsset extends AssetBundle
{
    public $basePath = '@webroot';
    public $baseUrl = '@web';
    public $css = [
      ...
      'css/shepherd-theme-arrows.css',      
    ];
    public $js = [
      'js/meeting.js',
      ...
      'js/tether.min.js',
      'js/shepherd.min.js',
      'js/meeting_tour.js',
    ];
    ...

您将在上面看到 Shepherd 主题的 CSS 和 Tether、Shepherd 和我的游览定义文件的 JavaScript meeting_tour.js，.

我还添加了 CSS 来将我的游览弹出窗口的整体宽度控制为视口的40%：

.shepherd-element.shepherd-theme-arrows {
  max-width: 40%;
}

您可以在上面或 Vimeo 上观看示例游览视频。如果您想亲自尝试，请在 Meeting Planner 注册，您将立即进入日程安排之旅。

其他需要考虑的事情

关闭视觉导览

我为人们创建了一个用户设置以快速关闭游览。我没有在每一步都包含一个令人分心的关闭按钮，而是添加了一个链接来关闭游览的第一步和最后一步的指南：

如何在JavaScript中使用Shepherd构建用户导览第4张

通过ajax以交互方式将其关闭，并显示指向下方设置页面的有用链接。这有助于新用户轻松找到如何重新开启导览：

如何在JavaScript中使用Shepherd构建用户导览第5张

Shepherd 的高级能力

我刚刚向您展示了 Shepherd 的基础知识以及如何将它快速集成到您的 Web 应用程序中。到目前为止，除了偶尔的箭头问题之外，它对我来说效果很好。然而，Shepherd 提供的东西比我回顾的要多得多，特别是在事件处理和管理方面。这允许您以更自定义的方式使您的游览适应您的应用程序和用户的当前状态。他们也有很好的文档。

例如，如果用户跳转到您网页的某个区域，您可以让事件自动触发跳转到浏览的另一个步骤。我可能会在以后的教程中深入探讨这一点。