TypeScript
React Query 现在使用 TypeScript 编写，以确保库和你的项目是类型安全的！
需要记住的事情
- 类型当前需要使用 TypeScript v4.7 或更高版本
- 此仓库中类型的更改被认为是非破坏性的，通常作为 patch semver 更改发布（否则每个类型增强都将是一个主要版本！）。
- 强烈建议您将 react-query 包版本锁定到特定的 patch 版本，并期望在任何版本之间类型可能会被修复或升级的情况下进行升级
- React Query 的非类型相关的公共 API 仍然严格遵循 semver。
类型推断
React Query 中的类型通常可以很好地流动，因此您不必为自己提供类型注释
const { data } = useQuery({
// ^? const data: number | undefined
queryKey: ['test'],
queryFn: () => Promise.resolve(5),
})
const { data } = useQuery({
// ^? const data: number | undefined
queryKey: ['test'],
queryFn: () => Promise.resolve(5),
})
const { data } = useQuery({
// ^? const data: string | undefined
queryKey: ['test'],
queryFn: () => Promise.resolve(5),
select: (data) => data.toString(),
})
const { data } = useQuery({
// ^? const data: string | undefined
queryKey: ['test'],
queryFn: () => Promise.resolve(5),
select: (data) => data.toString(),
})
如果你的 queryFn 具有良好定义的返回类型，这将效果最佳。请记住，大多数数据获取库默认返回 any，因此请确保将其提取到正确类型的函数中
const fetchGroups = (): Promise<Group[]> =>
axios.get('/groups').then((response) => response.data)
const { data } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const data: Group[] | undefined
const fetchGroups = (): Promise<Group[]> =>
axios.get('/groups').then((response) => response.data)
const { data } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const data: Group[] | undefined
类型收窄
React Query 对查询结果使用 可辨识联合类型，由 status 字段和派生的状态布尔标志区分。这将允许你检查例如 success 状态，以使 data 被定义
const { data, isSuccess } = useQuery({
queryKey: ['test'],
queryFn: () => Promise.resolve(5),
})
if (isSuccess) {
data
// ^? const data: number
}
const { data, isSuccess } = useQuery({
queryKey: ['test'],
queryFn: () => Promise.resolve(5),
})
if (isSuccess) {
data
// ^? const data: number
}
为 error 字段添加类型
error 的类型默认为 Error，因为这是大多数用户所期望的。
const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: Error
const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: Error
如果你想抛出一个自定义错误，或者根本不是 Error 的东西，你可以指定 error 字段的类型
const { error } = useQuery<Group[], string>(['groups'], fetchGroups)
// ^? const error: string | null
const { error } = useQuery<Group[], string>(['groups'], fetchGroups)
// ^? const error: string | null
但是，这有一个缺点，即 useQuery 的所有其他泛型的类型推断将不再起作用。通常不建议抛出不是 Error 的东西，因此如果你有一个像 AxiosError 这样的子类，你可以使用类型收窄来使 error 字段更具体
import axios from 'axios'
const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: Error | null
if (axios.isAxiosError(error)) {
error
// ^? const error: AxiosError
}
import axios from 'axios'
const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: Error | null
if (axios.isAxiosError(error)) {
error
// ^? const error: AxiosError
}
注册全局 Error
TanStack Query v5 允许通过修改 Register 接口来为所有内容设置全局 Error 类型，而无需在调用端指定泛型。这将确保推断仍然有效，但 error 字段将是指定的类型
import '@tanstack/react-query'
declare module '@tanstack/react-query' {
interface Register {
defaultError: AxiosError
}
}
const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: AxiosError | null
import '@tanstack/react-query'
declare module '@tanstack/react-query' {
interface Register {
defaultError: AxiosError
}
}
const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
// ^? const error: AxiosError | null
为 meta 添加类型
注册全局 Meta
与注册全局错误类型类似，你也可以注册全局 Meta 类型。这确保了 查询和突变上的可选 meta 字段保持一致且类型安全。请注意，注册的类型必须扩展 Record<string, unknown>，以便 meta 仍然是一个对象。
import '@tanstack/react-query'
interface MyMeta extends Record<string, unknown> {
// Your meta type definition.
}
declare module '@tanstack/react-query' {
interface Register {
queryMeta: MyMeta
mutationMeta: MyMeta
}
}
import '@tanstack/react-query'
interface MyMeta extends Record<string, unknown> {
// Your meta type definition.
}
declare module '@tanstack/react-query' {
interface Register {
queryMeta: MyMeta
mutationMeta: MyMeta
}
}
为 query 和 mutation 键添加类型
注册 query 和 mutation 键类型
同样与注册全局错误类型类似，你也可以注册全局 QueryKey 和 MutationKey 类型。这允许你为你的键提供更多结构，以匹配你的应用程序的层次结构，并使它们在库的所有表面区域中都是类型化的。请注意，注册的类型必须扩展 Array 类型，以便你的键仍然是一个数组。
import '@tanstack/react-query'
type QueryKey = ['dashboard' | 'marketing', ...ReadonlyArray<unknown>]
declare module '@tanstack/react-query' {
interface Register {
queryKey: QueryKey
mutationKey: QueryKey
}
}
import '@tanstack/react-query'
type QueryKey = ['dashboard' | 'marketing', ...ReadonlyArray<unknown>]
declare module '@tanstack/react-query' {
interface Register {
queryKey: QueryKey
mutationKey: QueryKey
}
}
为查询选项添加类型
如果你将查询选项内联到 useQuery 中，你将获得自动类型推断。但是，你可能希望将查询选项提取到单独的函数中，以便在 useQuery 和例如 prefetchQuery 之间共享它们。在这种情况下，你将失去类型推断。要恢复它，你可以使用 queryOptions 辅助函数
import { queryOptions } from '@tanstack/react-query'
function groupOptions() {
return queryOptions({
queryKey: ['groups'],
queryFn: fetchGroups,
staleTime: 5 * 1000,
})
}
useQuery(groupOptions())
queryClient.prefetchQuery(groupOptions())
import { queryOptions } from '@tanstack/react-query'
function groupOptions() {
return queryOptions({
queryKey: ['groups'],
queryFn: fetchGroups,
staleTime: 5 * 1000,
})
}
useQuery(groupOptions())
queryClient.prefetchQuery(groupOptions())
此外，从 queryOptions 返回的 queryKey 知道与之关联的 queryFn，我们可以利用该类型信息来使诸如 queryClient.getQueryData 之类的函数也意识到这些类型
function groupOptions() {
return queryOptions({
queryKey: ['groups'],
queryFn: fetchGroups,
staleTime: 5 * 1000,
})
}
const data = queryClient.getQueryData(groupOptions().queryKey)
// ^? const data: Group[] | undefined
function groupOptions() {
return queryOptions({
queryKey: ['groups'],
queryFn: fetchGroups,
staleTime: 5 * 1000,
})
}
const data = queryClient.getQueryData(groupOptions().queryKey)
// ^? const data: Group[] | undefined
如果没有 queryOptions，则 data 的类型将是 unknown，除非我们向其传递泛型
const data = queryClient.getQueryData<Group[]>(['groups'])
const data = queryClient.getQueryData<Group[]>(['groups'])
拓展阅读
有关类型推断的技巧和窍门，请查看社区资源中的React Query 和 TypeScript。要了解如何获得最佳的类型安全性，你可以阅读类型安全的 React Query。
使用 skipToken 安全地禁用查询
如果你正在使用 TypeScript，你可以使用 skipToken 来禁用查询。当你想根据条件禁用查询，但仍然希望保持查询的类型安全时，这非常有用。在禁用查询指南中阅读更多相关信息。
