Ta strona została przetłumaczona przez Cloud Translation API.

Dostęp do danych w trybie offline

Cloud Firestore obsługuje trwałość danych offline. Ta funkcja zapisuje w pamięci podręcznej kopię danych Cloud Firestore, z których aktywnie korzysta Twoja aplikacja, dzięki czemu aplikacja może uzyskiwać dostęp do danych, gdy urządzenie jest offline. Możesz pisać, czytać, słuchać i wysyłać zapytania do danych w pamięci podręcznej. Gdy urządzenie wróci do trybu online, Cloud Firestore zsynchronizuje wszelkie lokalne zmiany wprowadzone przez Twoją aplikację z zapleczem Cloud Firestore.

Aby korzystać z trwałości offline, nie musisz wprowadzać żadnych zmian w kodzie używanym do uzyskiwania dostępu do danych Cloud Firestore. Po włączeniu trwałości offline biblioteka kliencka Cloud Firestore automatycznie zarządza dostępem do danych w trybie online i offline oraz synchronizuje dane lokalne, gdy urządzenie jest ponownie w trybie online.

Skonfiguruj trwałość offline

Podczas inicjowania Cloud Firestore możesz włączyć lub wyłączyć trwałość offline:

W przypadku platform Android i Apple trwałość w trybie offline jest domyślnie włączona. Aby wyłączyć trwałość, ustaw opcję PersistenceEnabled na false .
W przypadku sieci Web trwałość offline jest domyślnie wyłączona. Aby włączyć trwałość, wywołaj metodę enablePersistence . Pamięć podręczna Cloud Firestore nie jest automatycznie czyszczona między sesjami. W związku z tym, jeśli Twoja aplikacja internetowa obsługuje poufne informacje, przed włączeniem trwałości zapytaj użytkownika, czy korzysta z zaufanego urządzenia.

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 successfullytest.firestore.js

Szybki

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i App Clip.

let settings = FirestoreSettings()

// Use memory-only cache
settings.cacheSettings =
    MemoryCacheSettings(garbageCollectorSettings: MemoryLRUGCSettings())

// Use persistent disk cache, with 1 MB cache size
settings.cacheSettings = PersistentCacheSettings(sizeBytes: 1_000_000)

// Any additional options
// ...

// Enable offline data persistence
let db = Firestore.firestore()
db.settings = settingsViewController.swift

Cel C

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i 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 1 million bytes, or 1 MB.
settings.cacheSettings = [[FIRPersistentCacheSettings alloc] initWithSizeBytes:@1000000];

// 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 = settingsDocSnippets.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 funkcja trwałości jest włączona, Cloud Firestore przechowuje w pamięci podręcznej każdy dokument otrzymany z zaplecza w celu uzyskania dostępu w trybie offline. Cloud Firestore ustawia domyślny próg rozmiaru pamięci podręcznej. Po przekroczeniu domyślnego, 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 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

Szybki

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i 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 1 MB
settings.cacheSettings = PersistentCacheSettings(sizeBytes: 1_000_000)
Firestore.firestore().settings = settingsViewController.swift

Cel C

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i 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 1 MB
settings.cacheSettings =
    [[FIRPersistentCacheSettings alloc] initWithSizeBytes:@1000000];
[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

Gdy urządzenie jest w trybie offline, jeśli włączono trwałość trybu offline, słuchacze będą otrzymywać zdarzenia nasłuchiwania, gdy zmienią się dane przechowywane lokalnie w pamięci podręcznej. Możesz słuchać dokumentów, kolekcji i zapytań.

Aby sprawdzić, czy otrzymujesz dane z serwera, czy z pamięci podręcznej, użyj właściwości fromCache w SnapshotMetadata w zdarzeniu migawki. Jeśli fromCache ma true , dane pochodzą z pamięci podręcznej i mogą być nieaktualne lub niekompletne. Jeśli fromCache ma wartość false , dane są kompletne i aktualne z najnowszymi aktualizacjami na serwerze.

Domyślnie żadne zdarzenie nie jest zgłaszane, jeśli zmieniono tylko SnapshotMetadata . Jeśli polegasz na wartościach fromCache , określ opcję nasłuchu includeMetadataChanges podczas dołączania programu obsługi nasłuchiwania.

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

Szybki

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i 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)")
}ViewController.swift

Cel C

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i 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);
    }];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

Uzyskaj dane offline

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

Podczas wysyłania zapytania do kolekcji zwracany jest pusty wynik, jeśli nie ma żadnych dokumentów w pamięci podręcznej. Zamiast tego podczas pobierania określonego dokumentu zwracany jest błąd.

Zapytaj o dane offline

Wykonywanie zapytań działa z trwałością w trybie offline. Wyniki zapytań można pobrać za pomocą bezpośredniego pobierania lub nasłuchiwania, zgodnie z opisem w poprzednich sekcjach. Możesz także tworzyć nowe zapytania dotyczące lokalnie utrwalonych danych, gdy urządzenie jest w trybie offline, ale zapytania będą początkowo uruchamiane tylko w odniesieniu do dokumentów przechowywanych w pamięci podręcznej.

Skonfiguruj indeksy zapytań offline

Domyślnie Firestore SDK skanuje wszystkie dokumenty w kolekcji w swojej lokalnej pamięci podręcznej podczas wykonywania zapytań offline. W przypadku tego domyślnego zachowania wydajność zapytań w trybie offline może ulec pogorszeniu, gdy użytkownicy są w trybie offline przez dłuższy czas.

Możesz poprawić wydajność zapytań w trybie offline, konfigurując lokalne indeksy zapytań:

Szybki

Zestaw SDK platformy Apple udostępnia metodę setIndexConfiguration , która odczytuje tę samą konfigurację o strukturze JSON, która jest używana do konfigurowania indeksów na serwerze, zgodnie z tym samym formatem definicji indeksu .

// You will normally read this from a file asset or cloud storage.
let indexConfigJson = """
  {
    indexes: [
        ...
    ],
    fieldOverrides: [
        ...
    ]
  }
"""

// Apply the configuration.
Firestore.firestore().setIndexConfiguration(indexConfigJson)

Cel C

Zestaw SDK platformy Apple udostępnia metodę setIndexConfiguration — metody odczytujące tę samą konfigurację o strukturze JSON, która jest używana do konfigurowania indeksów na serwerze, zgodnie z tym samym formatem definicji indeksu .

// You will normally read this from a file asset or cloud storage.
NSString *indexConfigJson = @" {                   "
                             "   indexes: [        "
                             "     ...             "
                             "   ],                "
                             "   fieldOverrides: [ "
                             "     ...             "
                             "   ]                 "
                             " }                   ";

// Apply the configuration.
[[FIRFirestore firestore] setIndexConfigurationFromJSON:indexConfigJson
                                             completion:^(NSError * _Nullable error) {
    // ...
}];

Java

Zestaw Android SDK udostępnia metodę setIndexConfiguration , która odczytuje tę samą konfigurację o strukturze JSON, która jest używana do konfigurowania indeksów na serwerze, zgodnie z tym samym formatem definicji indeksu .

// You will normally read this from a file asset or cloud storage.
String indexConfigJson = " {                   "
                       + "   indexes: [        "
                       + "     ...             "
                       + "   ],                "
                       + "   fieldOverrides: [ "
                       + "     ...             "
                       + "   ]                 "
                       + " }                   ";
// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson);

Kotlin+KTX

// You will normally read this from a file asset or cloud storage.
val indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
"""

// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson)

Dart

Flutter SDK udostępnia metodę setIndexConfigurationFromJSON , która odczytuje tę samą konfigurację o strukturze JSON, która jest używana do konfigurowania indeksów na serwerze, zgodnie z tym samym formatem definicji indeksu .

// You will normally read this from a file asset or cloud storage.
var indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
""";

// Apply the configuration.
await FirebaseFirestore.instance.setIndexConfigurationFromJSON(json: indexConfigJson);

Alternatywnie możesz użyć metody setIndexConfiguration , aby skonfigurować indeksy za pomocą interfejsu API opartego na klasach.

var indexes = [
  Index(
    collectionGroup: "posts",
    queryScope: QueryScope.collection,
    fields: [
      IndexField(fieldPath: "author", arrayConfig: ArrayConfig.contains),
      IndexField(fieldPath: "timestamp", order: Order.descending)
    ],
  ),
];
await FirebaseFirestore.instance.setIndexConfiguration(indexes: indexes);

Konfiguracja indeksu w trybie offline, która ma być używana, zależy od kolekcji i dokumentów, do których aplikacja często uzyskuje dostęp w trybie offline, oraz od wymaganej wydajności w trybie offline. Chociaż możesz wyeksportować konfigurację indeksu zaplecza do użytku na kliencie, wzorce dostępu w trybie offline Twojej aplikacji prawdopodobnie znacznie różnią się od wzorców dostępu w trybie online, więc konfiguracja indeksu online może nie nadawać się do użytku w trybie offline. Do jakich kolekcji i dokumentów chcesz, aby Twoja aplikacja miała dostęp w trybie offline z wysoką wydajnością? Po przeanalizowaniu zachowania aplikacji postępuj zgodnie z zasadami definiowania indeksu z przewodnika po indeksowaniu .

Aby udostępnić konfiguracje indeksów offline do załadowania w aplikacji klienckiej:

kompiluj i rozpowszechniaj je w swojej aplikacji
pobrać je z CDN
pobrać je z systemu pamięci masowej, takiego jak Cloud Storage dla Firebase .

Wyłącz i włącz dostęp do sieci

Możesz użyć poniższej metody, aby wyłączyć dostęp do sieci dla swojego klienta Cloud Firestore. Gdy dostęp do sieci jest wyłączony, wszystkie odbiorniki migawek i żądania dokumentów pobierają wyniki z pamięci podręcznej. Operacje zapisu są umieszczane w kolejce do momentu ponownego włączenia dostępu do sieci.

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

Szybki

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i App Clip.

Firestore.firestore().disableNetwork { (error) in
    // Do offline things
    // ...
}ViewController.swift

Cel C

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i App Clip.

[[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

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

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

Szybki

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i App Clip.

Firestore.firestore().enableNetwork { (error) in
    // Do online things
    // ...
}ViewController.swift

Cel C

Uwaga: ten produkt nie jest dostępny w docelowych systemach watchOS i App Clip.

[[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