TanStackQuery v5
自动
框架
版本
菜单
开始使用
API 参考
ESLint
示例

createQuery

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,
} = createQuery(
  () => ({
    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,
} = createQuery(
  () => ({
    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 中使用 createQuery 原始方法的一些示例。

基础

createQuery 最基本的用法是创建一个从 API 获取数据的 query。

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

function App() {
  const todos = createQuery(() => ({
    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 { createQuery } from '@tanstack/solid-query'

function App() {
  const todos = createQuery(() => ({
    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>
  )
}

响应式选项

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

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

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

  const todos = createQuery(() => ({
    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 { createQuery } from '@tanstack/solid-query'

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

  const todos = createQuery(() => ({
    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 一起使用

当 query 处于 pending 或 error 状态时，createQuery 支持触发 SolidJS Suspense 和 ErrorBoundary 组件。这允许您轻松处理组件中的加载和错误状态。

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

function App() {
  const todos = createQuery(() => ({
    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 { createQuery } from '@tanstack/solid-query'

function App() {
  const todos = createQuery(() => ({
    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>
  )
}

createQuery 参数

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

  • Query Client - Accessor<QueryClient>
    • 可选
    • 使用此项可使用自定义 QueryClient。否则，将使用来自最近上下文的 QueryClient。

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

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

  • status: QueryStatus
    • 将会是
      • 如果没有任何缓存数据且尚未完成任何 query 尝试，则为 pending。
      • 如果 query 尝试导致错误，则为 error。相应的 error 属性具有从尝试的 fetch 收到的错误。
      • 如果 query 已收到没有错误的响应并且已准备好显示其数据，则为 success。query 上的相应 data 属性是从成功 fetch 收到的数据，或者如果 query 的 enabled 属性设置为 false 并且尚未 fetch，则 data 是在初始化时提供给 query 的第一个 initialData。
  • isPending: boolean
    • 从上面的 status 变量派生的布尔值，为方便起见而提供。
  • isSuccess: boolean
    • 从上面的 status 变量派生的布尔值，为方便起见而提供。
  • isError: boolean
    • 从上面的 status 变量派生的布尔值，为方便起见而提供。
  • isLoadingError: boolean
    • 如果 query 在首次 fetch 时失败，则为 true。
  • isRefetchError: boolean
    • 如果 query 在 refetch 时失败，则为 true。
  • data: Resource<TData>
    • 默认为 undefined。
    • query 上次成功 resolve 的数据。
    • 重要提示：data 属性是一个 SolidJS resource。这意味着如果数据在 <Suspense> 组件下访问，如果数据尚不可用，它将触发 Suspense 边界。
  • dataUpdatedAt: number
    • query 最近一次将 status 作为 "success" 返回的时间戳。
  • error: null | TError
    • 默认为 null
    • query 的错误对象（如果抛出错误）。
  • errorUpdatedAt: number
    • query 最近一次将 status 作为 "error" 返回的时间戳。
  • isStale: boolean
    • 如果缓存中的数据无效或数据比给定的 staleTime 旧，则为 true。
  • isPlaceholderData: boolean
    • 如果显示的数据是占位符数据，则为 true。
  • isFetched: boolean
    • 如果 query 已被 fetch，则为 true。
  • isFetchedAfterMount: boolean
    • 如果 query 在组件挂载后已被 fetch，则为 true。
    • 此属性可用于不显示任何先前缓存的数据。
  • fetchStatus: FetchStatus
    • fetching：只要 queryFn 正在执行，则为 true，其中包括初始 pending 以及后台 refetch。
    • paused：query 想要 fetch，但已 paused。
    • idle：query 未 fetch。
    • 有关更多信息，请参阅 网络模式。
  • isFetching: boolean
    • 从上面的 fetchStatus 变量派生的布尔值，为方便起见而提供。
  • isPaused: boolean
    • 从上面的 fetchStatus 变量派生的布尔值，为方便起见而提供。
  • isRefetching: boolean
    • 只要后台 refetch 正在进行中，则为 true，这不包括初始 pending
    • 与 isFetching && !isPending 相同
  • isLoading: boolean
    • 只要 query 的首次 fetch 正在进行中，则为 true
    • 与 isFetching && isPending 相同
  • isInitialLoading: boolean
    • 已弃用
    • 是 isLoading 的别名，将在下一个主要版本中删除。
  • failureCount: number
    • query 的失败计数。
    • 每次 query 失败时递增。
    • 当 query 成功时重置为 0。
  • failureReason: null | TError
    • query 重试的失败原因。
    • 当 query 成功时重置为 null。
  • errorUpdateCount: number
    • 所有错误的总和。
  • refetch: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise<UseQueryResult>
    • 手动 refetch query 的函数。
    • 如果 query 发生错误，则只会记录错误。如果您希望抛出错误，请传递 throwOnError: true 选项
    • cancelRefetch?: boolean
      • 默认为 true
        • 默认情况下，在发出新请求之前，将取消当前正在运行的请求。
      • 当设置为 false 时，如果已有一个请求正在运行，则不会进行 refetch。
在 GitHub 上编辑
notifyManager
ESLint Plugin Query
想跳过文档吗？
Query.gg - The Official React Query Course - TanStack 中文
“如果您真的想*真正*理解 React Query，那么没有比 query.gg 更好的方法了”—Tanner Linsley