Tour
TsgcHTMLComponent_Tour: オンボーディング向けのガイド付きプロダクトツアーです。スポットライトとカードで、ページの要素を 1 ステップずつ強調表示します。初回の訪問時に自動で、ボタンから、またはサーバーから開始でき、各ユーザーの進行状況をサーバーイベントで報告します。Delphi、C++ Builder、.NET で利用できます。
TsgcHTMLComponent_Tour: オンボーディング向けのガイド付きプロダクトツアーです。スポットライトとカードで、ページの要素を 1 ステップずつ強調表示します。初回の訪問時に自動で、ボタンから、またはサーバーから開始でき、各ユーザーの進行状況をサーバーイベントで報告します。Delphi、C++ Builder、.NET で利用できます。
ステップ を追加し、それぞれを要素に向け、AutoStart を設定するか開始ボタンを追加します。OnStepChange、OnSkip、OnComplete が、各ユーザーがどこまで進んだかをサーバーに伝えます。
TsgcHTMLComponent_Tour、ステップごとに ステップ の TsgcHTMLTourStep を 1 つ使用します
設定を JSON として持つ非表示の要素とツアーのスクリプトで、スタイルは埋め込み、外部ファイルも CDN も不要です
Delphi, C++ Builder, .NET
AutoStart を使うと、ブラウザーが初めてページを開いたときにツアーが自動で始まり、開始ボタンでいつでも再生できます。HTMXEngine を割り当てると、ブラウザーはハンドラーのあるイベントを送信します。
uses
sgcHTML_Session, sgcHTML_Component_Tour;
// 一度だけ作成します。ページのレンダリング後もサーバーイベントに応答します
oTour := TsgcHTMLComponent_Tour.Create(Self);
oTour.Name := 'onboarding';
oTour.AutoStart := True;
oTour.HTMXEngine := HTMXEngine1;
oTour.OnComplete := TourComplete;
oTour.OnSkip := TourSkip;
with oTour.Steps.Add do
begin
Title := 'Welcome'; // ターゲットなし: 中央のカード
Content := '<p>Take a minute to see what is where.</p>';
end;
with oTour.Steps.Add do
begin
Target := '#sidebar';
Title := 'Navigation';
Content := '<p>Every module of the app is here.</p>';
Placement := trpRight;
end;
sHtml := oTour.HTML + oTour.GetStartButtonHTML('Restart tour');
procedure TForm1.TourComplete(Sender: TObject; var aResponse: string);
var
oSession: TsgcHTMLSession;
begin
oSession := sgcHTMLRequestSession; // このリクエストのセッション
if oSession <> nil then
SaveOnboardingDone(oSession.UserID); // 独自のコード
end;
procedure TForm1.TourSkip(Sender: TObject; aStep: Integer; var aResponse: string);
var
oSession: TsgcHTMLSession;
begin
oSession := sgcHTMLRequestSession;
if oSession <> nil then
SaveOnboardingSkipped(oSession.UserID, aStep);
end;@* 各ステップの内容がカードの HTML になります *@
<sgc-tour name="onboarding" auto-start="true" on-complete="Model.TourDone" on-skip="Model.TourSkipped">
<sgc-tour-step title="Welcome"><p>Take a minute to see what is where.</p></sgc-tour-step>
<sgc-tour-step target="#sidebar" title="Navigation" placement="right">
<p>Every module of the app is here.</p>
</sgc-tour-step>
<sgc-tour-step target="#btnSettings" title="Settings" image="/img/settings.png">
<p>Change the theme and your profile here.</p>
</sgc-tour-step>
</sgc-tour>using esegece.sgcWebSockets;
var tour = new TsgcHTMLComponent_Tour { Name = "onboarding" };
tour.AutoStart = true;
tour.HTMXEngine = htmxEngine;
tour.OnComplete += TourDone;
tour.OnSkip += TourSkipped;
var step = tour.Steps.Add();
step.Title = "Welcome";
step.Content = "<p>Take a minute to see what is where.</p>";
step = tour.Steps.Add();
step.Target = "#sidebar";
step.Title = "Navigation";
step.Content = "<p>Every module of the app is here.</p>";
step.Placement = TsgcHTMLTourPlacement.trpRight;
string html = tour.HTML + tour.GetStartButtonHTML("Restart tour");
public void TourDone(object sender, ref string response)
{
SaveOnboardingDone(User.Identity?.Name);
}
public void TourSkipped(object sender, int step, ref string response)
{
SaveOnboardingSkipped(User.Identity?.Name, step);
}新しいユーザーに何がどこにあるかを見せる初回体験と、各ユーザーがどこまで進んだかのサーバー側の記録です。
各ステップは、暗くした背景に切り抜かれたスポットライトで要素を強調し、その隣に、タイトル、HTML コンテンツ、省略可能な画像、進行ドット付きのステップカウンター、「戻る」「次へ」「ツアーをスキップ」「完了」ボタンを備えたカードを表示します。ターゲットのないステップでは、カードがページの中央に表示されます。
初回の訪問時に自動で (AutoStart)、ボタンから (GetStartButtonHTML、または任意の要素の data-sgc-tour-start)、独自のスクリプトから (GetStartScript)、またはサーバーから 1 人のユーザーに対して (GetStartHTML) です。
「完了」または「ツアーをスキップ」は、ブラウザーの localStorage に StorageKey (既定は sgc-tour:<Name>) で保存され、そこでは AutoStart がツアーを再び開始しません。改訂したツアーを全員に見せるには、StorageKey を変更してください。
ターゲットが存在しない、または非表示のステップ (たとえば、ユーザーが持たないロールのパネル) は、どちらの方向でもスキップされ、カウンターは表示できるステップだけを数えます。カードはビューポート内に収まり、狭い画面では下、上、または中央に切り替わります。
カードはタイトルを名前に持つダイアログです。ステップが表示されるとフォーカスは「次へ」に移り、ツアーが終わると元の位置に戻り、モーダルのカードでは Tab がボタンの間を循環します。矢印キーでステップを移動し、Esc で終了し、polite のライブリージョンが「ステップ n / m: タイトル」と読み上げます。
ボタンとステップのテキストは、ライブラリの 17 言語で提供されます。右から左のページでは配置と矢印キーが反転し、カードはページの data-bs-theme をコピーするため、ダークテーマにも従います。スタイルはツアーの開始時に追加され、終了時に削除されます。
最もよく使うメンバーです。
各ステップには、Target (CSS セレクター、最初に一致したもの) または TargetComponent、プレーンテキストの Title、sgcHTMLSanitizeHTML でサニタイズされる HTML の Content、sgcHTMLSanitizeURL を通る Image の URL、Placement、独自の ShowBackdrop と ScrollIntoView があります。
ShowBackdrop、ShowProgress、ShowSkip は、背景、ドット付きのカウンター、「ツアーをスキップ」ボタンのオンとオフを切り替えます。Padding (既定は 6) はターゲットの周囲のピクセル単位の余白、AllowKeyboard は Esc と矢印キーを有効にし、CloseOnBackdropClick は背景のクリックでツアーを終了します。
OnStepChange はステップが表示されるたびに発生し、OnSkip はユーザーが最後より前に離れたときにステップのインデックスとともに発生し、OnComplete は最後のステップでユーザーが「完了」を押したときに発生します。ブラウザーはハンドラーのあるイベントだけを送信し、ステップ の範囲外のステップインデックスは拒否されます。
ハンドラーはリクエストのスレッドで実行され、そこでは sgcHTMLRequestSession がセッションとユーザーを返します。aResponse で返す HTML は、その要素に hx-swap-oob="true" が付いていれば htmx が差し替えます。
HTMXEngine を割り当てるか、ActionURL を設定して、独自のルートから DispatchComponentEvent('tour', Params, Response) を呼び出します。どちらもない場合、ツアーはブラウザーで動作し、何も送信しません。ページで htmx が使える場合は htmx.ajax で、そうでなければページの CSRF メタタグ付きの XMLHttpRequest で送信します。
GetStartHTML は、受け取ったブラウザーでツアーを開始するフラグメントを、htmx のレスポンスまたは 1 つの接続へのプッシュとして返します。開始ボタン、GetStartScript、GetStartHTML は、ブラウザーに保存されたエントリを無視します。
window.sgcHTMLTour は start(id[, step])、next、back、end、reset、active を提供します。すべての関数はツアーの id、つまり GetElementIdentifier の値を受け取ります。reset は保存されたエントリを削除するため、AutoStart がツアーを再び実行します。
Razor ビューでは、<sgc-tour name="..."> Tag Helper がツアーをレンダリングし、ステップごとに 1 つの <sgc-tour-step> 子要素を置き、その内容がカードの HTML になります。最初のレンダリングでエンジンと名前ごとに 1 つのコンポーネントが作成され、AddSgcHtml のエンジンに登録されるため、ページのレンダリング後もサーバーイベントに応答します。
Demos\60.HTML\01.RunTime\29.Tour は、ポート 8131 の sgc Cloud Console です。スポットライト付きの 8 ステップの初回ツアー、同じページの 2 つ目の「新機能」ツアー、ツールバーのボタン、統計カード、フォームフィールドのツールチップ、そしてサーバーがユーザーごとに記録するオンボーディングファネルがあります。デザイン時、Lazarus、.NET の各バージョンも同様の内容です。
| オンラインで試すeSeGeCe デモサーバーでライブ動作する ツアーとツールチップ デモをご覧ください。 | 開く | |
| オンラインヘルプこのコンポーネントの完全な API リファレンスと使い方ガイドです。 | 開く | |
| Tooltip コンポーネントボタンとフィールドのヒントで、同じデモでツアーと一緒に表示されます。 | 開く | |
| すべての sgcHTML コンポーネント80 以上のコンポーネントの機能マトリックスをすべてご覧いただけます。 | 開く | |
| 無料体験版のダウンロード30 日間の体験版には 60.HTML のデモプロジェクトが含まれます。 | 開く | |
| 価格完全なソースコード付きの Single、Team、Site ライセンス。 | 開く |