איסוף נתונים בדפים

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

יצירת רשימה של פריטים שניתן לצפות בהם

בדרך כלל, קוד ממשק המשתמש צופה באובייקט LiveData<PagedList> (או, אם אתם משתמשים ב-RxJava2, באובייקט Flowable<PagedList> או Observable<PagedList>), שנמצא ב-ViewModel של האפליקציה. האובייקט הזה שניתן לצפייה יוצר חיבור בין התצוגה לבין התוכן של נתוני הרשימה של האפליקציה.

כדי ליצור אחד מהאובייקטים האלה של PagedList שניתן לצפות בהם, צריך להעביר מופע של DataSource.Factory לאובייקט LivePagedListBuilder או RxPagedListBuilder. אובייקט DataSource טוען דפים של PagedList יחיד. המחלקה של המפעל יוצרת מופעים חדשים של PagedList בתגובה לעדכוני תוכן, כמו ביטול תוקף של טבלאות במסד הנתונים ורענון הרשת. ספריית Room persistence יכולה לספק לכם אובייקטים מסוג DataSource.Factory, או שאתם יכולים ליצור אובייקטים משלכם.

בקטע הקוד הבא אפשר לראות איך יוצרים מופע חדש של LiveData<PagedList> בכיתה ViewModel של האפליקציה באמצעות יכולות ה-DataSource.Factory-building של Room:

ConcertDao

Kotlin

@Dao
interface ConcertDao {
    // The Int type parameter tells Room to use a PositionalDataSource
    // object, with position-based loading under the hood.
    @Query("SELECT * FROM concerts ORDER BY date DESC")
    fun concertsByDate(): DataSource.Factory<Int, Concert>
}

Java

@Dao
public interface ConcertDao {
    // The Integer type parameter tells Room to use a PositionalDataSource
    // object, with position-based loading under the hood.
    @Query("SELECT * FROM concerts ORDER BY date DESC")
    DataSource.Factory<Integer, Concert> concertsByDate();
}

ConcertViewModel

Kotlin

// The Int type argument corresponds to a PositionalDataSource object.
val myConcertDataSource : DataSource.Factory<Int, Concert> =
       concertDao.concertsByDate()

val concertList = myConcertDataSource.toLiveData(pageSize = 50)

Java

// The Integer type argument corresponds to a PositionalDataSource object.
DataSource.Factory<Integer, Concert> myConcertDataSource =
       concertDao.concertsByDate();

LiveData<PagedList<Concert>> concertList =
        LivePagedListBuilder(myConcertDataSource, /* page size */ 50).build();

הגדרת תצורה משלכם לדפדוף

כדי להגדיר LiveData<PagedList> למקרים מתקדמים, אתם יכולים גם להגדיר דפדוף משלכם. באופן ספציפי, אפשר להגדיר את המאפיינים הבאים:

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

אם אתם רוצים יותר שליטה על המועד שבו ספריית Paging טוענת רשימה ממסד הנתונים של האפליקציה, אתם יכולים להעביר אובייקט Executor בהתאמה אישית אל LivePagedListBuilder, כמו שמוצג בקטע הקוד הבא:

ConcertViewModel

Kotlin

val myPagingConfig = Config(
        pageSize = 50,
        prefetchDistance = 150,
        enablePlaceholders = true
)

// The Int type argument corresponds to a PositionalDataSource object.
val myConcertDataSource : DataSource.Factory<Int, Concert> =
        concertDao.concertsByDate()

val concertList = myConcertDataSource.toLiveData(
        pagingConfig = myPagingConfig,
        fetchExecutor = myExecutor
)

Java

PagedList.Config myPagingConfig = new PagedList.Config.Builder()
        .setPageSize(50)
        .setPrefetchDistance(150)
        .setEnablePlaceholders(true)
        .build();

// The Integer type argument corresponds to a PositionalDataSource object.
DataSource.Factory<Integer, Concert> myConcertDataSource =
        concertDao.concertsByDate();

LiveData<PagedList<Concert>> concertList =
        new LivePagedListBuilder<>(myConcertDataSource, myPagingConfig)
            .setFetchExecutor(myExecutor)
            .build();

בוחרים את הסוג הנכון של מקור הנתונים

חשוב להתחבר למקור הנתונים שהכי מתאים למבנה של נתוני המקור:

  • אם בדפים שאתם טוענים מוטמעים מקשים למעבר לדף הבא או הקודם, השתמשו ב-PageKeyedDataSource. לדוגמה, אם אתם מאחזרים פוסטים ברשתות החברתיות מהרשת, יכול להיות שתצטרכו להעביר אסימון nextPage מטעינה אחת לטעינה הבאה.
  • השתמשו ב-ItemKeyedDataSource אם אתם צריכים להשתמש בנתונים מפריט N כדי לאחזר את פריט N+1. לדוגמה, אם אתם מאחזרים תגובות בשרשור לאפליקציית דיונים, יכול להיות שתצטרכו להעביר את המזהה של התגובה האחרונה כדי לקבל את התוכן של התגובה הבאה.
  • משתמשים ב-PositionalDataSource אם צריך לאחזר דפי נתונים מכל מיקום שבוחרים במאגר הנתונים. המחלקה הזו תומכת בבקשה של קבוצת פריטי נתונים שמתחילה בכל מיקום שתבחרו. לדוגמה, הבקשה עשויה להחזיר את 50 פריטי הנתונים שמתחילים במיקום 1500.

הצגת התראה כשהנתונים לא חוקיים

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

יצירת מקורות נתונים משלכם

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

Kotlin

class ConcertTimeDataSource() :
        ItemKeyedDataSource<Date, Concert>() {
    override fun getKey(item: Concert) = item.startTime

    override fun loadInitial(
            params: LoadInitialParams<Date>,
            callback: LoadInitialCallback<Concert>) {
        val items = fetchItems(params.requestedInitialKey,
                params.requestedLoadSize)
        callback.onResult(items)
    }

    override fun loadAfter(
            params: LoadParams<Date>,
            callback: LoadCallback<Concert>) {
        val items = fetchItemsAfter(
            date = params.key,
            limit = params.requestedLoadSize)
        callback.onResult(items)
    }
}

Java

public class ConcertTimeDataSource
        extends ItemKeyedDataSource<Date, Concert> {
    @NonNull
    @Override
    public Date getKey(@NonNull Concert item) {
        return item.getStartTime();
    }

    @Override
    public void loadInitial(@NonNull LoadInitialParams<Date> params,
            @NonNull LoadInitialCallback<Concert> callback) {
        List<Concert> items =
            fetchItems(params.key, params.requestedLoadSize);
        callback.onResult(items);
    }

    @Override
    public void loadAfter(@NonNull LoadParams<Date> params,
            @NonNull LoadCallback<Concert> callback) {
        List<Concert> items =
            fetchItemsAfter(params.key, params.requestedLoadSize);
        callback.onResult(items);
    }
}

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

Kotlin

class ConcertTimeDataSourceFactory :
        DataSource.Factory<Date, Concert>() {
    val sourceLiveData = MutableLiveData<ConcertTimeDataSource>()
    var latestSource: ConcertDataSource?
    override fun create(): DataSource<Date, Concert> {
        latestSource = ConcertTimeDataSource()
        sourceLiveData.postValue(latestSource)
        return latestSource
    }
}

Java

public class ConcertTimeDataSourceFactory
        extends DataSource.Factory<Date, Concert> {
    private MutableLiveData<ConcertTimeDataSource> sourceLiveData =
            new MutableLiveData<>();

    private ConcertDataSource latestSource;

    @Override
    public DataSource<Date, Concert> create() {
        latestSource = new ConcertTimeDataSource();
        sourceLiveData.postValue(latestSource);
        return latestSource;
    }
}

איך פועלים עדכוני תוכן

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

כשמשתמשים ב-API של רשת עם דפים, בדרך כלל יש אינטראקציה של המשתמש, כמו "החלקה לרענון", שמשמשת כאות לביטול התוקף של ה-DataSource שהשתמשתם בו לאחרונה. אחר כך אתם מבקשים מופע חדש של מקור הנתונים הזה. בקטע הקוד הבא אפשר לראות את ההתנהגות הזו:

Kotlin

class ConcertActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        // ...
        concertTimeViewModel.refreshState.observe(this, Observer {
            // Shows one possible way of triggering a refresh operation.
            swipeRefreshLayout.isRefreshing =
                    it == MyNetworkState.LOADING
        })
        swipeRefreshLayout.setOnRefreshListener {
            concertTimeViewModel.invalidateDataSource()
        }
    }
}

class ConcertTimeViewModel(firstConcertStartTime: Date) : ViewModel() {
    val dataSourceFactory = ConcertTimeDataSourceFactory(firstConcertStartTime)
    val concertList: LiveData<PagedList<Concert>> =
            dataSourceFactory.toLiveData(
                pageSize = 50,
                fetchExecutor = myExecutor
            )

    fun invalidateDataSource() =
            dataSourceFactory.sourceLiveData.value?.invalidate()
}

Java

public class ConcertActivity extends AppCompatActivity {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        // ...
        viewModel.getRefreshState()
                .observe(this, new Observer<NetworkState>() {
            // Shows one possible way of triggering a refresh operation.
            @Override
            public void onChanged(@Nullable MyNetworkState networkState) {
                swipeRefreshLayout.isRefreshing =
                        networkState == MyNetworkState.LOADING;
            }
        };

        swipeRefreshLayout.setOnRefreshListener(new SwipeRefreshListener() {
            @Override
            public void onRefresh() {
                viewModel.invalidateDataSource();
            }
        });
    }
}

public class ConcertTimeViewModel extends ViewModel {
    private LiveData<PagedList<Concert>> concertList;
    private DataSource<Date, Concert> mostRecentDataSource;

    public ConcertTimeViewModel(Date firstConcertStartTime) {
        ConcertTimeDataSourceFactory dataSourceFactory =
                new ConcertTimeDataSourceFactory(firstConcertStartTime);
        mostRecentDataSource = dataSourceFactory.create();
        concertList = new LivePagedListBuilder<>(dataSourceFactory, 50)
                .setFetchExecutor(myExecutor)
                .build();
    }

    public void invalidateDataSource() {
        mostRecentDataSource.invalidate();
    }
}

מיפוי נתונים

ספריית העימוד תומכת בטרנספורמציות מבוססות-פריטים ומבוססות-דפים של פריטים שנטענו על ידי DataSource.

בקטע הקוד הבא, שילוב של שם ההופעה ותאריך ההופעה ממופה למחרוזת אחת שמכילה גם את השם וגם את התאריך:

Kotlin

class ConcertViewModel : ViewModel() {
    val concertDescriptions : LiveData<PagedList<String>>
        init {
            val concerts = database.allConcertsFactory()
                    .map { "${it.name} - ${it.date}" }
                    .toLiveData(pageSize = 50)
        }
}

Java

public class ConcertViewModel extends ViewModel {
    private LiveData<PagedList<String>> concertDescriptions;

    public ConcertViewModel(MyDatabase database) {
        DataSource.Factory<Integer, Concert> factory =
                database.allConcertsFactory().map(concert ->
                    concert.getName() + "-" + concert.getDate());
        concertDescriptions = new LivePagedListBuilder<>(
            factory, /* page size */ 50).build();
    }
}

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

שליחת משוב

נשמח לקבל ממך משוב ורעיונות באמצעות המשאבים הבאים:

Issue tracker
דווחו על בעיות כדי שנוכל לתקן באגים.

מקורות מידע נוספים

מידע נוסף על ספריית העימוד זמין במקורות המידע הבאים.

דוגמאות

סרטונים