Comment utiliser Shepherd pour créer la navigation des utilisateurs en JavaScript

Aussi simple que nous essayons de créer une application Web, il est souvent utile de guider les nouveaux utilisateurs dans leur première expérience. Une visite visuelle est probablement le moyen le plus simple.

Si vous avez suivi ma série Envato Tuts+ Créez votre startup avec PHP, alors vous serez familier avec les organisateurs de réunions. Après avoir observé les utilisateurs planifier leurs premières réunions, j'ai décidé qu'il serait préférable de créer une sorte de guide.

Au début, j'ai envisagé de le construire moi-même, mais j'ai ensuite trouvé une option open source, Shepherd.

Dans le tutoriel d'aujourd'hui, je vais vous montrer comment créer un parcours utilisateur visuel à l'aide de Shepherd. Utiliser Shepherd est relativement simple et je vais passer en revue un code que j'utilise moi-même pour simplifier le processus de création.

Shepherd est un produit open source de HubSpot, un service d'inbound marketing. Félicitations à eux pour avoir fourni une bibliothèque robuste et une bonne documentation.

Comment fonctionne Shepherd

Regardons une scène simple avec Shepherd.

L'intégration de la navigation de base dans votre application est facile avec Shepherd. Tout d'abord, vous sélectionnez un fichier de thème et intégrez son JavaScript comme ceci :

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

Vous pouvez télécharger le fichier depuis la page Shepherd GitHub. J'ai utilisé shepherd-theme-arrows.css ci-dessus, mais vous pouvez choisir parmi l'une des valeurs par défaut ci-dessous et les personnaliser :

Ensuite, vous créez un objet de visite :

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

Assurez-vous que toutes les étapes apparaissent dans la fenêtre visible à l'aide de la méthode defaultStepOptions 键创建游览时，可以为所有步骤定义默认值。 classes 指的是您使用的主题定义，例如shepherd-theme-arrows 和 scrollTo 有助于在 scrollIntoView().

Vous pouvez ensuite ajouter des étapes individuelles à votre visite :

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

text 是出现在视觉之旅正文中的内容。文本可以是常规 HTML 字符串，也可以是 HTMLElement 对象。您还可以在此处提供一个回调函数，该函数将在构建步骤时执行。但是，它必须返回 HTML 字符串或 HTMLElement Objet.

attachTo Points clés du sélecteur CSS de l'élément auquel cette étape doit être attachée. Il attend un objet comme valeur.

buttons 键允许您定义一个或多个按钮及其操作，例如。 Next.Cette clé accepte un tableau d'objets bouton comme valeur. L'objet bouton aura des paires clé-valeur qui contrôlent le comportement et l'apparence du bouton.

Enfin, vous commencez votre visite :

tour.start();

Shepherd est construit sur Tether (un autre produit open source HubSpot) et aide à positionner les éléments par rapport à d'autres éléments de la page. Tether garantit que vos pas ne débordent pas de l'écran et ne sont pas coupés.

Intégrez Tether dans vos propres applications

Quand j'ai commencé à essayer Shepherd, j'ai vite découvert que rédiger un guide comportant de nombreuses étapes pouvait être assez long. C'est un problème que j'ai résolu dans ma propre implémentation.

Je ne veux pas écrire une visite avec beaucoup de code JavaScript qui nécessite une maintenance à long terme. Au lieu de cela, j'ai choisi de créer un tableau et de personnaliser par programme les boutons selon que l'utilisateur se trouve au début ou à la fin de la visite.

Par exemple, je crée un tableau steps[] et je définis le tour en le remplissant :

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

const steps = [];

steps.push({
  attachTo: {
    element: '.nav-tabs',
    on: 'top'
  },
  title: 'Welcome',
  text: `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({
  attachTo: {
    element: '#headingWho',
    on: 'top'
  },
  title: 'Who would you like to invite?',
  text: `You can add one person or a group of people to your ${title}. <p>Click the person button to add participants.</p>`
});
steps.push({
  attachTo: {
    element: '#invitation-url',
    on: 'bottom'
  },
  title: 'Inviting by email',
  text: 'Alternately, you can email the meeting link to your participant(s)'
});
steps.push({
  attachTo: {
    element: '#headingWhat',
    on: 'bottom'
  },
  title: 'What is your meeting about?',
  text: `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({
    attachTo: {
      element: '#headingActivity',
      on: 'top'
    },
    title: 'What do you want to do?',
    text: '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({
  attachTo: {
    element: '#headingWhen',
    on: 'top'
  },
  title: 'When do you want to meet?',
  text: `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({
  attachTo: {
    element: '#headingWhere',
    on: 'top'
  },
  title: 'Where do you want to meet?',
  text: `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({
  attachTo: {
    element: '.virtualThing',
    on: 'top'
  },
  title: 'Is this a virtual meeting?',
  text: `Switch between <em>in person</em> and <em>virtual</em> ${title}s such as phone calls or online conferences.`
});
steps.push({
  attachTo: {
    element: '#actionSend',
    on: 'top'
  },
  title: 'Sending invitations',
  text: `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({
  attachTo: {
    element: '#actionFinalize',
    on: 'right'
  },
  title: 'Finalizing the plan',
  text: `Once you choose a time and place, you can <strong>Complete</strong> the plan. We'll email the invitations and setup reminders.`


});
steps.push({
  attachTo: {
    element: '#tourDiscussion',
    on: 'left'
  },
  title: 'Share messages with participants',
  text: 'You can write back and forth with participants on the <strong>Messages</strong> tab. <p>Messages are delivered via email.</p>'
});
steps.push({
  attachTo: {
    element: '.container',
    on: 'top'
  },
  title: 'Ask a question',
  text: `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>`
});

Chaque élément d'objet que j'ajoute au tableau contient trois informations clés :

1. L'élément visuel CSS vers lequel pointe cette étape et l'endroit où il doit être attaché à cet élément. Par exemple {element: '.nav-tabs', on:'top'}
2. title 键中标题的文本，例如'你想什么时候见面？'
3. text clé

Pour moi, maintenir ce tableau est bien plus simple que de définir des boutons pour chaque étape du tutoriel. Cependant, cela signifie que je dois définir les boutons par programme lors du chargement des étapes dans la visite guidée.

J'ai écrit ce code pour ajouter et répondre correctement au bouton de visite. A chaque étape, il crée un buttons tableau, que sinon je devrais définir manuellement :

for (let i = 0; i < steps.length; i++) {
    
    let 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();
          }
        });
    }

Par exemple, la première étape n'a pas de bouton Retour et la dernière étape n'a pas de bouton Suivant. Mais la dernière étape comporte un bouton Fermer.

Ensuite, chaque étape de mon tableau et chaque tableau de boutons est ajouté à la visite.

    tour.addStep(`step_${i}`, {
        text: steps[i].text,
        title: steps[i].title,
        attachTo: steps[i].attachTo,
        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 上注册，然后您将立即进入安排导览。

其他需要考虑的事项

关闭视觉游览

我创建了一个用户设置，供人们快速关闭游览。我没有在每个步骤中添加一个分散注意力的关闭按钮，而是在导览的第一个和最后一个步骤中添加了一个关闭指南的链接：

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

Shepherd 的高级功能

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

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

正在结束

我希望您喜欢了解 Shepherd。它无疑是一个视觉效果优美、开发人员友好的视觉之旅，您可以快速集成到任何应用程序中。

相关链接

• GitHub 上的 Shepherd
• 会议策划者（创建您的第一次会议以观看视觉导览）

本文已根据 Monty Shokeen 的贡献进行了更新。 Monty 是一位全栈开发人员，他也喜欢编写教程和学习新的 JavaScript 库。

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!