占位符查询数据 | TanStack Query React 文档

占位符 Query 数据

什么是占位符数据？

占位符数据允许 query 表现得好像它已经有数据了，类似于 initialData 选项，但数据不会持久化到缓存中。这在您有足够的局部（或伪造）数据来成功渲染 query，同时实际数据在后台获取的情况下非常有用。

示例：一个单独的博客文章 query 可以从父级博客文章列表中拉取“预览”数据，该列表仅包含标题和文章正文的小片段。您不希望将此部分数据持久化到单个 query 的 query 结果中，但在实际 query 完成以获取整个对象时，它对于尽快显示内容布局非常有用。

有几种方法可以在需要之前为 query 的缓存提供占位符数据

声明式
- 提供 placeholderData 给 query 以在缓存为空时预填充它
命令式
- 使用 queryClient 和 placeholderData 选项预取或获取数据

当我们使用 placeholderData 时，我们的 Query 将不会处于 pending 状态 - 它将以 success 状态开始，因为我们有 data 要显示 - 即使该数据只是“占位符”数据。为了将其与“真实”数据区分开来，我们还将在 Query 结果上设置 isPlaceholderData 标志为 true。

作为值的占位符数据

tsx

function Todos() {
  const result = useQuery({
    queryKey: ['todos'],
    queryFn: () => fetch('/todos'),
    placeholderData: placeholderTodos,
  })
}

function Todos() {
  const result = useQuery({
    queryKey: ['todos'],
    queryFn: () => fetch('/todos'),
    placeholderData: placeholderTodos,
  })
}

占位符数据记忆化

如果访问 query 的占位符数据的过程是密集的，或者只是您不想在每次渲染时执行的操作，则可以记忆化该值

tsx

function Todos() {
  const placeholderData = useMemo(() => generateFakeTodos(), [])
  const result = useQuery({
    queryKey: ['todos'],
    queryFn: () => fetch('/todos'),
    placeholderData,
  })
}

function Todos() {
  const placeholderData = useMemo(() => generateFakeTodos(), [])
  const result = useQuery({
    queryKey: ['todos'],
    queryFn: () => fetch('/todos'),
    placeholderData,
  })
}

placeholderData 也可以是一个函数，您可以在其中访问“先前”成功 Query 的数据和 Query 元信息。这对于您想要使用一个 query 的数据作为另一个 query 的占位符数据的情况很有用。当 QueryKey 更改时，例如从 ['todos', 1] 更改为 ['todos', 2]，我们可以继续显示“旧”数据，而不是在数据从一个 Query 过渡到下一个 Query 时必须显示加载指示器。有关更多信息，请参阅分页 Queries。

tsx

const result = useQuery({
  queryKey: ['todos', id],
  queryFn: () => fetch(`/todos/${id}`),
  placeholderData: (previousData, previousQuery) => previousData,
})

const result = useQuery({
  queryKey: ['todos', id],
  queryFn: () => fetch(`/todos/${id}`),
  placeholderData: (previousData, previousQuery) => previousData,
})

来自缓存的占位符数据

在某些情况下，您可能能够从另一个 query 的缓存结果中为 query 提供占位符数据。一个很好的例子是从博客文章列表 query 的缓存数据中搜索文章的预览版本，然后将其用作您的单个文章 query 的占位符数据

tsx

function Todo({ blogPostId }) {
  const queryClient = useQueryClient()
  const result = useQuery({
    queryKey: ['blogPost', blogPostId],
    queryFn: () => fetch(`/blogPosts/${blogPostId}`),
    placeholderData: () => {
      // Use the smaller/preview version of the blogPost from the 'blogPosts'
      // query as the placeholder data for this blogPost query
      return queryClient
        .getQueryData(['blogPosts'])
        ?.find((d) => d.id === blogPostId)
    },
  })
}

function Todo({ blogPostId }) {
  const queryClient = useQueryClient()
  const result = useQuery({
    queryKey: ['blogPost', blogPostId],
    queryFn: () => fetch(`/blogPosts/${blogPostId}`),
    placeholderData: () => {
      // Use the smaller/preview version of the blogPost from the 'blogPosts'
      // query as the placeholder data for this blogPost query
      return queryClient
        .getQueryData(['blogPosts'])
        ?.find((d) => d.id === blogPostId)
    },
  })
}

延伸阅读

有关 Placeholder Data 和 Initial Data 之间的比较，请查看社区资源。