Turbo リファレンス

:::note
この記事は[Google翻訳](https://translate.google.co.jp/)の結果を編集したものです。
:::

# ドライブ

https://turbo.hotwired.dev/reference/drive

## Turbo.visit

```javascript
Turbo.visit(location)
Turbo.visit(location, { action: action })
```

指定された場所（URLまたはパスを含む文字列）へのアプリケーション訪問を指定されたアクション(`"advance"`または`"replace"`のいずれかの文字列)で実行します。

locationがクロスオリジンURLであるか指定されたルート（ルートの場所の設定を参照）の外にある場合、Turboは`window.location`を設定してページ全体の読み込みを実行します。

アクションが指定されていない場合、Turbo Driveは`"advance"`の値を想定します。

訪問を実行する前にTurbo Driveはドキュメントに対して`turbo:before-visit`イベントを発生させます。 アプリケーションはこのイベントをリッスンし、`event.preventDefault()`を使用して訪問をキャンセルできます（[開始前の訪問のキャンセル](https://turbo.hotwired.dev/handbook/drive#canceling-visits-before-they-start)を参照）。

## Turbo.cache.clear

```javascript
Turbo.cache.clear()
```

Turbo Driveのページキャッシュからすべてのエントリーを削除します。 キャッシュされたページに影響を与える可能性のあるサーバーの状態が変化したときにこれを呼び出します。

**注意：** この関数は以前は`Turbo.clearCache()`として公開されていました。 トップレベル関数は新しい`Turbo.cache.clear()`関数を支持して廃止されました。

## Turbo.setProgressBarDelay

```javascript
Turbo.setProgressBarDelay(delayInMilliseconds)
```

ナビゲーション中に進行状況バーが表示されるまでの遅延をミリ秒単位で設定します。 プログレスバーはデフォルトで500ミリ秒後に表示されます。

このメソッドはiOSまたはAndroidアダプターで使用する場合は効果がないことに注意してください。

## Turbo.session.drive

```javascript
Turbo.session.drive = false
```

Turbo Driveではデフォルトでオフになっています。 `data-turbo="true"`を使用してリンクごとおよびフォームごとにTurbo Driveにオプトインする必要があります。

# フレーム

https://turbo.hotwired.dev/reference/frames

### フレームの基本

たどられたリンクまたはフォーム送信が一致するフレームタグを含む応答を返すことを期待することにより、すべてのナビゲーションをフレーム内に限定します。

```html
<turbo-frame id="messages">
  <a href="/messages/expanded">
    Show all expanded messages in this frame.
  </a>

  <form action="/messages">
    Show response from this form within this frame.
  </form>
</turbo-frame>
```

### Eager-loaded フレーム

基本のフレームと同じように機能しますが、コンテンツは最初にリモートの`src`からロードされます。

```html
<turbo-frame id="messages" src="/messages">
  Content will be replaced when /messages has been loaded.
</turbo-frame>
```

### Lazy-loaded フレーム

Eager-loaded フレームと同様ですが、フレームが表示されるまでコンテンツは`src`からロードされません。

```html
<turbo-frame id="messages" src="/messages" loading="lazy">
  Content will be replaced when the frame becomes visible and /messages has been loaded.
</turbo-frame>
```

### デフォルトでページ全体を対象とするフレーム

```html
<turbo-frame id="messages" target="_top">
  <a href="/messages/1">
    Following link will replace the whole page, not this frame.
  </a>

  <a href="/messages/1" data-turbo-frame="_self">
    Following link will replace just this frame.
  </a>

  <form action="/messages">
    Submitting form will replace the whole page, not this frame.
  </form>
</turbo-frame>
```

### ナビゲーションターゲットが上書きされたフレーム

```html
<turbo-frame id="messages">
  <a href="/messages/1">
    Following link will replace this frame.
  </a>

  <a href="/messages/1" data-turbo-frame="_top">
    Following link will replace the whole page, not this frame.
  </a>

  <form action="/messages" data-turbo-frame="navigation">
    Submitting form will replace the navigation frame.
  </form>
</turbo-frame>
```

### 訪問へのナビゲーションを促すフレーム

```html
<turbo-frame id="messages" data-turbo-action="advance">
  <a href="/messages?page=2">Advance history to next page</a>
  <a href="/messages?page=2" data-turbo-action="replace">Replace history with next page</a>
</turbo-frame>
```

## 属性、プロパティ、および関数

`<turbo-frame>`要素は独自のHTML属性とJavaScriptプロパティのセットを持つ[カスタム要素](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)です。

### HTML属性

- `src`は要素のナビゲーションを制御するURLまたはパスの値を受け入れます
- `loading`には"eager"と"lazy"の 2 つの有効な列挙値があります。`loading="eager"`の場合、`src`属性を変更するとすぐに要素がナビゲートされます。`loading="lazy"`の場合、`src`属性を変更すると要素がビューポートに表示されるまでナビゲーションが延期されます。
- `busy`は`<turbo-frame>`によって開始されたリクエストが開始されたときに存在するように切り替えられ、リクエストが終了したときにfalseに切り替えられるブール属性です
- `disabled`は存在する場合にナビゲーションを禁止するブール属性です
- `target`は別の`<turbo-frame>`要素をIDで参照し、子孫の`<a>`がクリックされたときにナビゲートされます。`target="_top"`の場合、ウィンドウをナビゲートします。
- `complete`は`<turbo-frame>`要素がナビゲートを終了したかどうかを示すブール属性です。
- `autoscroll`は、読み込み後に`<turbo-frame>`要素 (およびその子孫の`<turbo-frame>`要素) をスクロールして表示するかどうかを制御するブール属性です。`data-autoscroll-block`属性を有効な Element.scrollIntoView({ block: “…” }) 値 (`"end"`、`"start"`、`"center"`、または`"nearest"`のいずれか)に設定して、スクロールの垂直方向の配置を制御します。`data-autoscroll-block`がない場合、デフォルト値は`"end"`です。`data-autoscroll-behavior`属性を有効な[Element.scrollIntoView({ behavior: “…” })](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#parameters)値 (`"auto"`または`"smooth"`のいずれか) に設定して、スクロールの動作を制御します。`data-autoscroll-behavior`がない場合、デフォルト値は`"auto"`です。

### プロパティ

すべての`<turbo-frame>`要素は`FrameElement`クラスのインスタンスを介してJavaScript環境で制御できます。

- `FrameElement.src`はロードするパス名またはURLを制御します
- `FrameElement.disabled`は要素をロードするかどうかを制御するブール値のプロパティです。
- `FrameElement.loading`はフレームがそのコンテンツをロードするスタイル（`"eager"`または`"lazy"'）を制御します。
- `FrameElement.loaded`は`FrameElementの現在のナビゲーションが完了すると解決される[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)インスタンスを参照します。
- `FrameElement.complete`は`FrameElement`の移動が終了したときに`true`に設定され、それ以外の場合は`false`に設定される読み取り専用のブールプロパティです。
- `FrameElement.autoscroll`は読み込まれた要素をビューにスクロールするかどうかを制御します
- `FrameElement.isActive`はフレームが読み込まれて操作できる状態かどうかを示す読み取り専用のブール値プロパティです。
- `FrameElement.isPreview`は要素を含むドキュメントがプレビューの場合に`true`を返す読み取り専用のブール型プロパティです。

### 関数

`FrameElement.reload()`はフレーム要素をその`src`からリロードする関数です。

# ストリーム

https://turbo.hotwired.dev/reference/streams

## 7つのアクション

### Append

templateタグ内のコンテンツをターゲットdom idで指定されたコンテナーに追加します。

```html
<turbo-stream action="append" target="dom_id">
  <template>
    Content to append to container designated with the dom_id.
  </template>
</turbo-stream>
```

テンプレートの最初の要素のidがdom_idの対象となるコンテナー内の直接の子によって既に使用されている場合、追加される代わりに置き換えられます。

### Prepend

templateタグ内のコンテンツをターゲットdom idで指定されたコンテナーの先頭に追加します。

```html
<turbo-stream action="prepend" target="dom_id">
  <template>
    Content to prepend to container designated with the dom_id.
  </template>
</turbo-stream>
```

テンプレートの最初の要素にdom_idの対象となるコンテナ内の直接の子によって既に使用されているidがある場合、先頭に追加される代わりに置き換えられます。

### Replace

ターゲットdom idで指定された要素を置き換えます。

```html
<turbo-stream action="replace" target="dom_id">
  <template>
    Content to replace the element designated with the dom_id.
  </template>
</turbo-stream>
```

### Update

templateタグ内のコンテンツをターゲットdom idで指定されたコンテナーに更新します。

```html
<turbo-stream action="update" target="dom_id">
  <template>
    Content to update to container designated with the dom_id.
  </template>
</turbo-stream>
```

### Remove

ターゲットdom idで指定された要素を削除します。

```html
<turbo-stream action="remove" target="dom_id">
</turbo-stream>
```

### Before

ターゲットdom idで指定された要素の前に、テンプレートタグ内のコンテンツを挿入します。

```html
<turbo-stream action="before" target="dom_id">
  <template>
    Content to place before the element designated with the dom_id.
  </template>
</turbo-stream>
```

### After

ターゲットdom idで指定された要素の後にテンプレートタグ内にコンテンツを挿入します。

```html
<turbo-stream action="after" target="dom_id">
  <template>
    Content to place after the element designated with the dom_id.
  </template>
</turbo-stream>
```

## 複数の要素をターゲットにする

1回のアクションで複数の要素をターゲットにするには`target`属性の代わりに`targets`属性をCSSクエリーセレクターと共に使用します。

```html
<turbo-stream action="remove" targets=".elementsWithClass">
</turbo-stream>

<turbo-stream action="after" targets=".elementsWithClass">
  <template>
    Content to place after the elements designated with the css query.
  </template>
</turbo-stream>
```

## ストリーム要素の処理

Turboはストリームアクションを受信して処理するために任意の形式のストリームに接続できます。 ストリームソースはそのイベントの`data`属性にストリームアクションHTMLを含む[MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent)メッセージをディスパッチする必要があります。 その後、`Turbo.session.connectStreamSource(source)`によって接続され、`Turbo.session.disconnectStreamSource(source)`によって切断されます。`MessageEvents`を生成するものとは異なるソースからのストリーム アクションを処理する必要がある場合は、`Turbo.renderStreamMessage(streamActionHTML)`を使用して実行できます。

これらすべてをまとめる良い方法はturbo-railsが[TurboCableStreamSourceElement](https://github.com/hotwired/turbo-rails/blob/main/app/javascript/turbo/cable_stream_source_element.js)で行うようにカスタム要素を使用することです。

# イベント

https://turbo.hotwired.dev/reference/events

Turboはナビゲーションのライフサイクルを追跡し、ページの読み込みに応答できるようにするイベントを発行します。 特に明記されていない限り、Turboは`document.documentElement`オブジェクト（つまり`<html>`要素）でイベントを発生させます。

（jQueryを使用する場合、イベントのデータは`$event.originalEvent.detail`としてアクセスする必要があることに注意してください。）

- `Turbo:click`はTurboが有効なリンクをクリックすると発生します。クリックされた要素がイベントターゲットです。`event.detail.url`で要求された場所にアクセスします。このイベントをキャンセルしてクリックが通常のナビゲーションとしてブラウザーにフォールスルーされるようにします。
- `Turbo:before-visit`は履歴でナビゲートする場合を除き場所を訪れる前に起動します。`event.detail.url`で要求された場所にアクセスします。ナビゲーションを防止するにはこのイベントをキャンセルしてください。
- `Turbo:visit`は訪問の開始直後に発生します。`event.detail.url`で要求された場所にアクセスし`event.detail.action`でアクションにアクセスします。
- `Turbo:submit-start`はフォームの送信中に発火します。`event.detail.formSubmission`で`FormSubmission`オブジェクトにアクセスします。`event.detail.formSubmission.stop()`を使用して、フォームの送信を中止します (検証の失敗後など)。 (jQuery を使用している場合は`event.originalEvent.detail.formSubmission.stop()`を使用します)
- `Turbo:before-fetch-request`はTurboがページを取得するためのネットワークリクエストを発行する前に発生します。`event.detail.url`で要求された場所にアクセスし`event.detail.fetchOptions`でフェッチオプションオブジェクトにアクセスします。このイベントはそれをトリガーするそれぞれの要素（turbo-frameまたはフォーム要素）で発生し、`event.target`プロパティでアクセスできます。リクエストは`event.detail.resume`でキャンセルして続行できます（リクエストの一時停止を参照）。
- `Turbo:before-fetch-response`はネットワークリクエストが完了した後に発生します。`event.detail`でフェッチオプションオブジェクトにアクセスします。このイベントはそれをトリガーするそれぞれの要素（turbo-frameまたはフォーム要素) で発生し、`event.target`プロパティでアクセスできます。
- `Turbo:submit-end`はフォーム送信によって開始されたネットワークリクエストが完了すると発生します。`event.detail.formSubmission`と`event.detail`に含まれる`FormSubmissionResult`プロパティを使用して`FormSubmission`オブジェクトにアクセスします。
- `Turbo:before-cache`はTurboが現在のページをキャッシュに保存する前に起動します。
- `Turbo:before-render`はページをレンダリングする前に起動します。`event.detail.newBody`で新しい`<body>`要素にアクセスします。 レンダリングは`event.detail.resume`でキャンセルして続行できます (レンダリングの一時停止を参照)。
- `Turbo:before-stream-render`はTurbo Streamページの更新をレンダリングする前に起動します。
- `Turbo:render`はTurboがページをレンダリングした後に起動します。このイベントはキャッシュされた場所へのアプリケーションのアクセス中に2回発生します。1回目はキャッシュバージョンのレンダリング後、2回目は新しいバージョンのレンダリング後です。
- `Turbo:load`は最初のページの読み込み後に1回起動し、Turboにアクセスするたびに再度起動します。`event.detail.timing`オブジェクトを使用して、訪問のタイミング指標にアクセスします。
- `Turbo:frame-render`は` <turbo-frame>`要素がそのビューをレンダリングした直後に起動します。特定の`<turbo-frame>`要素がイベント ターゲットです。`event.detail.fetchResponse`プロパティを使用して`FetchResponse`オブジェクトにアクセスします。
- `Turbo:frame-load`は`<turbo-frame>`要素がナビゲートされ読み込みが完了すると発生します（`turbo:frame-render`の後に発生します）。 特定の`<turbo-frame>`要素がイベントターゲットです。
- `Turbo:fetch-request-error`はネットワークエラーが原因でフォームまたはフレームのフェッチ リクエストが失敗したときに発生します。このイベントは、それをトリガーするそれぞれの要素（turbo-frameまたはフォーム要素）で発生し`event.target`プロパティでアクセスできます。このイベントはキャンセルできます。

# 属性

https://turbo.hotwired.dev/reference/attributes

## データ属性

次のデータ属性を要素に適用してTurboの動作をカスタマイズできます。

- `data-turbo="false"`は子孫を含むリンクとフォームでTurbo Driveを無効にします。 祖先がオプトアウトしたときに再度有効にするには`data-turbo="true"`を使用します。注意:Turbo Driveが無効になっている場合、ブラウザーはリンクのクリックを通常どおりに処理しますが、ネイティブアダプターはアプリを終了する場合があります。
- `data-turbo-track="reload"`は要素のHTMLを追跡し変更時にページ全体のリロードを実行します。通常、`スクリプト`とCSS`リンク`要素を最新の状態に保つために使用されます。
- `data-turbo-frame`はナビゲートするTurbo Frameを識別します。詳細についてはフレームのドキュメントを参照してください。
- `data-turbo-action`はVisitアクションをカスタマイズします。 有効な値は`replace`または`advance`です。Turbo Framesと併用してフレームナビゲーションをページ訪問に促進することもできます。
- `data-turbo-permanent`はページの読み込み間で要素を永続化します。 要素には一意の`id`属性が必要です。
- `data-turbo-cache="false"`はドキュメントがキャッシュされる前に要素を削除し、復元の訪問時に再表示されないようにします。
- `data-turbo-eval="false"`はインラインスクリプト要素が訪問時に再評価されるのを防ぎます。
- `data-turbo-method`はリンクリクエストタイプをデフォルトの`GET`から変更します。 理想的には`GET`以外のリクエストはフォームでトリガーする必要がありますが、フォームが使用できない場合は`data-turbo-method`が役立つ場合があります。
- `data-turbo-stream`はリンクまたはフォームがTurbo Streams応答を受け入れることができることを指定します。Turboは`GET`以外のメソッドを使用したフォーム送信のストリーム応答を自動的に要求します。`data-turbo-stream`を使用するとTurbo Streamsを`GET`リクエストでも使用できます。
- `data-turbo-confirm`は指定された値で確認ダイアログを表示します。`data-turbo-method`を含む`form`要素またはリンクで使用できます。

## 自動的に追加される属性

次の属性はTurboによって自動的に追加され、特定の時点での訪問状態を判断するのに役立ちます。

- `disabled`はフォームリクエストの進行中にフォーム送信者に追加され、送信の繰り返しを防ぎます。
- 訪問中にプレビューを表示するときに`data-turbo-preview`が`html`要素に追加されます。
- ナビゲーションが進行中の場合、`aria-busy`が`html`および`turbo-frame`要素に追加されます。

## メタタグ

`head`に追加された次の`meta`要素を使用してキャッシングと訪問の動作をカスタマイズできます。

- `<meta name="turbo-cache-control">`でキャッシュをオプトアウトします。
- `<meta name="turbo-visit-control" content="reload">`はページ全体のリロードを実行します。
- `<meta name="turbo-root">`を使用してTurbo Driveを特定のルートの場所にスコープします。