事件

Inertia 提供了一個事件系統，讓您可以「掛勾」到這個函式庫的各個生命週期事件。

註冊監聽器

若要註冊事件監聽器，請使用 router.on() 方法。

import { router } from '@inertiajs/vue3'

router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

在幕後，Inertia 使用原生瀏覽器事件，因此您也可以使用您可能已經熟悉的典型事件方法與 Inertia 事件互動 - 只要確保在事件名稱前加上 inertia: 即可。

import { router } from '@inertiajs/vue3'

document.addEventListener('inertia:start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

移除監聽器

當您註冊事件監聽器時，Inertia 會自動傳回一個可以被呼叫以移除事件監聽器的回呼函數。

import { router } from '@inertiajs/vue3'

let removeStartEventListener = router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

// Remove the listener...
removeStartEventListener()

結合鉤子，您可以自動在元件解除安裝時移除事件監聽器。

import { router } from '@inertiajs/vue3'
import { onUnmounted } from 'vue'

onUnmounted(
  router.on('start', (event) => {
    console.log(`Starting a visit to ${event.detail.visit.url}`)
  })
)

或者，如果您使用原生瀏覽器事件，您可以使用 removeEventListener().

import { router } from '@inertiajs/vue3'

let startEventListener = (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
}

document.addEventListener('inertia:start', startEventListener)

// Remove the listener...
document.removeEventListener('inertia:start', startEventListener)

取消事件

某些事件，例如 before、invalid 和 error，支援取消，讓您可以防止 Inertia 的預設行為。就像原生事件一樣，如果只有一個事件監聽器呼叫 event.preventDefault()，事件就會被取消。

import { router } from '@inertiajs/vue3'

router.on('before', (event) => {
  if (!confirm('Are you sure you want to navigate away?')) {
    event.preventDefault()
  }
})

為了方便起見，如果您使用 router.on() 註冊事件監聽器，您可以從監聽器中傳回 false 來取消事件。

import { router } from '@inertiajs/vue3'

router.on('before', (event) => {
  return confirm('Are you sure you want to navigate away?')
})

請注意，瀏覽器不允許取消原生 popstate 事件，因此在使用 Inertia.js 時無法防止前後瀏覽歷史記錄。

Before

當要向伺服器發出請求時，before 事件會觸發。這對於攔截造訪很有用。

import { router } from '@inertiajs/vue3'

router.on('before', (event) => {
  console.log(`About to make a visit to ${event.detail.visit.url}`)
})

這個事件的主要目的是讓您可以防止造訪發生。

import { router } from '@inertiajs/vue3'

router.on('before', (event) => {
  return confirm('Are you sure you want to navigate away?')
})

Start

當向伺服器的請求開始時，start 事件會觸發。這對於顯示載入指示器很有用。

import { router } from '@inertiajs/vue3'

router.on('start', (event) => {
  console.log(`Starting a visit to ${event.detail.visit.url}`)
})

start 事件不可取消。

Progress

當檔案上傳期間進度遞增時，progress 事件會觸發。

import { router } from '@inertiajs/vue3'

router.on('progress', (event) => {
  this.form.progress = event.detail.progress.percentage
})

progress 事件不可取消。

Success

在成功造訪頁面時，success 事件會觸發，除非存在驗證錯誤。但是，這 *不* 包括瀏覽歷史記錄。

import { router } from '@inertiajs/vue3'

router.on('success', (event) => {
  console.log(`Successfully made a visit to ${event.detail.page.url}`)
})

success 事件不可取消。

Error

當「成功」造訪頁面時存在驗證錯誤時，error 事件會觸發。

import { router } from '@inertiajs/vue3'

router.on('error', (errors) => {
  console.log(errors)
})

error 事件不可取消。

Invalid

當從伺服器收到非 Inertia 回應時，invalid 事件會觸發，例如 HTML 或原生 JSON 回應。有效的 Inertia 回應是設定了 X-Inertia 標頭為 true，且包含 json 載荷的回應，其中包含 頁面物件.

這個事件會針對所有回應類型觸發，包括 200、400 和 500回應程式碼。

import { router } from '@inertiajs/vue3'

router.on('invalid', (event) => {
  console.log(`An invalid Inertia response was received.`)
  console.log(event.detail.response)
})

您可以取消 invalid 事件以防止 Inertia 顯示非 Inertia 回應模式。

import { router } from '@inertiajs/vue3'

router.on('invalid', (event) => {
  event.preventDefault()

  // Handle the invalid response yourself...
})

Exception

當發生意外的 XHR 錯誤（例如網路中斷）時，exception 事件會觸發。此外，這個事件也會針對解析頁面元件時產生的錯誤觸發。

import { router } from '@inertiajs/vue3'

router.on('exception', (event) => {
  console.log(`An unexpected error occurred during an Inertia visit.`)
  console.log(event.detail.error)
})

您可以取消 exception 事件以防止錯誤被拋出。

import { router } from '@inertiajs/vue3'

router.on('exception', (event) => {
  event.preventDefault()
  // Handle the error yourself
})

這個事件 *不會* 針對收到 400 和 500 級別回應的 XHR 請求或非 Inertia 回應觸發，因為這些情況會由 Inertia 以其他方式處理。請參閱 錯誤處理文件 了解更多資訊。

Finish

當 XHR 請求針對「成功」和「不成功」回應完成時，finish 事件會觸發。這個事件對於隱藏載入指示器很有用。

import { router } from '@inertiajs/vue3'

router.on('finish', (event) => {
  NProgress.done()
})

finish 事件不可取消。

Navigate

當成功造訪頁面以及瀏覽歷史記錄時，navigate 事件會觸發。

import { router } from '@inertiajs/vue3'

router.on('navigate', (event) => {
  console.log(`Navigated to ${event.detail.page.url}`)
})

navigate 事件不可取消。

事件回呼函數

除了本頁所述的全局事件之外，Inertia 還提供了一些 事件回呼函數，這些函數在手動進行 Inertia 造訪時會觸發。