ツアーガイドが簡単に作れるTourGuide JSを試す

2023/02/13

当ページのリンクには広告が含まれています。

WebサイトのUI説明などをステップ形式で伝えることができるJSライブラリ「TourGuide JS」を見つけたので試してみました。

2022/11/11に公開された新しめのライブラリでバージョンは0.0.7です。ライセンスはMIT。

TourGuide JS

Intuitive and customisable tours for user on-boarding TourGuide is a Javascript library for creating user tours and on-boarding steps for your apps.

GitHub

GitHub - sjmc11/tourguide-js: TourGuide is a Javascript library for creating user tours and on-board... TourGuide is a Javascript library for creating user tours and on-boarding steps for your apps. - sjmc11/tourguide-js

試した感想を先に述べると、いくつかのdata属性を設定するだけなので非常に簡単でした。もちろんdata属性を使用せずにJSコードを書いて使用することもできます。

intro.jsと類似している部分が多いので、使ったことがある人は触りやすいライブラリだと思います。

インストール

今回はCDNで話を進めるので以下をHTMLに記述するだけです。npmはこちらを参照してください。

<script src="https://unpkg.com/@sjmc11/tourguidejs/dist/tour.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<link rel="stylesheet" href="https://unpkg.com/@sjmc11/tourguidejs/dist/css/tour.min.css">

バージョンを0.0.7に固定したい場合はこちらです。

<script src="https://unpkg.com/@sjmc11/tourguidejs@0.0.7/dist/tour.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<link rel="stylesheet" href="https://unpkg.com/@sjmc11/tourguidejs@0.0.7/dist/css/tour.min.css">

使い方

ツアーガイドのステップにしたい要素にdata属性を入れていきます。

<div data-tg-tour="ステップ１"> ... </div>

サポートされているdata属性以下です。

data-tg-tour：本文を設定します
data-tg-title：タイトルを設定します
data-tg-group：1ページに複数のツアーがある場合に名称を設定します
data-tg-order：ステップの順番を設定します
data-tg-fixed：要素がfixedで固定されている場合に使用します
data-tg-margin：自動スクロールしたときの余白を設定します

<div data-tg-tour="ステップ1です" 
     data-tg-title="ステップ1のタイトル"
     data-tg-order="1">Hi!</div>

<div data-tg-tour="<style='color:red;'>ステップ2です</style>" 
     data-tg-title="ステップ2のタイトル"
     data-tg-order="2">Step2!</div>

<div data-tg-tour="ステップ3です<br>ステップ3です" 
     data-tg-title="ステップ3のタイトル"
     data-tg-order="3">Finish!</div>

ざっくりこんな感じです。data-tg-tourは<br>タグなどを入れることが可能です。styleを入れる場合はクォートに注意してください。

要素に各種設定を入れたらJSを実行します。

const tg = new tourguide.TourGuideClient(); // npmの場合は new TourGuideClient();
tg.start();

これだけで実装完了です！

TourGuideClient()に設定できるオプションはこちらから確認できます。nextLabelやprevLabelなどを日本語にしてもいいですね。

参考にこのページで動作するツアーを作成したので以下の[テストツアー]ボタンを押してみてください。

codepenにもサンプルを作りました。
※ページとiframeのスクロールが干渉するので、こちらから別タブで確認した方が分かりやすいです。

See the Pen TourGuide.JS 0.0.7 CDN example for data-attribute by hakoirioyaji (@hakoirioyaji) on CodePen.

ステップをJSコードで制御

JSコードでステップを制御する場合は2つの方法があります。

1つは以下のようにコンストラクタのオプションstepsに設定を入れます。

const steps = [{
  content: 'ステップのメッセージ'
  title: 'ステップのタイトル'
  target: '', // selector or node
  order: '',
  group: '',
}];

const tg = new tourguide.TourGuideClient({
  steps: steps
})

もう1つの方法は、インスタンスメソッドaddSteps()を使用します。

const step1 = {
  content: 'ステップのメッセージ'
  title: 'ステップのタイトル'
  target: '', // selector or node
  order: '',
  group: '',
};

const step2 = {
  content: 'ステップ2のメッセージ'
  title: 'ステップ2のタイトル'
};

const steps = [step1, step2];
const tg = new tourguide.TourGuideClient();
tg.addSteps(steps);

いずれも必要なステップをどんどん追加していく形です。

addSteps()を深いところまでテストしていませんが、ステップ中に条件分岐で別ステップを挿入するとかテクニカルな事ができるのかもしれません。

本家サイトのサンプルでは、ステップの中にインプットテキストを表示させてバリデーションが通ったら次に進む仕組みが実装されています。

私も同様のサンプルを作ってみたらイベント周りの実装で結構手こずりました。
やってみたことはcontentに文字列で直接要素を書くか、それともNodeを作成して設定するべきか。
ステップが切り替わったときにイベントがどう動くのかなど、殆ど挙動確認をするためのテストを行った感じです。参考程度にどうぞ。