# @capacitor-firebase/firestore 中文文档

规范地址：https://npmcn.com/package/%40capacitor-firebase/firestore/

版本：8\.6\.0
npm 元数据更新时间：2026-10-31T07:04:49.192Z
中文译文更新时间：2026-11-09T04:33:14.688Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40capacitor-firebase/firestore
原文对照：https://npmcn.com/package/%40capacitor-firebase/firestore/?lang=original
项目主页：https://capawesome.io/
源码仓库：https://github.com/capawesome-team/capacitor-firebase

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

- 包体积（解压后）：605 kB，114 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：firebase ^12\.6\.0，@capacitor/core \>=8\.0\.0
- 首次发布：2023-09-27T08:25:52.941Z
- 最新版本发布：2026-10-31T07:04:48.864Z
- 近 30 天下载量：18043（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 13 个）

## 中文简介

在Android,iOS,和Web上为Firebase Cloud Firestore提供电容插件.

## 安装

```sh
npm install @capacitor-firebase/firestore
```

也可以使用：`pnpm add @capacitor-firebase/firestore`、`yarn add @capacitor-firebase/firestore`、`bun add @capacitor-firebase/firestore`

## README

# 电源火库云火炉插件

非官方电容插件 [火地云炉](https://firebase.google.com/docs/firestore/)\[^1\]

[![Ship a fix in one command with Capawesome Cloud Live Updates, no store review](https://capawesome.io/assets/banners/cloud-ship-a-fix-in-one-command.png)](https://capawesome.io/)

## 使用大小写

Cloud Firestore插件通常用于存储并同步云中的应用数据,例如:

-   **实时更新**:通过收听文档和带快照收听器的收取更改来更新您的用户界面.
-   **用户生成的内容**: 创建,读取,更新并删除用户配置文件,帖子或其他应用数据的文档.
-   **复杂查询**: 带有复合过滤器和查询限制的过滤和排序集合,例如 `where`, (中文(简体) ), `orderBy`,以及 `limit`。 。 。 .
-   **离线支持**: 启用离线持久性并控制网络访问,以配合本地缓存数据.
-   **原子写**: 以单个原子批次执行多个写入操作 `writeBatch(...)`。 。 。 .

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 8.x.x (英语) | \>=8.x.x | 积极支持 |
| 7.x.x (中文(简体) ) | 7.x.x (中文(简体) ) | 折旧 |
| 6.x.x (中文(简体) ) | 6.x.x (中文(简体) ) | 折旧 |

## 指南

-   [宣布控制器火库云火炉插件](https://capawesome.io/blog/announcing-the-capacitor-firebase-cloud-firestore-plugin/)
-   [控制器 Firestore:实时数据和离线同步](https://capawesome.io/blog/capacitor-firebase-cloud-firestore-guide/):实时收听者,离线持续,原子用这个插件写作.
-   [如何用电容和火把包扎角相机](https://capawesome.io/blog/how-to-wrap-an-angular-app-with-capacitor-and-firebase/): 使用此插件与 Cloud 存储一起存储并同步用户数据 .
-   [如何在电容App中使用火把](https://capawesome.io/blog/how-to-use-firebase-in-a-capacitor-app/):数据库如何在真实的应用中与认证,存储,以及其他家庭结合.

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/firestore` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capacitor-firebase/firestore
npx cap sync
```

如果您还没有将 Firebase 添加到您的项目中([机器人](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) 编号 : [iOS系统](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) 编号 : [网页](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)) (中文(简体) ).

### 机器人

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要更改依赖的默认版本的文件 :

-   `$firebaseFirestoreVersion` 版本 `com.google.firebase:firebase-firestore` (默认 : `26.0.2`(中文(简体) )

如果您在工程中遇到其它插件的依赖性冲突, 这会有所帮助 .

### iOS系统

#### Swift 软件包管理器

在您的 `capacitor.config.json` (或 `capacitor.config.ts`) 避免 [SwiftPM 软件包识别相撞](https://github.com/capawesome-team/capacitor-firebase/issues/959)数字 :

```json
{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/firestore": {
            "symlink": true
          }
        }
      }
    }
  }
}
```

**请注意**目标 `packageOptions` 支持需要控制器 CLI **8.4.0+ (中文(简体) )**。 。 。 .

## 配置

这些配置值是可用的 :

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`databaseId`** | `string` | 要使用的 Firestore 数据库的数据库 ID 。 仅供Android和iOS使用. | 8.2.0 (中文(简体) ) |

### 实例

单位 `capacitor.config.json`数字 :

```json
{
  "plugins": {
    "FirebaseFirestore": {
      "databaseId": undefined
    }
  }
}
```

单位 `capacitor.config.ts`数字 :

```ts
/// <reference types="@capacitor-firebase/firestore" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseFirestore: {
      databaseId: undefined,
    },
  },
};

export default config;
```

## 演示

这里有一个实例: [robingenz/电容器-火力基地-插座-demo](https://github.com/robingenz/capacitor-firebase-plugin-demo)

## 启动模板

以下启动模板可供使用:

-   [角起火点](https://ionstarter.dev/)

## 使用量

以下例子显示如何创建,读取,更新并删除文档,更新带有字段值的文档,执行分批写作,查询集合,控制网络访问,使用Firebase模拟器,并聆听并删除实时更新.

### 创建文档

将新文档添加到自动生成的ID的收藏中,或者在已知的参考文献中写入文档 `setDocument(...)`设置 `merge` 改为 `true` 将数据与现有文档合并:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const addDocument = async () => {
  await FirebaseFirestore.addDocument({
    reference: 'users',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
};

const setDocument = async () => {
  await FirebaseFirestore.setDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
    merge: true,
  });
};
```

### 读取文档

阅读一份文件时参考:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getDocument = async () => {
  const { snapshot } = await FirebaseFirestore.getDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
  return snapshot;
};
```

### 更新或删除文档

更新现有文档的字段或全部删除:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const updateDocument = async () => {
  await FirebaseFirestore.updateDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
};

const deleteDocument = async () => {
  await FirebaseFirestore.deleteDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
};
```

### 用字段值更新文档

使用 `FieldValue` 帮助增加数字、设置服务器时间戳、修改数组或删除字段:

```typescript
import { FieldValue, FirebaseFirestore } from '@capacitor-firebase/firestore';

const updateDocumentWithFieldValue = async () => {
  await FirebaseFirestore.updateDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: {
      born: FieldValue.increment(1),
      updatedAt: FieldValue.serverTimestamp(),
      nicknames: FieldValue.arrayUnion('Prof'),
      tags: FieldValue.arrayRemove('draft'),
      deprecatedField: FieldValue.delete(),
    },
  });
};
```

### 执行批次写入

执行多集,更新,并删除单个原子批的操作 :

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const writeBatch = async () => {
  await FirebaseFirestore.writeBatch({
    operations: [
      {
        type: 'set',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
        options: { merge: true },
      },
      {
        type: 'update',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
      },
      {
        type: 'delete',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
      },
    ],
  });
};
```

### 查询收藏

从收藏组或收藏组读取多份文件。 您可以使用复合过滤器过滤结果, 并应用查询限制, 如 `orderBy` 财务报告和审定财务报表 `limit`数字 :

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getCollection = async () => {
  const { snapshots } = await FirebaseFirestore.getCollection({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};

const getCollectionGroup = async () => {
  const { snapshots } = await FirebaseFirestore.getCollectionGroup({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};
```

### 控制网络访问

禁用并重新启用网络的使用, 例如强制插件与本地缓存数据合作 :

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const enableNetwork = async () => {
  await FirebaseFirestore.enableNetwork();
};

const disableNetwork = async () => {
  await FirebaseFirestore.disableNetwork();
};
```

### 使用火地模拟器

将插件连接到本地端 [火地模拟器](https://firebase.google.com/docs/emulator-suite) 开发过程中的实例:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const useEmulator = async () => {
  await FirebaseFirestore.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};
```

### 听取实时更新

将快照收听器附加到文档、集合或集合组,以便在数据发生变化时得到通知:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const addDocumentSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addDocumentSnapshotListener(
    {
      reference: 'users/Aorq09lkt1ynbR7xhTUx',
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionGroupSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionGroupSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};
```

### 删除听众

使用其调回ID删除单个快照收听者, 或者立即删除所有收听者 :

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const removeSnapshotListener = async (callbackId: string) => {
  await FirebaseFirestore.removeSnapshotListener({
    callbackId,
  });
};

const removeAllListeners = async () => {
  await FirebaseFirestore.removeAllListeners();
};
```

## API 密码

-   [`addDocument(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-adddocument)
-   [`addCollectionGroupSnapshotListener(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-addcollectiongroupsnapshotlistener)
-   [`addCollectionSnapshotListener(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-addcollectionsnapshotlistener)
-   [`addDocumentSnapshotListener(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-adddocumentsnapshotlistener)
-   [`clearPersistence()`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-clearpersistence)
-   [`deleteDocument(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-deletedocument)
-   [`disableNetwork()`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-disablenetwork)
-   [`disablePersistence()`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-disablepersistence)
-   [`enablePersistence(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-enablepersistence)
-   [`enableNetwork()`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-enablenetwork)
-   [`getCollection(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcollection)
-   [`getCollectionGroup(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcollectiongroup)
-   [`getCountFromServer(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcountfromserver)
-   [`getDocument(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getdocument)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-removealllisteners)
-   [`removeSnapshotListener(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-removesnapshotlistener)
-   [`setDocument(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-setdocument)
-   [`updateDocument(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-updatedocument)
-   [`useEmulator(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-useemulator)
-   [`writeBatch(...)`](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-writebatch)
-   [接口](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-type-aliases)

### 添加文档(...)

```typescript
addDocument(options: AddDocumentOptions) => Promise<AddDocumentResult>
```

将新文档添加到带给定数据的收藏中.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[AddDocumentOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-adddocumentoptions)` |

**回返情况:** `Promise<[AddDocumentResult](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-adddocumentresult)>`

**自:** 5.2.0 (中文(简体) )

* * *

### 添加 Collection GroupSnapshot 倾听器(...)

```typescript
addCollectionGroupSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionGroupSnapshotListenerOptions, callback: AddCollectionGroupSnapshotListenerCallback<T>) => Promise<CallbackId>
```

添加收集组快照事件的听众 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[AddCollectionGroupSnapshotListenerOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-addcollectiongroupsnapshotlisteneroptions)` |
| **`callback`** | `[AddCollectionGroupSnapshotListenerCallback](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-addcollectiongroupsnapshotlistenercallback)<T>` |

**回返情况:** `Promise<string>`

**自:** 6.1.0 (中文(简体) )

* * *

### 添加 CollectionSnapshot 倾听器(...)

```typescript
addCollectionSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionSnapshotListenerOptions, callback: AddCollectionSnapshotListenerCallback<T>) => Promise<CallbackId>
```

为收集快照事件添加一个听众 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[AddCollectionSnapshotListenerOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-addcollectionsnapshotlisteneroptions)` |
| **`callback`** | `[AddCollectionSnapshotListenerCallback](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-addcollectionsnapshotlistenercallback)<T>` |

**回返情况:** `Promise<string>`

**自:** 5.2.0 (中文(简体) )

* * *

### 添加 DocumentSnapshot 倾听器(...)

```typescript
addDocumentSnapshotListener<T extends DocumentData = DocumentData>(options: AddDocumentSnapshotListenerOptions, callback: AddDocumentSnapshotListenerCallback<T>) => Promise<CallbackId>
```

为文档快照事件添加一个收听器.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[AddDocumentSnapshotListenerOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-adddocumentsnapshotlisteneroptions)` |
| **`callback`** | `[AddDocumentSnapshotListenerCallback](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-adddocumentsnapshotlistenercallback)<T>` |

**回返情况:** `Promise<string>`

**自:** 5.2.0 (中文(简体) )

* * *

### 持续时间( )

```typescript
clearPersistence() => Promise<void>
```

清除持续存储。 这包括待写和缓存文件.

**请注意**: 必须在应用程序关闭后或应用程序被初始化后调用 .

**自:** 5.2.0 (中文(简体) )

* * *

### 删除文档(...)

```typescript
deleteDocument(options: DeleteDocumentOptions) => Promise<void>
```

删除指定引用提及的文档.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[DeleteDocumentOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-deletedocumentoptions)` |

**自:** 5.2.0 (中文(简体) )

* * *

### 禁用网络

```typescript
disableNetwork() => Promise<void>
```

禁用网络 .

**自:** 5.2.0 (中文(简体) )

* * *

### 禁用持久性( C)

```typescript
disablePersistence() => Promise<void>
```

禁用离线持久性 .

**请注意**: 必须在任何其他 Firestore 方法之前调用.

**自:** 8.2.0 (中文(简体) )

* * *

### 启用持久性(...)

```typescript
enablePersistence(options?: EnablePersistenceOptions | undefined) => Promise<void>
```

启用离线持久性 .

**请注意**: 必须在任何其他 Firestore 方法之前调用.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[EnablePersistenceOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-enablepersistenceoptions)` |

**自:** 8.2.0 (中文(简体) )

* * *

### 启用网络

```typescript
enableNetwork() => Promise<void>
```

复能用通网相会.

**自:** 5.2.0 (中文(简体) )

* * *

### 获取收集(...)

```typescript
getCollection<T extends DocumentData = DocumentData>(options: GetCollectionOptions) => Promise<GetCollectionResult<T>>
```

读取指定引用的集合.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetCollectionOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcollectionoptions)` |

**回返情况:** `Promise<[GetCollectionResult](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcollectionresult)<T>>`

**自:** 5.2.0 (中文(简体) )

* * *

### 获取收集组(...)

```typescript
getCollectionGroup<T extends DocumentData = DocumentData>(options: GetCollectionGroupOptions) => Promise<GetCollectionGroupResult<T>>
```

读取指定引用的收藏组.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetCollectionGroupOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcollectiongroupoptions)` |

**回返情况:** `Promise<[GetCollectionGroupResult](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcollectiongroupresult)<T>>`

* * *

### 获取 Count from Server (...)

```typescript
getCountFromServer(options: GetCountFromServerOptions) => Promise<GetCountFromServerResult>
```

获取收藏中的文档数量.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetCountFromServerOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcountfromserveroptions)` |

**回返情况:** `Promise<[GetCountFromServerResult](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcountfromserverresult)>`

**自:** 6.4.0 (单位:千美元)

* * *

### 获取文档(...)

```typescript
getDocument<T extends DocumentData = DocumentData>(options: GetDocumentOptions) => Promise<GetDocumentResult<T>>
```

读取指定引用提及的文档.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[GetDocumentOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getdocumentoptions)` |

**回返情况:** `Promise<[GetDocumentResult](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getdocumentresult)<T>>`

**自:** 5.2.0 (中文(简体) )

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

**自:** 5.2.0 (中文(简体) )

* * *

### 删除 Snapshot 听取器(...)

```typescript
removeSnapshotListener(options: RemoveSnapshotListenerOptions) => Promise<void>
```

删除文档或收藏快照事件的收听器 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[RemoveSnapshotListenerOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-removesnapshotlisteneroptions)` |

**自:** 5.2.0 (中文(简体) )

* * *

### 设置文档(...)

```typescript
setDocument(options: SetDocumentOptions) => Promise<void>
```

写入指定引用所引用的文档. 如果文档尚未存在,则会创建.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SetDocumentOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-setdocumentoptions)` |

**自:** 5.2.0 (中文(简体) )

* * *

### 更新文档(...)

```typescript
updateDocument(options: UpdateDocumentOptions) => Promise<void>
```

更新指定引用所提及文档中的字段.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[UpdateDocumentOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-updatedocumentoptions)` |

**自:** 5.2.0 (中文(简体) )

* * *

### 使用计算器(...)

```typescript
useEmulator(options: UseEmulatorOptions) => Promise<void>
```

给Firestore模拟器提供你的应用程序.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[UseEmulatorOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-useemulatoroptions)` |

**自:** 6.1.0 (中文(简体) )

* * *

### 写入批次(...)

```typescript
writeBatch(options: WriteBatchOptions) => Promise<void>
```

执行多个写入操作作为单批.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[WriteBatchOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-writebatchoptions)` |

**自:** 6.1.0 (中文(简体) )

* * *

### 接口

#### 添加文档结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `DocumentReference` | 新增加的文件的参考文献. | 5.2.0 (中文(简体) ) |

#### 添加文档选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 5.2.0 (中文(简体) ) |
| **`data`** | `[DocumentData](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-documentdata)` | 含有新文档数据的对象. | 5.2.0 (中文(简体) ) |

#### 文档数据

#### 添加 Collection GroupSnapshot 听取选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 6.1.0 (中文(简体) ) |
| **`compositeFilter`** | `[QueryCompositeFilterConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-querycompositefilterconstraint)` | 要应用的过滤器 . | 6.1.0 (中文(简体) ) |
| **`queryConstraints`** | `QueryNonFilterConstraint[]` | 缩小或命令要取回的一组文档,但不明确过滤文档字段. | 6.1.0 (中文(简体) ) |

#### 查询复合纤维约束

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `'and' | 'or'` | 制约之类. | 5.2.0 (中文(简体) ) |
| **`queryConstraints`** | `QueryFilterConstraint[]` | 要应用的过滤器 . | 5.2.0 (中文(简体) ) |

#### 查询 Felter 约束

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `'where'` | 制约之类. | 5.2.0 (中文(简体) ) |
| **`fieldPath`** | `string` | 比较之道. | 5.2.0 (中文(简体) ) |
| **`opStr`** | `[QueryOperator](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-queryoperator)` | 要应用的操作字符串 . | 5.2.0 (中文(简体) ) |
| **`value`** | `any` | 比较值. | 5.2.0 (中文(简体) ) |

#### 查询命令By 约束

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `'orderBy'` | 制约之类. | 5.2.0 (中文(简体) ) |
| **`fieldPath`** | `string` | 比较之道. | 5.2.0 (中文(简体) ) |
| **`directionStr`** | `[OrderByDirection](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-orderbydirection)` | 排序的方向. | 5.2.0 (中文(简体) ) |

#### 查询Limit 约束

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `'limit' | 'limitToLast'` | 制约之类. | 5.2.0 (中文(简体) ) |
| **`limit`** | `number` | 返回的最大项数 . | 5.2.0 (中文(简体) ) |

#### 查询开始控制

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `'startAt' | 'startAfter'` | 制约之类. | 5.2.0 (中文(简体) ) |
| **`reference`** | `string` | 以字符串开头的引用,路径组件由前斜线分隔(`/`) (中文(简体) ). **请注意**: 这需要额外的文档读取. | 5.2.0 (中文(简体) ) |

#### 查询控制

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `'endAt' | 'endBefore'` | 制约之类. | 5.2.0 (中文(简体) ) |
| **`reference`** | `string` | 以字符串结尾或前面的引用,路径组件由前斜线分隔(`/`) (中文(简体) ). **请注意**: 这需要额外的文档读取. | 5.2.0 (中文(简体) ) |

#### 获取收集组结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`snapshots`** | `[DocumentSnapshot](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-documentsnapshot)<T>[]` | 收藏中的文档. | 5.2.0 (中文(简体) ) |

#### 文档抓取

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`id`** | `string` | 文档的标识符在其收藏中. | 5.2.0 (中文(简体) ) |
| **`path`** | `string` | 文档的路径 . | 5.2.0 (中文(简体) ) |
| **`data`** | `T | null` | 包含文档数据的对象。 回返 `null` 如果文档不存在. | 5.2.0 (中文(简体) ) |
| **`metadata`** | `[SnapshotMetadata](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-snapshotmetadata)` | 关于快照的元数据,关于快照的来源,如果有局部修改的话. | 6.2.0 (单位:千美元) |

#### 快照元数据

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`fromCache`** | `boolean` | 如果快照是从缓存数据创建的, 则为真 . | 6.2.0 (单位:千美元) |
| **`hasPendingWrites`** | `boolean` | 如果快照是从待定的写入数据创建的, 则为真 . | 6.2.0 (单位:千美元) |

#### 添加收听器选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 5.2.0 (中文(简体) ) |
| **`compositeFilter`** | `[QueryCompositeFilterConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-querycompositefilterconstraint)` | 要应用的过滤器 . | 5.2.0 (中文(简体) ) |
| **`queryConstraints`** | `QueryNonFilterConstraint[]` | 缩小或命令要取回的一组文档,但不明确过滤文档字段. | 5.2.0 (中文(简体) ) |

#### 获取收集结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`snapshots`** | `[DocumentSnapshot](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-documentsnapshot)<T>[]` | 收藏中的文档. | 5.2.0 (中文(简体) ) |

#### 添加文档截图听器选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 5.2.0 (中文(简体) ) |

#### 获取文档结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`snapshot`** | `[DocumentSnapshot](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-documentsnapshot)<T>` | 当前文档内容 . | 5.2.0 (中文(简体) ) |

#### 删除文档选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 5.2.0 (中文(简体) ) |

#### 启用持久性选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`cacheSizeBytes`** | `number` | 以字节表示的缓存大小 . | `104857600 (100 MB)` | 8.2.0 (中文(简体) ) |
| **`synchronizeTabs`** | `boolean` | 是否在多个标签中同步持久性 。 仅供Web使用. | `false` | 8.2.0 (中文(简体) ) |

#### 获取收集选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 5.2.0 (中文(简体) ) |
| **`compositeFilter`** | `[QueryCompositeFilterConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-querycompositefilterconstraint)` | 要应用的过滤器 . | 5.2.0 (中文(简体) ) |
| **`queryConstraints`** | `QueryNonFilterConstraint[]` | 缩小或命令要取回的一组文档,但不明确过滤文档字段. | 5.2.0 (中文(简体) ) |

#### 获取收集组选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 5.2.0 (中文(简体) ) |
| **`compositeFilter`** | `[QueryCompositeFilterConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-querycompositefilterconstraint)` | 要应用的过滤器 . | 5.2.0 (中文(简体) ) |
| **`queryConstraints`** | `QueryNonFilterConstraint[]` | 缩小或命令要取回的一组文档,但不明确过滤文档字段. | 5.2.0 (中文(简体) ) |

#### 从服务员那里获取数据

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`count`** | `number` | 所收文件数. | 6.4.0 (单位:千美元) |

#### 从服务选项中获取查询

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 6.4.0 (单位:千美元) |
| **`compositeFilter`** | `[QueryCompositeFilterConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-querycompositefilterconstraint)` | 要应用的过滤器 . | 8.3.0 (单位:千美元) |
| **`queryConstraints`** | `QueryNonFilterConstraint[]` | 缩小或命令要计数的一组文档,但不明确过滤文档字段. | 8.3.0 (单位:千美元) |

#### 获取文档选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 5.2.0 (中文(简体) ) |

#### 删除Snapshot 听筒选项

| Prop | 类型 | 自兹 |
| --- | --- | --- |
| **`callbackId`** | `[CallbackId](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-callbackid)` | 5.2.0 (中文(简体) ) |

#### 设置文档选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). |  | 5.2.0 (中文(简体) ) |
| **`data`** | `[DocumentData](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-documentdata)` | 含有新文档数据的对象. |  | 5.2.0 (中文(简体) ) |
| **`merge`** | `boolean` | 是否将所提供的数据与现有文档合并 . | `false` | 5.2.0 (中文(简体) ) |

#### 更新文档选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 5.2.0 (中文(简体) ) |
| **`data`** | `[DocumentData](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-documentdata)` | 含有新文档数据的对象. | 5.2.0 (中文(简体) ) |

#### 使用编辑器选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`host`** | `string` | 模拟器主机没有任何端口或方案. 使用Android模拟器设备时注意: 10.0.2.2是连接主机计算机"localhost"的特殊IP地址. |  | 6.1.0 (中文(简体) ) |
| **`port`** | `number` | 模拟器端口 . | `8080` | 6.1.0 (中文(简体) ) |

#### 写入批次选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`operations`** | `WriteBatchOperation[]` | 批量执行的操作. | 6.1.0 (中文(简体) ) |

#### 写批操作

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `'set' | 'update' | 'delete'` | 手术类型. | 6.1.0 (中文(简体) ) |
| **`reference`** | `string` | 引用为字符串,路径组件由前斜线分隔(`/`) (中文(简体) ). | 6.1.0 (中文(简体) ) |
| **`data`** | `[DocumentData](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-documentdata)` | 含有新文档数据的对象. | 6.1.0 (中文(简体) ) |
| **`options`** | `[SetOptions](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-setoptions)` | 配置设定行为的对象 . | 7.3.0 (单位:千美元) |

#### 设置选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`merge`** | `boolean` | 是否应当进行合并还是应当覆盖文档. | `false` | 7.3.0 (单位:千美元) |

### 类型异名

#### 查询过滤器约束

`[QueryFieldFilterConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-queryfieldfilterconstraint) | [QueryCompositeFilterConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-querycompositefilterconstraint)`

#### 查询操作器

`'<' | '<=' | '==' | '>=' | '>' | '!=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in'`

#### 查询非筛选约束

`[QueryOrderByConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-queryorderbyconstraint) | [QueryLimitConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-querylimitconstraint) | [QueryStartAtConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-querystartatconstraint) | [QueryEndAtConstraint](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-queryendatconstraint)`

#### 命令方向

`'desc' | 'asc'`

#### 添加 Collection GroupSnapshot 听取器回调

`(event: [AddCollectionGroupSnapshotListenerCallbackEvent](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-addcollectiongroupsnapshotlistenercallbackevent)<T> | null, error: any): void`

#### 添加 Collection Groups 即时收听器调用程序

`[GetCollectionGroupResult](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcollectiongroupresult)<T>`

#### 调用文件夹

`string`

#### 添加 CollectionSnapshot 听取器回调

`(event: [AddCollectionSnapshotListenerCallbackEvent](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-addcollectionsnapshotlistenercallbackevent)<T> | null, error: any): void`

#### 添加 CollectionSnapshot 收听器调用后事件

`[GetCollectionResult](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getcollectionresult)<T>`

#### 添加文档剪接器

`(event: [AddDocumentSnapshotListenerCallbackEvent](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-adddocumentsnapshotlistenercallbackevent)<T> | null, error: any): void`

#### 添加文档剪辑器

`[GetDocumentResult](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-getdocumentresult)<T>`

## 财务问题

### 如何实时通知我数据的变化?

附加快照监听器 `addDocumentSnapshotListener(...)`, (中文(简体) ), `addCollectionSnapshotListener(...)`,或 `addCollectionGroupSnapshotListener(...)`。每当观测到的数据发生变化时,都会引用回调。 每个收听者返回一个回调ID,您以后可以传给 `removeSnapshotListener(...)`,或者您可以同时删除所有听众 `removeAllListeners()`。见 [听取实时更新](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-listen-for-real-time-updates) 举个例子.

### 两者有什么区别 `getCollection` 财务报告和审定财务报表 `getCollectionGroup`? 吗?

这个 `getCollection(...)` 在给定的引用中读取单个集合的文档。 这个 `getCollectionGroup(...)` 方法读取一个收藏组的文档,该组由所有具有同一ID的收藏组成. 这两种方法都支持复合过滤和查询限制.

### 插件离线了吗?

是的,你可以启用离线持续 `enablePersistence(...)` 方法,必须在任何其他Firestore方法之前使用。 您也可以使用 `disableNetwork()` 财务报告和审定财务报表 `enableNetwork()`。持续存储,包括待写和缓存文件,可用 `clearPersistence()`,在应用程序关闭或初始化后必须使用.

### 我能用一个Firestore数据库吗?

是的,你可以设置 `databaseId` 在您的 Capacitor 配置中选择要使用的 Firestore 数据库的配置选项(参见 [配置](https://npmcn.com/package/%40capacitor-firebase/firestore/#readme-configuration)) (中文(简体) ). 此选项仅在Android和iOS上可用.

### 我如何测试我的应用 与本地的Firestore案例?

使用 `useEmulator(...)` 通过提供主机和端口将插件连接到本地 Firebase 模拟器实例的方法。 这使得您可以在不触碰生产数据的情况下进行开发和测试.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [Firebase 验证](https://capawesome.io/docs/sdks/capacitor/firebase/authentication/): Firebase 认证的非官方电容插件.
-   [火基地云函数](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-functions/):Firebase云函数的非官方电容插件.
-   [火地云存储](https://capawesome.io/docs/sdks/capacitor/firebase/cloud-storage/):Firebase云存储的非官方电容插件.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/firestore/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/firestore/LICENSE)。 。 。 .

\[^1\]: 这个项目不附属于Google LLC或其任何子公司或子公司,也不获得其认可、支持、赞助或批准.

## 常见问题

### @capacitor-firebase/firestore 是什么？

在Android,iOS,和Web上为Firebase Cloud Firestore提供电容插件\.

### 如何安装 @capacitor-firebase/firestore？

在项目目录运行 npm install @capacitor-firebase/firestore，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capacitor-firebase/firestore 支持 TypeScript 吗？

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

### @capacitor-firebase/firestore 支持 ESM 还是 CommonJS？

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

### @capacitor-firebase/firestore 可以商用吗？

@capacitor-firebase/firestore 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @capacitor-firebase/firestore 的下载量有多少？

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

### @capacitor-firebase/firestore 还在维护吗？

最新版本 8\.6\.0 发布于 2026/10/31（9 天前）；至今共发布 36 个版本，其中过去 12 个月发布了 13 个；首次发布于 2023/09/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。