框架
版本

useQuery

tsx
const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  failureReason,
  fetchStatus,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isInitialLoading,
  isLoading,
  isLoadingError,
  isPaused,
  isPending,
  isPlaceholderData,
  isRefetchError,
  isRefetching,
  isStale,
  isSuccess,
  refetch,
  status,
} = useQuery(
  () => ({
    queryKey,
    queryFn,
    enabled,
    select,
    placeholderData,
    deferStream,
    reconcile,
    gcTime,
    networkMode,
    initialData,
    initialDataUpdatedAt,
    meta,
    queryKeyHashFn,
    refetchInterval,
    refetchIntervalInBackground,
    refetchOnMount,
    refetchOnReconnect,
    refetchOnWindowFocus,
    retry,
    retryOnMount,
    retryDelay,
    staleTime,
    throwOnError,
  }),
  () => queryClient,
)
const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  failureReason,
  fetchStatus,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isInitialLoading,
  isLoading,
  isLoadingError,
  isPaused,
  isPending,
  isPlaceholderData,
  isRefetchError,
  isRefetching,
  isStale,
  isSuccess,
  refetch,
  status,
} = useQuery(
  () => ({
    queryKey,
    queryFn,
    enabled,
    select,
    placeholderData,
    deferStream,
    reconcile,
    gcTime,
    networkMode,
    initialData,
    initialDataUpdatedAt,
    meta,
    queryKeyHashFn,
    refetchInterval,
    refetchIntervalInBackground,
    refetchOnMount,
    refetchOnReconnect,
    refetchOnWindowFocus,
    retry,
    retryOnMount,
    retryDelay,
    staleTime,
    throwOnError,
  }),
  () => queryClient,
)

用法示例

以下是一些在 Solid Query 中使用 useQuery 原始值的示例。

基础

useQuery 最基本的使用方式是创建一个从 API 获取数据的查询。

tsx
import { useQuery } from '@tanstack/solid-query'

function App() {
  const todos = useQuery(() => ({
    queryKey: 'todos',
    queryFn: async () => {
      const response = await fetch('/api/todos')
      if (!response.ok) {
        throw new Error('Failed to fetch todos')
      }
      return response.json()
    },
  }))

  return (
    <div>
      <Show when={todos.isError}>
        <div>Error: {todos.error.message}</div>
      </Show>
      <Show when={todos.isLoading}>
        <div>Loading...</div>
      </Show>
      <Show when={todos.isSuccess}>
        <div>
          <div>Todos:</div>
          <ul>
            <For each={todos.data}>{(todo) => <li>{todo.title}</li>}</For>
          </ul>
        </div>
      </Show>
    </div>
  )
}
import { useQuery } from '@tanstack/solid-query'

function App() {
  const todos = useQuery(() => ({
    queryKey: 'todos',
    queryFn: async () => {
      const response = await fetch('/api/todos')
      if (!response.ok) {
        throw new Error('Failed to fetch todos')
      }
      return response.json()
    },
  }))

  return (
    <div>
      <Show when={todos.isError}>
        <div>Error: {todos.error.message}</div>
      </Show>
      <Show when={todos.isLoading}>
        <div>Loading...</div>
      </Show>
      <Show when={todos.isSuccess}>
        <div>
          <div>Todos:</div>
          <ul>
            <For each={todos.data}>{(todo) => <li>{todo.title}</li>}</For>
          </ul>
        </div>
      </Show>
    </div>
  )
}

响应式选项

useQuery 接受一个返回对象的函数是为了允许响应式选项。当查询选项依赖于可能随时间变化的其它值/信号时,这非常有用。Solid Query 可以跟踪在响应式作用域中传递的函数,并在依赖项更改时重新运行它。

tsx
import { useQuery } from '@tanstack/solid-query'

function App() {
  const [filter, setFilter] = createSignal('all')

  const todos = useQuery(() => ({
    queryKey: ['todos', filter()],
    queryFn: async () => {
      const response = await fetch(`/api/todos?filter=${filter()}`)
      if (!response.ok) {
        throw new Error('Failed to fetch todos')
      }
      return response.json()
    },
  }))

  return (
    <div>
      <div>
        <button onClick={() => setFilter('all')}>All</button>
        <button onClick={() => setFilter('active')}>Active</button>
        <button onClick={() => setFilter('completed')}>Completed</button>
      </div>
      <Show when={todos.isError}>
        <div>Error: {todos.error.message}</div>
      </Show>
      <Show when={todos.isLoading}>
        <div>Loading...</div>
      </Show>
      <Show when={todos.isSuccess}>
        <div>
          <div>Todos:</div>
          <ul>
            <For each={todos.data}>{(todo) => <li>{todo.title}</li>}</For>
          </ul>
        </div>
      </Show>
    </div>
  )
}
import { useQuery } from '@tanstack/solid-query'

function App() {
  const [filter, setFilter] = createSignal('all')

  const todos = useQuery(() => ({
    queryKey: ['todos', filter()],
    queryFn: async () => {
      const response = await fetch(`/api/todos?filter=${filter()}`)
      if (!response.ok) {
        throw new Error('Failed to fetch todos')
      }
      return response.json()
    },
  }))

  return (
    <div>
      <div>
        <button onClick={() => setFilter('all')}>All</button>
        <button onClick={() => setFilter('active')}>Active</button>
        <button onClick={() => setFilter('completed')}>Completed</button>
      </div>
      <Show when={todos.isError}>
        <div>Error: {todos.error.message}</div>
      </Show>
      <Show when={todos.isLoading}>
        <div>Loading...</div>
      </Show>
      <Show when={todos.isSuccess}>
        <div>
          <div>Todos:</div>
          <ul>
            <For each={todos.data}>{(todo) => <li>{todo.title}</li>}</For>
          </ul>
        </div>
      </Show>
    </div>
  )
}

Suspense 一起使用

useQuery 支持在查询处于挂起或错误状态时触发 SolidJS 的 SuspenseErrorBoundary 组件。这使您可以轻松地在组件中处理加载和错误状态。

tsx
import { useQuery } from '@tanstack/solid-query'

function App() {
  const todos = useQuery(() => ({
    queryKey: 'todos',
    queryFn: async () => {
      const response = await fetch('/api/todos')
      if (!response.ok) {
        throw new Error('Failed to fetch todos')
      }
      return response.json()
    },
    throwOnError: true,
  }))

  return (
    <ErrorBoundary fallback={<div>Error: {todos.error.message}</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <div>
          <div>Todos:</div>
          <ul>
            <For each={todos.data}>{(todo) => <li>{todo.title}</li>}</For>
          </ul>
        </div>
      </Suspense>
    </ErrorBoundary>
  )
}
import { useQuery } from '@tanstack/solid-query'

function App() {
  const todos = useQuery(() => ({
    queryKey: 'todos',
    queryFn: async () => {
      const response = await fetch('/api/todos')
      if (!response.ok) {
        throw new Error('Failed to fetch todos')
      }
      return response.json()
    },
    throwOnError: true,
  }))

  return (
    <ErrorBoundary fallback={<div>Error: {todos.error.message}</div>}>
      <Suspense fallback={<div>Loading...</div>}>
        <div>
          <div>Todos:</div>
          <ul>
            <For each={todos.data}>{(todo) => <li>{todo.title}</li>}</For>
          </ul>
        </div>
      </Suspense>
    </ErrorBoundary>
  )
}

useQuery 参数

  • 查询选项 - Accessor<QueryOptions>

    • queryKey: unknown[]
      • 必需
      • 用于此查询的查询键。
      • 查询键将被哈希为一个稳定的哈希值。有关更多信息,请参阅 查询键
      • 只要 enabled 未设置为 false,查询将在该键更改时自动更新。
    • queryFn: (context: QueryFunctionContext) => Promise<TData>
      • 必需,但仅在未定义默认查询函数时。有关更多信息,请参阅 默认查询函数
      • 查询将用于请求数据的函数。
      • 接收一个 QueryFunctionContext
      • 必须返回一个解析数据或抛出错误的 Promise。数据不能是 undefined
    • enabled: boolean
      • 将其设置为 false 以禁用此查询的自动运行。
      • 可用于 依赖查询,了解更多信息。
    • select: (data: TData) => unknown
      • Optional (可选)
      • 此选项可用于转换或选择查询函数返回数据的一部分。它会影响返回的 data 值,但不会影响存储在查询缓存中的内容。
      • 仅当 data 更改或 select 函数的引用本身更改时,才会运行 select 函数。为了优化,请将该函数包装在 useCallback 中。
    • placeholderData: TData | (previousValue: TData | undefined; previousQuery: Query | undefined,) => TData
      • Optional (可选)
      • 如果设置,此值将用作此特定查询观察者在查询仍处于 pending 状态期间的占位符数据。
      • placeholderData **不会被持久化**到缓存中。
      • 如果您为 placeholderData 提供了一个函数,作为第一个参数,您将收到之前观察到的查询数据(如果可用),第二个参数将是完整的 previousQuery 实例。
    • deferStream: boolean
      • Optional (可选)
      • 默认为 false
      • 仅在服务器端使用流式传输渲染查询时适用。
      • deferStream 设置为 true,以便在刷新流之前等待查询在服务器上解析。
      • 这有助于避免在查询解析之前将加载状态发送到客户端。
    • reconcile: false | string | ((oldData: TData | undefined, newData: TData) => TData)
      • Optional (可选)
      • 默认为 false
      • 将其设置为字符串以启用基于字符串键的查询结果之间的协调。
      • 将其设置为一个函数,该函数接受旧数据和新数据,并返回相同类型的数据,以实现自定义协调逻辑。
    • gcTime: number | Infinity
      • 默认为 5 * 60 * 1000(5 分钟)或服务器端渲染期间的 Infinity
      • 未使用/不活动的缓存数据在内存中保留的时间(毫秒)。当查询的缓存变得未使用或不活动时,该缓存数据将在该持续时间后被垃圾回收。当指定了不同的垃圾回收时间时,将使用最长的时间。
      • 注意:允许的最大时间约为 24 天,尽管可以使用 timeoutManager.setTimeoutProvider 来规避此限制。
      • 如果设置为 Infinity,将禁用垃圾回收。
    • networkMode: 'online' | 'always' | 'offlineFirst'
      • 可选
      • 默认为 'online'
      • 有关更多信息,请参阅 网络模式
    • initialData: TData | () => TData
      • Optional (可选)
      • 如果设置,此值将用作查询缓存的初始数据(只要查询尚未创建或缓存)。
      • 如果设置为函数,该函数将在共享/根查询初始化期间 **仅调用一次**,并期望同步返回 initialData。
      • 默认情况下,除非设置了 staleTime,否则初始数据将被视为过时。
      • initialData **会被持久化**到缓存中。
    • initialDataUpdatedAt: number | (() => number | undefined)
      • Optional (可选)
      • 如果设置,此值将用作 initialData 本身最后更新时间的时间戳(以毫秒为单位)。
    • meta: Record<string, unknown>
      • Optional (可选)
      • 如果设置,则在查询缓存条目上存储额外信息,以备需要时使用。它将在查询可用的任何地方访问,并且也是提供给 queryFnQueryFunctionContext 的一部分。
    • queryKeyHashFn: (queryKey: QueryKey) => string
      • Optional (可选)
      • 如果指定,此函数将用于将 queryKey 哈希为一个字符串。
    • refetchInterval: number | false | ((query: Query) => number | false | undefined)
      • Optional (可选)
      • 如果设置为一个数字,所有查询将以该频率(以毫秒为单位)连续重新获取。
      • 如果设置为一个函数,该函数将使用查询进行执行,以计算频率。
    • refetchIntervalInBackground: boolean
      • Optional (可选)
      • 如果设置为 true,则设置为连续重新获取的查询(具有 refetchInterval)将在其标签页/窗口处于后台时继续重新获取。
    • refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")
      • Optional (可选)
      • 默认为 true
      • 如果设置为 true,如果数据已过时,则查询将在挂载时重新获取。
      • 如果设置为 false,则查询在挂载时不会重新获取。
      • 如果设置为 "always",则查询将在挂载时始终重新获取。
      • 如果设置为函数,该函数将使用查询进行执行,以计算值。
    • refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")
      • Optional (可选)
      • 默认为 true
      • 如果设置为 true,如果数据已过时,则查询将在窗口聚焦时重新获取。
      • 如果设置为 false,则查询在窗口聚焦时不会重新获取。
      • 如果设置为 "always",则查询将在窗口获得焦点时始终重新获取。
      • 如果设置为函数,该函数将使用查询进行执行,以计算值。
    • refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")
      • Optional (可选)
      • 默认为 true
      • 如果设置为 true,如果数据已过时,则查询将在重新连接时重新获取。
      • 如果设置为 false,则查询在重新连接时不会重新获取。
      • 如果设置为 "always",则查询将在重新连接时始终重新获取。
      • 如果设置为函数,该函数将使用查询进行执行,以计算值。
    • retry: boolean | number | (failureCount: number, error: TError) => boolean
      • 如果设置为 false,失败的查询默认将不会重试。
      • 如果设置为 true,失败的查询将无限重试。
      • 如果设置为 number,例如 3,则失败的查询将重试,直到失败的查询计数达到该数字。
      • 在客户端上默认为 3,在服务器上默认为 0
    • retryOnMount: boolean
      • 如果设置为 false,则在挂载时如果查询包含错误,将不会重试。默认为 true
    • retryDelay: number | (retryAttempt: number, error: TError) => number
      • 此函数接收一个 retryAttempt 整数和实际的错误,并返回在下次尝试之前应用的延迟(以毫秒为单位)。
      • attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) 这样的函数会应用指数退避。
      • attempt => attempt * 1000 这样的函数会应用线性退避。
    • staleTime: number | Infinity
      • Optional (可选)
      • 默认为 0
      • 数据被视为陈旧之前的时间(毫秒)。此值仅适用于其定义的 hook。
      • 如果设置为 Infinity,则数据永远不会被视为陈旧。
    • throwOnError: undefined | boolean | (error: TError, query: Query) => boolean
      • 如果您希望错误在渲染阶段抛出并传播到最近的错误边界,请将其设置为 true
      • 将此设置为 false 以禁用 suspense 将错误抛出到错误边界的默认行为。
      • 如果设置为函数,它将接收错误和查询,并且应返回一个布尔值,指示是否应在错误边界中显示错误(true)或将错误作为状态返回(false)。
  • Query Client - Accessor<QueryClient>

    • Optional (可选)
    • 使用此选项可以使用自定义 QueryClient。否则,将使用最近上下文中的 QueryClient。

useQuery 返回值 - Store<QueryResult<TData, TError>>

useQuery 返回一个具有以下属性的 SolidJS store。

  • status: QueryStatus
    • 将是
      • pending,如果还没有缓存数据并且还没有完成查询尝试。
      • error:如果查询尝试导致错误。相应的 error 属性包含尝试获取时收到的错误。
      • success:如果查询已收到无错误的响应,并准备好显示其数据。查询上的相应 data 属性是来自成功获取的数据,或者如果查询的 enabled 属性设置为 false 且尚未获取,则 data 是在初始化时提供给查询的第一个 initialData
  • isPending: boolean
    • 来自上面 status 变量的派生布尔值,为了方便起见提供。
  • isSuccess: boolean
    • 来自上面 status 变量的派生布尔值,为了方便起见提供。
  • isError: boolean
    • 来自上面 status 变量的派生布尔值,为了方便起见提供。
  • isLoadingError: boolean
    • 如果查询在首次获取时失败,此值为 true
  • isRefetchError: boolean
    • 如果查询在重新获取时失败,此值为 true
  • data: Resource<TData>
    • 默认为 undefined
    • 查询的最后一个成功解析的数据。
    • 重要提示data 属性是 SolidJS 资源。这意味着,如果数据在 <Suspense> 组件下访问,则在数据可用之前会触发 Suspense 边界。
  • dataUpdatedAt: number
    • 查询最近一次将 status 返回为 "success" 的时间戳。
  • error: null | TError
    • 默认为 null
    • 如果抛出了错误,则为查询的错误对象。
  • errorUpdatedAt: number
    • 查询最近一次将 status 返回为 "error" 的时间戳。
  • isStale: boolean
    • 如果缓存中的数据被无效化,或者数据比给定的 staleTime 旧,则为 true
  • isPlaceholderData: boolean
    • 如果显示的数据是占位符数据,此值为 true
  • isFetched: boolean
    • 如果查询已被获取,此值为 true
  • isFetchedAfterMount: boolean
    • 如果查询在组件挂载后已被获取,此值为 true
    • 此属性可用于不显示任何先前缓存的数据。
  • fetchStatus: FetchStatus
    • fetching:每当 `queryFn` 执行时为 true,包括初始 pending 以及后台重新获取。
    • paused:查询需要获取,但已被 paused
    • idle:查询未在获取。
    • 有关更多信息,请参阅 网络模式
  • isFetching: boolean
    • 来自上面 fetchStatus 变量的派生布尔值,为了方便起见提供。
  • isPaused: boolean
    • 来自上面 fetchStatus 变量的派生布尔值,为了方便起见提供。
  • isRefetching: boolean
    • 每当后台重新获取正在进行中时为 true,这包括初始 pending
    • 等同于 isFetching && !isPending
  • isLoading: boolean
    • 当查询的首次获取正在进行中时为 true
    • 等同于 isFetching && isPending
  • isInitialLoading: boolean
    • 已弃用
    • isLoading 的别名,将在下一个主要版本中移除。
  • failureCount: number
    • 查询的失败计数。
    • 每次查询失败时递增。
    • 当查询成功时重置为 0
  • failureReason: null | TError
    • 查询重试的失败原因。
    • 当查询成功时重置为 null
  • errorUpdateCount: number
    • 所有错误的总和。
  • refetch: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise<UseQueryResult>
    • 手动重新获取查询的函数。
    • 如果查询出错,错误只会记录下来。如果您希望抛出错误,请传递 throwOnError: true 选项。
    • cancelRefetch?: boolean
      • 默认为 true
        • 默认情况下,当前正在进行的请求将在新请求之前被取消。
      • 当设置为 false 时,如果已有请求正在进行,则不会进行重新获取。