الوصول إلى البيانات بلا اتصال بالإنترنت

تتيح 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
test.firestore.js
Swift
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
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
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
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

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

ضبط حجم ذاكرة التخزين المؤقت

عند تفعيل الثبات، تخزّن Cloud Firestore مؤقتًا كل مستند تم تلقّيه من الخلفية للوصول إليه بلا إنترنت. يضبط Cloud Firestore الحدّ التلقائي لحجم ذاكرة التخزين المؤقت. بعد تجاوز الحدّ التلقائي، يحاول Cloud Firestore بشكل دوري تنظيف المستندات القديمة وغير المستخدَمة. يمكنك ضبط حدّ مختلف لحجم ذاكرة التخزين المؤقت أو إيقاف عملية التنظيف تمامًا باتّباع الخطوات التالية:

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
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
// 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
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
// 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


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

الاستماع إلى البيانات المتوفّرة بلا إنترنت

أثناء عدم اتصال الجهاز بالإنترنت، إذا فعّلت ميزة استمرار البيانات بلا إنترنت، ستتلقّى أدوات معالجة البيانات أحداث استماع عند تغيُّر البيانات المخزّنة مؤقتًا على الجهاز. يمكنك الاستماع إلى المستندات والمجموعات وطلبات البحث.

للتأكّد ممّا إذا كنت تتلقّى البيانات من الخادم أو ذاكرة التخزين المؤقت، استخدِم السمة fromCache في SnapshotMetadata في حدث اللقطة. إذا كانت قيمة fromCache هي true، فهذا يعني أنّ البيانات مصدرها ذاكرة التخزين المؤقت وقد تكون قديمة أو غير مكتملة. إذا كانت قيمة fromCache هي false، تكون البيانات كاملة وحديثة مع آخر التعديلات على الخادم.

بشكلٍ تلقائي، لا يتم إنشاء أي حدث إذا تم تغيير SnapshotMetadata فقط. إذا كنت تعتمد على قيم fromCache، حدِّد الخيار includeMetadataChanges listen عند ربط معالج الاستماع.

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
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
// 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
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
// 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

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

الحصول على البيانات المتوفّرة بلا إنترنت

إذا تلقّيت مستندًا أثناء عدم اتصال الجهاز بالإنترنت، سيعرض Cloud Firestore البيانات من ذاكرة التخزين المؤقت.

عند الاستعلام عن مجموعة، يتم عرض نتيجة فارغة إذا لم تكن هناك مستندات مخزّنة مؤقتًا. عند جلب مستند معيّن، يتم عرض رسالة خطأ بدلاً من ذلك.

طلب البحث عن بيانات متوفّرة بلا إنترنت

يعمل البحث مع ميزة "استمرار البيانات بلا إنترنت". يمكنك استرداد نتائج طلبات البحث إما من خلال عملية استرداد مباشرة أو من خلال الاستماع، كما هو موضّح في الأقسام السابقة. يمكنك أيضًا إنشاء طلبات بحث جديدة على البيانات المخزَّنة محليًا أثناء عدم اتصال الجهاز بالإنترنت، ولكن لن يتم تنفيذ طلبات البحث في البداية إلا على المستندات المخزَّنة مؤقتًا.

ضبط فهارس طلبات البحث بلا إنترنت

تتضمّن الإعدادات التلقائية لحزمة تطوير البرامج (SDK) الخاصة بخدمة Firestore فحص جميع المستندات في مجموعة ضمن ذاكرة التخزين المؤقت المحلية عند تنفيذ طلبات البحث بلا إنترنت. في حال استخدام هذا السلوك التلقائي، قد يتأثر أداء طلبات البحث بلا إنترنت عندما يكون المستخدمون غير متصلين بالإنترنت لفترات طويلة.

عند تفعيل ذاكرة التخزين المؤقت الثابتة، يمكنك تحسين أداء طلبات البحث بلا إنترنت من خلال السماح لحزمة 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

// 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
// ...
disable_network.js

Web

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js
Swift
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
Firestore.firestore().disableNetwork { (error) in
  // Do offline things
  // ...
}
ViewController.swift
Objective-C
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];
ViewController.m

Kotlin

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

استخدِم الطريقة التالية لإعادة تفعيل إذن الوصول إلى الشبكة:

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
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
Firestore.firestore().enableNetwork { (error) in
  // Do online things
  // ...
}
ViewController.swift
Objective-C
ملاحظة: لا يتوفّر هذا المنتج على watchOS واستهدافات "مقاطع التطبيقات". 
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];
ViewController.m

Kotlin

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