Vue3 Suspenseで非同期処理のUXを改善する方法【実装パターン・コード例付き】

<script setup lang="ts">
import { ref, onMounted } from 'vue'

const isLoading = ref(true)
const data = ref<string[]>([])

onMounted(async () => {
  data.value = await fetchItems()
  isLoading.value = false
})
</script>

<template>
  <div v-if="isLoading">読み込み中...</div>
  <ul v-else>
    <li v-for="item in data" :key="item">{{ item }}</li>
  </ul>
</template>

<template>
  <Suspense>
    <template #default>
      <AsyncUserList />
    </template>
    <template #fallback>
      <p>ユーザー一覧を取得しています...</p>
    </template>
  </Suspense>
</template>

<!-- NG: 直下に複数のルートノード -->
<template #default>
  <UserProfile />
  <UserPosts />
</template>

<!-- OK: ラッパーで囲む -->
<template #default>
  <div>
    <UserProfile />
    <UserPosts />
  </div>
</template>

<!-- AsyncUserList.vue -->
<script setup lang="ts">
interface User {
  id: number
  name: string
  email: string
}

const res = await fetch('https://jsonplaceholder.typicode.com/users')
const users: User[] = await res.json()
</script>

<template>
  <ul>
    <li v-for="user in users" :key="user.id">
      {{ user.name }} ({{ user.email }})
    </li>
  </ul>
</template>

import { defineComponent } from 'vue'

export default defineComponent({
  async setup() {
    const res = await fetch('https://jsonplaceholder.typicode.com/users')
    const users = await res.json()
    return { users }
  }
})

import { defineAsyncComponent } from 'vue'

const HeavyChart = defineAsyncComponent(
  () => import('./components/HeavyChart.vue')
)

<script setup lang="ts">
function onPending() {
  console.log('非同期処理を待機中...')
}

function onResolve() {
  console.log('描画完了')
}

function onFallback() {
  console.log('フォールバック表示')
}
</script>

<template>
  <Suspense
    @pending="onPending"
    @resolve="onResolve"
    @fallback="onFallback"
  >
    <AsyncDashboard />
    <template #fallback>
      <LoadingSpinner />
    </template>
  </Suspense>
</template>

<!-- 200ms以上かかった場合のみローディング表示 -->
<Suspense timeout="200">
  <AsyncContent />
  <template #fallback>
    <LoadingSpinner />
  </template>
</Suspense>

<!-- ParentWithErrorHandling.vue -->
<script setup lang="ts">
import { ref, onErrorCaptured } from 'vue'
import AsyncUserList from './AsyncUserList.vue'

const error = ref<Error | null>(null)

onErrorCaptured((err) => {
  error.value = err as Error
  return false // エラーの伝播を止める
})
</script>

<template>
  <div v-if="error" class="error-message">
    エラーが発生しました: {{ error.message }}
  </div>
  <Suspense v-else>
    <AsyncUserList />
    <template #fallback>
      <p>読み込み中...</p>
    </template>
  </Suspense>
</template>

<script setup lang="ts">
import { ref, onErrorCaptured } from 'vue'
import AsyncContent from './AsyncContent.vue'

const error = ref<Error | null>(null)
const retryKey = ref(0)

onErrorCaptured((err) => {
  error.value = err as Error
  return false
})

function retry() {
  error.value = null
  retryKey.value++
}
</script>

<template>
  <div v-if="error" class="error-container">
    <p>{{ error.message }}</p>
    <button @click="retry">再読み込み</button>
  </div>
  <Suspense v-else :key="retryKey">
    <AsyncContent />
    <template #fallback>
      <p>読み込み中...</p>
    </template>
  </Suspense>
</template>

<!-- App.vue -->
<template>
  <RouterView v-slot="{ Component }">
    <Suspense>
      <component :is="Component" />
      <template #fallback>
        <div class="page-loading">ページを読み込み中...</div>
      </template>
    </Suspense>
  </RouterView>
</template>

<RouterView v-slot="{ Component }">
  <Suspense timeout="0">
    <component :is="Component" />
    <template #fallback>
      <LoadingSpinner />
    </template>
  </Suspense>
</RouterView>

<RouterView v-slot="{ Component }">
  <Transition mode="out-in">
    <KeepAlive>
      <Suspense>
        <component :is="Component" />
        <template #fallback>
          <LoadingSpinner />
        </template>
      </Suspense>
    </KeepAlive>
  </Transition>
</RouterView>

<Suspense>
  <template #default>
    <OuterAsyncComponent>
      <!-- suspensible を付けると、外側の Suspense に制御を委譲 -->
      <Suspense suspensible>
        <InnerAsyncComponent />
      </Suspense>
    </OuterAsyncComponent>
  </template>
  <template #fallback>
    <p>全体を読み込み中...</p>
  </template>
</Suspense>

<!-- pages/users.vue (Nuxt 3) -->
<script setup lang="ts">
const { data: users, status } = await useFetch('/api/users')
</script>

<template>
  <div>
    <ul>
      <li v-for="user in users" :key="user.id">{{ user.name }}</li>
    </ul>
  </div>
</template>

[Vue warn]: Component <Anonymous>: setup function returned a promise, but no <Suspense> boundary was found in the parent component tree.