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

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

ملاحظة: لا تتوفّر ميزة الاحتفاظ بالبيانات بلا إنترنت إلا في تطبيقات Android وApple وتطبيقات الويب.

لاستخدام ميزة "التخزين المؤقت بلا إنترنت"، ليس عليك إجراء أي تغييرات على الرمز الذي تستخدمه للوصول إلى بيانات Cloud Firestore. عند تفعيل ميزة "الوصول إلى البيانات بلا إنترنت"، تدِير مكتبة عملاء Cloud Firestore تلقائيًا إمكانية الوصول إلى البيانات على الإنترنت وعلى الأجهزة بلا إنترنت، كما تتم مزامنة البيانات المحلية عند إعادة اتصال الجهاز بالإنترنت.

ضبط ميزة الاحتفاظ بالبيانات بلا إنترنت

عند بدء Cloud Firestore، يمكنك تفعيل أو إيقاف الحفاظ على البيانات بلا إنترنت:

• بالنسبة إلى منصّتَي Android وApple، تكون ميزة الاحتفاظ بالبيانات بلا إنترنت مفعّلة تلقائيًا. لإيقاف الاستمرارية، اضبط الخيار PersistenceEnabled على false.
• بالنسبة إلى الويب، يكون الاحتفاظ بالبيانات بلا إنترنت غير مفعَّل تلقائيًا. لتفعيل الثبات، يمكنك استدعاء الطريقة enablePersistence. لا يتم محو ذاكرة التخزين المؤقت لتطبيق Cloud Firestore تلقائيًا بين الجلسات. نتيجةً لذلك، إذا كان تطبيق الويب الخاص بك يعالج معلومات حسّاسة، احرص على سؤال المستخدم عمّا إذا كان يستخدم جهازًا موثوقًا قبل تفعيل ميزة الاحتفاظ بالبيانات.

ملاحظة مهمة: بالنسبة إلى الويب، لا تتوفّر ميزة الاحتفاظ بالبيانات بلا إنترنت إلا في متصفّحات الويب Chrome وSafari وFirefox.

Web

اطّلِع على مزيد من المعلومات عن حزمة تطوير البرامج (SDK) القابلة للإزالة من الشجرة والمكوّنة من وحدات للإصدار 9 من حزمة تطوير البرامج (SDK) على الويب والترقية من الإصدار 8.

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

اطّلِع على مزيد من المعلومات عن حزمة تطوير البرامج (SDK) القابلة للإزالة من الشجرة والمكوّنة من وحدات للإصدار 9 من حزمة تطوير البرامج (SDK) على الويب والترقية من الإصدار 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
test.firestore.js

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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 وأهداف تطبيقات Apple Clips.

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

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

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

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

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
test.firestore.js

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

// 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 وأهداف تطبيقات Apple Clips.

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

مزيد من المعلومات عن Web 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

مزيد من المعلومات عن Web 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

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

// 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 وأهداف تطبيقات Apple Clips.

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

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

import { disableNetwork } from "firebase/firestore"; 

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

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
test.firestore.js

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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

Objective-C

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

import { enableNetwork } from "firebase/firestore"; 

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

Web

مزيد من المعلومات عن Web API المكوّنة من وحدات قابلة للإزالة من الشجرة والترقية من واجهة برمجة التطبيقات المستندة إلى مساحة الاسم

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
test.firestore.js

Swift

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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

Objective-C

ملاحظة: لا يتوفّر هذا المنتج على أجهزة watchOS وأهداف تطبيقات Apple Clips.

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