Dostęp do danych offline

Funkcja Cloud Firestore obsługuje trwałość danych offline. Ta funkcja zapisuje kopię w pamięci podręcznej Cloud Firestore danych, których aktywnie używa Twoja aplikacja. mogą uzyskiwać dostęp do danych, gdy urządzenie jest offline. Możesz pisać, czytać, słuchać i wysyłanie zapytań o dane w pamięci podręcznej. Gdy urządzenie znów będzie online, Cloud Firestore synchronizuje wszystkie lokalne zmiany wprowadzone przez Twoją aplikację ze Backend Cloud Firestore.

Aby korzystać z trwałości offline, nie musisz wprowadzać żadnych zmian w kodzie, których używasz do uzyskiwania dostępu do danych z usługi Cloud Firestore. Po włączeniu trwałości offline biblioteka klienta Cloud Firestore automatycznie zarządza online dostępu do danych offline oraz synchronizuje dane lokalne, gdy urządzenie znów będzie online.

Skonfiguruj trwałość offline

Po zainicjowaniu aplikacji Cloud Firestore możesz ją włączyć lub wyłączyć trwałość w trybie offline:

  • Na platformach Android i Apple trwałość trybu offline jest domyślnie włączona. Aby wyłączyć trwałość, ustaw opcję PersistenceEnabled na false.
  • W przypadku internetu trwałość offline jest domyślnie wyłączona. Aby włączyć trwałość, wywołaj metodę enablePersistence. Pamięć podręczna użytkownika Cloud Firestore nie jest automatycznie czyszczona między sesjami. Jeśli więc Twoja aplikacja internetowa danych poufnych, zapytaj użytkownika, czy korzysta z zaufanej urządzenia przed włączeniem trwałości.
.

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
test.firestore.js
Swift
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
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
Objective-C
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
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

Skonfiguruj rozmiar pamięci podręcznej

Gdy trwałość jest włączona, Cloud Firestore zapisuje w pamięci podręcznej każdy dokument odbieranych z backendu w celu dostępu offline. Cloud Firestore ustawia domyślny próg rozmiaru pamięci podręcznej. Po przekroczeniu wartości domyślnej Cloud Firestore okresowo próbuje wyczyścić starsze, nieużywane dokumenty. Możesz skonfigurować inny próg rozmiaru pamięci podręcznej lub całkowicie wyłączyć proces czyszczenia:

Web

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

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

Web

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js
Swift
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
// 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
Objective-C
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
// 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

Słuchaj danych offline

Jeśli urządzenie jest offline, to jeśli masz włączone zachowanie offline, detektory będą otrzymywać zdarzenia nasłuchiwania, gdy zmienią się dane w lokalnej pamięci podręcznej. Ty mogą nasłuchiwać dokumentów, kolekcji i zapytań.

Aby sprawdzić, czy otrzymujesz dane z serwera czy pamięci podręcznej, użyj Właściwość fromCache w elemencie SnapshotMetadata w zdarzeniu zrzutu. Jeśli Parametr fromCache to true, dane pochodzą z pamięci podręcznej i mogą być nieaktualne lub niekompletna. Jeśli fromCache ma wartość false, dane są pełne i aktualne w parametrze aktualizacje serwera.

Domyślnie żadne zdarzenie nie jest tworzone, jeśli tylko zmieniono SnapshotMetadata. Jeśli opierają się na wartościach fromCache, określ nasłuchiwanie includeMetadataChanges podczas dołączania modułu obsługi nasłuchiwania.

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

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);
      });
  });
test.firestore.js
Swift
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
// 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
Objective-C
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
// 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

Pobierz dane offline

Jeśli otrzymasz dokument, gdy urządzenie jest offline, Cloud Firestore zwraca dane z pamięci podręcznej.

W przypadku zapytań dotyczących kolekcji, jeśli w pamięci podręcznej nie ma żadnych pamięci podręcznej, zwracany jest pusty wynik dokumenty. Podczas pobierania określonego dokumentu zwracany jest komunikat o błędzie.

Wysyłanie zapytań o dane offline

Zapytania działają z trwałością offline. Możesz pobierać wyniki zapytań, za pomocą bezpośredniego pobierania lub nasłuchiwania, jak opisano w poprzedniej sekcji sekcji. Możesz też tworzyć nowe zapytania na danych przechowywanych lokalnie, urządzenie jest offline, ale zapytania będą początkowo uruchamiane tylko w odniesieniu do dokumenty.

Skonfiguruj indeksy zapytań offline

Domyślnie pakiet SDK Firestore skanuje wszystkie dokumenty w kolekcji lokalnej pamięci podręcznej podczas wykonywania zapytań offline. Przy tym domyślnym działaniu w trybie offline wydajność zapytań może się zmniejszyć, gdy użytkownicy są przez dłuższy czas offline.

Po włączeniu stałej pamięci podręcznej możesz zwiększyć wydajność działania offline pozwala pakietowi SDK na automatyczne tworzenie lokalnych indeksów zapytań.

Automatyczne indeksowanie jest domyślnie wyłączone. Musisz włączyć aplikację automatycznego indeksowania przy każdym uruchomieniu. Określ, czy automatyczne indeksowanie ma być jak widać poniżej.

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

Po włączeniu automatycznego indeksowania pakiet SDK ocenia, które kolekcje wiele dokumentów zapisanych w pamięci podręcznej i optymalizuje wydajność zapytań lokalnych.

Pakiet SDK udostępnia metodę usuwania indeksów zapytań.

Wyłączanie i włączanie dostępu do sieci

Możesz użyć metody opisanej poniżej, aby wyłączyć dostęp do sieci dla swojego urządzenia Cloud Firestore. Przy wyłączonym dostępie do sieci wszystkie zrzuty detektory i żądania dokumentu pobierają wyniki z pamięci podręcznej. Zapis operacje będą w kolejce do czasu ponownego włączenia dostępu do sieci.

Web

import { disableNetwork } from "firebase/firestore"; 

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

Web

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js
Swift
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift
Objective-C
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
[[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

Aby ponownie włączyć dostęp do sieci, użyj następującej metody:

Web

import { enableNetwork } from "firebase/firestore"; 

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

Web

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js
Swift
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift
Objective-C
Uwaga: ten produkt nie jest dostępny na urządzeniach docelowych watchOS i wycinków aplikacji. 
[[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