Cloud Firestore รองรับการคงอยู่ของข้อมูลออฟไลน์ ฟีเจอร์นี้จะแคชสำเนาของข้อมูล Cloud Firestore ที่แอปของคุณใช้งานอยู่ เพื่อให้แอปของคุณสามารถเข้าถึงข้อมูลได้เมื่ออุปกรณ์ออฟไลน์ คุณสามารถเขียน อ่าน ฟัง และสืบค้นข้อมูลที่แคชไว้ได้ เมื่ออุปกรณ์กลับมาออนไลน์อีกครั้ง Cloud Firestore จะซิงโครไนซ์การเปลี่ยนแปลงภายในเครื่องที่ทำโดยแอปของคุณกับแบ็กเอนด์ Cloud Firestore
หากต้องการใช้การคงอยู่แบบออฟไลน์ คุณไม่จำเป็นต้องทำการเปลี่ยนแปลงใดๆ กับโค้ดที่คุณใช้ในการเข้าถึงข้อมูล Cloud Firestore เมื่อเปิดใช้งานการคงอยู่แบบออฟไลน์ ไลบรารีไคลเอ็นต์ Cloud Firestore จะจัดการการเข้าถึงข้อมูลออนไลน์และออฟไลน์โดยอัตโนมัติ และซิงโครไนซ์ข้อมูลในเครื่องเมื่ออุปกรณ์กลับมาออนไลน์อีกครั้ง
กำหนดค่าการคงอยู่แบบออฟไลน์
เมื่อคุณเริ่มต้น Cloud Firestore คุณสามารถเปิดหรือปิดใช้งานการคงอยู่แบบออฟไลน์ได้:
- สำหรับแพลตฟอร์ม Android และ Apple การคงอยู่แบบออฟไลน์จะถูกเปิดใช้งานตามค่าเริ่มต้น หากต้องการปิดใช้งานการคงอยู่ ให้ตั้งค่าตัวเลือก
PersistenceEnabled
เป็นfalse
- สำหรับเว็บ การคงอยู่แบบออฟไลน์จะถูกปิดใช้งานตามค่าเริ่มต้น หากต้องการเปิดใช้งานการคงอยู่ ให้เรียกใช้เมธอด
enablePersistence
แคชของ Cloud Firestore จะไม่ล้างระหว่างเซสชันโดยอัตโนมัติ ดังนั้น หากเว็บแอปของคุณจัดการข้อมูลที่ละเอียดอ่อน อย่าลืมถามผู้ใช้ว่าพวกเขาอยู่ในอุปกรณ์ที่เชื่อถือได้หรือไม่ ก่อนที่จะเปิดใช้งานการคงอยู่
Web modular API
// Memory cache is the default if no config is specified.
initializeFirestore(app);
// This is the default behavior if no persistence is specified.
initializeFirestore(app, {localCache: memoryLocalCache()});
// Defaults to single-tab persistence if no tab manager is specified.
initializeFirestore(app, {localCache: persistentLocalCache(/*settings*/{})});
// Same as `initializeFirestore(app, {localCache: persistentLocalCache(/*settings*/{})})`,
// but more explicit about tab management.
initializeFirestore(app,
{localCache:
persistentLocalCache(/*settings*/{tabManager: persistentSingleTabManager()})
});
// Use multi-tab IndexedDb persistence.
initializeFirestore(app,
{localCache:
persistentLocalCache(/*settings*/{tabManager: persistentMultipleTabManager()})
});
Web namespaced API
firebase.firestore().enablePersistence() .catch((err) => { if (err.code == 'failed-precondition') { // Multiple tabs open, persistence can only be enabled // in one tab at a a time. // ... } else if (err.code == 'unimplemented') { // The current browser does not support all of the // features required to enable persistence // ... } }); // Subsequent queries will use persistence, if it was enabled successfully
สวิฟท์
let settings = FirestoreSettings() // Use memory-only cache settings.cacheSettings = MemoryCacheSettings(garbageCollectorSettings: MemoryLRUGCSettings()) // Use persistent disk cache, with 100 MB cache size settings.cacheSettings = PersistentCacheSettings(sizeBytes: 100 * 1024 * 1024 as NSNumber) // Any additional options // ... // Enable offline data persistence let db = Firestore.firestore() db.settings = settings
วัตถุประสงค์-C
FIRFirestoreSettings *settings = [[FIRFirestoreSettings alloc] init]; // Use memory-only cache settings.cacheSettings = [[FIRMemoryCacheSettings alloc] initWithGarbageCollectorSettings:[[FIRMemoryLRUGCSettings alloc] init]]; // Use persistent disk cache (default behavior) // This example uses 100 MB. settings.cacheSettings = [[FIRPersistentCacheSettings alloc] initWithSizeBytes:@(100 * 1024 * 1024)]; // Any additional options // ... // Enable offline data persistence FIRFirestore *db = [FIRFirestore firestore]; db.settings = settings;
Kotlin+KTX
val settings = firestoreSettings { // Use memory cache setLocalCacheSettings(memoryCacheSettings {}) // Use persistent disk cache (default) setLocalCacheSettings(persistentCacheSettings {}) } db.firestoreSettings = settings
Java
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder(db.getFirestoreSettings()) // Use memory-only cache .setLocalCacheSettings(MemoryCacheSettings.newBuilder().build()) // Use persistent disk cache (default) .setLocalCacheSettings(PersistentCacheSettings.newBuilder() .build()) .build(); db.setFirestoreSettings(settings);
Dart
// Apple and Android db.settings = const Settings(persistenceEnabled: true); // Web await db .enablePersistence(const PersistenceSettings(synchronizeTabs: true));
กำหนดขนาดแคช
เมื่อเปิดใช้งานการคงอยู่ Cloud Firestore จะแคชเอกสารทุกฉบับที่ได้รับจากแบ็กเอนด์สำหรับการเข้าถึงแบบออฟไลน์ Cloud Firestore กำหนดเกณฑ์เริ่มต้นสำหรับขนาดแคช หลังจากเกินค่าเริ่มต้นแล้ว Cloud Firestore จะพยายามล้างเอกสารเก่าและไม่ได้ใช้เป็นระยะๆ คุณสามารถกำหนดค่าขีดจำกัดขนาดแคชอื่นหรือปิดใช้งานกระบวนการล้างข้อมูลทั้งหมดได้:
Web modular API
import { initializeFirestore, CACHE_SIZE_UNLIMITED } from "firebase/firestore"; const firestoreDb = initializeFirestore(app, { cacheSizeBytes: CACHE_SIZE_UNLIMITED });
Web namespaced API
firebase.firestore().settings({ cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED });
สวิฟท์
// The default cache size threshold is 100 MB. Configure "cacheSizeBytes" // for a different threshold (minimum 1 MB) or set to "FirestoreCacheSizeUnlimited" // to disable clean-up. let settings = Firestore.firestore().settings // Set cache size to 100 MB settings.cacheSettings = PersistentCacheSettings(sizeBytes: 100 * 1024 * 1024 as NSNumber) Firestore.firestore().settings = settings
วัตถุประสงค์-C
// The default cache size threshold is 100 MB. Configure "cacheSizeBytes" // for a different threshold (minimum 1 MB) or set to "kFIRFirestoreCacheSizeUnlimited" // to disable clean-up. FIRFirestoreSettings *settings = [FIRFirestore firestore].settings; // Set cache size to 100 MB settings.cacheSettings = [[FIRPersistentCacheSettings alloc] initWithSizeBytes:@(100 * 1024 * 1024)]; [FIRFirestore firestore].settings = settings;
Kotlin+KTX
// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes" // for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED" // to disable clean-up. val settings = FirebaseFirestoreSettings.Builder() .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED) .build() db.firestoreSettings = settings
Java
// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes" // for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED" // to disable clean-up. FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder() .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED) .build(); db.setFirestoreSettings(settings);
Dart
db.settings = const Settings( persistenceEnabled: true, cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED, );
ฟังข้อมูลออฟไลน์
ในขณะที่อุปกรณ์ออฟไลน์ หากคุณเปิดใช้งานการคงอยู่แบบออฟไลน์ ผู้ฟังของคุณจะได้รับเหตุการณ์การฟังเมื่อข้อมูลที่แคชในเครื่องเปลี่ยนแปลง คุณสามารถฟังเอกสาร คอลเลกชัน และแบบสอบถามได้
หากต้องการตรวจสอบว่าคุณได้รับข้อมูลจากเซิร์ฟเวอร์หรือแคชหรือไม่ ให้ใช้คุณสมบัติ fromCache
บน SnapshotMetadata
ในเหตุการณ์สแน็ปช็อตของคุณ หาก fromCache
เป็น true
แสดงว่าข้อมูลมาจากแคชและอาจเก่าหรือไม่สมบูรณ์ หาก fromCache
เป็น false
แสดงว่าข้อมูลเสร็จสมบูรณ์และเป็นปัจจุบันด้วยการอัปเดตล่าสุดบนเซิร์ฟเวอร์
ตามค่าเริ่มต้น ไม่มีเหตุการณ์ใดเกิดขึ้นหาก เพียง SnapshotMetadata
เท่านั้นที่เปลี่ยนแปลง หากคุณใช้ค่า fromCache
ให้ระบุตัวเลือกการฟัง includeMetadataChanges
เมื่อคุณแนบตัวจัดการการฟังของคุณ
Web modular API
import { collection, onSnapshot, where, query } from "firebase/firestore"; const q = query(collection(db, "cities"), where("state", "==", "CA")); onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => { snapshot.docChanges().forEach((change) => { if (change.type === "added") { console.log("New city: ", change.doc.data()); } const source = snapshot.metadata.fromCache ? "local cache" : "server"; console.log("Data came from " + source); }); });
Web namespaced API
db.collection("cities").where("state", "==", "CA") .onSnapshot({ includeMetadataChanges: true }, (snapshot) => { snapshot.docChanges().forEach((change) => { if (change.type === "added") { console.log("New city: ", change.doc.data()); } var source = snapshot.metadata.fromCache ? "local cache" : "server"; console.log("Data came from " + source); }); });
สวิฟท์
// Listen to metadata updates to receive a server snapshot even if // the data is the same as the cached data. db.collection("cities").whereField("state", isEqualTo: "CA") .addSnapshotListener(includeMetadataChanges: true) { querySnapshot, error in guard let snapshot = querySnapshot else { print("Error retreiving snapshot: \(error!)") return } for diff in snapshot.documentChanges { if diff.type == .added { print("New city: \(diff.document.data())") } } let source = snapshot.metadata.isFromCache ? "local cache" : "server" print("Metadata: Data fetched from \(source)") }
วัตถุประสงค์-C
// Listen to metadata updates to receive a server snapshot even if // the data is the same as the cached data. [[[db collectionWithPath:@"cities"] queryWhereField:@"state" isEqualTo:@"CA"] addSnapshotListenerWithIncludeMetadataChanges:YES listener:^(FIRQuerySnapshot *snapshot, NSError *error) { if (snapshot == nil) { NSLog(@"Error retreiving snapshot: %@", error); return; } for (FIRDocumentChange *diff in snapshot.documentChanges) { if (diff.type == FIRDocumentChangeTypeAdded) { NSLog(@"New city: %@", diff.document.data); } } NSString *source = snapshot.metadata.isFromCache ? @"local cache" : @"server"; NSLog(@"Metadata: Data fetched from %@", source); }];
Kotlin+KTX
db.collection("cities").whereEqualTo("state", "CA") .addSnapshotListener(MetadataChanges.INCLUDE) { querySnapshot, e -> if (e != null) { Log.w(TAG, "Listen error", e) return@addSnapshotListener } for (change in querySnapshot!!.documentChanges) { if (change.type == DocumentChange.Type.ADDED) { Log.d(TAG, "New city: ${change.document.data}") } val source = if (querySnapshot.metadata.isFromCache) { "local cache" } else { "server" } Log.d(TAG, "Data fetched from $source") } }
Java
db.collection("cities").whereEqualTo("state", "CA") .addSnapshotListener(MetadataChanges.INCLUDE, new EventListener<QuerySnapshot>() { @Override public void onEvent(@Nullable QuerySnapshot querySnapshot, @Nullable FirebaseFirestoreException e) { if (e != null) { Log.w(TAG, "Listen error", e); return; } for (DocumentChange change : querySnapshot.getDocumentChanges()) { if (change.getType() == Type.ADDED) { Log.d(TAG, "New city:" + change.getDocument().getData()); } String source = querySnapshot.getMetadata().isFromCache() ? "local cache" : "server"; Log.d(TAG, "Data fetched from " + source); } } });
Dart
db .collection("cities") .where("state", isEqualTo: "CA") .snapshots(includeMetadataChanges: true) .listen((querySnapshot) { for (var change in querySnapshot.docChanges) { if (change.type == DocumentChangeType.added) { final source = (querySnapshot.metadata.isFromCache) ? "local cache" : "server"; print("Data fetched from $source}"); } } });
รับข้อมูลออฟไลน์
หากคุณได้รับเอกสารในขณะที่อุปกรณ์ออฟไลน์ Cloud Firestore จะส่งคืนข้อมูลจากแคช
เมื่อสอบถามคอลเลกชัน ผลลัพธ์ที่ว่างเปล่าจะถูกส่งกลับหากไม่มีเอกสารที่แคชไว้ เมื่อดึงเอกสารเฉพาะ ข้อผิดพลาดจะถูกส่งกลับแทน
ค้นหาข้อมูลออฟไลน์
การค้นหาทำงานด้วยความคงอยู่แบบออฟไลน์ คุณสามารถดึงผลลัพธ์ของการสืบค้นด้วยการรับโดยตรงหรือโดยการฟัง ตามที่อธิบายไว้ในส่วนก่อนหน้า คุณยังสามารถสร้างการสืบค้นใหม่บนข้อมูลที่เก็บไว้ในเครื่องในขณะที่อุปกรณ์ออฟไลน์ได้ แต่การสืบค้นจะทำงานในขั้นต้นกับเอกสารที่แคชไว้เท่านั้น
กำหนดค่าดัชนีแบบสอบถามแบบออฟไลน์
ตามค่าเริ่มต้น Firestore SDK จะสแกนเอกสารทั้งหมดในคอลเลกชันในแคชในเครื่องเมื่อดำเนินการค้นหาแบบออฟไลน์ ด้วยลักษณะการทำงานเริ่มต้นนี้ ประสิทธิภาพการทำงานของแบบสอบถามแบบออฟไลน์อาจประสบเมื่อผู้ใช้ออฟไลน์เป็นระยะเวลานาน
เมื่อเปิดใช้งานแคชถาวร คุณสามารถปรับปรุงประสิทธิภาพของการสืบค้นแบบออฟไลน์ได้โดยการอนุญาตให้ SDK สร้างดัชนีการสืบค้นในเครื่องโดยอัตโนมัติ
การทำดัชนีอัตโนมัติถูกปิดใช้งานตามค่าเริ่มต้น แอปของคุณต้องเปิดใช้งานการจัดทำดัชนีอัตโนมัติทุกครั้งที่เริ่มต้น ควบคุมว่าจะเปิดใช้งานการสร้างดัชนีอัตโนมัติตามที่แสดงด้านล่างหรือไม่
สวิฟท์
if let indexManager = Firestore.firestore().persistentCacheIndexManager { // Indexing is disabled by default indexManager.enableIndexAutoCreation() } else { print("indexManager is nil") }
วัตถุประสงค์-C
PersistentCacheIndexManager *indexManager = [FIRFirestore firestore].persistentCacheIndexManager; if (indexManager) { // Indexing is disabled by default [indexManager enableIndexAutoCreation]; }
Kotlin+KTX
// return type: PersistentCacheManager? Firebase.firestore.persistentCacheIndexManager?.apply { // Indexing is disabled by default enableIndexAutoCreation() } ?: println("indexManager is null")
Java
// return type: @Nullable PersistentCacheIndexManager PersistentCacheIndexManager indexManager = FirebaseFirestore.getInstance().getPersistentCacheIndexManager(); if (indexManager != null) { // Indexing is disabled by default indexManager.enableIndexAutoCreation(); } // If not check indexManager != null, IDE shows warning: Method invocation 'enableIndexAutoCreation' may produce 'NullPointerException' FirebaseFirestore.getInstance().getPersistentCacheIndexManager().enableIndexAutoCreation();
เมื่อเปิดใช้งานการจัดทำดัชนีอัตโนมัติ SDK จะประเมินว่าคอลเลกชันใดมีเอกสารแคชจำนวนมาก และเพิ่มประสิทธิภาพการสืบค้นในเครื่อง
SDK จัดเตรียมวิธีการในการลบดัชนีแบบสอบถาม
ปิดการใช้งานและเปิดใช้งานการเข้าถึงเครือข่าย
คุณสามารถใช้วิธีการด้านล่างเพื่อปิดการเข้าถึงเครือข่ายสำหรับไคลเอนต์ Cloud Firestore ของคุณ ในขณะที่การเข้าถึงเครือข่ายถูกปิดใช้งาน ผู้ฟังสแน็ปช็อตและคำขอเอกสารทั้งหมดจะดึงผลลัพธ์จากแคช การดำเนินการเขียนจะถูกจัดคิวจนกว่าจะเปิดใช้งานการเข้าถึงเครือข่ายอีกครั้ง
Web modular API
import { disableNetwork } from "firebase/firestore"; await disableNetwork(db); console.log("Network disabled!"); // Do offline actions // ...
Web namespaced API
firebase.firestore().disableNetwork() .then(() => { // Do offline actions // ... });
สวิฟท์
Firestore.firestore().disableNetwork { (error) in // Do offline things // ... }
วัตถุประสงค์-C
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) { // Do offline actions // ... }];
Kotlin+KTX
db.disableNetwork().addOnCompleteListener { // Do offline things // ... }
Java
db.disableNetwork() .addOnCompleteListener(new OnCompleteListener<Void>() { @Override public void onComplete(@NonNull Task<Void> task) { // Do offline things // ... } });
Dart
db.disableNetwork().then((_) { // Do offline things });
ใช้วิธีการต่อไปนี้เพื่อเปิดใช้งานการเข้าถึงเครือข่ายอีกครั้ง:
Web modular API
import { enableNetwork } from "firebase/firestore"; await enableNetwork(db); // Do online actions // ...
Web namespaced API
firebase.firestore().enableNetwork() .then(() => { // Do online actions // ... });
สวิฟท์
Firestore.firestore().enableNetwork { (error) in // Do online things // ... }
วัตถุประสงค์-C
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) { // Do online actions // ... }];
Kotlin+KTX
db.enableNetwork().addOnCompleteListener { // Do online things // ... }
Java
db.enableNetwork() .addOnCompleteListener(new OnCompleteListener<Void>() { @Override public void onComplete(@NonNull Task<Void> task) { // Do online things // ... } });
Dart
db.enableNetwork().then((_) { // Back online });