useFirestore

类别

@Firebase

导出体积

661 B

依赖包

@vueuse/firebase

上次更改

7 minutes ago

响应式的 Firestore 绑定。使得始终将本地数据与远程数据库同步变得简单直观。 Available in the @vueuse/firebase add-on.

用法

import { useFirestore } from '@vueuse/firebase/useFirestore'
import { initializeApp } from 'firebase/app'
import { collection, doc, getFirestore, limit, orderBy, query } from 'firebase/firestore'
import { computed, shallowRef } from 'vue'

const app = initializeApp({ projectId: 'MY PROJECT ID' })
const db = getFirestore(app)

const todos = useFirestore(collection(db, 'todos'))

// 或者用于文档引用
const user = useFirestore(doc(db, 'users', 'my-user-id'))

// 你还可以使用 ref 值来创建响应式查询
const postsLimit = shallowRef(10)
const postsQuery = computed(() => query(collection(db, 'posts'), orderBy('createdAt', 'desc'), limit(postsLimit.value)))
const posts = useFirestore(postsQuery)

// 你可以使用布尔值告诉查询何时准备好运行
// 当它获取到假值时，返回初始值
const userId = shallowRef('')
const userQuery = computed(() => userId.value && doc(db, 'users', userId.value))
const userData = useFirestore(userQuery, null)

返回值

• 对于 文档引用（Document Reference）：返回 Ref<T | null>（单个带有 id 属性的文档）
• 对于 查询（Query）：返回 Ref<T[]>（文档数组，每个文档都有 id 属性）

文档的 id 会自动作为只读属性添加到每个返回的文档中。

选项

选项	类型	默认值	说明
errorHandler	(err: Error) => void	console.error	自定义错误处理函数
autoDispose	boolean | number	true	在作用域销毁时自动取消订阅。传入数字可延迟指定毫秒数后释放。

错误处理

const todos = useFirestore(collection(db, 'todos'), [], {
  errorHandler: (err) => {
    console.error('Firestore 错误:', err)
    // 处理错误（例如显示通知）
  },
})

在实例之间共享

你可以通过传递 autoDispose: false 来重用 db 引用。你还可以设置自动释放 db 引用之前的毫秒数。

注意：再次获取未释放的 db 引用不会产生 Firestore 读取成本。

const todos = useFirestore(collection(db, 'todos'), undefined, { autoDispose: false })

或者使用核心包中的 createGlobalState

// store.ts
import { createGlobalState } from '@vueuse/core'
import { useFirestore } from '@vueuse/firebase/useFirestore'

export const useTodos = createGlobalState(
  () => useFirestore(collection(db, 'todos')),
)

<!-- app.vue -->
<script setup lang="ts">
import { useTodos } from './store'

const todos = useTodos()
</script>

类型声明

export interface UseFirestoreOptions {
  errorHandler?: (err: Error) => void
  autoDispose?: boolean | number
}
export type FirebaseDocRef<T> = Query<T> | DocumentReference<T>
type Falsy = false | 0 | "" | null | undefined
export declare function useFirestore<T extends DocumentData>(
  maybeDocRef: MaybeRef<DocumentReference<T> | Falsy>,
  initialValue: T,
  options?: UseFirestoreOptions,
): Ref<T | null>
export declare function useFirestore<T extends DocumentData>(
  maybeDocRef: MaybeRef<Query<T> | Falsy>,
  initialValue: T[],
  options?: UseFirestoreOptions,
): Ref<T[]>
export declare function useFirestore<T extends DocumentData>(
  maybeDocRef: MaybeRef<DocumentReference<T> | Falsy>,
  initialValue?: T | undefined | null,
  options?: UseFirestoreOptions,
): Ref<T | undefined | null>
export declare function useFirestore<T extends DocumentData>(
  maybeDocRef: MaybeRef<Query<T> | Falsy>,
  initialValue?: T[],
  options?: UseFirestoreOptions,
): Ref<T[] | undefined>

源码

源码 • 文档

贡献者

一纸忘忧

更新日志

没有最近的更新日志