查询函数

更新于 2026-11-02 Lit 查看英文原文 ↗

查询函数可以是任何返回 Promise 的函数。该 Promise 应当解析出数据，或抛出错误。

TypeScript

1createQueryController(this, {2  queryKey: ['todos'],3  queryFn: fetchTodos,4})5 6createQueryController(this, () => ({7  queryKey: ['todo', this.todoId],8  queryFn: () => fetchTodo(this.todoId),9}))

错误处理

TanStack Query 要求失败的查询函数必须抛出错误或返回被拒绝的 Promise。某些客户端会自动执行此操作，但浏览器 fetch API 不会，因此你需要自行检查 response.ok：

TypeScript

1async function fetchTodos(): Promise<Todo[]> {2  const response = await fetch('/api/todos')3 4  if (!response.ok) {5    throw new Error('Failed to fetch todos')6  }7 8  return response.json() as Promise<Todo[]>9}

抛出的错误可在查询结果中获取：

TypeScript

1const query = this.todos()2 3if (query.isError) {4  return html`Error: ${query.error.message}`5}

查询函数上下文

TanStack Query 会向每个查询函数传入一个上下文对象，其中包含以下字段：

queryKey：当前查询键
client： QueryClient
signal：一个用于取消的 AbortSignal
meta：可选的查询元数据

TypeScript

1createQueryController(this, {2  queryKey: ['todos', { status: 'open' }] as const,3  queryFn: async ({ queryKey, signal }) => {4    const [, filters] = queryKey5    const response = await fetch(`/api/todos?status=${filters.status}`, {6      signal,7    })8    if (!response.ok) throw new Error('Failed to fetch todos')9    return response.json() as Promise<Todo[]>10  },11})

无限查询函数还会额外接收 pageParam：

TypeScript

1createInfiniteQueryController(this, {2  queryKey: ['projects'],3  queryFn: ({ pageParam }) => fetchProjectsPage(pageParam),4  initialPageParam: 1,5  getNextPageParam: (lastPage) =>6    lastPage.hasMore ? lastPage.page + 1 : undefined,7})

有关控制器特定行为，请参阅无限查询。