React Native Academy · 课时

实时监听器与离线持久化

使用 onSnapshot 订阅 Firestore 集合，在界面中接收实时更新，并启用离线持久化，使应用无网络连接时也能读取缓存数据。

实时监听器与离线持久化 是 CoddyKit 上的免费 React Native Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 React Native Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Native Academy 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Real-Time Listeners vs One-Time Reads

Firestore offers two ways to read data: one-time reads with .get() and real-time listeners with .onSnapshot(). A real-time listener keeps a persistent connection open and fires your callback every time the document or query result changes, including the initial data load.

Use .get() when you only need data once (like loading user settings on app start). Use .onSnapshot() when data changes frequently and the UI must stay up to date, like a chat feed or a live score.

Listening to a Single Document

Call .onSnapshot(callback) on a DocumentReference to listen for changes to a specific document. The callback fires immediately with the current data and again whenever the document changes.

.onSnapshot() returns an unsubscribe function. Store it in a variable and call it in your useEffect cleanup to stop the listener when the component unmounts and avoid memory leaks.

import { useEffect, useState } from 'react';
import firestore from '@react-native-firebase/firestore';

export function usePost(postId: string) {
  const [post, setPost] = useState(null);

  useEffect(() => {
    const unsubscribe = firestore()
      .collection('posts')
      .doc(postId)
      .onSnapshot((snapshot) => {
        if (snapshot.exists) {
          setPost({ id: snapshot.id, ...snapshot.data() });
        }
      });

    return unsubscribe; // Stop listener on unmount
  }, [postId]);

  return post;
}

Listening to a Collection Query

Attach .onSnapshot() to a collection query to receive live updates whenever any document in the result set is added, modified, or removed. The QuerySnapshot passed to the callback contains all matching documents — not just the changed ones.

This means each time a document changes, you rebuild the entire list from snapshot.docs. This is fine for small to medium lists, and Firestore's local cache makes it fast even without a network round-trip for cached data.

useEffect(() => {
  const unsubscribe = firestore()
    .collection('messages')
    .where('roomId', '==', roomId)
    .orderBy('createdAt', 'desc')
    .limit(50)
    .onSnapshot((snapshot) => {
      const messages = snapshot.docs.map((doc) => ({
        id: doc.id,
        ...doc.data(),
      }));
      setMessages(messages);
    });

  return unsubscribe;
}, [roomId]);

Using DocumentChange for Efficiency

Instead of rebuilding the entire list on every snapshot, you can inspect the changes array to see exactly what was added, modified, or removed. Each entry in snapshot.docChanges() has a type property: 'added', 'modified', or 'removed'.

This approach is more efficient for large collections where only a few documents change at a time. You surgically update the local state array instead of replacing it entirely.

snapshot.docChanges().forEach((change) => {
  const item = { id: change.doc.id, ...change.doc.data() };

  if (change.type === 'added') {
    setItems((prev) => [item, ...prev]);
  } else if (change.type === 'modified') {
    setItems((prev) => prev.map((i) => (i.id === item.id ? item : i)));
  } else if (change.type === 'removed') {
    setItems((prev) => prev.filter((i) => i.id !== item.id));
  }
});

Handling Listener Errors

.onSnapshot() accepts a second argument for error handling. When the listener fails — typically due to a permission error from Firestore Security Rules — the error callback fires with a FirebaseError.

Common error codes include permission-denied (security rules blocked the read) and unavailable (offline and no cached data). Always provide an error handler so you can display a fallback UI instead of silently failing.

const unsubscribe = firestore()
  .collection('private-data')
  .onSnapshot(
    (snapshot) => {
      setData(snapshot.docs.map((doc) => doc.data()));
    },
    (error) => {
      if (error.code === 'permission-denied') {
        setError('You do not have access to this data.');
      } else {
        setError('Could not load data. Check your connection.');
      }
    }
);

Firestore Offline Persistence

React Native Firebase enables offline persistence by default on mobile. This means Firestore caches all documents you read or listen to in a local SQLite database on the device. When the device has no internet, reads return cached data immediately.

You do not need any configuration to enable this — it just works. You can control the cache size limit (default 40 MB). When the cache is full, Firestore evicts the least recently used documents. You can also set it to unlimited with cacheSizeBytes: firestore.CACHE_SIZE_UNLIMITED.

import firestore from '@react-native-firebase/firestore';

// Configure cache size (call before any Firestore operations)
await firestore().settings({
  cacheSizeBytes: firestore.CACHE_SIZE_UNLIMITED,
  persistence: true, // enabled by default on mobile
});

// After this, all reads and writes work offline automatically

Reading from Cache vs Server

By default, .get() tries the server first and falls back to the cache if offline. You can override this by specifying a source option: { source: 'cache' } always reads from local cache (instant, no network) and { source: 'server' } always goes to the network.

Cache-only reads are useful for optimistic UI patterns where you want to render existing data immediately while a fresh network request is in progress. If the document is not in the cache, a cache-only read throws an error.

// Always use cached data (instant, works offline)
const snapshot = await firestore()
  .collection('posts')
  .doc(postId)
  .get({ source: 'cache' });

// Always fetch from server (throws if offline)
const freshSnapshot = await firestore()
  .collection('posts')
  .doc(postId)
  .get({ source: 'server' });

// Default: server first, cache fallback
const snapshot2 = await firestore()
  .collection('posts')
  .doc(postId)
  .get();

Pagination with Query Cursors

For large collections, load data in pages using query cursors: .startAfter(lastDocument). You keep a reference to the last document you loaded and pass it to the next query to get the next page. This is known as cursor-based pagination.

Store the last document snapshot in state. When the user scrolls to the bottom of the list (FlatList's onEndReached), trigger a new query starting after the last document. Append the new results to the existing list.

const [posts, setPosts] = useState([]);
const [lastDoc, setLastDoc] = useState(null);
const [hasMore, setHasMore] = useState(true);

async function loadMore() {
  if (!hasMore) return;

  let query = firestore()
    .collection('posts')
    .orderBy('createdAt', 'desc')
    .limit(20);

  if (lastDoc) {
    query = query.startAfter(lastDoc);
  }

  const snapshot = await query.get();
  if (snapshot.empty) {
    setHasMore(false);
    return;
  }

  setLastDoc(snapshot.docs[snapshot.docs.length - 1]);
  const newPosts = snapshot.docs.map((doc) => ({ id: doc.id, ...doc.data() }));
  setPosts((prev) => [...prev, ...newPosts]);
}

Composite Indexes

When you combine .where() and .orderBy() on different fields, Firestore requires a composite index. Without it, the query throws a failed-precondition error with a URL to create the index automatically.

Composite indexes are configured in firestore.indexes.json and deployed with the Firebase CLI. During development, just click the URL from the error log — Firebase creates the index for you. For production, always manage indexes in code so they are version controlled.

// This query requires a composite index on (userId ASC, createdAt DESC)
const snapshot = await firestore()
  .collection('posts')
  .where('userId', '==', userId)
  .orderBy('createdAt', 'desc')
  .get();

// If the index is missing, you see:
// FirebaseError: The query requires an index.
// https://console.firebase.google.com/project/.../firestore/indexes?...
// Click the link to auto-create the index

Detaching Listeners on Screen Change

Real-time listeners consume bandwidth and battery. Detach them when the user navigates away from a screen by using React Navigation's useFocusEffect hook instead of useEffect. useFocusEffect runs the effect when the screen comes into focus and cleans up when the screen loses focus.

This way, you only maintain an active Firestore listener when the relevant screen is visible, and the listener is paused (and re-established) as the user navigates away and back.

import { useFocusEffect } from '@react-navigation/native';
import { useCallback } from 'react';

export function ChatScreen({ route }) {
  useFocusEffect(
    useCallback(() => {
      // Start listener when screen is focused
      const unsubscribe = firestore()
        .collection('messages')
        .onSnapshot(handleSnapshot);

      // Stop listener when screen loses focus
      return unsubscribe;
    }, [route.params.roomId])
  );
}

Optimistic Updates with Local State

For a snappy user experience, apply changes to local state immediately before the Firestore write completes — this is called an optimistic update. Show the change right away, then let the real-time listener confirm or correct it when the server response arrives.

For example, when the user likes a post, increment the like count in local state immediately. If the server write fails, revert the local state by decrementing the count and showing an error toast. This avoids perceived lag on slow connections.

async function toggleLike(postId: string, currentlyLiked: boolean) {
  // 1. Optimistically update local state
  setLiked(!currentlyLiked);
  setLikeCount((prev) => prev + (currentlyLiked ? -1 : 1));

  try {
    // 2. Persist to Firestore
    await firestore().collection('posts').doc(postId).update({
      likesCount: firestore.FieldValue.increment(currentlyLiked ? -1 : 1),
    });
  } catch (error) {
    // 3. Revert on failure
    setLiked(currentlyLiked);
    setLikeCount((prev) => prev + (currentlyLiked ? 1 : -1));
    Alert.alert('Error', 'Could not update like. Try again.');
  }
}

Quick Check

Test your understanding of React Native Mobile Development concepts from this lesson.

Lesson Recap

In this lesson you learned: how to attach real-time listeners with .onSnapshot() for live data updates, how Firestore offline persistence automatically caches data for offline use, and how to paginate large collections using startAfter cursor-based pagination. Next up we profile React Native apps and eliminate performance bottlenecks.

常见问题解答

「实时监听器与离线持久化」课时是免费的吗？

是的 — 「实时监听器与离线持久化」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Native Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Native Academy 课程共包含 4 节课。

「实时监听器与离线持久化」这节课中我会学到什么？

使用 onSnapshot 订阅 Firestore 集合，在界面中接收实时更新，并启用离线持久化，使应用无网络连接时也能读取缓存数据。你通过在浏览器中直接运行的动手代码来练习 React Native Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 React Native Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 React Native Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「实时监听器与离线持久化」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 React Native Academy 课中编写并运行代码吗？

能。每节 React Native Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 React Native Academy