AngularFire Cloud Firestore 实战指南：依赖注入、实时数据读写与 Zone 包装原理

后端【免费下载链接】angularfireAngular Firebase ❤️项目地址https://gitcode.com/gh_mirrors/an/angularfire点击查看免费下载本文以 AngularFire 官方开发者指南中的 Cloud Firestore 章节为骨架结合仓库内src/firestore的真实源码实现系统讲解如何在 Angular 应用中通过angular/fire/firestore完成 Firestore 的依赖注入、集合/文档的实时读写并深入解析其“包装 Firebase JS SDK RxFire 并做 Zone 隔离”的底层机制。读完本文你将能在自己的 Angular 项目中正确配置 Firestore、用collectionData渲染实时列表、用addDoc写入数据并理解为什么所有 API 必须从angular/fire/firestore导入而不是直接从firebase/firestore导入。Cloud Firestore 是什么Cloud Firestore 是 Firebase 与 Google Cloud 提供的一款灵活、可横向扩展的 NoSQL 文档数据库面向移动端、Web 端和服务端开发。它通过实时监听器realtime listeners在客户端应用之间同步数据并为移动端和 Web 端提供离线支持offline support——因此你可以构建出无论网络延迟高低、甚至完全断网都能流畅响应的应用。在本项目中Cloud Firestore 是让 Angular 应用访问云端数据库或本地 Firebase Emulator Suite即模拟器中数据库的 API 入口。AngularFire 的 Firestore 模块位于仓库的 src/firestore 目录对外发布为angular/fire/firestore其公共 API 汇总在 public_api.tsexport { Firestore, FirestoreInstances, firestoreInstance$ } from ./firestore; export { provideFirestore, FirestoreModule } from ./firestore.module; export * from ./rxfire; export * from ./firebase;即一个Firestore可注入类型、一个provideFirestore提供者函数以及两个export *分别暴露 RxFire 的响应式函数和 Firebase Firestore 的完整 API。依赖注入把 Firestore 实例接入 Angular前置条件添加 AngularFire在使用任何 Firestore API 之前需要先通过 Angular CLI 的 schematics 把 AngularFire 添加到项目中ng add angular/fire该命令会安装angular/fire相关依赖并生成 Firebase 配置。仓库根目录的 package.json 中即包含angular/fire各模块的构建与发布配置src/firestore/package.json则定义了 Firestore 子包仅含 ng-packagr 的 schema 配置无独立依赖表明它直接复用主包依赖。在 app.config.ts 中提供 Firestore 实例AngularFire 的现代 API 基于 Angular 的ApplicationConfig与provide*函数。在应用的app.config.ts中完成配置import { ApplicationConfig } from angular/core; import { provideFirebaseApp, initializeApp } from angular/fire/app; import { provideFirestore, getFirestore } from angular/fire/firestore; export const appConfig: ApplicationConfig { providers: [ provideFirebaseApp(() initializeApp({ ... })), provideFirestore(() getFirestore()), ... ], ... }其中initializeApp({ ... })里的配置对象应替换为你在 Firebase 控制台获得的项目配置apiKey、authDomain、projectId 等provideFirestore(() getFirestore())默认会基于已初始化的默认 FirebaseApp 创建 Firestore 实例。从源码看provideFirestore的实际实现在 src/firestore/firestore.module.ts其内部做了三件关键事情注册版本信息调用registerVersion(angularfire, VERSION.full, fst)让 Firebase JS SDK 能识别 AngularFire 的版本fst为 firestore 的标识后缀提供默认实例通过DEFAULT_FIRESTORE_INSTANCE_PROVIDER与defaultFirestoreInstanceFactory使用ɵgetDefaultInstanceOfFirebaseFirestore(FIRESTORE_PROVIDER_NAME, provided, defaultApp)从已提供的实例中挑选默认实例并包装为Firestore支持多实例以multi: true的方式把每次调用provideFirestore(fn)生成的实例注册到PROVIDED_FIRESTORE_INSTANCES令牌下FirestoreInstances可注入得到全部实例数组。值得注意的实现细节在 firestoreInstanceFactory创建 Firestore 实例时使用了zone.runOutsideAngular(() fn(injector))即在 Angular Zone 之外执行getFirestore()等初始化调用避免 Firebase 内部的定时器等副作用干扰 Angular 的变更检测与稳定性判定。此外该工厂的依赖中还包含AuthInstances与AppCheckInstances均带Optional注释说明“Firestore Auth 一起使用时先加载 Auth 效果更好”。把 Firestore 注入组件配置好提供者后即可在组件中通过inject(Firestore)注入 Firestore 实例import { Component, inject } from angular/core; import { Firestore } from angular/fire/firestore; Component({ ... }) export class UserProfileComponent { private firestore inject(Firestore); ... }这里注入的Firestore类型定义在 src/firestore/firestore.ts它是一个继承自firebase/firestore的FirebaseFirestore的接口与包装类构造函数直接返回原始实例。仓库测试 src/firestore/firestore.spec.ts 验证了这一点注入得到的firestore与provideFirestore回调中创建的实例完全相等expect(firestore).toEqual(providedFirestore)且firestore.app与注入的FirebaseApp一致。Firebase APIAngularFire 的同名包装AngularFire包装wrap了 Firebase JS SDK以保证其在 Angular 应用中正确运行同时对外提供完全一致的 API。这意味着你只需要修改 import 来源// 从 import { ... } from firebase/firestore // 改为 import { ... } from angular/fire/firestore然后按照 Firebase 官方文档使用即可。该包装的完整清单在 src/firestore/firebase.ts文件先export * from firebase/firestore重导出全部类型与函数再对每个函数做ɵzoneWrap包装后显式导出。以写入类函数为例你可以直接使用的函数包括addDoc、setDoc、updateDoc、deleteDocwriteBatch、runTransactiongetDoc、getDocs、getDocFromCache、getDocsFromServer等读取函数where、orderBy、limit、limitToLast、query、collectionGroup、endAt、startAfter等查询函数onSnapshot、onSnapshotsInSync等实时监听函数increment、sum、vector、deleteField、documentId等字段值函数connectFirestoreEmulator、enableIndexedDbPersistence、enableMultiTabIndexedDbPersistence、loadBundle、namedQuery、terminate等环境/持久化函数其中ɵzoneWrap(_addDoc, true, 2)这类调用的第二个参数true表示需要 Zone 包装第三个数字表示参数个数用于包装器在调用前快速校验。这些包装保证 Firebase 的 Promise、Observable 和回调 API 在返回首个值之前会被标记为“会使应用不稳定”从而让 SSR / SSG 等待数据就绪后再渲染 HTML。关于 Zone 包装的完整设计可参阅仓库文档 docs/zones.md。此外同一模块还提供了基于 RxFire 的响应式函数见 src/firestore/rxfire.ts它们同样经过ɵzoneWrap包装collectionData/collectionSnapshots/collectionChanges/sortedChangesdocData/docSnapshots/fromRefauditTrail/snapToDatacollectionCount/collectionCountSnap集合文档计数读取数据集合、文档与实时 Observable数据模型集合与文档路径在 Cloud Firestore 中数据以documents文档形式存储文档存放在collections集合中。数据的路径遵循collection_name/document_id的格式若存在子集合subcollections则继续追加层级。例如路径users/ABC12345/posts/XYZ6789表示users集合文档 id 为ABC12345的文档posts集合文档 id 为XYZ6789的文档用 collection collectionData 读取集合官方指南以collection和collectionData两个函数演示实时读取。在user-profile.component.ts中import { Firestore, collection, collectionData} from angular/fire/firestore; import { Component, inject } from angular/core; import { Observable } from rxjs; Component ({ selector: app-user-profile, standalone: true, ... }) export class UserProfileComponent { private firestore: Firestore inject(Firestore); // inject Cloud Firestore users$: ObservableUserProfile[]; constructor() { // get a reference to the user-profile collection const userProfileCollection collection(this.firestore, users); // get documents (data) from the collection using collectionData this.users$ collectionData(userProfileCollection) as ObservableUserProfile[]; } } export interface UserProfile { username: string; }流程拆解collection(this.firestore, users)返回一个CollectionReference它只是对路径的引用不会触发任何网络请求collectionData(userProfileCollection)返回一个Observable——这是 RxFire 的collectionData经 Zone 包装后的版本见 src/firestore/rxfire.ts每当集合内的文档发生变化Observable 就会发射新的数据数组这里通过类型断言as ObservableUserProfile[]为数据标注接口类型。collectionData返回的 observable 可以直接在模板中通过async管道展示。在user-profile.component.html中section h1User Profiles/h1 ul li *ngForlet user of users$ | async {{user.username}} /li /ul /sectionasync管道会自动订阅 Observable并在组件销毁时自动取消订阅因此无需手动管理订阅生命周期。从源码看读取 API 的更多选择除了collectionDatasrc/firestore/rxfire.ts 还暴露了多种读取形态可按需选用docData/docSnapshots读取单个文档。docData直接发射文档数据docSnapshots发射DocumentSnapshot含元数据collectionSnapshots发射QuerySnapshot而非纯数据数组collectionChanges/sortedChanges发射带变更类型added / modified / removed的文档变更流适合做增量 UI 更新fromRef把单个快照事件包装为 Observable 的低层原语auditTrail发射带变更类型的审计轨迹流collectionCount/collectionCountSnap发射集合文档数量。仓库中的示例应用 sample/src/app/firestore/firestore.component.ts 展示了docData(doc(this.firestore, test/1))的用法并配合TransferState实现 SSR 场景下的状态转移服务端读取test/1文档后通过transferState.set(...)写入状态客户端检测到已有状态时用startWith(...)立即以缓存值渲染避免闪烁。这为“读取数据 SSR”提供了可直接借鉴的完整范例。写入数据用 addDoc 新增文档要向 Cloud Firestore 写入数据使用addDoc函数。它会在集合指定的路径下创建一个新文档文档 id 由 Firestore 自动生成。官方指南在user-profile.component.ts中演示了点击button时新增文档import { Firestore, collection, collectionData, addDoc, CollectionReference, DocumentReference } from angular/fire/firestore; import { Component, inject } from angular/core; import { Observable } from rxjs; Component ({ selector: app-user-profile, standalone: true, ... }) export class UserProfileComponent { private firestore: Firestore inject(Firestore); // inject Cloud Firestore users$: ObservableUserProfile[]; usersCollection: CollectionReference; constructor() {...} addUserProfile(username: string) { if (!username) return; addDoc(this.usersCollection, UserProfile { username }).then((documentReference: DocumentReference) { // the documentReference provides access to the newly created document }); } } export interface UserProfile { username: string; }要点说明this.usersCollection是CollectionReference应如上面读取示例那样在构造器中通过collection(this.firestore, users)获得并保存复用addDoc(this.usersCollection, { username })第二个参数是要写入的文档数据这里用UserProfile断言类型字段须与 Firestore 中允许的数据类型一致字符串、数字、布尔、数组、嵌套对象、时间戳等addDoc返回一个Promiseresolve 时拿到DocumentReference——它提供对新创建文档的访问如docRef.id、docRef.pathPromise 的catch分支可以在此处捕获写入错误。除了addDoc从 src/firestore/firebase.ts 的重导出清单可以看到同一模块还提供了其他写入手段可按场景选用setDoc(docRef, data, options)写入或覆盖指定路径的文档可配合{ merge: true }只合并更新部分字段updateDoc(docRef, field, value)只更新文档的指定字段不覆盖整篇文档deleteDoc(docRef)删除文档writeBatch(...)批量原子写入多个文档runTransaction(...)事务性读写保证多文档操作的一致性。更多能力速览来自模块源码虽然官方指南只展开讲解了collectionData与addDoc但angular/fire/firestore模块本身还封装了 Firestore 的完整能力这里结合 src/firestore/firebase.ts 的重导出清单做一次速览方便你按需查阅能力分类代表函数查询与过滤query、where、orderBy、limit、limitToLast、startAt、startAfter、endAt、endBefore、and、or集合组查询collectionGroup聚合查询getCountFromServer、getAggregateFromServer、sum、increment实时监听onSnapshot、onSnapshotResume、onSnapshotsInSync离线持久化enableIndexedDbPersistence、enableMultiTabIndexedDbPersistence、clearIndexedDbPersistence、disableNetwork、enableNetwork模拟器/环境connectFirestoreEmulator、terminate、setLogLevelBundleloadBundle、namedQuery其中模拟器连接在仓库中随处可见测试 src/firestore/firestore.spec.ts 在提供 Firestore 实例时调用connectFirestoreEmulator(providedFirestore, localhost, firestoreEmulatorPort)示例应用 sample/src/app/firestore/firestore.component.ts 也根据environment.emulatorPorts?.firestore在本地开发时自动连接模拟器。这意味着你完全可以在不消耗云端配额的情况下用 Firebase Emulator 本地开发与测试 Firestore 功能。另外仓库还提供Firestore Lite变体src/firestore/lite对应firebase/firestore/lite——它移除了实时监听与离线持久化等重量级能力换取更小的包体积适合对包大小敏感、只需一次性读取的场景。其提供者名称为firestore/lite见 src/firestore/lite/lite.ts使用方式与完整版一致。为什么必须从 angular/fire/firestore 导入这是使用 AngularFire Firestore 最容易踩坑的一点不要直接从firebase/firestore导入函数。原因在 docs/zones.md 中有完整阐述AngularFire 的包装确保 Firebase API 在Angular Zone 之外被调用隔离定时器等副作用避免它们反复触发变更检测、破坏应用稳定性对 Observable、Promise、回调类 API包装会将其标记为“在返回首个值之前使应用不稳定”从而让SSR / SSG预渲染等待数据到达后再渲染 HTML避免超时或空白页未经包装的 API 或脱离注入上下文injection context的调用可能导致变更检测、双向绑定、水合rehydration异常。因此无论读取还是写入请统一从angular/fire/firestore导入collection、collectionData、addDoc、doc、docData等全部 API若需在switchMap等异步回调中构造查询请先用runInInjectionContext重新建立注入上下文具体写法见 docs/zones.md。测试验证仓库为 Firestore 模块提供了单元测试 src/firestore/firestore.spec.ts验证了核心的依赖注入契约通过provideFirebaseApp(() initializeApp(COMMON_CONFIG, appName))与provideFirestore(() {...})配置 TestBed断言TestBed.inject(Firestore)得到的实例与provideFirestore回调中创建并连接模拟器的实例完全一致toEqual断言注入的 Firestore 与注入的FirebaseApp正确关联firestore.app app。这组测试可作为你本地配置的“金标准”如果你的注入结果与此不符多半是app.config.ts的提供者顺序或初始化回调写错了。延伸阅读官方指南原文所在的开发者文档目录docs/firestore.md以及配套的 Firestore 集合/文档/查询指南Zone 包装机制详解docs/zones.mdFirebase 模拟器使用说明docs/emulators/emulators.md完整 Firestore 模块源码与导出src/firestore/public_api.ts可运行的示例组件sample/src/app/firestore/firestore.component.ts赞分享后端【免费下载链接】angularfireAngular Firebase ❤️项目地址https://gitcode.com/gh_mirrors/an/angularfire点击查看免费下载相关推荐AngularFirecompat 版Cloud Firestore 离线数据持久化实战指南AngularFirecompat 版Cloud Firestore 离线数据持久化实战指南 Cloud Firestore 的离线数据持久化允许 Web后端TREK Demo Mode 完全指南搭建可公开体验的自托管旅行规划器试用实例TREK Demo Mode 完全指南搭建可公开体验的自托管旅行规划器试用实例 导读 Demo Mode 是 TREK自托管旅行规划器内置的一套先试用、后端Hydrogen-v1多通行证(Multipass)认证为企业客户打造无缝登录体验Hydrogen v1多通行证 Multipass 认证为企业客户打造无缝登录体验 Hydrogen v1是基于React的框架专为构建动态的、Shopif前端Web框架电商上一篇OpenSees完全指南从入门到精通的结构工程有限元分析平台下一篇Famo.us性能优化终极指南实现60fps流畅渲染的10个核心技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考