Offline auf Daten zugreifen

Cloud Firestore unterstützt die Offline-Datenpersistenz. Diese Funktion speichert eine Kopie der Cloud Firestore-Daten, die Ihre App aktiv nutzt, zwischen, sodass Ihre App auf die Daten zugreifen kann, wenn das Gerät offline ist. Sie können die zwischengespeicherten Daten schreiben, lesen, anhören und abfragen. Wenn das Gerät wieder online ist, synchronisiert Cloud Firestore alle von Ihrer App vorgenommenen lokalen Änderungen mit dem Cloud Firestore-Backend.

Um die Offline-Persistenz zu verwenden, müssen Sie keine Änderungen am Code vornehmen, den Sie für den Zugriff auf Cloud Firestore-Daten verwenden. Bei aktivierter Offline-Persistenz verwaltet die Cloud Firestore-Clientbibliothek automatisch den Online- und Offline-Datenzugriff und synchronisiert lokale Daten, wenn das Gerät wieder online ist.

Konfigurieren Sie die Offline-Persistenz

Wenn Sie Cloud Firestore initialisieren, können Sie die Offline-Persistenz aktivieren oder deaktivieren:

  • Für Android- und Apple-Plattformen ist die Offline-Persistenz standardmäßig aktiviert. Um die Persistenz zu deaktivieren, legen Sie die Option PersistenceEnabled auf false fest.
  • Für das Web ist die Offline-Persistenz standardmäßig deaktiviert. Um die Persistenz zu aktivieren, rufen Sie die Methode enablePersistence auf. Der Cache von Cloud Firestore wird zwischen Sitzungen nicht automatisch geleert. Wenn Ihre Web-App vertrauliche Informationen verarbeitet, fragen Sie den Benutzer daher unbedingt, ob er sich auf einem vertrauenswürdigen Gerät befindet, bevor Sie die Persistenz aktivieren.

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
test.firestore.js
Schnell
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
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
ViewController.swift
Ziel c
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
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;
ViewController.m

Kotlin+KTX

val settings = firestoreSettings {
    // Use memory cache
    setLocalCacheSettings(memoryCacheSettings {})
    // Use persistent disk cache (default)
    setLocalCacheSettings(persistentCacheSettings {})
}
db.firestoreSettings = settings
DocSnippets.kt

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);
DocSnippets.java

Dart

// Apple and Android
db.settings = const Settings(persistenceEnabled: true);

// Web
await db
    .enablePersistence(const PersistenceSettings(synchronizeTabs: true));
firestore.dart

Konfigurieren Sie die Cachegröße

Wenn die Persistenz aktiviert ist, speichert Cloud Firestore jedes vom Backend empfangene Dokument für den Offline-Zugriff zwischen. Cloud Firestore legt einen Standardschwellenwert für die Cache-Größe fest. Nach Überschreiten des Standardwerts versucht Cloud Firestore regelmäßig, ältere, nicht verwendete Dokumente zu bereinigen. Sie können einen anderen Schwellenwert für die Cache-Größe konfigurieren oder den Bereinigungsprozess vollständig deaktivieren:

Web modular API

import { initializeFirestore, CACHE_SIZE_UNLIMITED } from "firebase/firestore";

const firestoreDb = initializeFirestore(app, {
  cacheSizeBytes: CACHE_SIZE_UNLIMITED
});
fs_setup_cache.js

Web namespaced API

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js
Schnell
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
// 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
ViewController.swift
Ziel c
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
// 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;
ViewController.m

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,
);
firestore.dart

Hören Sie sich Offline-Daten an

Wenn das Gerät offline ist und Sie die Offline-Persistenz aktiviert haben, erhalten Ihre Listener Abhörereignisse, wenn sich die lokal zwischengespeicherten Daten ändern. Sie können Dokumente, Sammlungen und Abfragen anhören.

Um zu überprüfen, ob Sie Daten vom Server oder vom Cache erhalten, verwenden Sie die fromCache Eigenschaft für SnapshotMetadata in Ihrem Snapshot-Ereignis. Wenn fromCache true ist, stammen die Daten aus dem Cache und sind möglicherweise veraltet oder unvollständig. Wenn fromCache den Wert false hat, sind die Daten vollständig und aktuell mit den neuesten Updates auf dem Server.

Standardmäßig wird kein Ereignis ausgelöst, wenn sich nur die SnapshotMetadata geändert haben. Wenn Sie sich auf die fromCache Werte verlassen, geben Sie beim Anhängen Ihres Listen-Handlers die Listenoption includeMetadataChanges an.

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);
    });
});
use_from_cache.js

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);
      });
  });
test.firestore.js
Schnell
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
// 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)")
  }
ViewController.swift
Ziel c
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
// 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);
    }];
ViewController.m

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")
        }
    }
DocSnippets.kt

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);
                }

            }
        });
DocSnippets.java

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}");
    }
  }
});
firestore.dart

Holen Sie sich Offline-Daten

Wenn Sie ein Dokument erhalten, während das Gerät offline ist, gibt Cloud Firestore Daten aus dem Cache zurück.

Beim Abfragen einer Sammlung wird ein leeres Ergebnis zurückgegeben, wenn keine zwischengespeicherten Dokumente vorhanden sind. Beim Abrufen eines bestimmten Dokuments wird stattdessen ein Fehler zurückgegeben.

Offline-Daten abfragen

Die Abfrage funktioniert mit Offline-Persistenz. Sie können die Ergebnisse von Abfragen entweder mit einem direkten Abruf oder durch Abhören abrufen, wie in den vorherigen Abschnitten beschrieben. Sie können auch neue Abfragen für lokal gespeicherte Daten erstellen, während das Gerät offline ist. Die Abfragen werden jedoch zunächst nur für die zwischengespeicherten Dokumente ausgeführt.

Konfigurieren Sie Offline-Abfrageindizes

Standardmäßig scannt das Firestore SDK alle Dokumente in einer Sammlung in seinem lokalen Cache, wenn Offline-Abfragen ausgeführt werden. Bei diesem Standardverhalten kann die Leistung von Offline-Abfragen beeinträchtigt werden, wenn Benutzer über einen längeren Zeitraum offline sind.

Wenn der persistente Cache aktiviert ist, können Sie die Leistung von Offline-Abfragen verbessern, indem Sie dem SDK erlauben, automatisch lokale Abfrageindizes zu erstellen.

Die automatische Indizierung ist standardmäßig deaktiviert. Ihre App muss bei jedem Start die automatische Indizierung aktivieren. Steuern Sie, ob die automatische Indizierung aktiviert ist, wie unten gezeigt.

Schnell
if let indexManager = Firestore.firestore().persistentCacheIndexManager {
  // Indexing is disabled by default
  indexManager.enableIndexAutoCreation()
} else {
  print("indexManager is nil")
}
Ziel 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();

Sobald die automatische Indizierung aktiviert ist, wertet das SDK aus, welche Sammlungen über eine große Anzahl zwischengespeicherter Dokumente verfügen, und optimiert die Leistung lokaler Abfragen.

Das SDK bietet eine Methode zum Löschen von Abfrageindizes.

Deaktivieren und aktivieren Sie den Netzwerkzugriff

Mit der folgenden Methode können Sie den Netzwerkzugriff für Ihren Cloud Firestore-Client deaktivieren. Während der Netzwerkzugriff deaktiviert ist, rufen alle Snapshot-Listener und Dokumentanforderungen Ergebnisse aus dem Cache ab. Schreibvorgänge werden in die Warteschlange gestellt, bis der Netzwerkzugriff wieder aktiviert wird.

Web modular API

import { disableNetwork } from "firebase/firestore"; 

await disableNetwork(db);
console.log("Network disabled!");
// Do offline actions
// ...
disable_network.js

Web namespaced API

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js
Schnell
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift
Ziel c
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
ViewController.m

Kotlin+KTX

db.disableNetwork().addOnCompleteListener {
    // Do offline things
    // ...
}
DocSnippets.kt

Java

db.disableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do offline things
                // ...
            }
        });
DocSnippets.java

Dart

db.disableNetwork().then((_) {
  // Do offline things
});
firestore.dart

Verwenden Sie die folgende Methode, um den Netzwerkzugriff wieder zu aktivieren:

Web modular API

import { enableNetwork } from "firebase/firestore"; 

await enableNetwork(db);
// Do online actions
// ...
enable_network.js

Web namespaced API

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js
Schnell
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift
Ziel c
Hinweis: Dieses Produkt ist nicht auf watchOS- und App Clip-Zielen verfügbar.
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
ViewController.m

Kotlin+KTX

db.enableNetwork().addOnCompleteListener {
    // Do online things
    // ...
}
DocSnippets.kt

Java

db.enableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do online things
                // ...
            }
        });
DocSnippets.java

Dart

db.enableNetwork().then((_) {
  // Back online
});
firestore.dart