تبدیل جریان‌های داده (نماها)

مفاهیم و پیاده‌سازی Jetpack Compose

وقتی با داده‌های صفحه‌بندی‌شده کار می‌کنید، اغلب لازم است جریان داده‌ها را هنگام بار کردن آن تبدیل کنید. برای مثال، ممکن است لازم باشد فهرستی از موارد را فیلتر کنید یا موارد را به نوع دیگری تبدیل کنید تا بتوانید آن‌ها را در میانای کاربر ارائه دهید. یکی دیگر از موارد استفاده رایج برای تبدیل جریان داده، افزودن جداکننده‌های فهرست است.

به‌طور کلی‌تر، اعمال تبدیل‌ها مستقیماً روی جریان داده به شما امکان می‌دهد ساختارهای مخزن و ساختارهای میانای کاربر را جدا نگه دارید.

این صفحه فرض می‌کند که با استفاده پایه از کتابخانه صفحه‌بندی آشنا هستید.

اعمال تبدیلات پایه

چون PagingData در یک جاری‌سازی واکنشی کپسوله‌سازی شده است، می‌توانید عملیات تبدیل را به‌صورت افزایشی روی داده‌ها بین بارگیری داده‌ها و ارائه آن‌ها اعمال کنید.

برای اعمال تبدیل‌ها به هر شیء PagingData در جاری‌سازی، تبدیل‌ها را در داخل یک عملیات map() در جاری‌سازی قرار دهید:

جاوا

PagingRx.getFlowable(pager) // Type is Flowable<PagingData<User>>.
  // Map the outer stream so that the transformations are applied to
  // each new generation of PagingData.
  .map(pagingData -> {
    // Transformations in this block are applied to the items
    // in the paged data.
  });

جاوا

// Map the outer stream so that the transformations are applied to
// each new generation of PagingData.
Transformations.map(
  // Type is LiveData<PagingData<User>>.
  PagingLiveData.getLiveData(pager),
  pagingData -> {
    // Transformations in this block are applied to the items
    // in the paged data.
  });

تبدیل داده‌ها

اساسی‌ترین عملیات روی جریان داده، تبدیل آن به نوع دیگری است. وقتی به شیء PagingData دسترسی پیدا کردید، می‌توانید عملیات map() را روی هر مورد جداگانه در فهرست صفحه‌بندی‌شده در شیء PagingData انجام دهید.

یک مورد استفاده رایج برای این کار، نگاشت یک شیء لایه شبکه یا پایگاه داده روی یک شیء است که به‌طور خاص در لایه میانای کاربر استفاده می‌شود. مثال زیر نشان می‌دهد که چگونه این نوع عملیات نقشه را اعمال کنید:

جاوا

// Type is Flowable<PagingData<User>>.
PagingRx.getFlowable(pager)
  .map(pagingData ->
    pagingData.map(UiModel.UserModel::new)
  )

جاوا

Transformations.map(
  // Type is LiveData<PagingData<User>>.
  PagingLiveData.getLiveData(pager),
  pagingData ->
    pagingData.map(UiModel.UserModel::new)
)

یکی دیگر از تبدیل‌های رایج داده، گرفتن ورودی از کاربر، مانند رشته پُرسمان، و تبدیل آن به خروجی درخواست برای نمایش است. برای راه‌اندازی این ویژگی، باید ورودی پُرسمان کاربر را گوش دهید و ضبط کنید، درخواست را اجرا کنید، و نتیجه پُرسمان را به میانای کاربر برگردانید.

می‌توانید بااستفاده از میانای برنامه‌سازی کاربردی جاری‌سازی، ورودی پُرسمان را گوش کنید. مرجع جاری‌سازی را در ViewModel خود نگه دارید. لایه میانای کاربر نباید دسترسی مستقیم به آن داشته باشد؛ درعوض، تابعی تعریف کنید تا ViewModel را از پرسمان کاربر مطلع کند.

جاوا

private BehaviorSubject<String> querySubject = BehaviorSubject.create("");

public void onQueryChanged(String query) {
  queryFlow.onNext(query)
}

جاوا

private MutableLiveData<String> queryLiveData = new MutableLiveData("");

public void onQueryChanged(String query) {
  queryFlow.setValue(query)
}

وقتی مقدار پُرسمان در جریان داده تغییر می‌کند، می‌توانید عملیاتی را برای تبدیل مقدار پُرسمان به نوع داده مطلوب انجام دهید و نتیجه را به لایه میانای کاربر برگردانید. تابع تبدیل خاص به زبان و چارچوب مورداستفاده بستگی دارد، اما همه آن‌ها عملکرد مشابهی ارائه می‌دهند.

جاوا

Observable<User> querySearchResults =
  querySubject.switchMap(query -> userDatabase.searchBy(query));

جاوا

LiveData<User> querySearchResults = Transformations.switchMap(
  queryLiveData,
  query -> userDatabase.searchBy(query)
);

استفاده از عملیات‌هایی مثل flatMapLatest یا switchMap تضمین می‌کند که فقط جدیدترین نتایج به میانای کاربر برگردانده می‌شود. اگر کاربر ورودی پُرسمان خود را قبل‌از تکمیل عملیات پایگاه داده تغییر دهد، این عملیات نتایج پُرسمان قدیمی را کنار می‌گذارد و بلافاصله جستجوی جدید را راه‌اندازی می‌کند.

فیلتر کردن داده‌ها

عملیات رایج دیگر فیلتر کردن است. می‌توانید داده‌ها را براساس معیارهای کاربر فیلتر کنید، یا اگر داده‌ها باید براساس معیارهای دیگری پنهان شوند، می‌توانید آن‌ها را از میانای کاربر بردارید.

باید این عملیات فیلتر را در فراخوانی map() قرار دهید زیرا فیلتر بر شیء PagingData اعمال می‌شود. وقتی داده‌ها از PagingData فیلتر می‌شوند، نمونه جدید PagingData برای نمایش به لایه میانای کاربر منتقل می‌شود.

جاوا

// Type is Flowable<PagingData<User>>.
PagingRx.getFlowable(pager)
  .map(pagingData ->
    pagingData.filter(user -> !user.isHiddenFromUi())
  )
}

جاوا

Transformations.map(
  // Type is LiveData<PagingData<User>>.
  PagingLiveData.getLiveData(pager),
  pagingData ->
    pagingData.filter(user -> !user.isHiddenFromUi())
)

افزودن جداکننده‌های فهرست

کتابخانه Paging از جداکننده‌های فهرست پویا پشتیبانی می‌کند. می‌توانید خوانایی فهرست را با درج جداکننده‌ها مستقیماً در جریان داده به‌عنوان موارد فهرست RecyclerView بهبود بخشید. درنتیجه، جداکننده‌ها اشیای ViewHolder با ویژگی‌های کامل هستند که تعامل‌پذیری، تمرکز دسترس‌پذیری، و همه ویژگی‌های دیگر ارائه‌شده توسط View را فعال می‌کنند.

سه مرحله برای درج جداکننده‌ها در فهرست صفحه‌بندی‌شده وجود دارد:

  1. مدل میانای کاربر را برای گنجاندن موارد جداکننده تبدیل کنید.
  2. جریان داده را تبدیل کنید تا جداکننده‌ها به‌طور پویا بین بار کردن داده و ارائه داده اضافه شوند.
  3. میانای کاربر را برای مدیریت موارد جداکننده به‌روز کنید.

تبدیل مدل واسط کاربر

کتابخانه «صفحه‌بندی» جداکننده‌های فهرست را به‌عنوان موارد فهرست واقعی در RecyclerView درج می‌کند، اما موارد جداکننده باید از موارد داده در فهرست قابل‌تشخیص باشند تا بتوانند به نوع ViewHolder متفاوتی با میانای کاربر متمایز متصل شوند. راه حل این است که یک کلاس مهروموم‌شده Kotlin با زیرکلاس‌ها ایجاد کنید تا داده‌ها و جداکننده‌های شما را نشان دهد. یا به‌جای آن، می‌توانید کلاس پایه‌ای ایجاد کنید که توسط کلاس مورد فهرست و کلاس جداکننده شما گسترش داده شود.

فرض کنید می‌خواهید جداکننده‌هایی به فهرست صفحه‌بندی‌شده‌ای از User مورد اضافه کنید. تکه‌کد زیر نشان می‌دهد که چگونه یک کلاس پایه ایجاد کنید که در آن نمونه‌ها می‌توانند UserModel یا SeparatorModel باشند:

جاوا

class UiModel {
  private UiModel() {}

  static class UserModel extends UiModel {
    @NonNull
    private String mId;
    @NonNull
    private String mLabel;

    UserModel(@NonNull String id, @NonNull String label) {
      mId = id;
      mLabel = label;
    }

    UserModel(@NonNull User user) {
      mId = user.id;
      mLabel = user.label;
    }

    @NonNull
    public String getId() {
      return mId;
    }

    @NonNull
    public String getLabel() {
      return mLabel;
      }
    }

    static class SeparatorModel extends UiModel {
    @NonNull
    private String mDescription;

    SeparatorModel(@NonNull String description) {
      mDescription = description;
    }

    @NonNull
    public String getDescription() {
      return mDescription;
    }
  }
}

جاوا

class UiModel {
  private UiModel() {}

  static class UserModel extends UiModel {
    @NonNull
    private String mId;
    @NonNull
    private String mLabel;

    UserModel(@NonNull String id, @NonNull String label) {
      mId = id;
      mLabel = label;
    }

    UserModel(@NonNull User user) {
      mId = user.id;
      mLabel = user.label;
    }

    @NonNull
    public String getId() {
      return mId;
    }

    @NonNull
    public String getLabel() {
      return mLabel;
      }
    }

    static class SeparatorModel extends UiModel {
    @NonNull
    private String mDescription;

    SeparatorModel(@NonNull String description) {
      mDescription = description;
    }

    @NonNull
    public String getDescription() {
      return mDescription;
    }
  }
}

تبدیل کردن جریان داده‌ها

باید تبدیل‌ها را پس‌از بار کردن جاری‌سازی داده و قبل‌از ارائه آن اعمال کنید. تبدیل‌ها باید کارهای زیر را انجام دهند:

  • موارد فهرست بارشده را تبدیل کنید تا نوع مورد پایه جدید را منعکس کند.
  • از روش PagingData.insertSeparators() برای افزودن جداکننده‌ها استفاده کنید.

برای کسب اطلاعات بیشتر درباره عملیات تبدیل، اعمال تبدیل‌های پایه را ببینید.

مثال زیر عملیات تبدیل را برای به‌روزرسانی جاری‌سازی PagingData<User> به جاری‌سازی PagingData<UiModel> با جداکننده‌های اضافه‌شده نشان می‌دهد:

جاوا

// Map outer stream, so you can perform transformations on each
// paging generation.
PagingRx.getFlowable(pager).map(pagingData -> {
  // First convert items in stream to UiModel.UserModel.
  PagingData<UiModel> uiModelPagingData = pagingData.map(
    UiModel.UserModel::new);

  // Insert UiModel.SeparatorModel, which produces PagingData of
  // generic type UiModel.
  return PagingData.insertSeparators(uiModelPagingData,
    (@Nullable UiModel before, @Nullable UiModel after) -> {
      if (before == null) {
        return new UiModel.SeparatorModel("HEADER");
      } else if (after == null) {
        return new UiModel.SeparatorModel("FOOTER");
      } else if (shouldSeparate(before, after)) {
        return new UiModel.SeparatorModel("BETWEEN ITEMS "
          + before.toString() + " AND " + after.toString());
      } else {
        // Return null to avoid adding a separator between two
        // items.
        return null;
      }
    });
});

جاوا

// Map outer stream, so you can perform transformations on each
// paging generation.
Transformations.map(PagingLiveData.getLiveData(pager),
  pagingData -> {
    // First convert items in stream to UiModel.UserModel.
    PagingData<UiModel> uiModelPagingData = pagingData.map(
      UiModel.UserModel::new);

    // Insert UiModel.SeparatorModel, which produces PagingData of
    // generic type UiModel.
    return PagingData.insertSeparators(uiModelPagingData,
      (@Nullable UiModel before, @Nullable UiModel after) -> {
        if (before == null) {
          return new UiModel.SeparatorModel("HEADER");
        } else if (after == null) {
          return new UiModel.SeparatorModel("FOOTER");
        } else if (shouldSeparate(before, after)) {
          return new UiModel.SeparatorModel("BETWEEN ITEMS "
            + before.toString() + " AND " + after.toString());
        } else {
          // Return null to avoid adding a separator between two
          // items.
          return null;
        }
      });
  });

مدیریت جداکننده‌ها در واسط کاربر

مرحله نهایی این است که میانای کاربر خود را تغییر دهید تا نوع مورد جداکننده را در خود جای دهد. چیدمان و نگهدارنده نمایشی برای موارد جداکننده ایجاد کنید و آداپتور فهرست را تغییر دهید تا از RecyclerView.ViewHolder به‌عنوان نوع نگهدارنده نمایش استفاده کند تا بتواند بیش‌از یک نوع نگهدارنده نمایش را مدیریت کند. یا می‌توانید کلاس پایه مشترکی تعریف کنید که هم کلاس نگهدارنده نمای مورد و هم کلاس نگهدارنده نمای جداکننده آن را گسترش دهند.

همچنین باید تغییرات زیر را در آداپتور فهرستتان اعمال کنید:

  • موارد را به روش‌های onCreateViewHolder() و onBindViewHolder() اضافه کنید تا موارد فهرست جداکننده را درنظر بگیرید.
  • مقایسه‌گر جدیدی پیاده‌سازی کنید.

جاوا

class UiModelAdapter extends PagingDataAdapter<UiModel, RecyclerView.ViewHolder> {
  UiModelAdapter() {
    super(new UiModelComparator(), Dispatchers.getMain(),
      Dispatchers.getDefault());
  }

  @NonNull
  @Override
  public RecyclerView.ViewHolder onCreateViewHolder(@NonNull ViewGroup parent,
    int viewType) {
    if (viewType == R.layout.item) {
      return new UserModelViewHolder(parent);
    } else {
      return new SeparatorModelViewHolder(parent);
    }
  }

  @Override
  public int getItemViewType(int position) {
    // Use peek over getItem to avoid triggering page fetch / drops, since
    // recycling views is not indicative of the user's current scroll position.
    UiModel item = peek(position);
    if (item instanceof UiModel.UserModel) {
      return R.layout.item;
    } else if (item instanceof UiModel.SeparatorModel) {
      return R.layout.separator_item;
    } else {
      throw new IllegalStateException("Unknown view");
    }
  }

  @Override
  public void onBindViewHolder(@NonNull RecyclerView.ViewHolder holder,
    int position) {
    if (holder instanceOf UserModelViewHolder) {
      UserModel userModel = (UserModel) getItem(position);
      ((UserModelViewHolder) holder).bind(userModel);
    } else {
      SeparatorModel separatorModel = (SeparatorModel) getItem(position);
      ((SeparatorModelViewHolder) holder).bind(separatorModel);
    }
  }
}

class UiModelComparator extends DiffUtil.ItemCallback<UiModel> {
  @Override
  public boolean areItemsTheSame(@NonNull UiModel oldItem,
    @NonNull UiModel newItem) {
    boolean isSameRepoItem = oldItem instanceof UserModel
      && newItem instanceof UserModel
      && ((UserModel) oldItem).getId().equals(((UserModel) newItem).getId());

    boolean isSameSeparatorItem = oldItem instanceof SeparatorModel
      && newItem instanceof SeparatorModel
      && ((SeparatorModel) oldItem).getDescription().equals(
      ((SeparatorModel) newItem).getDescription());

    return isSameRepoItem || isSameSeparatorItem;
  }

  @Override
  public boolean areContentsTheSame(@NonNull UiModel oldItem,
    @NonNull UiModel newItem) {
    return oldItem.equals(newItem);
  }
}

جاوا

class UiModelAdapter extends PagingDataAdapter<UiModel, RecyclerView.ViewHolder> {
  UiModelAdapter() {
    super(new UiModelComparator(), Dispatchers.getMain(),
      Dispatchers.getDefault());
  }

  @NonNull
  @Override
  public RecyclerView.ViewHolder onCreateViewHolder(@NonNull ViewGroup parent,
    int viewType) {
    if (viewType == R.layout.item) {
      return new UserModelViewHolder(parent);
    } else {
      return new SeparatorModelViewHolder(parent);
    }
  }

  @Override
  public int getItemViewType(int position) {
    // Use peek over getItem to avoid triggering page fetch / drops, since
    // recycling views is not indicative of the user's current scroll position.
    UiModel item = peek(position);
    if (item instanceof UiModel.UserModel) {
      return R.layout.item;
    } else if (item instanceof UiModel.SeparatorModel) {
      return R.layout.separator_item;
    } else {
      throw new IllegalStateException("Unknown view");
    }
  }

  @Override
  public void onBindViewHolder(@NonNull RecyclerView.ViewHolder holder,
    int position) {
    if (holder instanceOf UserModelViewHolder) {
      UserModel userModel = (UserModel) getItem(position);
      ((UserModelViewHolder) holder).bind(userModel);
    } else {
      SeparatorModel separatorModel = (SeparatorModel) getItem(position);
      ((SeparatorModelViewHolder) holder).bind(separatorModel);
    }
  }
}

class UiModelComparator extends DiffUtil.ItemCallback<UiModel> {
  @Override
  public boolean areItemsTheSame(@NonNull UiModel oldItem,
    @NonNull UiModel newItem) {
    boolean isSameRepoItem = oldItem instanceof UserModel
      && newItem instanceof UserModel
      && ((UserModel) oldItem).getId().equals(((UserModel) newItem).getId());

    boolean isSameSeparatorItem = oldItem instanceof SeparatorModel
      && newItem instanceof SeparatorModel
      && ((SeparatorModel) oldItem).getDescription().equals(
      ((SeparatorModel) newItem).getDescription());

    return isSameRepoItem || isSameSeparatorItem;
  }

  @Override
  public boolean areContentsTheSame(@NonNull UiModel oldItem,
    @NonNull UiModel newItem) {
    return oldItem.equals(newItem);
  }
}

جلوگیری از کار تکراری

یکی از مشکلات کلیدی که باید از آن اجتناب کرد این است که برنامه کارهای غیرضروری انجام دهد. واکشی داده‌ها عملیاتی پرهزینه است و تبدیل داده‌ها نیز می‌تواند زمان ارزشمندی را به خود اختصاص دهد. وقتی داده‌ها بارگیری و برای نمایش در میانای کاربر آماده شد، باید ذخیره شود تا درصورت تغییر پیکربندی و نیاز به بازسازی میانای کاربر، از آن استفاده شود.

عملیات cachedIn() نتایج هرگونه تبدیلی را که قبل‌از آن رخ می‌دهد در حافظه نهان ذخیره می‌کند. بنابراین، cachedIn() باید آخرین فراخوانی در ViewModel شما باشد.

جاوا

// CoroutineScope helper provided by the lifecycle-viewmodel-ktx artifact.
CoroutineScope viewModelScope = ViewModelKt.getViewModelScope(viewModel);
PagingRx.cachedIn(
  // Type is Flowable<PagingData<User>>.
  PagingRx.getFlowable(pager)
    .map(pagingData -> pagingData
      .filter(user -> !user.isHiddenFromUi())
      .map(UiModel.UserModel::new)),
  viewModelScope);
}

جاوا

// CoroutineScope helper provided by the lifecycle-viewmodel-ktx artifact.
CoroutineScope viewModelScope = ViewModelKt.getViewModelScope(viewModel);
PagingLiveData.cachedIn(
  Transformations.map(
    // Type is LiveData<PagingData<User>>.
    PagingLiveData.getLiveData(pager),
    pagingData -> pagingData
      .filter(user -> !user.isHiddenFromUi())
      .map(UiModel.UserModel::new)),
  viewModelScope);

برای اطلاعات بیشتر درباره استفاده از cachedIn() با جاری‌سازی PagingData، به راه‌اندازی جاری‌سازی PagingData مراجعه کنید.