Events
Turbo 会发出各种 自定义事件 类型，这些事件从以下来源发出
当使用 jQuery 时，必须以 $event.originalEvent.detail 形式访问事件中的数据。
﹟ 文档
Turbo Drive 会发出事件，让你能够跟踪导航生命周期并响应页面加载。除非另有说明，否则以下事件会在 document.documentElement 对象（即 <html> 元素）上触发。
﹟ turbo:click
当你单击启用了 Turbo 的链接时触发。单击的元素是 event.target。使用 event.detail.url 访问请求的位置。取消此事件以让单击像正常导航一样传递到浏览器。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
url |
字符串 |
请求的位置 |
originalEvent |
MouseEvent | 原始 click 事件 |
﹟ turbo:before-visit
在访问位置之前触发，但通过历史记录导航时除外。使用 event.detail.url 访问请求的位置。取消此事件以阻止导航。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
url |
字符串 |
请求的位置 |
﹟ turbo:visit
在访问开始后立即触发。使用 event.detail.url 访问请求的位置，并使用 event.detail.action 访问操作。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
url |
字符串 |
请求的位置 |
action |
"advance" | "replace" | "restore" |
访问的 操作 |
﹟ turbo:before-cache
在 Turbo 将当前页面保存到缓存之前触发。
turbo:before-cache 事件的实例没有 event.detail 属性。
﹟ turbo:before-render
在渲染页面之前触发。使用 event.detail.newBody 访问新的 <body> 元素。可以取消渲染并使用 event.detail.resume 继续（请参阅 暂停渲染）。通过覆盖 event.detail.render 函数来自定义 Turbo Drive 渲染响应的方式（请参阅 自定义渲染）。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
renderMethod |
"replace" | "morph" |
用于渲染新内容的策略 |
newBody |
HTMLBodyElement | 将替换文档当前 <body> 元素的新 <body> 元素 |
isPreview |
boolean |
渲染是否为缓存页面的 预览 |
resume |
(value?: any) => void |
在 暂停请求 时调用 |
render |
(currentBody, newBody) => void |
覆盖以 自定义渲染 |
﹟ turbo:render
在 Turbo 渲染页面之后触发。此事件在应用程序访问缓存位置期间触发两次：一次在渲染缓存版本后，另一次在渲染新版本后。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
renderMethod |
"replace" | "morph" |
用于渲染新内容的策略 |
isPreview |
boolean |
渲染是否为缓存页面的 预览 |
﹟ turbo:load
在初始页面加载后触发一次，并在每次 Turbo 访问后再次触发。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
url |
字符串 |
请求的位置 |
timing.visitStart |
number |
访问开始时的时间戳 |
timing.requestStart |
number |
下一页的 HTTP 请求开始时的时间戳 |
timing.requestEnd |
number |
下一页的 HTTP 请求结束时的时间戳 |
timing.visitEnd |
number |
访问结束时的时间戳 |
﹟ 页面刷新
Turbo Drive 在转换页面内容时会发出事件。
﹟ turbo:morph
在 Turbo 转换页面后触发。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
currentElement |
Element | 变形后仍然保持连接的原始 元素（最常见的是 document.body） |
newElement |
Element | 变形后未连接的具有新属性和子元素的 元素 |
﹟ turbo:before-morph-element
在 Turbo 变形元素之前触发。 event.target 引用将保持连接到文档的原始元素。通过调用 event.preventDefault() 取消此事件，以跳过变形并保留原始元素、其属性及其子元素。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
newElement |
Element | 变形后未连接的具有新属性和子元素的 元素 |
﹟ turbo:before-morph-attribute
在 Turbo 变形元素的属性之前触发。 event.target 引用将保持连接到文档的原始元素。通过调用 event.preventDefault() 取消此事件，以跳过变形并保留原始属性值。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
attributeName |
字符串 |
要变异的属性的名称 |
mutationType |
"updated" | "removed" |
属性的变异方式 |
﹟ turbo:morph-element
在 Turbo 变形元素之后触发。 event.target 引用变形后保持连接的变形元素。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
newElement |
Element | 变形后未连接的具有新属性和子元素的 元素 |
﹟ 表单
Turbo Drive 在提交、重定向和提交失败期间会发出事件。以下事件在提交期间在 <form> 元素上触发。
﹟ turbo:submit-start
在表单提交期间触发。使用 event.detail.formSubmission 访问 FormSubmission 对象。使用 event.detail.formSubmission.stop() 中止表单提交（例如在验证失败后）。如果你正在使用 jQuery，请使用 event.originalEvent.detail.formSubmission.stop()。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
formSubmission |
FormSubmission |
<form> 元素提交 |
﹟ turbo:submit-end
在表单提交发起的网络请求完成后触发。使用 event.detail.formSubmission 访问 FormSubmission 对象，以及包含在 event.detail 中的 FormSubmissionResult 属性。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
success |
boolean |
表示请求是否成功的 boolean |
fetchResponse |
FetchResponse | null |
当 success: true 时显示，当 success: false 时为 null |
error |
错误 或 null |
当 success: true 时为 null，当 success: false 时显示 |
﹟ 框架
Turbo 框架在其导航生命周期中会发出事件。以下事件会在 <turbo-frame> 元素上触发。
﹟ turbo:before-frame-render
在渲染 <turbo-frame> 元素之前触发。使用 event.detail.newFrame 访问新的 <turbo-frame> 元素。可以取消渲染并使用 event.detail.resume 继续（请参阅 暂停渲染）。通过覆盖 event.detail.render 函数来自定义 Turbo Drive 渲染响应的方式（请参阅 自定义渲染）。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
newFrame |
FrameElement |
将替换当前 <turbo-frame> 元素的新 <turbo-frame> 元素 |
resume |
(value?: any) => void |
在 暂停请求 时调用 |
render |
(currentFrame, newFrame) => void |
覆盖以 自定义渲染 |
﹟ turbo:frame-render
在 <turbo-frame> 元素渲染其视图后立即触发。特定的 <turbo-frame> 元素是 event.target。使用 event.detail.fetchResponse 属性访问 FetchResponse 对象。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
fetchResponse |
FetchResponse |
HTTP 请求的响应 |
﹟ turbo:frame-load
在 <turbo-frame> 元素导航并完成加载时触发（在 turbo:frame-render 之后触发）。特定的 <turbo-frame> 元素是 event.target。
turbo:frame-load 事件的实例没有 event.detail 属性。
﹟ turbo:frame-missing
当对 <turbo-frame> 元素请求的响应不包含匹配的 <turbo-frame> 元素时触发。默认情况下，Turbo 会在框架中写入一条信息消息并抛出异常。取消此事件以覆盖此处理。可以使用 event.detail.response 访问 Response 实例，并通过调用 event.detail.visit(location, visitOptions) 执行访问（请参阅 Turbo.visit 以了解有关 VisitOptions 的更多信息）。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
response |
Response | 由 <turbo-frame> 元素发起的请求的 HTTP 响应 |
visit |
async (location: string | URL, visitOptions: VisitOptions) => void |
一个用于启动页面范围导航的便捷函数 |
﹟ 流
Turbo 流在其生命周期中会发出事件。以下事件会在 <turbo-stream> 元素上触发。
﹟ turbo:before-stream-render
在渲染 Turbo 流页面更新之前触发。使用 event.detail.newStream 访问新的 <turbo-stream> 元素。通过覆盖 event.detail.render 函数来自定义元素的行为（请参阅 自定义操作）。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
newStream |
StreamElement |
将替换文档当前 <body> 元素的新 <body> 元素 |
render |
async (currentElement) => void |
覆盖以定义自定义操作 |
﹟ HTTP 请求
Turbo 在通过 HTTP 获取内容时会发出事件。根据发起请求的内容，事件可能会在以下位置触发
<turbo-frame>在其导航期间<form>在其提交期间<html>元素在整个页面的 Turbo 访问期间
﹟ turbo:before-fetch-request
在 Turbo 发出网络请求（获取页面、提交表单、预加载链接等）之前触发。使用 event.detail.url 访问请求的位置，使用 event.detail.fetchOptions 访问获取选项对象。此事件在触发它的相应元素（<turbo-frame> 或 <form> 元素）上触发，可以使用 event.target 属性进行访问。请求可以通过 event.detail.resume 取消并继续（请参阅暂停请求）。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
fetchOptions |
RequestInit | 用于构造 Request 的 options |
url |
URL | 请求的位置 |
resume |
(value?: any) => void 回调 |
在 暂停请求 时调用 |
﹟ turbo:before-fetch-response
在网络请求完成后触发。使用 event.detail 访问获取选项对象。此事件在触发它的相应元素（<turbo-frame> 或 <form> 元素）上触发，可以使用 event.target 属性进行访问。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
fetchResponse |
FetchResponse |
HTTP 请求的响应 |
﹟ turbo:before-prefetch
在 Turbo 预取链接之前触发。链接是 event.target。取消此事件以阻止预取。
﹟ turbo:fetch-request-error
当表单或框架获取请求由于网络错误而失败时触发。此事件在触发它的相应元素（<turbo-frame> 或 <form> 元素）上触发，可以使用 event.target 属性进行访问。此事件可以取消。
event.detail 属性 |
类型 | 描述 |
|---|---|---|
request |
FetchRequest |
失败的 HTTP 请求 |
error |
Error | 提供失败的原因 |