属性とメタタグ
# データ属性
次のデータ属性を要素に対して利用することで、Turbo の挙動をカスタマイズできます。
data-turbo="false"
は、リンクやフォーム、その子孫要素に対しても Turbo ドライブを無効にします。Turbo ドライブを有効にしたい場合は、data-turbo="true"
を使います。Turbo ドライブを無効にする場合、振る舞いの違いに注意してください。ブラウザではリンクをクリックした時の振る舞いが通常通りになるだけですが、native adaptersではアプリが終了するかもしれません。また、Turbo が無視するパスとして扱っている URL については、data-turbo="true"
を付けても Turbo ドライブを有効にはできません。data-turbo-track="reload"
はHTML要素を追跡し、それが変わったときに全ページをリロードします。通常、script
やCSS
のリンクを最新の状態に保つために使われます。data-turbo-track="dynamic"
は、要素のHTMLを監視し、HTMLレスポンスに含まれていなければその要素を削除します。主に、ナビゲーション中にstyle
やlink
要素を削除するために使われます。data-turbo-frame
は、ナビゲートするための Turbo フレームを識別します。詳細は、フレームのドキュメントを参照してください。data-turbo-preload
は、Turbo ドライブに次のページのコンテンツをプリフェッチさせます。data-turbo-prefetch="false"
は、要素にマウスホバーしたときのリンクのプリフェッチを無効にします。data-turbo-action
は、Visitアクションをカスタマイズします。有効な値は、replace
あるいはadvance
のいずれかです。 Turbo フレームと一緒に使うことで、フレームのナビゲーションをページアクセスに昇格できます。data-turbo-permanent
は、ページ・ロード間で要素を永続化します。その要素のid
属性はユニークでないといけません。モーフィングによるページ更新から要素を除外したい場合も、data-turbo-permanent
を使います。data-turbo-temporary
は、ドキュメントがキャッシュされる前に要素を削除します。これにより、data-turbo-temporary
がある要素をキャッシュから復元しません。data-turbo-eval="false"
を指定することで、ページを再表示したときにインラインのscript
要素を再評価しません。data-turbo-method
で、リンクのリクエストタイプをデフォルトのGET
から変更できます。理想的には、GET
ではないリクエストはフォームで発行されるべきですが、data-turbo-method
はフォームが使えない場合に便利かもしれません。data-turbo-stream
により、リンクまたはフォームが Turbo ストリームのレスポンスを受け付けられます。Turbo は、GET
でないメソッドによるフォーム送信に対して、自動的にストリーム・レスポンスを要求します。data-turbo-stream
により、GET
リクエストに対しても Turbo ストリームを使えます。data-turbo-confirm
は、指定された値で確認ダイアログを表示します。data-turbo-method
を持つform
要素またはリンクで使えます。data-turbo-submits-with
により、フォーム送信時に表示するテキストを指定できます。この属性は、input
要素またはbutton
要素で使えます。フォーム送信中に、要素のテキストはdata-turbo-submits-with
の値を表示します。送信後は、元のテキストに戻ります。操作の進行中に「保存中…」のようなメッセージを表示すれば、ユーザーにフィードバックを与えられるので便利です。download
属性が付いたリンクは、ファイルをダウンロードするためのものでページ遷移ではないため、Turbo の処理から除外されます。
原文
The following data attributes can be applied to elements to customize Turbo’s behaviour.
data-turbo="false"
disables Turbo Drive on links and forms including descendants. To reenable when an ancestor has opted out, use data-turbo="true"
. Be careful: when Turbo Drive is disabled, browsers treat link clicks as normal, but native adapters may exit the app. Note that if Turbo ignores a path, then setting data-turbo="true"
will not force/override it to enable.
data-turbo-track="reload"
tracks the element’s HTML and performs a full page reload when it changes. Typically used to keepscript
and CSSlink
elements up-to-date.data-turbo-track="dynamic"
tracks the element’s HTML and removes the element when it is absent from an HTML response. Typically used to removestyle
andlink
elements during navigation.data-turbo-frame
identifies the Turbo Frame to navigate. Refer to the Frames documentation for further details.data-turbo-preload
signals to Drive to pre-fetch the next page’s contentdata-turbo-prefetch="false"
disables prefetching links when the element is hovered.data-turbo-action
customizes the Visit action. Valid values arereplace
oradvance
. Can also be used with Turbo Frames to promote frame navigations to page visits.data-turbo-permanent
persists the element between page loads. The element must have a uniqueid
attribute. It also serves to exclude elements from being morphed when using page refreshes with morphingdata-turbo-temporary
removes the element before the document is cached, preventing it from reappearing when restored.data-turbo-eval="false"
prevents inlinescript
elements from being re-evaluated on Visits.data-turbo-method
changes the link request type from the defaultGET
. Ideally, non-GET
requests should be triggered with forms, butdata-turbo-method
might be useful where a form is not possible.data-turbo-stream
specifies that a link or form can accept a Turbo Streams response. Turbo automatically requests stream responses for form submissions with non-GET
methods;data-turbo-stream
allows Turbo Streams to be used withGET
requests as well.data-turbo-confirm
presents a confirm dialog with the given value. Can be used onform
elements or links withdata-turbo-method
.data-turbo-submits-with
specifies text to display when submitting a form. Can be used oninput
orbutton
elements. While the form is submitting the text of the element will show the value ofdata-turbo-submits-with
. After the submission, the original text will be restored. Useful for giving user feedback by showing a message like “Saving…” while an operation is in progress.download
opts out of Turbo since the link is for downloading files and not navigation.
# 自動的に追加される属性
次の属性は Turbo が自動的に追加します。ある瞬間の Visit の状態を判断するのに便利です。
disabled
は、フォーム送信中、フォームの送信ボタンに追加されます。これは、フォームの再送信を防ぐためです。data-turbo-preview
は、Visit 中にプレビューを表示しているときに、html
要素に追加されます。data-turbo-visit-direction
は、Visit 中にhtml
要素に追加されます。この属性の値には、forward
、back
、none
のいずれかが入ります。これらは、Visitの方向を表しています。aria-busy
は、ページ遷移中、html
要素とturbo-frame
要素に追加されます。aria-busy
は、処理中であることを示すために次の要素に追加されます。- ページ遷移中には
html
要素 - フォーム送信中には
form
要素 - フレーム内で遷移またはフォーム送信が行われているときには
turbo-frame
要素
- ページ遷移中には
busy
は、フレーム内でページ遷移やフォーム送信が行われている間、turbo-frame
要素に付与されます。
原文
The following attributes are automatically added by Turbo and are useful to determine the Visit state at a given moment.
disabled
is added to the form submitter while the form request is in progress, to prevent repeat submissions.data-turbo-preview
is added to thehtml
element when displaying a preview during a Visit.data-turbo-visit-direction
is added to thehtml
element during a visit, with a value offorward
orback
ornone
, to indicate its direction.aria-busy
is added to:- the
html
element when a visit is in progress - the
form
element when a submission is in progress. - the
turbo-frame
element when a visit or form submission is in progress within the frame.
- the
busy
is added to theturbo-frame
element when a navigation or form submission is in progress within the frame.
# メタタグ
次のmeta
要素をhead
要素に追加することで、キャッシュや Visit の振る舞いをカスタマイズできます。
<meta name="turbo-cache-control">
で、キャッシュのオプトアウトができます。<meta name="turbo-visit-control" content="reload">
で、Turbo でページ遷移するたびに、全ページリロードします。これは、<turbo-frame>
からリクエストした時も同様です。<meta name="turbo-root">
で、Turbo ドライブを適用するルートロケーションを設定できます。<meta name="view-transition" content="same-origin">
により、View Transition APIをサポートしているブラウザでビュートランジションが動きます。<meta name="turbo-refresh-method" content="morph">
で、モーフィングによるページ更新が使えます。<meta name="turbo-refresh-scroll" content="preserve">
で、ページ更新時にスクロールの位置を保存します。<meta name="turbo-prefetch" content="false">
を指定すると、マウスホバーしたときのリンクのプリフェッチを無効にします。
原文
The following meta
elements, added to the head
, can be used to customize caching and Visit behavior.
<meta name="turbo-cache-control">
to opt out of caching.<meta name="turbo-visit-control" content="reload">
will perform a full page reload whenever Turbo navigates to the page, including when the request originates from a<turbo-frame>
.<meta name="turbo-root">
to scope Turbo Drive to a particular root location.<meta name="view-transition" content="same-origin">
to trigger view transitions on browsers that support the View Transition API.<meta name="turbo-refresh-method" content="morph">
will configure page refreshes with morphing.<meta name="turbo-refresh-scroll" content="preserve">
will enable scroll preservation during page refreshes.<meta name="turbo-prefetch" content="false">
will disable prefetching links on hover.