#TanStack Query 在 Vue3 中的完整新手指南（v5）

<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'

type Todo = { id: number; title: string; completed: boolean }

async function fetchTodos({ signal }: { signal?: AbortSignal }) {
  const res = await fetch('/api/todos', { signal })
  if (!res.ok) throw new Error('获取待办失败')
  return (await res.json()) as Todo[]
}

const { data, isPending, isError, error, isFetching } = useQuery({
  queryKey: ['todos'],
  queryFn: ({ signal }) => fetchTodos({ signal }),
  staleTime: 30_000,
})
</script>

<template>
  <p v-if="isPending">加载中...</p>
  <p v-else-if="isError">错误：{{ (error as Error).message }}</p>
  <div v-else>
    <ul>
      <li v-for="todo in data" :key="todo.id">{{ todo.title }}</li>
    </ul>
    <small v-if="isFetching">后台刷新中...</small>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import { useQuery } from '@tanstack/vue-query'

type User = { id: number; name: string }
type Project = { id: number; name: string }

const email = 'alice@example.com'

const getUserByEmail = async (value: string): Promise<User> => {
  const res = await fetch(`/api/users?email=${encodeURIComponent(value)}`)
  if (!res.ok) throw new Error('查询用户失败')
  return res.json()
}

const getProjectsByUser = async (userId: number): Promise<Project[]> => {
  const res = await fetch(`/api/projects?userId=${userId}`)
  if (!res.ok) throw new Error('查询项目失败')
  return res.json()
}

const userQuery = useQuery({
  queryKey: ['user', email],
  queryFn: () => getUserByEmail(email),
})

const userId = computed(() => userQuery.data.value?.id)

const projectsQuery = useQuery({
  queryKey: ['projects', userId],
  queryFn: () => getProjectsByUser(userId.value as number),
  enabled: computed(() => !!userId.value),
})
</script>

<template>
  <p v-if="userQuery.isPending || projectsQuery.isPending">加载中...</p>
  <p v-else-if="userQuery.isError">用户加载失败</p>
  <p v-else-if="projectsQuery.isError">项目加载失败</p>
  <ul v-else>
    <li v-for="p in projectsQuery.data" :key="p.id">{{ p.name }}</li>
  </ul>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { keepPreviousData, useQuery } from '@tanstack/vue-query'

type ProjectsPage = {
  items: { id: number; name: string }[]
  hasMore: boolean
}

const page = ref(1)

async function fetchProjects(currentPage: number): Promise<ProjectsPage> {
  const res = await fetch(`/api/projects?page=${currentPage}`)
  if (!res.ok) throw new Error('分页查询失败')
  return res.json()
}

const { data, isPending, isFetching, isPlaceholderData } = useQuery({
  queryKey: ['projects', page],
  queryFn: () => fetchProjects(page.value),
  placeholderData: keepPreviousData,
})
</script>

<template>
  <p v-if="isPending">加载中...</p>
  <div v-else>
    <p v-for="item in data?.items" :key="item.id">{{ item.name }}</p>
    <button :disabled="page === 1" @click="page = Math.max(1, page - 1)">上一页</button>
    <button :disabled="isPlaceholderData || !data?.hasMore" @click="page = page + 1">
      下一页
    </button>
    <span v-if="isFetching"> 加载中...</span>
  </div>
</template>

<script setup lang="ts">
import { useMutation, useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()

async function addTodo(payload: { title: string }) {
  const res = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  })
  if (!res.ok) throw new Error('新增失败')
  return res.json()
}

const mutation = useMutation({
  mutationFn: addTodo,
  onSuccess: async () => {
    await queryClient.invalidateQueries({ queryKey: ['todos'] })
  },
})
</script>

<template>
  <button :disabled="mutation.isPending" @click="mutation.mutate({ title: '学习 TanStack Query' })">
    {{ mutation.isPending ? '提交中...' : '新增' }}
  </button>
</template>

<script setup lang="ts">
import { useMutation, useQueryClient } from '@tanstack/vue-query'

type Todo = { id: number; title: string; completed: boolean }

const queryClient = useQueryClient()

async function editTodo(input: { id: number; title: string }): Promise<Todo> {
  const res = await fetch(`/api/todos/${input.id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: input.title }),
  })
  if (!res.ok) throw new Error('更新失败')
  return res.json()
}

const mutation = useMutation({
  mutationFn: editTodo,
  onSuccess: (updatedTodo, variables) => {
    queryClient.setQueryData(['todo', { id: variables.id }], updatedTodo)
  },
})
</script>

<template>
  <button @click="mutation.mutate({ id: 1, title: '新标题' })">更新标题</button>
</template>

<script setup lang="ts">
import { useMutation, useQueryClient } from '@tanstack/vue-query'

type Todo = { id: number; title: string; completed: boolean }

const queryClient = useQueryClient()

async function createTodo(payload: { title: string }): Promise<Todo> {
  const res = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  })
  if (!res.ok) throw new Error('新增失败')
  return res.json()
}

const mutation = useMutation({
  mutationFn: createTodo,
  onMutate: async (newTodo, context) => {
    await context.client.cancelQueries({ queryKey: ['todos'] })
    const previousTodos = context.client.getQueryData<Todo[]>(['todos'])

    context.client.setQueryData<Todo[]>(['todos'], (old = []) => [
      ...old,
      { id: -1, title: newTodo.title, completed: false },
    ])

    return { previousTodos }
  },
  onError: (_error, _variables, onMutateResult, context) => {
    context.client.setQueryData(['todos'], onMutateResult?.previousTodos)
  },
  onSettled: async (_data, _error, _variables, _onMutateResult, context) => {
    await context.client.invalidateQueries({ queryKey: ['todos'] })
  },
})
</script>

<template>
  <button @click="mutation.mutate({ title: '先乐观更新' })">乐观新增</button>
</template>