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

よっしー

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

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

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

afterNavigate

コンポーネントがマウントされたとき、およびURLへのナビゲーションが発生するたびに、指定された callback を実行するライフサイクル関数です。 afterNavigate はコンポーネントの初期化中に呼び出す必要があります。コンポーネントがマウントされている限り、この関数はアクティブな状態を維持します。

function afterNavigate(
	callback: (
		navigation: import('@sveltejs/kit').AfterNavigate
	) => void
): void;

解説

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

ライフサイクル関数 – コンポーネントのライフサイクルに密接に関連しており、コンポーネントの初期化時に設定する必要があります。
タイミング – この関数は以下の2つのタイミングで実行されます：
- コンポーネントが最初にマウントされたとき
- アプリケーション内で新しいURLにナビゲーションしたとき
コールバック関数 – afterNavigate に渡すコールバック関数は、navigation オブジェクト（@sveltejs/kit の AfterNavigate 型）を引数として受け取ります。このオブジェクトにはナビゲーションに関する情報が含まれています。
持続性 – 一度設定すると、コンポーネントがアンマウントされるまでアクティブな状態を保ちます。

使用例

<script>
  import { afterNavigate } from '$app/navigation';
  
  let currentPath;
  
  afterNavigate((navigation) => {
    // ナビゲーション後の処理
    currentPath = navigation.to?.url.pathname;
    console.log('現在のパス:', currentPath);
    
    // ページ遷移後にスクロール位置を調整するなどの処理も可能
    if (navigation.to?.url.hash) {
      const element = document.getElementById(navigation.to.url.hash.substring(1));
      if (element) element.scrollIntoView();
    }
  });
</script>

このような形で、ページナビゲーション後の様々な処理を実装することができます。例えば、アナリティクス計測の実装やページ遷移後のUI調整などに活用できます。

beforeNavigate

リンクのクリック、goto(...) の呼び出し、またはブラウザの戻る/進むボタンの使用によってURLへのナビゲーションが発生する前に起動するナビゲーション・インターセプターです。 cancel() を呼び出すと、ナビゲーションの完了を防ぐことができます。navigation.type === 'leave' の場合（ユーザーがアプリから離れる、またはタブを閉じる場合）、cancel を呼び出すとブラウザのネイティブなアンロード確認ダイアログがトリガーされます。この場合、ユーザーの応答によってナビゲーションがキャンセルされるかどうかが決まります。ナビゲーション先が SvelteKit が所有するルート（SvelteKit のクライアントサイドルーターによって制御される）でない場合、navigation.to.route.id は null になります。ナビゲーションが（キャンセルされなければ）ドキュメントのアンロードを引き起こす場合、つまり 'leave' ナビゲーションや navigation.to.route === null となる 'link' ナビゲーションの場合、navigation.willUnload は true になります。 beforeNavigate はコンポーネントの初期化中に呼び出す必要があります。コンポーネントがマウントされている限り、この関数はアクティブな状態を維持します。

function beforeNavigate(
	callback: (
		navigation: import('@sveltejs/kit').BeforeNavigate
	) => void
): void;

解説

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

ナビゲーション・インターセプター – ナビゲーションが発生する前に処理を挟むことができます。
キャンセル機能 – コールバック内で cancel() を呼び出すことで、ナビゲーションをキャンセルできます。
ナビゲーションタイプ – 以下のようなナビゲーションタイプを区別できます：
- 'leave' – アプリから離れる（タブを閉じるなど）
- 'link' – リンクによるナビゲーション
- その他（goto や履歴ナビゲーションなど）
アンロード判定 – navigation.willUnload プロパティを通じて、ナビゲーションがドキュメントのアンロードを引き起こすかどうかを判断できます。
ルート判定 – navigation.to.route.id が null かどうかで、SvelteKit が制御するルートへのナビゲーションかどうかを判断できます。

使用例

<script>
  import { beforeNavigate } from '$app/navigation';
  
  let formChanged = false;
  
  beforeNavigate((navigation) => {
    // フォームが変更されていて、かつユーザーがページから離れようとしている場合
    if (formChanged && navigation.type !== 'popstate') {
      // ナビゲーションをキャンセルし、確認ダイアログを表示
      const confirmed = confirm('変更が保存されていません。本当に移動しますか？');
      if (!confirmed) {
        navigation.cancel();
      }
    }
    
    // 外部サイトへのナビゲーションの前に警告を表示
    if (navigation.to && !navigation.to.route.id) {
      console.log('外部サイトへ移動します');
    }
  });
  
  function updateForm() {
    formChanged = true;
  }
</script>

<form on:change={updateForm}>
  <!-- フォーム要素 -->
</form>

この関数は、未保存のフォームデータがある場合の警告表示や、特定の条件下でのナビゲーション制御など、ユーザー体験を向上させるための様々なシナリオで活用できます。