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

よっしー

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

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

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

replaceState

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

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

解説

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

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

使用例

<script>
  import { replaceState } from '$app/navigation';
  
  // URL クエリパラメータを更新するが、履歴には新しいエントリを作成しない
  function updateSearchParams(key, value) {
    // 現在の URL を基に新しい URL を構築
    const url = new URL(window.location);
    
    if (value) {
      url.searchParams.set(key, value);
    } else {
      url.searchParams.delete(key);
    }
    
    // 現在の履歴エントリを置き換え
    replaceState(url, {
      lastUpdated: Date.now(),
      [key]: value
    });
    
    // 必要に応じてページの状態を更新
    updatePageContent();
  }
  
  // 一時的な状態の更新（履歴に残したくない変更）
  function updateTempState(newState) {
    replaceState('', {
      ...newState,
      isTemporary: true
    });
  }
  
  // ページロード直後に URL を正規化
  import { onMount } from 'svelte';
  
  onMount(() => {
    // URL を正規化（例: 余分なスラッシュの削除、パラメータの並べ替えなど）
    const currentUrl = new URL(window.location);
    const normalizedUrl = normalizeUrl(currentUrl);
    
    if (currentUrl.toString() !== normalizedUrl.toString()) {
      replaceState(normalizedUrl, {});
    }
  });
  
  function normalizeUrl(url) {
    // URL 正規化ロジック
    // この例では単に URL をそのまま返します
    return url;
  }
</script>

<div class="search-controls">
  <input 
    type="text" 
    placeholder="検索..."
    on:input={(e) => updateSearchParams('q', e.target.value)}
  />
  
  <select on:change={(e) => updateSearchParams('sort', e.target.value)}>
    <option value="relevance">関連性</option>
    <option value="date">日付</option>
    <option value="price">価格</option>
  </select>
</div>

<button on:click={() => updateTempState({ showHelpPanel: true })}>
  ヘルプを表示
</button>

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