使用 Intro.js 向 JavaScript 应用程序添加交互式文档

Question

以现代的、动态的方式实现 Web 应用程序的个性化导览。

原文：https://www.ibm.com/developerworks/cn/web/wa-interactive-doc-javascript-introjs-bluemix-trs/index.html

用户想要快速掌握一种新的 Web 应用程序 — 或者他们已经使用的应用程序中的新特性 —他们通常对阅读冗长的文档或指南不感兴趣。在介绍和举例说明应用程序功能时，产品演示比静态文档更容易吸引用户的注意。导览尤其有效，因为它们会在用户使用应用程序时解释和演示产品特性。

Intro.js 库采用一种创新的、交互式的方法来创建 JavaScript 应用程序文档。该库提供了需要的 JavaScript 和级联样式表 (CSS)文件，您可使用它们创建向用户演示 Web 应用程序功能与特性的分步导览。使用Intro.js，您可以将动态信息集成到应用程序中，用户在应用程序环境中进行导航时可以查看这些信息。该库集成了 AngularJS 和 Node.js，使您能够从开发环境中添加教学信息。UI 设计人员和JavaScript 开发人员都可以利用 Intro.js 功能和资源，以一种简单、现代和动态的方式提高其应用程序的价值。

示例导览

您可从 最新版 Intro.js 的示例文件夹中获得示例导览。

Intro.js 功能很容易在任何网站 UI 中实现。该库是免费的、开源的，而且兼容最新版的 Internet Explorer、Chrome 和 Firefox。本教程将展示主要的 Intro.js 特性，并提供一个实现导览的分步示例。

Intro.js 导航

Intro.js 实现了以下通用导航特性：

• 导览启动：Intro.js 库提供了一些示例按钮，您可以使用它们来定义导览初始化。您还可以设计您自己的按钮（示例： ），将用户的注意力吸引到导览的开始处。
• 导览步骤：您必须指定用户要导航的步骤，直到他们完成导览。您可以通过导览文件中的一组 HTML
  元素指定这些步骤，在本教程的后面可以看到更详细的介绍。默认情况下，Intro.js 库会指定标记为 Prev （Previous 的缩写）和
  Next 的导航按钮： 
• 导览完成或结束：在导览的每一步中，Intro.js 都为用户提供了跳过剩余步骤的选项。
  用户可以单击一个按钮 — 默认情况下标记为 End tour — 来离开导览： 。用户到达导览的最后一步时，该库实现了一个标记为 Done () 的按钮，它取代了最后一步中的 End tour 按钮。单击 Done 按钮完成导览。

接下来，我们将会展示导览在我们的示例应用程序中是什么样。

Intro.js 中的基本导览

可免费使用的图标

示例应用程序中的图标来自 flaticon travel and tourism 和 Freebie:Tourism & Travel Icon Set，二者都提供了一组可免费用于任何项目（包括软件和在线服务）的图标。

我们的示例应用程序原型包含一个使用 Node.js 和 AngularJS 在 JavaScript 中编写的网站。My Travel App 帮助游客管理其行程。这是该应用程序初始页面的外观：

My Travel App 有一个名为 Travellers Information 的菜单，用于管理游客、群组和语言：

我们创建了一个新的 Launch Tour 菜单，为 My Travel App 用户运行三种导览 — Getting Started、Navigate My Travel App 和 Manage Travellers：

为了举例说明，我们仅实现了 Manage Travellers 导览。（Getting Started 和 Navigate My Travel App 选项只是一些占位符。）Manage Travellers 导览记录了用户通过 Travellers Information
菜单管理其游客、群组和语言的每一步。

为了提供导览功能的实时演示，我们将 My Travel App 部署到 IBM Bluemix，按照“将一个 ‘Hello World’ 网页部署到 Bluemix”中描述的步骤开始部署，然后使用我们现有的 My Travel
App 项目代码。

启动 My Travel App 并自行尝试 Manage Travellers 导览。 然后继续阅读，了解我们使用 Intro.js 编写导览的实际过程。

创建 Manage Travellers 导览

创建导览

现在我们将引导您使用 Intro.js 库在 My Travel App 中创建 Manage Travellers 导览。您还可以按照我们的创建导览视频演示进行操作。

将 Intro.js 库添加到您的项目中

因为示例应用程序使用了 Node.js 和 bower 组件，所以您可以通过 bower 安装程序来安装 Intro.js 库，在本地获得它：

bower install intro.js

您还可以通过在 dependencies 部分包含 Intro.js 库，将该库添加到 bower.json 包中：

"dependencies":{
...
"angular-intro.js":"~1.1.3",
...
}

 

请参阅 GitHub 上的 Intro.js 项目页面，了解关于如何下载和安装 Intro.js 的更多信息。

更新您的 HTML，以便将 Intro.js 库添加到您的网站中

以下是在一个 HTML 页面中包含 Intro.js 代码的方法：

<li>
 <a role="menuitem" tabindex="-1"
   ng-controller="TravellersTourController"
   ng-click="startTravellersTour()">
 <i class="header-nav-icon" ng-include="'/static/icon/travel_icon.svg'"></i>
   <span translate="NAV_TOUR_MANAGE_TRAVELLERS"></span>
 </a>

 

前面代码中的 id、 ng-controller 和 ng-click 的值特定于我们的实现。我们将在下文中解释它们。

创建控制器文件

示例应用程序使用了 AngularJS 和一个新控制器—TravellersTourController— 我们创建该控制器来存储所有与Intro.js 库相关的代码。控制器代码：

1. 声明使用 Intro.js 库
2. 启动 Intro.js
3. 定义导览上显示的步骤
4. 结束导览

参见下载部分，获取 TravellersTourController 的代码。

定义 Intro.js 变量

在定义导览步骤之前，控制器代码定义了一个新变量 intro:

var intro = Intro.js();

 

现在，控制器中的函数和事件可以使用 intro 变量来引用 Intro.js 库。

定义导览步骤

要指定导览步骤，可以创建一个新的 Intro.js 对象。在这个对象中，您定义了一个对象数组，该数组依次包含导览中的每个步骤：

$scope.IntroOptions = {
  steps:[
  {
    element:'#toolbar-travellers-info-icon',
    intro:"<div class='tour-header'>Open Travellers Information Menu</div>" +
    "<div class='tour-step'>Click <b>" + TOUR.iconUsers + " Travellers Information</b> 
      icon to open the " +
    "travellers information menu.<br><br>" +
    "Use this menu to manage travellers, travellers groups " +
    "and also the language for each traveller.</div>",
    position:'left'
  },
  {
    element:'#travellersmenu',
    intro:"<div class='tour-header'>Travellers list</div>" +
    "<div class='tour-step'>Click <b>Travellers</b> 
      to view a list of travellers that belong to " +
    "the configured trips.</div>", 
    position:'left'
  },
  {
    element:'#travellersmenu',
    intro:"<div class='tour-header'>Add new travellers</div>" +
    "<div class='tour-step'>You can also add a new traveller to the trips you have.Use the " +
    "<b>Filter by search</b> field to look for existing travellers."+
    "Add them by clicking " + TOUR.iconAdd + " <b>Add travellers</b> at the " +
    "right corner of the menu.</div>",
    position:'left'
  },
  {
    element:'#groupsmenu',
    intro:"<div class='tour-header'>Groups</div>" +
    "<div class='tour-step'>This tab allows travellers to create groups and 
      subgroups of travellers." +
    "Any traveller that is already part of a group can add new travellers and subgroups.</div>",
    position:'left'
  },
  {
    element:'#groupsmenu',
    intro:"<div class='tour-header'>Add new groups</div>" +
    "<div class='tour-step'>You can also add a new group of travellers to the 
      trips you have.Use the " +
    "<b>Filter by search</b> field to look for existing groups."+
    "Add them by clicking " + TOUR.iconAdd + " <b>Add groups</b> 
      at the right corner of the menu.</div>",
    position:'left'
  },
  {
    element:'#languagesmenu',
    intro:"<div class='tour-header'>Languages</div>" +
    "<div class='tour-step'>By default, users have <b>English</b> 
      language configured as the preferred language."+
    "Travellers can add new languages to My Travel App at any time.</div>",
    position:'left'
  },
  {
    element:'#tour-icon-dropdown',
    intro:"<div class='tour-header'>End of Travellers Info Tour</div>" + 
    "<div class='tour-step'>See this tour any time by clicking " + 
      TOUR.iconTour + " in the upper right toolbar </div>",
    position:'left'
  }
  ],
  showStepNumbers: false,
  exitOnEsc:true,
  showBullets: false,
  scrollToElement:true,
  nextLabel:'Next',
  prevLabel:'Prev',
  skipLabel:'End tour',
  doneLabel:'Done'
};

 

对于每一步，您必须定义：

• 目标 element，它是该步骤引用的 HTML 元素的 ID
• 一个名为 intro 的元素，其中包含该导览步骤的 HTML 内容
• 一个 position 元素，指定了该步骤在页面中的位置

接下来的 7 个屏幕截图和配套代码段展示了在 Intro.js 对象中为 Manager Travellers 导览定义的每一步是如何按照 element、 intro 和 position 的顺序在导览中显示的。

导览的初始步骤使用了 Intro.js 对象代码的以下部分：

{element:'#toolbar-travellers-info-icon',
    intro:"<div class='tour-header'>Open Travellers Information Menu</div>" +
    "<div class='tour-step'>Click <b>" + TOUR.iconUsers + " Travellers Information</b> 
      icon to open the " +
    "travellers information menu.<br><br>" +
    "Use this menu to manage travellers, travellers groups " +
    "and also the language for each traveller.</div>",
    position:'left'
}

列出游客的导览步骤使用了 Intro.js 对象代码的这一部分：

{
    element:'#travellersmenu',
    intro:"<div class='tour-header'>Add new travellers</div>" +
    "<div class='tour-step'>You can also add a new traveller to the trips you have.Use the " +
    "<b>Filter by search</b> field to look for existing travellers."+
    "Add them by clicking " + TOUR.iconAdd + " <b>Add travellers</b> at the " +
    "right corner of the menu.</div>",
    position:'left'
}

添加新游客的导览步骤使用了 Intro.js 对象代码的这一部分：

{
    element:'#travellersmenu',
    intro:"<div class='tour-header'>Add new travellers</div>" +
    "<div class='tour-step'>You can also add a new traveller to the trips you have.Use the " +
    "<b>Filter by search</b> field to look for existing travellers."+
    "Add them by clicking " + TOUR.iconAdd + " <b>Add travellers</b> at the " +
    "right corner of the menu.</div>",
    position:'left'
}

解释 Groups 选项卡的导览步骤使用了 Intro.js 对象代码的这一部分：

{
    element:'#groupsmenu',
    intro:"<div class='tour-header'>Add new groups</div>" +
    "<div class='tour-step'>You can also add a new group of travellers to the 
      trips you have.Use the " +
    "<b>Filter by search</b> field to look for existing groups."+
    "Add them by clicking " + TOUR.iconAdd + " <b>Add groups</b> 
      at the right corner of the menu.</div>",
    position:'left'
}

添加新组的导览步骤使用了 Intro.js 对象代码的这一部分：

{
    element:'#groupsmenu',
    intro:"<div class='tour-header'>Add new groups</div>" +
    "<div class='tour-step'>You can also add a new group of travellers to the 
      trips you have.Use the " +
    "<b>Filter by search</b> field to look for existing groups."+
    "Add them by clicking " + TOUR.iconAdd + " <b>Add groups</b> 
      at the right corner of the menu.</div>",
    position:'left'
}

解释 Languages 选项卡的导览步骤使用了 Intro.js 对象代码的这一部分：

{
    element:'#languagesmenu',
    intro:"<div class='tour-header'>Languages</div>" +
    "<div class='tour-step'>By default, users have <b>English</b> 
      language configured as the preferred language."+
    "Travellers can add new languages to My Travel App at any time.</div>",
    position:'left'
}

导览的最后一步使用了 Intro.js 对象代码的这一部分：

{
    element:'#tour-icon-dropdown',
    intro:"<div class='tour-header'>End of Travellers Info Tour</div>" + 
    "<div class='tour-step'>See this tour any time by clicking " + 
      TOUR.iconTour + " in the upper right toolbar </div>",
    position:'left'
}

定义其他导览元素

除了步骤数组，您还可以定义其他元素 — 比如显示在导览上的按钮标签，以及使用一个 escape 按钮来结束导览。请参阅 Intro.js 库的文档，了解有关的更多信息。

将步骤对象设置为 Intro.js 变量

定义 Manage Travellers 导览的所有步骤和其他导览元素后，我们将 Intro.js 对象设置为之前创建的 intro 变量，使用 setOptions() 方法实现此目的：

intro.setOptions($scope.IntroOptions);

启动 Intro.js

在 HTML 菜单中，指定控制器和一个要执行的函数作为导览的起点。对于示例应用程序，我们指定了 startTravellersTour() 函数：

$scope.startTravellersTour = function() {
   startTravellersPath();
   intro.start();
};

 

startTravellersTour() 函数包含的调用可启动 Intro.js，这是您启动导览所需的全部操作。请注意，本教程在启动 Intro.js 之前还执行了另一个函数。

startTravellersPath() 函数（它使用了 JQuery）确保在导览启动时打开了应用程序的正确菜单：

var startTravellersPath = function() {
$timeout(function(){
  $("#toolbar-travellers-info-button").click();
  $timeout(function(){
    $("#loadTravellersMenu").click();
  },500);
  $('.dropdown').removeClass('open');
},500);
};

确保正确的步骤过渡

在进行导览时，用户必须能够导航 Travellers Information 菜单的选项卡，所以我们还定义了一个onchange 事件，确保在运行导览时为每个步骤显示了正确的选项卡：

intro.onchange (function(targetElement) {
  if (targetElement.id === 'travellersmenu') {
    $("#loadTravellersMenu").click();
  }
  if (targetElement.id === 'groupsmenu') {
    $("#loadGroupsMenu").click();
  }
  if (targetElement.id === 'languagesmenu') {
     $("#loadLanguagesMenu").click();
  }
});

结束 Intro.js

为了结束导览的执行，我们定义了 onexit 和 oncomplete 事件来确保能正确结束导览：

intro.onexit (function(targetElement) {
  $("#toolbar-travellers-info-button").click();
});
intro.oncomplete (function(targetElement) {
  $("#toolbar-travellers-info-button").click();
});

在模板中声明控制器文件

最后，在使用新的控制器之前，必须在 EJS 模板文件中将它声明为一个自定义文件：

<script src="/static/js/guided_tour/travellersTourController.js"></script>

结束语

本教程介绍了 Intro.js 库中的交互式、动态用户文档创建方法，展示了使用该库创建导览的所有必要步骤。您可轻松地将 Intro.js 与任何网站集成 — 包括我们所展示的在 Bluemix 云中运行的 Web 应用程序。结合使用 Bluemix 和 Intro.js，可以显著增强 Web 应用程序的用户体验。