This is the abridged developer documentation for Svelte and SvelteKit. # Start of Svelte documentation # 概要 Svelte は Web 上のユーザーインターフェースを構築するためのフレームワークです。Svelte はコンパイラを使用し、HTML、CSS、JavaScript で記述された宣言的なコンポーネントを... ```svelte ``` ...無駄のない、タイトで最適化された JavaScript に変換します。 これにより、スタンドアローンなコンポーネントからフルスタックアプリ (Svelte のアプリケーションフレームワークである [SvelteKit](../kit) を使用) まで、お望みのものをなんでも構築することができます。 こちらのページはリファレンスドキュメントとして提供されています。もしあなたが Svelte の初心者なら、先に[インタラクティブなチュートリアル](/tutorial)から始めて、わからないことがあるときにこちらに戻ってくることをおすすめします。 また、[Playground](/playground) を使ってオンラインで Svelte を試すこともできますし、より高機能な環境が必要なら [StackBlitz](https://sveltekit.new) で試すこともできます。 # Getting started Svelte チームによるオフィシャルなアプリケーションフレームワークである [SvelteKit](../kit) をお使いいただくことをおすすめします。これには [Vite](https://vite.dev/) が搭載されています: ```bash npx sv create myapp cd myapp npm install npm run dev ``` まだ Svelte についてよく知らなくても心配いりません! SvelteKit が提供する便利な機能等は一旦無視して、後から学び始めても問題ありません。 ## SvelteKit の代替手段 Svelteを直接Viteで使用することもできます。その場合、`npm create vite@latest` を実行し、`svelte` オプションを選択します。この方法では、`npm run build` を実行すると、[vite-plugin-svelte](https://github.com/sveltejs/vite-plugin-svelte) を使用して、`dist` ディレクトリ内に HTML、JS、CSSファイルが生成されます。ほとんどの場合、[ルーティングライブラリ](faq#Is-there-a-router)を選択する必要があるでしょう。 また、[Rollup](https://github.com/sveltejs/rollup-plugin-svelte)、[Webpack](https://github.com/sveltejs/svelte-loader)、[その他いくつかのプラグイン](https://sveltesociety.dev/packages?category=build-plugins)もありますが、Viteをお勧めします。 ## エディタツール Svelteチームは、[VS Code 拡張機能](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)を提供しています。また、様々な[他のエディター](https://sveltesociety.dev/resources#editor-support)やツールとの統合も利用可能です。 さらに、[sv check](https://github.com/sveltejs/cli) を使ってコマンドラインからコードをチェックすることもできます。 ## サポートを受ける [Discord チャットルーム](/chat)で気軽に質問してください！また、[Stack Overflow](https://stackoverflow.com/questions/tagged/svelte) でも回答を見つけることができます。 # .svelte ファイル コンポーネントは Svelte アプリケーションの構成要素です。これらは `.svelte` ファイルに書かれ、HTML のスーパーセットを使って記述されます。 以下の3つのセクション — script, styles, markup — は任意です。 ```svelte /// file: MyComponent.svelte ``` ## ` ``` このブロックから `export` バインディングを使用してエクスポートすることができ、それらはコンパイルされたモジュールのエクスポートとして扱われます。ただし、コンポーネント自体にデフォルトエクスポートがされるため `export default` は使用できません。 > Svelte 4 では、このスクリプトタグは ` ``` (もしかしたらあなたが使用したことがあるかもしれない) 他のフレームワークとは違い、state を操作するための API はありません — `count` はオブジェクトや関数ではなくただの number であり、他の変数を更新するのと同じように更新することができます。 ### Deep state もし `$state` を配列やシンプルなオブジェクトで使用した場合、リアクティブが深い (原文: deeply reactive) _state proxy_ になります。[proxy](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Proxy) によって Svelte はプロパティが読み書き (`array.push(...)` のようなメソッド経由で行われたものを含む) されたときにコードを実行でき、きめ細やかな更新 (原文: granular updates) をトリガーすることができます。 state は、Svelte が配列やシンプルなオブジェクト以外のものを見つけるまで再帰的に proxy 化 されます。このような場合... ```js let todos = $state([ { done: false, text: 'add more todos' } ]); ``` ...個々の todo のプロパティが変更されると、UI の中の、その変更されたプロパティに依存する部分に対して更新がトリガーされます: ```js let todos = [{ done: false, text: 'add more todos' }]; // ---cut--- todos[0].done = !todos[0].done; ``` 配列に新たなオブジェクトを push すると、それも proxy 化されます。 ```js let todos = [{ done: false, text: 'add more todos' }]; // ---cut--- todos.push({ done: false, text: 'eat lunch' }); ``` もしリアクティブな値を分割した場合、その参照はリアクティブではありません — 通常の JavaScript と同じように、分割時点で評価されます: ```js let todos = [{ done: false, text: 'add more todos' }]; // ---cut--- let { done, text } = todos[0]; // this will not affect the value of `done` todos[0].done = !todos[0].done; ``` ### Classes class のフィールド (public か private かを問わず) にも `$state` を使用することができます : ```js // @errors: 7006 2554 class Todo { done = $state(false); text = $state(); constructor(text) { this.text = text; } reset() { this.text = ''; this.done = false; } } ``` JavaScript でメソッドを呼び出すとき、[`this`](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Operators/this) の値が問題になります。以下のコードは動作しません、なぜなら `reset` メソッドの中にある `this` が `Todo` ではなく ` ``` インライン関数を使うこともできますし... ```svelte ``` ...class の定義でアロー関数を使うこともできます: ```js // @errors: 7006 2554 class Todo { done = $state(false); text = $state(); constructor(text) { this.text = text; } +++reset = () => {+++ this.text = ''; this.done = false; } } ``` ## `$state.raw` オブジェクトや配列を、深いリアクティブ (deeply reactive) にしたくない場合は、`$state.raw` を使用します。 `$state.raw` で宣言された state は変更できません、再代入のみ可能です。言い換えると、もし更新したいのであれば、オブジェクトのプロパティに代入したり配列のメソッドの `push` などを使用するのではなく、オブジェクトや配列を丸ごと置き換えてください。 ```js let person = $state.raw({ name: 'Heraclitus', age: 49 }); // this will have no effect person.age += 1; // this will work, because we're creating a new person person = { name: 'Heraclitus', age: 50 }; ``` 変更する予定がない大きい配列やオブジェクトでこれを使用すると、パフォーマンスを改善することができます。リアクティブにするためのコストを避けられるからです。raw state には、リアクティブな state を含められることにご注意ください (例えば、リアクティブなオブジェクトの配列 (原文: a raw array of reactive objects))。 ## `$state.snapshot` 深いリアクティブ (deeply reactive) な `$state` proxy の静的なスナップショットを取得するには、`$state.snapshot` を使用します: ```svelte ``` これは、例えば `structuredClone` のような proxy を受け付けない外部のライブラリや API に state を渡したいときに便利です。 ## 関数に state を渡す JavaScript は _値渡し_ の言語です — 関数を呼び出すとき、その引数は _変数_ ではなく _値_ です。言い換えると: ```js /// file: index.js // @filename: index.js // ---cut--- /** * @param {number} a * @param {number} b */ function add(a, b) { return a + b; } let a = 1; let b = 2; let total = add(a, b); console.log(total); // 3 a = 3; b = 4; console.log(total); // still 3! ``` もし `add` が `a` と `b` の現在の値にアクセスし、`total` の現在の値を返したいのであれば、代わりに関数を使う必要があります: ```js /// file: index.js // @filename: index.js // ---cut--- /** * @param {() => number} getA * @param {() => number} getB */ function add(+++getA, getB+++) { return +++() => getA() + getB()+++; } let a = 1; let b = 2; let total = add+++(() => a, () => b)+++; console.log(+++total()+++); // 3 a = 3; b = 4; console.log(+++total()+++); // 7 ``` Svelte の state も同様です — `$state` rune で宣言されたものを参照するとき... ```js let a = +++$state(1)+++; let b = +++$state(2)+++; ``` ...その現在の値にアクセスします。 '関数(function)' は意味が広範囲にわたることにご注意ください — proxy のプロパティや [`get`](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Functions/get)/[`set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) プロパティも包含しています... ```js /// file: index.js // @filename: index.js // ---cut--- /** * @param {{ a: number, b: number }} input */ function add(input) { return { get value() { return input.a + input.b; } }; } let input = $state({ a: 1, b: 2 }); let total = add(input); console.log(total.value); // 3 input.a = 3; input.b = 4; console.log(total.value); // 7 ``` ...もしこのようなコードを書いている場合は、代わりに [class](#Classes) を使用することをご検討ください。 # $derived derived state は `$derived` rune を使用して宣言します: ```svelte

{count} doubled is {doubled}

``` `$derived(...)` 内の式は副作用(side-effects)がないものでなければなりません。Svelte は derived の式の中での state の変更 (例: `count++`) を許可しません。 `$state` と同様に、class のフィールドを `$derived` としてマークすることができます。 ## `$derived.by` 短い式に収まらない複雑な derived を作成する必要がある場合があります。その場合は、引数として関数を受け取る `$derived.by` を使用できます。 ```svelte ``` 本質的に、`$derived(expression)` は `$derived.by(() => expression)` と同等です。 ## 依存関係を理解する `$derived` 式 (または `$derived.by` の関数本体) 内で同期的に読み取られるものはすべて、derived state の _依存関係(dependency)_ と見なされます。その state が変更されると、derived は _dirty_ としてマークされ、次回読み取られる際に再計算されます。 state の一部を依存関係として扱わないようにするには、[`untrack`](svelte#untrack) を使用します。 ## 更新の伝搬 Svelte は _push-pull reactivity_ と呼ばれる仕組みを使用しています — state が更新されると、それに依存するすべてのもの (直接的または間接的であるかを問わず) に即座に変更が通知されますが ('push')、derived の値は実際に読み取られるまで再評価されません ('pull')。 derived の新しい値が以前の値と参照的に同一である場合、下流の更新はスキップされます。つまり、`large` が変更されたときのみ、ボタン内のテキストが更新され、`count` が変更されても更新されません (たとえ `large` が `count` に依存していたとしても): ```svelte ``` # $effect effect とは、アプリケーションに「動作」をさせるものを指します。Svelte が effect 関数を実行すると、その関数内でアクセスされる state (および derived state) を追跡し (ただし、[`untrack`](svelte#untrack) 内でアクセスされた場合は除く)、その state が後で変更されると関数を再実行します。 Svelte アプリのほとんどの effect は Svelte 自体によって作成されます — 例えば、`name` が変更されたときに `

hello {name}!

` のテキストを更新する部分です。 しかし、自分自身で `$effect` rune を使用して独自の effect を作成することもできます。これは、外部システム (ライブラリや `` 要素、またはネットワークをまたぐ何か) を Svelte アプリ内の state と同期する必要がある場合に便利です。 effect は、コンポーネントが DOM にマウントされた後に実行され、state の変更後には [マイクロタスク](https://developer.mozilla.org/ja/docs/Web/API/HTML_DOM_API/Microtask_guide) 内で実行されます ([デモ](/REMOVED)): ```svelte ``` 再実行はバッチで処理され(例えば、`color` と `size` を同時に変更しても、別々の再実行は発生しません)、DOM 更新が適用された後に発生します。 `$effect` は、コンポーネント初期化中 (または親の effect がアクティブな間) に呼び出される限り、コンポーネントのトップレベルだけでなくどこにでも配置できます。それはコンポーネント (または親の effect) のライフサイクルに結び付けられるため、コンポーネントがアンマウントされるとき (または親の effect が破棄されるとき) に自動的に破棄されます。 `$effect` から関数を返すことができ、その関数は effect が再実行される直前および破棄される直前に実行されます ([デモ](/REMOVED))。 ```svelte

{count}

``` ### 依存関係を理解する `$effect` は、その関数内で _同期的に_ 読み取られたリアクティブな値 (`$state`, `$derived`, `$props`) を自動的に検出し、それらを依存関係として登録します。それらの依存関係が変更されたとき、`$effect` は再実行をスケジュールします。 非同期的に読み取られる値 (例えば、`await` の後や `setTimeout` 内) は追跡されません。この例では、`color` が変更されると canvas が再描画されますが、`size` が変更されても再描画されません ([デモ](/REMOVED))。 ```ts // @filename: index.ts declare let canvas: { width: number; height: number; getContext(type: '2d', options?: CanvasRenderingContext2DSettings): CanvasRenderingContext2D; }; declare let color: string; declare let size: number; // ---cut--- $effect(() => { const context = canvas.getContext('2d'); context.clearRect(0, 0, canvas.width, canvas.height); // これは `color` が変更されるたびに再実行されます... context.fillStyle = color; setTimeout(() => { // ...しかしこれは `size` が変更されても再実行されません context.fillRect(0, 0, size, size); }, 0); }); ``` effect は、読み取るオブジェクトそのものが変更された場合にのみ再実行され、その中のプロパティが変更された場合には再実行されません。(オブジェクト内部の変更を開発時に観察したい場合は、[`$inspect`]($inspect) を使用できます。) ```svelte

{state.value} doubled is {derived.value}

``` effect は、前回実行されたときに読み取られた値のみに依存します。これは、条件付きコードを持つ effect にとって興味深い含意があります。 例えば、以下のコードスニペットで `a` が `true` の場合、`if` ブロック内のコードが実行され、`b` が評価されます。そのため、`a` または `b` の変更が [effect を再実行を引き起こします](/REMOVED)。 一方で、`a` が `false` の場合、`b` は評価されず、 effect は `a` が変更されたときに _のみ_ 再実行されます。 ```ts let a = false; let b = false; // ---cut--- $effect(() => { console.log('running'); if (a) { console.log('b:', b); } }); ``` ## `$effect.pre` 稀なケースでは、DOM 更新の _前に_ コードを実行する必要がある場合があります。そのためには `$effect.pre` rune を使用できます: ```svelte
{#each messages as message}

{message}

{/each}
``` タイミングを除けば、`$effect.pre` は `$effect` とまったく同じように機能します。 ## `$effect.tracking` `$effect.tracking` rune は高度な機能で、コードが effect やテンプレートなどの tracking context の中でで実行されているかどうかを示します ([デモ](/REMOVED)): ```svelte

in template: {$effect.tracking()}

``` これは、[`createSubscriber`](/docs/svelte/svelte-reactivity#createSubscriber) のような抽象化を実装するために使用されます。これにより、リアクティブな値を更新するリスナーが作成されますが、それらの値が追跡されている場合に _のみ_ 実行されます (例えば、イベントハンドラー内で読み取られる場合は除きます)。 ## `$effect.root` `$effect.root` rune は高度な機能で、自動クリーンアップされない非トラッキングスコープ (non-tracked scope) を作成します。これは、手動で制御したいネストされた effect に便利です。また、この rune は、コンポーネント初期化フェーズの外部で effect を作成することも可能にします。 ```svelte ``` ## `$effect` を使うべきでないとき 一般的に、`$effect` は脱出口 (エスケープハッチ) のようなものと考えるのが最善です。たとえば、アナリティクス や直接的な DOM 操作などに便利ですが、頻繁に使用するツールではありません。特に、state を同期するために使用するのは避けてください。このように使用するのではなく... ```svelte ``` ...このようにしてください: ```svelte ``` effect を使ってある値を別の値に関連付けるような複雑な処理をしたくなるかもしれません。次の例は、「支出金額(money spent)」と「残高(money left)」という2つの入力が互いに連動していることを示しています。一方を更新すると、もう一方もそれに応じて更新されるべきです。このようなケースで effect を使用しないでください ([デモ](/REMOVED)): ```svelte ``` 代わりに、可能な場合はコールバックを使用してください ([デモ](/REMOVED)): ```svelte ``` 何らかの理由でバインディングを使用する必要がある場合 (例えば "書き込み可能な `$derived`" が必要な場合)、getter と setter を使用して state を同期することを検討してください ([デモ](/REMOVED)): ```svelte ``` どうしても effect 内で `$state` を更新する必要があり、同じ `$state` を読み書きすることで無限ループに陥った場合は、[untrack](svelte#untrack) を使用してください。 # $props コンポーネントへの入力は _props_ (プロパティの省略形) と呼ばれます。属性を要素に渡すのと同じように、props をコンポーネントに渡します: ```svelte ``` それに対し、`MyComponent.svelte` の内部では、`$props` rune を使用して props を受け取ることができます... ```svelte

this component is {props.adjective}

``` ...ただし、一般的には props を [_分割代入_](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) することが多いです: ```svelte

this component is {+++adjective+++}

``` ## Fallback values 分割代入を使用するとフォールバック値を宣言できます。これは親コンポーネントが特定の props を設定しない場合に使用されます: ```js let { adjective = 'happy' } = $props(); ``` ## Renaming props 分割代入を使用して props をリネームすることもできます。これは元の props の名前が無効な識別子や `super` のような JavaScript キーワードである場合に必要となります: ```js let { super: trouper = 'lights are gonna find me' } = $props(); ``` ## Rest props 最後に、_rest property_ を使用して、他のすべての props を取得できます: ```js let { a, b, c, ...others } = $props(); ``` ## Updating props コンポーネント内の props に対する参照は、その props 自体が更新されると更新されます — `App.svelte` の `count` が変更されると、それは `Child.svelte` 内でも変更されます。ただし、子コンポーネントは一時的に prop の値を上書きすることができ、これは保存されない一時的な state として便利です ([demo](/REMOVED)): ```svelte ``` ```svelte ``` props は一時的に再代入（reassign）することができます。一方で、[bindable]($bindable) でない限り変異（mutate）すべきではありません。 prop が通常のオブジェクトの場合、変異させても何の効果もありません ([デモ](/REMOVED)): ```svelte ``` ```svelte ``` props がリアクティブな state proxy の場合、変異(mutation)は反映されますが、[`ownership_invalid_mutation`](runtime-warnings#Client-warnings-ownership_invalid_mutation) 警告が表示されます。これは、そのコンポーネントが「所有していない」state を変異(mutate)しているためです ([デモ](/REMOVED)): ```svelte ``` ```svelte ``` `$bindable` として宣言されていない props のフォールバック値はそのままです — リアクティブな state proxy には変換されません — つまり変異(mutation)しても更新は発生しません ([デモ](/REMOVED)) ```svelte ``` 要約: props を変異(mutate)しないでください。変更を伝えるためにコールバック props を使用するか、親と子が同じオブジェクトを共有する必要がある場合は [`$bindable`]($bindable) rune を使用してください。 ## Type safety 他の変数宣言と同様に、props にアノテーションを付けることでコンポーネントに型安全性を追加できます。TypeScript では次のようになります... ```svelte ``` ...一方、JSDoc では次のようにできます: ```svelte ``` もちろん、型宣言をアノテーションから分離することもできます: ```svelte ``` 型を追加することをお勧めします。これにより、コンポーネントを使用する人々が、渡すべき props を簡単に発見できるようになります。 # $bindable 通常、props は親から子へ一方向に流れます。これにより、アプリ内のデータの流れを簡単に理解することができます。 Svelte では、コンポーネントの props を _バインド_ することができ、データを子から親へと _逆方向_ に流すこともできます。これは頻繁に行うべきことではありませんが、慎重かつ控えめに使用すればコードを簡素化できます。 また、子コンポーネント内で state proxy を _変異_ (mutate) できることを意味します。 props をバインド可能 (bindable) としてマークするには、`$bindable` rune を使用します: ```svelte /// file: FancyInput.svelte ``` これで、`` を使用するコンポーネントに [`bind:`](bind) ディレクティブを追加することができます ([デモ](/REMOVED)): ```svelte /// App.svelte

{message}

``` 親コンポーネントは必ずしも `bind:` を使用する必要はありません — その場合、通常の props を渡すだけで構いません。子の発言を聞きたくない親もいるかもしれません。 この場合、何も props が渡されないときのフォールバック値を指定することができます: ```js /// file: FancyInput.svelte let { value = $bindable('fallback'), ...props } = $props(); ``` # $inspect `$inspect` rune はおおむね `console.log` と同等ですが、引数が変更されるたびに再実行される点が異なります。`$inspect` はリアクティブな state を深く追跡し、オブジェクトや配列内のプロパティやアイテムなどをきめ細やかなリアクティビティで更新すると、再度発火します ([デモ](/REMOVED)): ```svelte ``` ## $inspect(...).with `$inspect` は `with` プロパティを返します。このプロパティにはコールバックを渡すことができ、`console.log` の代わりにそのコールバックが呼び出されます。コールバックの最初の引数は `"init"` または `"update"` で、以降の引数には `$inspect` に渡された値が含まれます ([デモ](/REMOVED)): ```svelte ``` 変更の起点を見つける便利な方法は、`with` に `console.trace` を渡すことです: ```js // @errors: 2304 $inspect(stuff).with(console.trace); ``` ## $inspect.trace(...) この rune は 5.14 で追加され、開発中に周囲の関数を _トレース_ することを可能にします。関数が [effect]($effect) または [derived]($derived) の一部として再実行されるたびに、どのリアクティブ state がその effect を引き起こしたかについての情報がコンソールに出力されます。 ```svelte ``` `$inspect.trace` はオプションで第1引数を受け取り、これがラベルとして使用されます。 # $host コンポーネントをカスタム要素 (custom element) としてコンパイルする際、`$host` rune を使用するとホスト要素 (host element) にアクセスでき、（例えば）custom event をディスパッチすることができます ([デモ](/REMOVED)): ```svelte /// file: Stepper.svelte ``` ```svelte /// file: App.svelte count -= 1} onincrement={() => count += 1} >

count: {count}

``` # Basic markup Svelte コンポーネント内のマークアップは、HTML++ と考えることができます。 ## Tags 小文字のタグ (`
` のようなもの) は通常の HTML 要素を表します。一方、大文字で始まるタグやドット表記を使用したタグ (`` や `` など) は _コンポーネント_ を表します。 ```svelte
``` ## Element attributes デフォルトでは、属性は HTML のそれと同じように動作します。 ```svelte
``` HTML と同様に、値は引用符なしでも指定することができます。 ```svelte ``` 属性値には JavaScript の式を含めることができます。 ```svelte page {p} ``` または、それ自体を JavaScript の式にすることも可能です。 ```svelte ``` Boolean の属性は、その値が [truthy](https://developer.mozilla.org/ja/docs/Glossary/Truthy) であれば要素に含まれ、[falsy](https://developer.mozilla.org/ja/docs/Glossary/Falsy) であれば除外されます。 その他の属性は、値が [nullish](https://developer.mozilla.org/ja/docs/Glossary/Nullish) (`null` または `undefined`) でない限り含まれます。 ```svelte
This div has no title attribute
``` > > > ```svelte > > ``` 属性名と値が一致する場合 (`name={name}`)、`{name}` という形で簡略化できます。 ```svelte ``` ## Component props 慣習として、コンポーネントに渡される値は、DOM の機能である _属性_ ではなく、_プロパティ_ または _props_ と呼ばれます。 要素の場合と同様に、`name={name}` は `{name}` の短縮形に置き換えることができます。 ```svelte ``` _スプレッド属性_ を使用すると、複数の属性やプロパティを一度に要素やコンポーネントに渡すことができます。 要素やコンポーネントには、通常のものと混在させて、複数のスプレッド属性を使用できます。 ```svelte ``` ## Events DOM イベントを監視するには、要素に `on` で始まる属性を追加します。例えば、`click` イベントを監視するには、ボタンに `onclick` 属性を追加します: ```svelte ``` イベント属性は大文字小文字を区別します。`onclick` は `click` イベントを監視し、`onClick` は異なる `Click` イベントを監視します。これにより、大文字を含むカスタムイベントを監視することが可能になります。 イベントは単なる属性であるため、属性と同じルールが適用されます: - 短縮形を使用できます: `` - スプレッドも使用できます: `` タイミング的に、イベント属性は常にバインディングのイベントの後に発火します (例えば、`oninput` は `bind:value` の更新後に発火します)。内部では、一部のイベントハンドラーは `addEventListener` を使用して直接アタッチされ、その他は _委任(delegate)_ されます。 `ontouchstart` や `ontouchmove` イベント属性を使用する場合、ハンドラーは [passive](https://developer.mozilla.org/ja/docs/Web/API/EventTarget/addEventListener#パッシブリスナーの使用) として動作し、パフォーマンスが向上します。これにより、イベントハンドラーが `event.preventDefault()` を呼び出すかどうかを待つのではなく、ブラウザが即座にドキュメントをスクロールできるようになり、レスポンシブ性が大幅に改善されます。 これらのイベントのデフォルト動作を防ぐ必要がある非常に稀な場合には、代わりに [`on`](svelte-events#on) を使用するべきです (例えば action 内で)。 ### Event delegation メモリ消費を減らし、パフォーマンスを向上させるため、Svelte はイベントデリゲーション (event delegation) というテクニックを使用しています。これは、以下のリストにある特定のイベントについては、アプリケーションルートの単一のイベントリスナーがイベントのパス上のハンドラーを実行する役割を担うことを意味します。 注意すべきポイントがいくつかあります: - 委任されたリスナー(delegated listener)でイベントを手動でディスパッチする場合、`{ bubbles: true }` オプションを設定してください。さもないとアプリケーションルートに到達しません。 - `addEventListener` を直接使用する場合、`stopPropagation` を呼び出さないようにしてください。そうしないと、イベントがアプリケーションルートに到達せず、ハンドラーが実行されなくなります。同様に、アプリケーションルート内に手動で追加されたハンドラーは、DOM の深い場所に宣言的に追加されたハンドラー (例えば `onclick={...}` など) よりも _前に_ 実行されます (キャプチャおよびバブリングフェーズの両方で)。これらの理由から、`addEventListener` よりも `svelte/events` からインポートされる `on` 関数を使用する方が、順序が保持され、`stopPropagation` が正しく処理されるため推奨されます。 以下のイベントハンドラーが委任(delegate)されます: - `beforeinput` - `click` - `change` - `dblclick` - `contextmenu` - `focusin` - `focusout` - `input` - `keydown` - `keyup` - `mousedown` - `mousemove` - `mouseout` - `mouseover` - `mouseup` - `pointerdown` - `pointermove` - `pointerout` - `pointerover` - `pointerup` - `touchend` - `touchmove` - `touchstart` ## Text expressions JavaScript 式は中括弧 `{}` で囲むことでテキストとして含めることができます。 ```svelte {expression} ``` 中括弧は、その [HTML エンティティ](https://developer.mozilla.org/ja/docs/Glossary/Entity) 文字列を使用することで Svelte テンプレート内に含めることができます。`{` の場合は `{`, `{`, または `{`、`}` の場合は `}`, `}`, または `}` を使用します。 正規表現 (`RegExp`) の [リテラル表記](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp#リテラル記法とコンストラクター) を使用する場合、それを括弧で囲む必要があります。 ```svelte

Hello {name}!

{a} + {b} = {a + b}.

{(/^[A-Za-z ]+$/).test(value) ? x : y}
``` 式は文字列化され、コードインジェクションを防ぐためにエスケープされます。HTML をレンダリングしたい場合は、代わりに `{@html}` タグを使用してください。 ```svelte {@html potentiallyUnsafeHtmlString} ``` ## Comments コンポーネント内で HTML コメントを使用することができます。 ```svelte

Hello world

``` `svelte-ignore` で始まるコメントは、その次にくるマークアップブロックに対する警告を無効にします。通常、これらはアクセシビリティに関する警告であることが多いですが、適切な理由がある場合にのみ無効化するようにしてください。 ```svelte ``` `@component` で始まる特別なコメントを追加することで、他のファイルでコンポーネント名にカーソルを合わせたときに表示されるコメントを作成できます。 ````svelte

Hello, {name}

```` # {#if ...} ```svelte {#if expression}...{/if} ``` ```svelte {#if expression}...{:else if expression}...{/if} ``` ```svelte {#if expression}...{:else}...{/if} ``` 条件付きでレンダリングされるコンテンツは、if ブロックで囲むことができます。 ```svelte {#if answer === 42}

what was the question?

{/if} ``` `{:else if expression}` を使用して追加の条件を指定することができ、`{:else}` 句で終わらせることもできます。 ```svelte {#if porridge.temperature > 100}

too hot!

{:else if 80 > porridge.temperature}

too cold!

{:else}

just right!

{/if} ``` (ブロックは要素を囲む必要はなく、要素内のテキストを囲むこともできます。) # {#each ...} ```svelte {#each expression as name}...{/each} ``` ```svelte {#each expression as name, index}...{/each} ``` 値を繰り返し処理するには、each ブロックを使用します。対象の値は配列、配列のようなオブジェクト (例えば `length` プロパティを持つような)、または `Map` や `Set` のようなイテラブルである必要があります — つまり、`Array.from` を使用できるものであれば問題ありません。 ```svelte

Shopping list

    {#each items as item}
  • {item.name} x {item.qty}
    • {/each}
``` each ブロックは _インデックス_ も指定可能で、これは `array.map(...)` コールバックの第二引数に相当します: ```svelte {#each items as item, i}
  • {i + 1}: {item.name} x {item.qty}
    • {/each} ``` ## Keyed each blocks ```svelte {#each expression as name (key)}...{/each} ``` ```svelte {#each expression as name, index (key)}...{/each} ``` _key_ の式（各リストアイテムを一意に識別できる必要があります）が与えられた場合、Svelte は、データが変化したときに（末尾にアイテムを追加したり削除するのではなく）キーを使用してリストの差分を取ります。key はどんなオブジェクトでもよいですが、そのオブジェクト自体が変更されたときに同一性を維持できるため、文字列か数値を推奨します。 ```svelte {#each items as item (item.id)}
  • {item.name} x {item.qty}
    • {/each} {#each items as item, i (item.id)}
  • {i + 1}: {item.name} x {item.qty}
    • {/each} ``` each ブロック内では分割代入や残余構文のパターンを自由に使用できます。 ```svelte {#each items as { id, name, qty }, i (id)}
  • {i + 1}: {name} x {qty}
    • {/each} {#each objects as { id, ...rest }}
  • {id}
    • {/each} {#each items as [id, ...rest]}
  • {id}
    • {/each} ``` ## Each blocks without an item ```svelte {#each expression}...{/each} ``` ```svelte {#each expression, index}...{/each} ``` もし `n` 回レンダリングしたいだけの場合は、`as` 部分を省略することができます ([デモ](/REMOVED)): ```svelte
    {#each { length: 8 }, rank} {#each { length: 8 }, file}
    {/each} {/each}
    ``` ## Else blocks ```svelte {#each expression as name}...{:else}...{/each} ``` each ブロックは `{:else}` 節を持つことができ、リストが空の場合にそれがレンダリングされます。 ```svelte {#each todos as todo}

    {todo.text}

    {:else}

    No tasks today!

    {/each} ``` # {#key ...} ```svelte {#key expression}...{/key} ``` key ブロックは、式の値が変化したときにその内容を破棄して再生成します。コンポーネントを囲んで使用した場合、コンポーネントの再インスタンス化され、再初期化されます: ```svelte {#key value} {/key} ``` 値が変更されるたびにトランジションを再生したい場合にも便利です: ```svelte {#key value}
    {value}
    {/key} ``` # {#await ...} ```svelte {#await expression}...{:then name}...{:catch name}...{/await} ``` ```svelte {#await expression}...{:then name}...{/await} ``` ```svelte {#await expression then name}...{/await} ``` ```svelte {#await expression catch name}...{/await} ``` await ブロックを使用すると、[`Promise`](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise) の 3 つの可能な状態 — 待機 (pending)、成功 (fulfilled)、または失敗 (rejected) — に応じて処理を分岐させることができます。 ```svelte {#await promise}

    waiting for the promise to resolve...

    {:then value}

    The value is {value}

    {:catch error}

    Something went wrong: {error.message}

    {/await} ``` > > 提供された式が `Promise` でない場合は、サーバーサイドレンダリング中も含め、`:then` の分岐のみがレンダリングされます。 promise が失敗した場合に何もレンダリングする必要がない場合 (またはエラーが発生しない場合)、`catch` ブロックを省略できます。 ```svelte {#await promise}

    waiting for the promise to resolve...

    {:then value}

    The value is {value}

    {/await} ``` 待機中の状態を気にしない場合、最初のブロックを省略することもできます。 ```svelte {#await promise then value}

    The value is {value}

    {/await} ``` 同様に、エラー状態のみを表示したい場合は、`then` ブロックを省略できます。 ```svelte {#await promise catch error}

    The error is {error}

    {/await} ``` > > ```svelte > {#await import('./Component.svelte') then { default: Component }} > > {/await} > ``` # {#snippet ...} ```svelte {#snippet name()}...{/snippet} ``` ```svelte {#snippet name(param1, param2, paramN)}...{/snippet} ``` Snippet と [render タグ](@render) を使用すると、コンポーネント内で再利用可能なマークアップのチャンクを作成することができます。このような重複が多い[コード](/REMOVED) を書く代わりに... ```svelte {#each images as image} {#if image.href}
    {image.caption}
    {image.caption}
     {:else}
    {image.caption}
    {image.caption}
    {/if} {/each} ``` ...[このように](/REMOVED) 書くことができます: ```svelte {#snippet figure(image)}
    {image.caption}
    {image.caption}
    {/snippet} {#each images as image} {#if image.href} {@render figure(image)} {:else} {@render figure(image)} {/if} {/each} ``` 関数宣言と同様に、snippet は任意の数のパラメーターを持つことができ、それぞれにデフォルト値を設定したり、分割代入を使用することができます。ただし、残余引数 (rest parameters) は使用できません。 ## Snippet scope snippet はコンポーネント内の任意の場所で宣言できます。その snippet の外側、例えば ` {#snippet hello(name)}

    hello {name}! {message}!

    {/snippet} {@render hello('alice')} {@render hello('bob')} ``` ...また、同じレキシカルスコープ内のすべての要素 (つまり兄弟要素やその子要素) から '見える (visible)' 状態になります: ```svelte
    {#snippet x()} {#snippet y()}...{/snippet} {@render y()} {/snippet} {@render y()}
    {@render x()} ``` snippet は、自身や他の snippet を参照することができます ([デモ](/REMOVED)): ```svelte {#snippet blastoff()} 🚀 {/snippet} {#snippet countdown(n)} {#if n > 0} {n}... {@render countdown(n - 1)} {:else} {@render blastoff()} {/if} {/snippet} {@render countdown(10)} ``` ## snippet をコンポーネントに渡す テンプレート内では、snippet は他の値と同じように扱われます。そのため、snippet は props としてコンポーネントに渡すことができます ([デモ](/REMOVED)): ```svelte {#snippet header()} fruit qty price total {/snippet} {#snippet row(d)} {d.name} {d.qty} {d.price} {d.qty * d.price} {/snippet} ``` データの代わりにコンテンツをコンポーネントに渡すようなものと考えてください。このコンセプトは web component の slot に似ています。 作成を簡単にするため、コンポーネント内に直接宣言された snippet は、自動的にそのコンポーネントの props になります ([デモ](/REMOVED)): ```svelte
    {#snippet header()} {/snippet} {#snippet row(d)} {/snippet}
    fruit qty price total{d.name} {d.qty} {d.price} {d.qty * d.price}
    ``` コンポーネントタグ内で、snippet 宣言でないすべてのコンテンツは、自動的に `children` snippet の一部になります ([デモ](/REMOVED)): ```svelte ``` ```svelte ``` snippet の props をオプションとして宣言することができます。snippet が設定されていない場合は、オプショナルチェーン (optional chaining) を使用して何もレンダリングしないようにするか... ```svelte {@render children?.()} ``` ...または、`#if` ブロックを使用してフォールバックコンテンツをレンダリングすることができます: ```svelte {#if children} {@render children()} {:else} fallback content {/if} ``` ## snippet に型を付ける snippet は、`'svelte'` からインポートされる `Snippet` インターフェースを実装します: ```svelte ``` この変更により、`data` プロパティと `row` snippet を提供せずにコンポーネントを使用しようとすると、赤い波線が表示されるようになります。snippet には複数のパラメーターを持たせることができるため、`Snippet` に提供される型引数がタプルになっていることに注意してください。 generic を宣言することで、`data` と `row` が同じ型を参照するように、さらに厳密にすることができます: ```svelte ``` ## snippet をエクスポートする `.svelte` ファイルのトップレベルで宣言された snippet は、non-module な ` {#snippet add(a, b)} {a} + {b} = {a + b} {/snippet} ``` > これには Svelte 5.5.0 以上が必要です ## プログラマティックな snippet snippet は、[`createRawSnippet`](svelte#createRawSnippet) API を使用してプログラムで作成することができます。これは高度なユースケースを意図しています。 ## Snippet と slot Svelte 4 では、[slot](legacy-slots) を使用してコンテンツをコンポーネントに渡すことができます。snippet はより強力で柔軟性があるため、Svelte 5 では slot は非推奨となりました。 # {@render ...} [snippet](snippet) をレンダリングするには、`{@render ...}` タグを使用します。 ```svelte {#snippet sum(a, b)}

    {a} + {b} = {a + b}

    {/snippet} {@render sum(1, 2)} {@render sum(3, 4)} {@render sum(5, 6)} ``` 式は `sum` のような識別子、または任意の JavaScript 式にすることができます: ```svelte {@render (cool ? coolSnippet : lameSnippet)()} ``` ## Optional snippets snippet が undefined である可能性がある場合 — 例えば、それが外部から渡されたプロパティである場合、オプショナルチェーン(optional chaining)を使用して、それが定義されている場合のみレンダリングすることができます: ```svelte {@render children?.()} ``` または、[`{#if ...}`](if) ブロックを `:else` 句と組み合わせて使用し、フォールバックコンテンツをレンダリングします: ```svelte {#if children} {@render children()} {:else}

    fallback content

    {/if} ``` # {@html ...} 生の HTML をコンポーネントに挿入するには、`{@html ...}` タグを使用します: ```svelte
    {@html content}
    ``` 式は単体で有効な HTML である必要があります — 例えば、`
    ` は有効な HTML ではないため機能しません: ```svelte {@html '
    '}content{@html '
    '} ``` また、Svelte のコードをコンパイルすることもできません。 ## Styling この方法でレンダリングされたコンテンツは Svelte からは '見えない(invisible)' ため、[スコープ付きスタイル](scoped-styles) を適用することはできません — 言い換えると、次の例は機能せず、`a` と `img` のスタイルは未使用と見なされます: ```svelte
    {@html content}
    ``` 代わりに、`:global` 修飾子を使用して `
    ` 内のすべてをターゲットにします: ```svelte ``` # {@const ...} `{@const ...}` タグはローカル定数を定義します。 ```svelte {#each boxes as box} {@const area = box.width * box.height} {box.width} * {box.height} = {area} {/each} ``` `{@const}` は、`{#if ...}`、`{#each ...}`、`{#snippet ...}` などのブロックや、``、または ` let user = { firstname: 'Ada', lastname: 'Lovelace' }; {@debug user}

    Hello {user.firstname}!

    ``` `{@debug ...}` は、変数名をカンマ区切りで指定することができます (任意の式は指定できません)。 ```svelte {@debug user} {@debug user1, user2, user3} {@debug user.firstname} {@debug myArray[0]} {@debug !isReady} {@debug typeof user === 'object'} ``` 引数なしの `{@debug}` タグは、特定の変数ではなく、_何らかの_ state が変化した際にトリガーされる `debugger` ステートメントを挿入します。 # bind: データは通常、親から子へと流れますが、`bind:` ディレクティブを使用すると、データを子から親へ流すことができます。 一般的な構文は `bind:property={expression}` であり、`expression` は _lvalue_ (つまり、変数やオブジェクトのプロパティ) です。式がプロパティと同じ名前の識別子である場合、式を省略することができます — 言い換えると、以下は等価です: ```svelte ``` Svelte は、バインドされた値を更新するイベントリスナーを作成します。要素が既に同じイベントのリスナーを持っている場合、そのリスナーはバインドされた値が更新される前に実行されます。 ほとんどのバインディングは _双方向_ であり、値の変更が要素に影響し、その逆も同様です。一部のバインディングは _読み取り専用_ であり、値を変更しても要素に影響を与えません。 ## Function bindings `bind:property={get, set}` を使用して、`get` と `set` を関数として指定し、バリデーションや変換を行うことができます: ```svelte value, (v) => value = v.toLowerCase()} /> ``` [dimension bindings](#Dimensions) のような読み取り専用バインディングの場合、`get` の値は `null` にする必要があります: ```svelte
    ...
    ``` > Function bindings は Svelte 5.9.0 以降で使用可能です。 ## `` `` 要素に対する `bind:value` ディレクティブは、input の `value` プロパティをバインドします: ```svelte

    {message}

    ``` 数値を扱う input (`type="number"` または `type="range"`) の場合、値は数値に変換されます ([デモ](/REMOVED)): ```svelte

    {a} + {b} = {a + b}

    ``` 入力が空または無効 (`type="number"` の場合) の場合、値は `undefined` になります。 バージョン 5.6.0 以降、`` に `defaultValue` が設定されていてフォームの一部である場合、フォームがリセットされると空文字列ではなくその値に戻ります。初回のレンダリングでは、バインディングの値が `null` または `undefined` でない限り優先されることに注意してください。 ```svelte
    ``` > リセットボタンは慎重に使用し、ユーザーがフォームを送信しようとしているときに誤ってクリックしないようにしてください。 ## `` checkbox および radio の input には、`bind:checked` を使用してバインドできます: ```svelte ``` バージョン 5.6.0 以降、`` に `defaultChecked` 属性が設定されておりフォームの一部である場合、フォームがリセットされると `false` ではなくその値に戻ります。初回のレンダリングでは、バインディングの値が `null` または `undefined` でない限り優先されます。 ```svelte
    ``` ## `` 相互に動作する input は、`bind:group` を使用できます。 ```svelte ``` ## `` `type="file"` を持つ `` 要素では、`bind:files` を使用して [選択されたファイルの `FileList`](https://developer.mozilla.org/ja/docs/Web/API/FileList) を取得できます。プログラムでファイルを更新する場合、常に `FileList` オブジェクトを使用する必要があります。現在、`FileList` オブジェクトは直接作成できないため、新しい [`DataTransfer`](https://developer.mozilla.org/ja/docs/Web/API/DataTransfer) オブジェクトを作成し、そこから `files` を取得する必要があります。 ```svelte ``` `FileList` オブジェクトも変更できないため、例えばリストから単一のファイルを削除したい場合は、新しい `DataTransfer` オブジェクトを作成し、保持したいファイルを追加する必要があります。 ## `` の値のバインディングは、選択された ` ``` ` ``` ## `