# @falcondev-oss/trpc-vue-query 中文文档

规范地址：https://npmcn.com/package/%40falcondev-oss/trpc-vue-query/

版本：0\.7\.0
npm 元数据更新时间：2026-09-22T22:57:00.071Z
中文译文更新时间：2026-11-14T09:23:07.878Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40falcondev-oss/trpc-vue-query
原文对照：https://npmcn.com/package/%40falcondev-oss/trpc-vue-query/?lang=original
源码仓库：https://github.com/falcondev-oss/trpc-vue-query

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：38 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vue ^3\.5\.30，@trpc/client ^11\.13\.4，@trpc/server ^11\.13\.4，@tanstack/vue-query ^5\.102\.0
- 首次发布：2024-03-18T14:35:18.683Z
- 最新版本发布：2026-09-22T22:56:59.694Z
- 近 30 天下载量：3620（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 4 个）

## 中文简介

TRPC 围绕“ @ tanstack/vue- query” 进行包装

## 安装

```sh
npm install @falcondev-oss/trpc-vue-query
```

也可以使用：`pnpm add @falcondev-oss/trpc-vue-query`、`yarn add @falcondev-oss/trpc-vue-query`、`bun add @falcondev-oss/trpc-vue-query`

## README

# tRPC Vue 查询

[![NPM version](https://img.shields.io/npm/v/@falcondev-oss/trpc-vue-query.svg)](https://npmjs.org/package/@falcondev-oss/trpc-vue-query "View this project on NPM")

TRPC的包装纸, 此套件提供了一组用Vue Query来使用tRPC的钩子.

## 安装

```bash
pnpm add @falcondev-oss/trpc-vue-query
```

## 文档

👉 [https://trpc-vue-query.falcondev.io/getting-started 互联网档案馆的存檔,存档日期2014-12-21](https://trpc-vue-query.falcondev.io/getting-started) 👈

## 使用 Vue

### 1\. 创建客户端和可堆肥

```ts
import { createTRPCVueQueryClient } from '@falcondev-oss/trpc-vue-query'
import { VueQueryPlugin, useQueryClient } from '@tanstack/vue-query'

import type { AppRouter } from '../your_server/trpc'

app.use(VueQueryPlugin)
app.use({
  install(app) {
    const queryClient = app.runWithContext(useQueryClient)
    const trpc = createTRPCVueQueryClient<AppRouter>({
      queryClient,
      trpc: {
        links: [
          httpBatchLink({
            url: '/api/trpc',
          }),
        ],
      },
    })

    app.provide('trpc', trpc)
  },
})
```

```ts
import { createTRPCVueQueryClient } from '@falcondev-oss/trpc-vue-query'

import type { AppRouter } from '../your_server/trpc'

export function useTRPC() {
  return inject('trpc') as ReturnType<typeof createTRPCVueQueryClient<AppRouter>>
}
```

### 2\. 在组件中使用

```vue
<script lang="ts" setup>
const { data: greeting } = useTRPC().hello.useQuery({ name: 'World' })
</script>

<template>
  <div>
    <h1>{{ greeting }}</h1>
  </div>
</template>
```

### 3\. 通过排水方案

```vue
<script lang="ts" setup>
const { data: greeting } = useTRPC().hello.useQuery(
  { name: 'World' },
  {
    refetchOnMount: false,
    refetchOnReconnect: false,
    refetchOnWindowFocus: false,
    staleTime: 1000 * 60 * 5,
  },
)
</script>

<template>
  <div>
    <h1>{{ greeting }}</h1>
  </div>
</template>
```

### 4\. 使用 `useMutation` 钩子

```vue
<script lang="ts" setup>
const name = ref('')
const { mutate: updateGreeting } = useTRPC().hello.update.useMutation({
  onSuccess: () => {
    console.log('Greeting updated')
  },
})
</script>

<template>
  <div>
    <input v-model="name" type="text" />
    <button @click="() => updateGreeting({ name })">Update greeting</button>
  </div>
</template>
```

### 5\. 反应参数

输入参数可以是 refs——当它们改变时的查询 refetches.

```vue
<script lang="ts" setup>
const productId = ref(1)
const { data: product } = useTRPC().product.getById.useQuery(productId)
</script>
```

## 帮助者

### `invalidate()`

无效并重排查询 .

```vue
<script lang="ts" setup>
const trpc = useTRPC()
const { mutate: addToCart } = trpc.cart.addProduct.useMutation({
  onSuccess: () => {
    // this will invalidate and refetch the `cart.get` query
    trpc.cart.get.invalidate()
  },
})
</script>
```

### `setQueryData()`

手动更新查询数据.

```vue
<script lang="ts" setup>
const trpc = useTRPC()
const { mutate: addToCart } = trpc.cart.addProduct.useMutation({
  onSuccess: (newCart) => {
    // this will update the `cart.get` query data
    trpc.cart.get.setQueryData(newCart)
  },
})
</script>
```

### `key()`

获取查询密钥 。 使用密钥,您可以访问所有其它的 TanStack 查询功能 .

```vue
<script lang="ts" setup>
const trpc = useTRPC()
const cartKey = trpc.cart.get.key()

const productKey = trpc.product.getById.key(1)

// eg. cancel queries by key:
const queryClient = useQueryClient()
await queryClient.cancelQueries({ queryKey: cartKey })
</script>
```

## 操作背景

每一次请求都是通过可调和的(`useQuery`, (中文(简体) ), `useQueries`, (中文(简体) ), `useInfiniteQuery`, (中文(简体) ), `useMutation`, (中文(简体) ), `queryOptions`) 标记为导出 `vueQueryContext` tRPC 中的符号 [操作环境](https://trpc.io/docs/client/links#managing-context)常规 `query()` 编号 : `mutate()` 电话不是.

该符号被宣布为tRPC的 `OperationContext` 接口,所以 `op.context[vueQueryContext]` 在链接中输入.

链接可以使用它来跳过 vue-query 已经做的处理, 例如, 查询/ 移动缓存中出错的托盘 :

```ts
import { vueQueryContext } from '@falcondev-oss/trpc-vue-query'

const errorToastLink: TRPCLink<AppRouter> =
  () =>
  ({ op, next }) =>
    observable((observer) =>
      next(op).subscribe({
        next: (value) => observer.next(value),
        complete: () => observer.complete(),
        error(err) {
          // vue-query requests are toasted by the query/mutation cache instead
          if (!(vueQueryContext in op.context)) toast.error(err.message)
          observer.error(err)
        },
      }),
    )
```

## 用法为 `trpc-nuxt`

设置 `trpc-nuxt` 说明 [文档](https://trpc-nuxt.vercel.app/get-started/usage/recommended)。然后更新 `plugins/client.ts` 文件 :

```ts
import { createTRPCVueQueryClient } from '@falcondev-oss/trpc-vue-query'
import { useQueryClient } from '@tanstack/vue-query'
import { httpBatchLink } from 'trpc-nuxt/client'

import type { AppRouter } from '~/server/trpc/routers'

export default defineNuxtPlugin(() => {
  const queryClient = useQueryClient()

  // ⬇️ use `createTRPCVueQueryClient` instead of `createTRPCNuxtClient` ⬇️
  const trpc = createTRPCVueQueryClient<AppRouter>({
    queryClient,
    trpc: {
      links: [
        httpBatchLink({
          url: '/api/trpc',
        }),
      ],
    },
  })

  return {
    provide: {
      trpc,
    },
  }
})
```

```ts
export function useTRPC() {
  return useNuxtApp().$trpc
}
```

## 鸣谢

谢谢 [罗伯特·索里亚诺](https://github.com/wobsoriano) 用于创建 `trpc-nuxt`我们刚刚调整了他的工作 与Vue Query合作.

## 常见问题

### @falcondev-oss/trpc-vue-query 是什么？

TRPC 围绕“ @ tanstack/vue- query” 进行包装

### 如何安装 @falcondev-oss/trpc-vue-query？

在项目目录运行 npm install @falcondev-oss/trpc-vue-query，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.5\.30）、@trpc/client（^11\.13\.4）、@trpc/server（^11\.13\.4）、@tanstack/vue-query（^5\.102\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @falcondev-oss/trpc-vue-query 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @falcondev-oss/trpc-vue-query 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @falcondev-oss/trpc-vue-query 可以商用吗？

@falcondev-oss/trpc-vue-query 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @falcondev-oss/trpc-vue-query 的下载量有多少？

根据 npm 官方下载统计，@falcondev-oss/trpc-vue-query 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,620 次，日均约 121 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @falcondev-oss/trpc-vue-query 还在维护吗？

最新版本 0\.7\.0 发布于 2026/09/23（1 个月前）；至今共发布 30 个版本，其中过去 12 个月发布了 4 个；首次发布于 2024/03/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。