Svelte入門：リファレンス $app/navigation -Vol.2-

よっしー

こんにちは。よっしーです(^^)

今日は、SvelteKitのリファレンスについて解説しています。

背景
$app/navigation
1. disableScrollHandling
  1. 解説
  2. 使用例
2. goto
  1. 解説
  2. 使用例
おわりに

背景

SvelteKitのリファレンスについて調査する機会がありましたので、その時の内容を備忘として記事に残しました。

$app/navigation

import {
	afterNavigate,
	beforeNavigate,
	disableScrollHandling,
	goto,
	invalidate,
	invalidateAll,
	onNavigate,
	preloadCode,
	preloadData,
	pushState,
	replaceState
} from '$app/navigation';

$app/navigation モジュールは SvelteKit アプリケーションでクライアントサイドのナビゲーションを制御するための関数を提供します。主な機能は以下の通りです：

afterNavigate – ナビゲーション完了後に実行されるコールバック関数を設定します。ページ遷移後の処理に使用します。
beforeNavigate – ナビゲーション開始前に実行されるコールバック関数を設定します。ページ遷移前の処理に使用します。
disableScrollHandling – SvelteKit のデフォルトのスクロール処理を無効化します。カスタムのスクロール動作を実装したい場合に使用します。
goto – プログラムによるナビゲーションを実行します。指定されたURLに移動します。
invalidate – 特定のデータの依存関係を無効化し、ページのデータを再読み込みします。
invalidateAll – すべてのデータの依存関係を無効化し、ページ全体のデータを再読み込みします。
onNavigate – ナビゲーション中に実行されるコールバック関数を設定します。
preloadCode – 指定されたページのコードを事前に読み込みます。パフォーマンス向上のために使用します。
preloadData – 指定されたページのデータを事前に読み込みます。パフォーマンス向上のために使用します。
pushState – ブラウザの履歴に新しいエントリを追加します。新しいURLにナビゲーションする際に使用します。
replaceState – 現在のブラウザ履歴エントリを置き換えます。現在のURLを別のURLに置き換える際に使用します。

これらの関数を使用することで、SvelteKit アプリケーション内でのナビゲーション体験をカスタマイズし、よりスムーズで効率的なユーザー体験を提供することができます。

disableScrollHandling

ナビゲーション後にページが更新されている際（例えば onMount や afterNavigate 内、またはアクション内で）に呼び出すと、SvelteKit の組み込みスクロール処理を無効化します。これはユーザーの期待を損なうため、一般的には推奨されていません。

function disableScrollHandling(): void;

解説

disableScrollHandling は SvelteKit のナビゲーション機能で、以下のような特徴があります：

スクロール処理の無効化 – SvelteKit が提供する標準のスクロール動作を無効にします。
使用タイミング – ナビゲーション後のページ更新中（onMount、afterNavigate、アクション内など）に呼び出す必要があります。
非推奨の理由 – この機能の使用は一般的に推奨されていません。その理由は、標準的なスクロール動作を無効化することで、以下のようなユーザー体験の問題が生じる可能性があるためです：
- ページ遷移後に期待される位置（ページ上部やハッシュリンク先）にスクロールされない
- 戻るボタンを使用した際に前回のスクロール位置が復元されない
- 一貫性のないナビゲーション体験
使用シナリオ – 特殊なアニメーションやカスタムのスクロール処理を実装する場合など、非常に限定的なケースでのみ使用すべきです。

使用例

<script>
  import { onMount } from 'svelte';
  import { afterNavigate, disableScrollHandling } from '$app/navigation';
  
  // カスタムスクロール処理を実装する例
  afterNavigate((navigation) => {
    // SvelteKit のデフォルトスクロール処理を無効化
    disableScrollHandling();
    
    // 独自のスクロール処理を実装
    setTimeout(() => {
      // 例: 特定の要素に滑らかにスクロール
      const targetElement = document.querySelector('#target-section');
      if (targetElement) {
        targetElement.scrollIntoView({ behavior: 'smooth' });
      } else {
        // ターゲットがなければページトップへ
        window.scrollTo({ top: 0, behavior: 'smooth' });
      }
    }, 100);
  });
</script>

上記のような実装は、特殊なケースでのみ検討すべきで、通常は SvelteKit の標準スクロール処理を尊重することが推奨されています。ユーザーはページ遷移後に特定の動作（ページトップへのスクロールやハッシュリンクへのスクロールなど）を期待しているため、それを変更すると混乱を招く可能性があります。

goto

プログラムによって特定のルートにナビゲーションすることができ、現在フォーカスされている要素を維持するなどのオプションを提供します。SvelteKit が指定された url にナビゲーションした（またはナビゲーションに失敗した場合は、プロミスが拒否される）ときに解決する Promise を返します。外部 URL の場合は、goto(url) を呼び出す代わりに window.location = url を使用してください。

function goto(
	url: string | URL,
	opts?:
		| {
				replaceState?: boolean | undefined;
				noScroll?: boolean | undefined;
				keepFocus?: boolean | undefined;
				invalidateAll?: boolean | undefined;
				invalidate?:
					| (string | URL | ((url: URL) => boolean))[]
					| undefined;
				state?: App.PageState | undefined;
		  }
		| undefined
): Promise<void>;

解説

goto は SvelteKit のナビゲーション機能で、以下のような特徴があります：

プログラムによるナビゲーション – JavaScript からページ遷移を制御できます。
引数:
- url: 文字列または URL オブジェクトで、ナビゲーション先を指定します。
- opts: オプションのオブジェクト（以下で詳細に説明）
オプション:
- replaceState: true の場合、ブラウザの履歴に新しいエントリを追加せず、現在のエントリを置き換えます。
- noScroll: true の場合、ナビゲーション後にページ上部へのスクロールを行いません。
- keepFocus: true の場合、ナビゲーション後も現在フォーカスされている要素のフォーカスを維持します。
- invalidateAll: true の場合、すべてのデータを再取得します。
- invalidate: 特定のデータ（URL パターンなど）を再取得するための配列を指定します。
- state: ページの状態情報をブラウザの履歴エントリに関連付けることができます。
Promise の返却 – ナビゲーションの成功または失敗に応じて解決または拒否される Promise を返します。
内部/外部 URL の扱い – SvelteKit アプリ内のルートへのナビゲーションに使用し、外部 URL には window.location を使用すべきです。

使用例

<script>
  import { goto } from '$app/navigation';
  
  async function handleLogin() {
    // ログイン処理
    const success = await loginUser();
    
    if (success) {
      // ログイン成功後、ダッシュボードページへ移動
      try {
        await goto('/dashboard', {
          // 履歴に「戻る」でログイン画面に戻れないようにする
          replaceState: true,
          // ダッシュボードのトップにスクロール
          noScroll: false,
          // 最新のデータを取得
          invalidateAll: true
        });
        console.log('ダッシュボードへ移動しました');
      } catch (error) {
        console.error('ナビゲーションに失敗しました', error);
      }
    }
  }
  
  function navigateWithState() {
    // 状態情報を付与してナビゲーション
    goto('/product/123', {
      state: { 
        fromSearch: true,
        searchQuery: 'スマートフォン' 
      }
    });
  }
  
  function handleExternalLink() {
    // 外部リンクには goto ではなく location を使用
    window.location = 'https://example.com';
  }
</script>

<button on:click={handleLogin}>ログイン</button>
<button on:click={navigateWithState}>商品詳細へ</button>
<button on:click={handleExternalLink}>外部サイトへ</button>

この関数は、フォーム送信後のリダイレクト、ボタンクリック時のページ遷移、条件に応じた動的なナビゲーションなど、様々なシナリオでプログラムによるページ遷移を実現するために使用できます。