svelte-reference

Svelte API リファレンス（Svelte 5）

このスキルは、svelte/store、svelte/action、svelte/transition、svelte/animate、svelte/easing、svelte/events、svelte/compiler の公式 Svelte モジュール API と、よく使われるコンパイラー／ランタイムのエラーコードを素早く確認するためのリファレンスです。

このスキルを使う場面

Svelte の特定モジュールの API シグネチャを確認したい場合、transition／in／out／animate ディレクティブ、use: アクション、easing 関数、エラーコードの意味、またはコンパイラー設定を調べたい場合に、このスキルを使います。

重要：svelte/store

import { writable, readable, derived, readonly, get } from 'svelte/store';

関数	シグネチャ	説明
writable	(initial, start?) => { subscribe, set, update }	書き込み可能なストア
readable	(initial, start) => { subscribe }	読み取り専用ストア（値を設定できるのは内部の start のみです）
derived	(stores, fn, initial?) => { subscribe }	派生ストア
readonly	(store) => store	読み取り専用バージョンを返します（set／update はありません）
get	(store) => value	購読せずに値を取得します（同期的に、一時的な購読を作成します）

ストアの契約

store = {
  subscribe: (subscription: (value: any) => void) => (() => void),
  set?: (value: any) => void
}

ストアと Runes の使い分け

• Runes を優先してください（.svelte.js ファイル内の $state）。共有状態やロジックの抽出に適しています。
• 複雑な非同期データストリームがある場合、更新を手動で制御する必要がある場合、または RxJS スタイルのオペレーターを使いたい場合は、ストアを使ってください。

writable の Start 関数

writable(initial, start) — 購読者数が 0 → 1 になったとき（1 → 2 ではありません）、start コールバックが呼び出されます。購読者数が 1 → 0 になったときに実行される stop 関数を返します。start コールバックは set に加えて、変換ベースの更新に使う update 関数も受け取ります。

derived の形式

// single store
const doubled = derived(a, ($a) => $a * 2);

// array of stores
const sum = derived([a, b], ([$a, $b]) => $a + $b);

// async — second arg is `set`, third is `update`, third `derived` arg is initial value
const delayed = derived(a, ($a, set) => {
  setTimeout(() => set($a), 1000);
}, 0);

// with cleanup — return a function from the callback
const tick = derived(frequency, ($frequency, set) => {
  const id = setInterval(() => set(Date.now()), 1000 / $frequency);
  return () => clearInterval(id);
}, 0);

get(store) の注意点

一時的な購読を作成し、値を読み取った後に購読を解除します。頻繁に実行される処理では避けてください。

重要：svelte/action（use: ディレクティブ）

アクションは、要素のマウント時に呼び出される関数です。use: ディレクティブを使って追加します。

<script>
  /** @type {import('svelte/action').Action} */
  function myAction(node) {
    // node: HTMLElement — runs once on mount (client only, not SSR)
    $effect(() => {
      // setup
      return () => {
        // teardown — runs on unmount
      };
    });
  }
</script>

<div use:myAction>...</div>

メモ

Svelte 5.29 以降では、より柔軟で組み合わせやすい {@attach ...} の使用を検討してください。

パラメーターを持つアクション

パラメーターはリアクティブではありません。アクションはマウント時に一度だけ実行されます。パラメーターの変更に反応させるには、内部で $effect を使ってください。

<script>
  /** @type {import('svelte/action').Action<HTMLInputElement, number>} */
  function debounce(node, delay) {
    $effect(() => {
      const handler = () => setTimeout(() => node.dispatchEvent(new Event('done')), delay);
      node.addEventListener('input', handler);
      return () => node.removeEventListener('input', handler);
    });
  }
</script>

<input use:debounce={300} />

レガシーな update／destroy 形式

<script>
  /** @type {import('svelte/action').Action<HTMLDivElement, string>} */
  function colorize(node, color) {
    node.style.color = color;
    return {
      update(newColor) { node.style.color = newColor; },
      destroy() { node.style.color = ''; }
    };
  }
</script>

<div use:colorize={'red'}>...</div>

新しいコードでは $effect 形式を優先してください。

型付け — Action<Node, Parameter, Events>

<script lang="ts">
  import type { Action } from 'svelte/action';

  const gestures: Action<HTMLDivElement, undefined, {
    onswipeleft: (e: CustomEvent) => void;
    onswiperight: (e: CustomEvent) => void;
  }> = (node) => {
    // dispatch: node.dispatchEvent(new CustomEvent('swipeleft'));
  };
</script>

<div use:gestures onswipeleft={next} onswiperight={prev}>...</div>

3 番目の型パラメーターを指定すると、テンプレート内の onswipeleft／onswiperight が型チェックされます。

重要：svelte/transition（transition: ディレクティブ）

<script>
  import { fade, fly, slide, scale, blur, draw, crossfade } from 'svelte/transition';
</script>

{#if visible}
  <div transition:fade={{ duration: 300, delay: 100 }}>fade</div>
  <div transition:fly={{ y: 20, duration: 300 }}>fly</div>
  <div transition:slide>slide</div>
  <div transition:scale={{ start: 0.5, duration: 300 }}>scale</div>
  <div transition:blur={{ amount: 10 }}>blur</div>
{/if}

transition: は双方向です。中断されると逆方向に再生されます。

組み込みトランジション

関数	効果	主なパラメーター
fade	透明度	duration
fly	位置を移動しながら表示	x, y, opacity
slide	スライド	axis: 'x' | 'y'
scale	拡大・縮小	start, opacity
blur	ぼかし＋透明度	amount
draw	SVG パスの描画	speed or duration
crossfade	ペア間のフェード	duration, fallback

トランジションのパラメーター

{
  delay?: number,        // ms before starting (default 0)
  duration?: number,     // ms (default 400)
  easing?: function,     // easing (default linear)
  css?: (t, u) => string,// web animation CSS (preferred)
  tick?: (t, u) => void  // imperative (use only when CSS cannot)
}

イントロ時は t が 0 → 1、アウトロ時は 1 → 0 になります。u = 1 - t です。イージングは、css／tick に渡される前に t に適用されます。css と tick は同時に指定できません。

ローカルとグローバル

<div transition:fade>...</div>


<div transition:fade|global>...</div>

トランジションイベント

イベント	発生タイミング
introstart	イントロアニメーションの前
introend	イントロアニメーションの後
outrostart	アウトロアニメーションの前
outroend	アウトロアニメーションの後

<div
  transition:fly={{ y: 200, duration: 2000 }}
  onintrostart={() => (status = 'intro started')}
  onoutroend={() => (status = 'outro ended')}
>...</div>

カスタムトランジション関数

// @noErrors
transition = (
  node: HTMLElement,
  params: any,
  options: { direction: 'in' | 'out' | 'both' }
) => {
  delay?: number;
  duration?: number;
  easing?: (t: number) => number;
  css?: (t: number, u: number) => string;
  tick?: (t: number, u: number) => void;
}

関数がオブジェクトではなく関数を返す場合、Svelte は次のマイクロタスクでその関数を呼び出します。これは crossfade がペアのトランジションを連携させるために使う仕組みです。

重要：in: と out:（個別のトランジション）

in: と out: は一方向で、割り込み時に反転しません。イントロ中にブロックをオフにすると、進行中のイントロは中断され、アウトロトランジションが t=0 から再開します。

<script>
  import { fade, fly } from 'svelte/transition';
  let visible = $state(false);
</script>

{#if visible}
  
  <div in:fly={{ y: 200 }} out:fade>...</div>
{/if}

ディレクティブ	実行されるタイミング	割り込み時に反転するか
transition:	入場時または退場時	はい（進行中に反転します）
in:	入場時のみ	いいえ（中断されます）
out:	退場時のみ	いいえ（常に順方向に再生します）

入場時と退場時でアニメーションの見た目を変えたい場合は、in: / out: を使います。カスタムトランジション関数の第3引数は { direction: 'in' | 'out' | 'both' } です。

重要：svelte/easing

import { cubicIn, cubicOut, cubicInOut, elasticOut, bounceOut } from 'svelte/easing';

イージング	説明
linear	等速
quadIn/quadOut/quadInOut	二次
cubicIn/cubicOut/cubicInOut	三次イージング
quartIn/quartOut/quartInOut	四次
quintIn/quintOut/quintInOut	五次
sineIn/sineOut/sineInOut	正弦
expoIn/expoOut/expoInOut	指数
circIn/circOut/circInOut	円
elasticIn/elasticOut/elasticInOut	弾性
backIn/backOut/backInOut	戻り
bounceIn/bounceOut/bounceInOut	バウンス

<div transition:fly={{ y: 100, easing: cubicOut }}>...</div>

重要：animate: (svelte/animate)

animate: は、キー付き {#each} ブロック内で既存のアイテムのインデックスが変わったときに実行されます。追加や削除時には実行されません。キー付き each ブロックの直接の子要素に指定する必要があります。

<script>
  import { flip } from 'svelte/animate';
  let items = $state(['apple', 'banana', 'cherry']);
</script>

{#each items as item (item)}
  <li animate:flip={{ duration: 400, easing: quintOut }}>{item}</li>
{/each}

flip（FLIP テクニック）

変更前後の境界矩形を測定し、逆向きの transform を適用した後、恒等変換に戻るようアニメーションします。API の詳細は references/animations-reference.md を参照してください。

flip(node, {
  delay?: number,
  duration?: number | (node, { from, to }) => number,
  easing?: function
})

カスタムアニメーション関数

// @noErrors
animation = (
  node: HTMLElement,
  { from: DOMRect, to: DOMRect },
  params: any
) => {
  delay?: number;
  duration?: number;
  easing?: (t: number) => number;
  css?: (t: number, u: number) => string;
  tick?: (t: number, u: number) => void;
}

from と to は、並べ替え前後における要素の境界矩形です。距離や角度などを計算して、カスタムエフェクトに反映します。

<script>
  import { cubicOut } from 'svelte/easing';

  function whizz(node, { from, to }) {
    const dx = from.left - to.left;
    const dy = from.top - to.top;
    const d = Math.sqrt(dx * dx + dy * dy);
    return {
      duration: Math.sqrt(d) * 120,
      easing: cubicOut,
      css: (t, u) => `transform: translate(${u * dx}px, ${u * dy}px) rotate(${t * 360}deg);`
    };
  }
</script>

{#each list as item (item)}
  <div animate:whizz>{item}</div>
{/each}

animate: は追加や削除時には実行されません。その場合は in: / out: と組み合わせてください。

重要：svelte/events

イベント委譲と stopPropagation を正しく処理する、addEventListener の代替となる on 関数を提供します。

<script>
  import { on } from 'svelte/events';

  const handler = on(node, 'click', (event) => {
    // 正确处理委托和 stopPropagation
  }, { passive: true });
</script>

重要：svelte/reactivity

$effect.tracking

$effect.tracking(); // boolean，是否在追踪上下文中

createSubscriber

サブスクライバーを作成します（追跡コンテキスト内でのみ動作します）。

import { createSubscriber } from 'svelte/reactivity';
const subscriber = createSubscriber((track) => {
  track(value); // 声明依赖
});

重要：コンパイラーエラー（よくあるもの）

コード	意味	解決方法
2304	未定義の参照	変数名のスペルとインポートを確認します
2322	対象の要素が存在しません	target セレクターを確認します
2554	型が一致しません	TypeScript の型注釈を確認します
2451	effect の外で state を変更しています	$effect 内で $state を直接代入しないでください
7006	引数の型が正しくありません	関数シグネチャを確認します

重要：ランタイム警告（よくあるもの）

コード	意味	解決方法
ownership_invalid_mutation	所有していない状態を変更しています	prop を直接変更せず、$bindable を使います
await_waterfall	await の依存関係によってパフォーマンスの問題が発生しています	データ取得ロジックをリファクタリングします
state_teardown	破棄後に更新しようとしています	コンポーネントがアンマウントされた後にアクセスしていないことを確認します

重要：svelte/compiler

設定項目

import { compile } from 'svelte/compiler';
const result = compile(source, {
  filename: 'App.svelte',
  generate: 'dom',       // 'dom' | 'ssr' | false
  name: 'Component',      // 导出名
  format: 'esm',         // 'esm' | 'cjs'
  sveltePath: 'svelte',  // svelte 包路径
  dev: true,             // 开发模式（添加检查）
  css: 'injected',       // CSS 注入方式
  runes: false,           // 强制 Legacy Mode
  // ...
});

compile の出力

result.js.code;      // 编译后的 JS
result.css.code;     // 编译后的 CSS（如有）
result.warnings;     // 警告列表
result.stats;        // 编译统计

クイック修正

問題	解決方法
トランジションが実行されない	条件ブロックの変更時に要素が破棄・再作成されることを確認します。{#key} を使います
in:/out: の途中で切り替えたときの動作がおかしい	これは一方向の想定された動作です。反転できるのは transition: です
animate:flip が動作しない	(key) が必要です。また、animate: はキー付き each の直接の子要素に指定する必要があります
flip アニメーションが滑らかでない	key が一意で安定していることを確認します
イージング関数が動作しない	svelte/easing から正しくインポートしていることを確認します
use: の引数の変更が反映されない	アクションは一度しか呼び出されません。$effect 内で引数を読み取ります
コンパイラーエラーが発生する	上記のエラーコード表を確認します
ランタイム警告が発生する	所有権の連鎖を確認します

例

詳細な説明付きの実践的な使用パターン：

• examples/README.md - エントリーポイント
• examples/store-patterns.md - 書き込み可能、読み取り専用、派生ストア、自動購読、コンポーネント間での共有
• examples/motion.md - イージングを使ったトゥイーンアニメーションとスプリングアニメーション
• examples/transition.md - 組み込みトランジション、カスタムトランジション、in/out トランジション
• examples/transitions-advanced.md - クロスフェード、遅延トランジション、トランジションイベント、カスタム css/tick
• examples/in-out-animate.md - in:/out: による個別のトランジション、animate:flip、カスタムアニメーション関数
• examples/use-action.md - 型指定、ライフサイクル、カスタムイベントを含む use: ディレクティブ

リファレンス

API の完全なドキュメント：

• references/README.md - エントリーポイント
• references/store-reference.md - ストア API のシグネチャ：writable、readable、derived、get、readonly
• references/motion-reference.md - モーション API：tweened、spring、イージング関数
• references/transition-reference.md - トランジション API：fade、fly、slide、scale、カスタムトランジション
• references/transitions-complete.md - すべての組み込みトランジション、イベント、|global、カスタム関数の完全なリファレンス
• references/in-out-reference.md - 個別の（単方向）トランジションを指定する in: / out:
• references/animations-reference.md - animate: ディレクティブ、flip、カスタムアニメーション関数
• references/use-action-reference.md - use: action の型指定、ライフサイクル、Action<>、カスタムイベント

注意点

1. svelte/transition の css と tick は相互排他的です — どちらか一方だけを使用できます
2. in: / out: は可逆ではありません — 中断されると、進行中の intro は破棄され、outro は t=0 から再開します
3. animate: は keyed each の直接の子要素に指定する必要があります — ネストされた div 上の animate: は実行されません
4. flip には安定した key が必要です — 配列インデックスではなく、一意の ID を使用します
5. animate: は追加／削除には反応しません — 並べ替え時にのみ実行されます
6. Store の subscribe は unsubscribe 関数を返します — コンポーネントのアンマウント時に自動的に購読が解除されます
7. get(store) は一時的な購読を作成します — 頻繁に呼び出すとパフォーマンスに影響します
8. elasticIn/elasticOut は遅くなります — 多用するとパフォーマンスに影響する場合があります
9. use:action は引数が変わっても再呼び出しされません — action 内で $effect を使って変更に反応させます