pinia-colada-skilld

@pinia/colada 1.4.5

基于 Pinia 构建的 Vue.js 智能数据获取层。查询读取并缓存数据（useQuery），变更写入数据（useMutation），所有内容都存放在 Pinia store 中（useQueryCache、useMutationCache）。

• 文档：https://pinia-colada.esm.dev
• API 类型：准备好的软件包源码中的 dist/index.d.mts
• 运行时导出：dist/index.mjs:1487
• 对等依赖：vue ^3.5.41、pinia ^2.2.6 || ^3.0.0 || ^4.0.2（从 1.4.1 起允许使用 pinia 4，package.json:91-94）
• 捆绑的 codemod：软件包中的 codemods/rules/*.yaml

设置

npm install pinia @pinia/colada

import { createPinia } from 'pinia'
import { PiniaColada } from '@pinia/colada'

const app = createApp(App)
app.use(createPinia())
// install after pinia; the options object is required for correct typing
app.use(PiniaColada, {
  queryOptions: { staleTime: 60_000 },
  plugins: [],
})

全局选项放在 queryOptions / mutationOptions 下（dist/index.d.mts:1601-1618）。

心智模型

• 查询由其 key 标识：一个可序列化为 JSON 的数组（EntryKey，dist/index.d.mts:119）。键具有层级结构：筛选时，{ key: ['todos'] } 也会匹配 ['todos', { filter: 'done' }]。
• status 是数据状态：'pending' | 'success' | 'error'。asyncStatus 是操作状态：'idle' | 'loading'。两者有意分开（https://pinia-colada.esm.dev/guide/queries.md）。
• 默认值：staleTime: 5000、gcTime: 300_000、refetchOnMount、refetchOnWindowFocus、refetchOnReconnect、enabled: true（dist/index.mjs:92-97）。Mutation 的 gcTime 默认值为 60_000（dist/index.d.mts:1379）。

核心模式

基本查询

<script setup lang="ts">
import { useQuery } from '@pinia/colada'

const { state, asyncStatus } = useQuery({
  key: ['todos'],
  query: () => fetch('/api/todos').then(res => res.json()),
})
</script>

<template>
  <div v-if="state.status === 'pending'">Loading...</div>
  <div v-else-if="state.status === 'error'">{{ state.error.message }}</div>
  <ul v-else>
    <li v-for="todo in state.data" :key="todo.id">{{ todo.text }}</li>
  </ul>
</template>

在模板中使用分组的 state 对象进行类型收窄。TypeScript 无法根据 status 收窄分开的 data / error 引用（https://pinia-colada.esm.dev/guide/queries.md）。

响应式键：传入 getter

query 函数读取的所有内容（路由参数、引用）都必须包含在 key 中。将 key 作为 getter 传入，这样依赖发生变化时查询就会重新获取：

const { data } = useQuery({
  key: () => ['contacts', route.params.id as string],
  query: () => fetch(`/api/contacts/${route.params.id}`).then(r => r.json()),
})

使用 enabled 为查询添加条件

当必需参数缺失时，避免发起无效请求（在 store 和全局查询中很常见）：

useQuery({
  key: () => ['decks', route.params.deckId],
  query: () => fetchDeck(route.params.deckId as string),
  enabled: () => 'deckId' in route.params,
})

类型安全的共享选项：defineQueryOptions

export const todoOptions = defineQueryOptions((id: string) => ({
  key: ['todos', id],
  query: () => fetchTodo(id),
}))

// single-function form; the returned key is tagged so queryCache infers TData
const { data } = useQuery(() => todoOptions(route.params.id as string))
const todo = queryCache.getQueryData(todoOptions('1').key) // typed

useQuery 接受选项，或返回选项的 getter（dist/index.d.mts:733）。从 1.0 起，已移除双参数形式 useQuery(options, paramsGetter)；请参阅 references/migration.md。

共享查询状态：defineQuery

将多个组件使用的查询封装起来，让引用只创建一次，就像一个小型 Pinia store。设置函数必须是同步的：

export const useFilteredTodos = defineQuery(() => {
  const search = ref('')
  const query = useQuery({
    key: () => ['todos', { search: search.value }],
    query: () => fetchTodos(search.value),
  })
  return { ...query, search }
})

详情：references/queries.md。

Mutation 与失效处理

const queryCache = useQueryCache()

const { mutate, isLoading } = useMutation({
  mutation: (text: string) => createTodo(text),
  async onSettled() {
    await queryCache.invalidateQueries({ key: ['todos'] })
  },
})

• mutate(vars) 不会拒绝；可在模板和事件处理程序中使用。
• mutateAsync(vars) 返回一个 promise，失败时会拒绝。
• 在选项对象中将 onMutate 放在 mutation 之前，这样其返回的上下文就能在后续钩子中推断出来（dist/index.d.mts:1410-1433）。
• 乐观更新：在 onMutate 中写入缓存；仅当缓存中仍是你的乐观值时，才在 onError 中回滚。完整模式请参阅 references/mutations.md。

查询没有 onSuccess / onError

这是有意为之：一个查询可能有多个监听器。请使用 watch(data, ...)，或通过 PiniaColadaQueryHooksPlugin 使用全局钩子（https://pinia-colada.esm.dev/plugins/official/query-hooks.md）。

1.x 版本关键规则

• useQuery(setup, paramsGetter) 和 useQueryState(setup, paramsGetter) 已在 1.0.0 中移除。请使用随包提供的 codemod 进行迁移： ast-grep scan -r node_modules/@pinia/colada/codemods/rules/migration-0-21-to-1-0.yaml -i src (https://github.com/posva/pinia-colada/blob/main/CHANGELOG.md)。
• useQueryState(key) 读取查询状态，但不发起请求；key 是唯一参数（dist/index.d.mts:920-926）。
• initialData 会将查询状态更改为 success；placeholderData 不会更改缓存（dist/index.d.mts:558-600）。
• 若要手动重置条目的状态，请使用 queryCache.setEntryState(entry, state)；通过 setQueryData() 将数据设为 undefined 不再会重置状态。
• 无限查询数据的结构为 { pages, pageParams }；请使用 setInfiniteQueryData()（在 1.2.0 中添加），而非 setQueryData()，来预填充无限查询条目。
• Devtools 是独立的软件包：@pinia/colada-devtools。
• Nuxt：安装 @pinia/colada-nuxt 模块；它会自动处理 SSR 序列化。

参考资料

• 查询：useQuery API、选项、返回值、useQueryState、defineQuery、defineQueryOptions、键工厂
• 变更：useMutation API、钩子和上下文、乐观更新、defineMutation、defineMutationOptions
• 无限查询：useInfiniteQuery、defineInfiniteQueryOptions、setInfiniteQueryData、maxPages
• 查询缓存：缓存存储、失效、筛选器、手动缓存写入、错误代码
• 插件：插件 API、PiniaColadaQueryHooksPlugin、TypesConfig 扩展、官方插件软件包
• SSR：序列化和水合、惰性查询、PiniaColadaSSRNoGc
• 迁移：0.x 到 1.x 的变更和 codemod