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

よっしー

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

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

背景
$app/navigation
1. preloadData
  1. 解説
  2. 使用例
2. pushState
  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 アプリケーション内でのナビゲーション体験をカスタマイズし、よりスムーズで効率的なユーザー体験を提供することができます。

preloadData

指定されたページをプログラムによって事前に読み込みます。これは以下を意味します：

ページのコードが確実に読み込まれること
適切なオプションでページの load 関数を呼び出すこと

これは、ユーザーが data-sveltekit-preload-data 属性を持つ <a> 要素をタップまたはマウスオーバーしたときに SvelteKit がトリガーするのと同じ動作です。次のナビゲーションが href への移動である場合、load から返された値が使用され、ナビゲーションが瞬時に行われます。事前読み込みが完了すると、新しいルートの load 関数の実行結果で解決する Promise を返します。

function preloadData(href: string): Promise
	| {
			type: 'loaded';
			status: number;
			data: Record<string, any>;
	  }
	| {
			type: 'redirect';
			location: string;
	  }
>;

解説

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

コードとデータの事前読み込み – ページのコードだけでなく、load 関数も実行してデータを事前に取得します。
瞬時のナビゲーション – 事前に読み込まれたデータは次のナビゲーションで再利用されるため、ページ遷移が瞬時に行われます。
HTML 属性との一貫性 – <a data-sveltekit-preload-data> と同じ動作をプログラムから実行できます。
返り値 – 以下のいずれかの形式のオブジェクトを解決する Promise を返します：
- { type: 'loaded', status: number, data: Record<string, any> } – 読み込みが成功した場合
- { type: 'redirect', location: string } – リダイレクトが発生した場合
preloadCode との違い – preloadCode がコードのみを読み込むのに対し、preloadData はコードとデータの両方を読み込みます。

使用例

<script>
  import { preloadData } from '$app/navigation';
  
  // マウスホバー時にデータを事前読み込み
  async function handleMouseEnter(href) {
    try {
      const result = await preloadData(href);
      
      if (result.type === 'loaded') {
        console.log(`${href} のデータが事前読み込みされました:`, result.data);
      } else if (result.type === 'redirect') {
        console.log(`${href} はリダイレクトします: ${result.location}`);
      }
    } catch (error) {
      console.error(`データの事前読み込みエラー: ${error}`);
    }
  }
  
  // プログラムによる事前読み込みと条件付きナビゲーション
  async function checkAndNavigate(href) {
    try {
      const result = await preloadData(href);
      
      if (result.type === 'loaded') {
        // 例: データに基づいて追加の確認を行う
        if (result.data.requiresConfirmation) {
          const confirmed = confirm('このページに移動してもよろしいですか？');
          if (!confirmed) return;
        }
        
        // goto を使ってナビゲーション（瞬時に行われる）
        import { goto } from '$app/navigation';
        goto(href);
      } else if (result.type === 'redirect') {
        // リダイレクト先に移動
        import { goto } from '$app/navigation';
        goto(result.location);
      }
    } catch (error) {
      console.error('チェックに失敗しました', error);
    }
  }
</script>

<!-- HTML属性を使った事前読み込み -->
<a href="/dashboard" data-sveltekit-preload-data>
  ダッシュボード
</a>

<!-- JavaScript を使った事前読み込み -->
<a 
  href="/profile" 
  on:mouseenter={() => handleMouseEnter('/profile')}
>
  プロフィール
</a>

<button on:click={() => checkAndNavigate('/restricted-area')}>
  制限エリアに移動
</button>

この関数は、以下のようなシナリオで特に役立ちます：

カスタムインタラクション – 標準のリンクホバー以外のインタラクションでデータを事前読み込みしたい場合。
条件付きナビゲーション – 事前に読み込んだデータに基づいて、ナビゲーションを続行するかどうかを決定したい場合。
パフォーマンス最適化 – ユーザーの行動パターンに基づいて、次に訪問する可能性が高いページを予測して事前読み込みする場合。

preloadData はユーザー体験を大幅に向上させる強力なツールですが、不必要なデータ取得を避けるため、ユーザーが実際に訪問する可能性が高いページに限定して使用することをお勧めします。

pushState

指定された page.state で新しい履歴エントリをプログラムによって作成します。現在のURLを使用するには、最初の引数として '' を渡すことができます。シャロールーティングに使用されます。

function pushState(
	url: string | URL,
	state: App.PageState
): void;

解説

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

履歴エントリの作成 – ブラウザの履歴スタックに新しいエントリを追加します。
引数:
- url: 新しい履歴エントリに関連付ける URL。空文字列 '' を渡すと現在の URL が使用されます。
- state: ページの状態情報を表すオブジェクト。この状態は履歴エントリに関連付けられます。
シャロールーティング – ページをリロードせずに URL を変更し、新しい履歴エントリを作成したい場合に使用します。
戻るボタンの動作 – 新しいエントリが履歴に追加されるため、ブラウザの「戻る」ボタンで前の状態に戻ることができます。
replaceState との違い – pushState は新しい履歴エントリを追加しますが、replaceState は現在の履歴エントリを置き換えます。

使用例

<script>
  import { pushState } from '$app/navigation';
  
  // フィルタリングやソートなどのパラメータ変更時に履歴エントリを作成
  function updateFilter(filterValue) {
    // 現在の URL を基に新しい URL を構築
    const url = new URL(window.location);
    url.searchParams.set('filter', filterValue);
    
    // 新しい履歴エントリを作成
    pushState(url, {
      filterApplied: true,
      filterValue: filterValue,
      timestamp: Date.now()
    });
    
    // ページの状態を更新（この例ではフィルターを適用）
    applyFilter(filterValue);
  }
  
  // タブ切り替え時に履歴エントリを作成
  function switchTab(tabId) {
    // 現在の URL の hash を変更
    const url = new URL(window.location);
    url.hash = `tab-${tabId}`;
    
    // 新しい履歴エントリを作成
    pushState(url, {
      activeTab: tabId,
      scrollPosition: window.scrollY
    });
    
    // タブコンテンツを表示
    showTabContent(tabId);
  }
  
  // 現在の URL を維持したまま状態のみ変更
  function updateState(newState) {
    pushState('', {
      ...newState,
      updatedAt: new Date().toISOString()
    });
  }
</script>

<div class="filter-controls">
  <button on:click={() => updateFilter('recent')}>最近</button>
  <button on:click={() => updateFilter('popular')}>人気</button>
  <button on:click={() => updateFilter('recommended')}>おすすめ</button>
</div>

<div class="tabs">
  <button on:click={() => switchTab('info')}>情報</button>
  <button on:click={() => switchTab('specs')}>仕様</button>
  <button on:click={() => switchTab('reviews')}>レビュー</button>
</div>

<button on:click={() => updateState({ darkMode: true })}>
  ダークモードを有効化
</button>

この関数は、以下のようなシナリオで特に役立ちます：