Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

גישה לנתונים במצב לא מקוון

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

Cloud Firestore תומך בהתמדה של נתונים לא מקוונים. תכונה זו מאחסנת עותק של נתוני Cloud Firestore שהאפליקציה שלך משתמשת בהם באופן פעיל, כך שהאפליקציה שלך יכולה לגשת לנתונים כשהמכשיר במצב לא מקוון. אתה יכול לכתוב, לקרוא, להאזין ולשאול את הנתונים המאוחסנים במטמון. כאשר המכשיר חוזר לאינטרנט, Cloud Firestore מסנכרן את כל השינויים המקומיים שבוצעו על ידי האפליקציה שלך ל-Cloud Firestore.

כדי להשתמש בהתמדה במצב לא מקוון, אינך צריך לבצע שינויים כלשהם בקוד שבו אתה משתמש כדי לגשת לנתוני Cloud Firestore. כאשר התמדה במצב לא מקוון מופעלת, ספריית הלקוחות של Cloud Firestore מנהלת אוטומטית גישה לנתונים מקוונים ולא מקוונים ומסנכרנת נתונים מקומיים כשהמכשיר חוזר למצב מקוון.

הגדר התמדה במצב לא מקוון

כאשר אתה מאתחל את Cloud Firestore, אתה יכול להפעיל או להשבית התמדה במצב לא מקוון:

  • עבור פלטפורמות אנדרואיד ואפל, התמדה במצב לא מקוון מופעלת כברירת מחדל. כדי להשבית את ההתמדה, הגדר את האפשרות PersistenceEnabled ל- false .
  • עבור האינטרנט, התמדה במצב לא מקוון מושבתת כברירת מחדל. כדי לאפשר התמדה, קרא לשיטת enablePersistence . המטמון של Cloud Firestore אינו ניקה אוטומטית בין הפעלות. כתוצאה מכך, אם אפליקציית האינטרנט שלך מטפלת במידע רגיש, הקפד לשאול את המשתמש אם הוא נמצא במכשיר מהימן לפני שתאפשר התמדה.

Web version 9

import { enableIndexedDbPersistence } from "firebase/firestore"; 

enableIndexedDbPersistence(db)
  .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

Web version 8

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
מָהִיר
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
let settings = FirestoreSettings()
settings.isPersistenceEnabled = true

// Any additional options
// ...

// Enable offline data persistence
let db = Firestore.firestore()
db.settings = settings
Objective-C
הערה: מוצר זה אינו זמין ביעדי watchOS ו-App Clip.
FIRFirestoreSettings *settings = [[FIRFirestoreSettings alloc] init];
settings.persistenceEnabled = YES;

// Any additional options
// ...

// Enable offline data persistence
FIRFirestore *db = [FIRFirestore firestore];
db.settings = settings;

Java

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(true)
        .build();
db.setFirestoreSettings(settings);

Kotlin+KTX

val settings = firestoreSettings {
    isPersistenceEnabled = true
}
db.firestoreSettings = settings

Dart

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

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

הגדר את גודל המטמון

כאשר התמדה מופעלת, Cloud Firestore מאחסנת כל מסמך המתקבל מה-backend לגישה לא מקוונת. Cloud Firestore מגדירה סף ברירת מחדל לגודל המטמון. לאחר חריגה מברירת המחדל, Cloud Firestore מנסה מעת לעת לנקות מסמכים ישנים שאינם בשימוש. אתה יכול להגדיר סף גודל מטמון שונה או להשבית לחלוטין את תהליך הניקוי:

Web version 9

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

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

Web version 8

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
מָהִיר
הערה: מוצר זה אינו זמין ביעדי 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
settings.cacheSizeBytes = FirestoreCacheSizeUnlimited
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;
settings.cacheSizeBytes = kFIRFirestoreCacheSizeUnlimited;
[FIRFirestore firestore].settings = 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);

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

Dart

db.settings = const Settings(
  persistenceEnabled: true,
  cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED,
);

האזן לנתונים לא מקוונים

כשהמכשיר במצב לא מקוון, אם הפעלת התמדה במצב לא מקוון, המאזינים שלך יקבלו אירועי האזנה כאשר הנתונים המאוחסנים במטמון ישתנו. אתה יכול להאזין למסמכים, אוספים ושאילתות.

כדי לבדוק אם אתה מקבל נתונים מהשרת או מהמטמון, השתמש במאפיין fromCache ב- SnapshotMetadata באירוע תמונת המצב שלך. אם fromCache true , הנתונים הגיעו מהמטמון ועשויים להיות מיושנים או לא שלמים. אם fromCache הוא false , הנתונים מלאים ועדכניים עם העדכונים האחרונים בשרת.

כברירת מחדל, שום אירוע לא מועלה אם רק ה- SnapshotMetadata השתנו. אם אתה מסתמך על ערכי fromCache , ציין את אפשרות ההאזנה includeMetadataChanges כאשר אתה מצרף את מטפל ההאזנה שלך.

Web version 9

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 version 8

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);
      });
  });
מָהִיר
הערה: מוצר זה אינו זמין ביעדי 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);
    }];

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

            }
        });

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

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 מחזיר נתונים מהמטמון.

בעת שאילתת אוסף, תוצאה ריקה מוחזרת אם אין מסמכים שמורים. בעת שליפת מסמך ספציפי, במקום זאת מוחזרת שגיאה.

שאילתות נתונים לא מקוונים

שאילתה עובדת עם התמדה במצב לא מקוון. אתה יכול לאחזר את התוצאות של שאילתות עם Get ישיר או על ידי האזנה, כמתואר בסעיפים הקודמים. אתה יכול גם ליצור שאילתות חדשות על נתונים קבועים מקומיים כשהמכשיר במצב לא מקוון, אבל השאילתות יפעלו בתחילה רק מול המסמכים המאוחסנים במטמון.

הגדר אינדקסים של שאילתות לא מקוונות

כברירת מחדל, Firestore SDK סורק את כל המסמכים באוסף במטמון המקומי שלו בעת ביצוע שאילתות לא מקוונות. עם התנהגות ברירת מחדל זו, ביצועי שאילתות לא מקוונות עלולים להיפגע כאשר משתמשים נמצאים במצב לא מקוון לפרקי זמן ארוכים.

פלטפורמת Apple , Android ו- JavaScript SDK מספקות שיטת setIndexConfiguration המאפשרת לך להגדיר אינדקסים של שאילתות מקומיות כדי לשפר את הביצועים של השאילתות הלא מקוונות שלך.

שיטות אלה קוראות את אותה תצורה מובנית של JSON המשמשת להגדרת אינדקסים בשרת, בעקבות אותו פורמט הגדרת אינדקס .

תצורת האינדקס הלא מקוון לשימוש תלויה באילו אוספים ומסמכים האפליקציה שלך ניגשת בכבדות במצב לא מקוון ובביצועים הלא מקוונים שאתה רוצה. בעוד שאתה יכול לייצא את תצורת האינדקס האחורי שלך לשימוש בלקוח, סביר להניח שדפוסי הגישה הלא מקוונים של האפליקציה שלך שונים באופן משמעותי מדפוסי גישה מקוונים, כך שתצורת האינדקס המקוונת שלך עשויה שלא להתאים לשימוש במצב לא מקוון. לאילו אוספים ומסמכים אתה רוצה שהאפליקציה שלך תיגש במצב לא מקוון עם ביצועים גבוהים? לאחר שניתחת את התנהגות האפליקציה שלך, עקוב אחר העקרונות להגדרת אינדקס ממדריך ההוספה לאינדקס .

כדי להפוך תצורות אינדקס לא מקוונות לזמינות לטעינה באפליקציית הלקוח שלך:

  • לאסוף ולהפיץ אותם עם האפליקציה שלך
  • הורד אותם מ-CDN
  • אחזר אותם ממערכת אחסון כמו Cloud Storage for Firebase .

השבת והפעל גישה לרשת

אתה יכול להשתמש בשיטה שלהלן כדי להשבית את הגישה לרשת עבור לקוח Cloud Firestore שלך. בזמן שהגישה לרשת מושבתת, כל מאזיני תמונת המצב ובקשות המסמכים מאחזרות תוצאות מהמטמון. פעולות הכתיבה עומדות בתור עד להפעלת הגישה לרשת מחדש.

Web version 9

import { disableNetwork } from "firebase/firestore"; 

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

Web version 8

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
מָהִיר
הערה: מוצר זה אינו זמין ביעדי 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
  // ...
}];

Java

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

Kotlin+KTX

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

Dart

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

השתמש בשיטה הבאה כדי להפעיל מחדש את הגישה לרשת:

Web version 9

import { enableNetwork } from "firebase/firestore"; 

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

Web version 8

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
מָהִיר
הערה: מוצר זה אינו זמין ביעדי 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
  // ...
}];

Java

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

Kotlin+KTX

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

Dart

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