Cloud Firestore 支援離線資料保留功能。這項功能會快取 也就是應用程式經常使用的 Cloud Firestore 資料，因此您的應用程式 也能在裝置離線時存取資料。您可以寫入、讀取、聆聽及查詢快取資料。裝置恢復連線後 Cloud Firestore 會將應用程式所做的任何本機變更同步處理到 Cloud Firestore 後端。
如要使用離線持久性，您不必對用於存取 Cloud Firestore 資料的程式碼進行任何變更。啟用離線保存功能後，Cloud Firestore 用戶端程式庫會自動管理線上和離線資料存取權，並在裝置重新上線時同步處理本機資料。
設定離線持久性
初始化 Cloud Firestore 時，您可以啟用或停用離線持久性：
- Android 和 Apple 平台預設啟用離線保存功能。如要停用，請按照下列步驟操作：
持續性，請將
PersistenceEnabled選項設為false。 - 在網頁版中，離線持久性預設為停用。如要啟用持久性，請呼叫
enablePersistence方法。Cloud Firestore的快取 系統不會自動清除切換工作階段因此，如果您的網頁應用程式 會處理機密資訊，請務必詢問使用者是否為可信 再啟用保留設定。
Web
// 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
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
Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。
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
Objective-C
注意：這項產品不適用於 watchOS 和 App Clip 目標。
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
import { initializeFirestore, CACHE_SIZE_UNLIMITED } from "firebase/firestore";
const firestoreDb = initializeFirestore(app, {
cacheSizeBytes: CACHE_SIZE_UNLIMITED
});
Web
firebase.firestore().settings({
cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。
// 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
Objective-C
注意：這項產品不適用於 watchOS 和 App Clip 目標。
// 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, );
聆聽離線資料
裝置處於離線狀態時，如果已啟用離線保存功能， 當本機快取的資料變更時，接聽程式就會收到監聽事件。您可以聆聽文件、集合和查詢。
如要檢查您接收的資料是來自伺服器或快取，請使用
快照事件中 SnapshotMetadata 的 fromCache 屬性。如果 fromCache 是 true，資料就來自快取，可能已過時或不完整。如果 fromCache 為 false，表示資料完整且為最新狀態，且包含伺服器上的最新更新。
根據預設，如果僅 SnapshotMetadata 有變更，系統就不會觸發事件。如果您依賴 fromCache 值，請在附加監聽處理常式時指定 includeMetadataChanges 監聽選項。
Web
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
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);
});
});
Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。
// 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)")
}
Objective-C
注意：這項產品不適用於 watchOS 和 App Clip 目標。
// 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 自動建立本機查詢索引。
自動索引功能預設為停用。應用程式每次啟動時，都必須啟用自動索引功能。控制是否啟用自動索引功能，如下所示。
Swift
if let indexManager = Firestore.firestore().persistentCacheIndexManager {
// Indexing is disabled by default
indexManager.enableIndexAutoCreation()
} else {
print("indexManager is nil")
}
Objective-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
import { disableNetwork } from "firebase/firestore";
await disableNetwork(db);
console.log("Network disabled!");
// Do offline actions
// ...
Web
firebase.firestore().disableNetwork()
.then(() => {
// Do offline actions
// ...
});
Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。
Firestore.firestore().disableNetwork { (error) in
// Do offline things
// ...
}
Objective-C
注意：這項產品不適用於 watchOS 和 App Clip 目標。
[[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
import { enableNetwork } from "firebase/firestore";
await enableNetwork(db);
// Do online actions
// ...
Web
firebase.firestore().enableNetwork()
.then(() => {
// Do online actions
// ...
});
Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。
Firestore.firestore().enableNetwork { (error) in
// Do online things
// ...
}
Objective-C
注意：這項產品不適用於 watchOS 和 App Clip 目標。
[[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
});