Turbo リファレンス

この記事はGoogle翻訳の結果を編集したものです。

ドライブ

Turbo.visit

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()を使用して訪問をキャンセルできます（開始前の訪問のキャンセルを参照）。

Turbo.cache.clear

Turbo.cache.clear()

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

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

Turbo.setProgressBarDelay

Turbo.setProgressBarDelay(delayInMilliseconds)

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

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

Turbo.session.drive

Turbo.session.drive = false

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

フレーム

フレームの基本

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

<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からロードされます。

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

Lazy-loaded フレーム

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

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

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

<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>

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

<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>

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

<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プロパティのセットを持つカスタム要素です。

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: “…” })値 ("auto"または"smooth"のいずれか) に設定して、スクロールの動作を制御します。data-autoscroll-behaviorがない場合、デフォルト値は"auto"です。

プロパティ

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

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

関数

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

ストリーム

7つのアクション

Append

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

<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で指定されたコンテナーの先頭に追加します。

<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で指定された要素を置き換えます。

<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で指定されたコンテナーに更新します。

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

Remove

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

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

Before

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

<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で指定された要素の後にテンプレートタグ内にコンテンツを挿入します。

<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クエリーセレクターと共に使用します。

<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メッセージをディスパッチする必要があります。 その後、Turbo.session.connectStreamSource(source)によって接続され、Turbo.session.disconnectStreamSource(source)によって切断されます。MessageEventsを生成するものとは異なるソースからのストリーム アクションを処理する必要がある場合は、Turbo.renderStreamMessage(streamActionHTML)を使用して実行できます。

これらすべてをまとめる良い方法はturbo-railsがTurboCableStreamSourceElementで行うようにカスタム要素を使用することです。

イベント

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プロパティでアクセスできます。このイベントはキャンセルできます。

属性

データ属性

次のデータ属性を要素に適用して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を特定のルートの場所にスコープします。