Gloading

Введение:

• Gloading обеспечивает глубокое разделение глобального состояния загрузки, состояния ошибки загрузки и пустых данных в представлении для поддержки процесса компонентной модернизации.

• Разделяет реализацию и использование представления состояния глобальной загрузки.

• Не требует добавления дополнительного представления состояния загрузки в макет каждой страницы.

• Может использоваться в Ability, Slice, а также для отображения состояния загрузки определённого компонента или различных элементов списка (например, ListContainer).

• Лёгкий вес: один файл Java без дополнительных зависимостей, менее 300 строк кода, из которых более 100 занимают комментарии, размер jar-файла составляет всего 6 КБ.

• Хорошая совместимость: совместим с большинством сторонних впечатляющих LoadingComponents (предоставляет их как компоненты в Adapter для использования с Gloading).

• Расширяемость: по умолчанию предоставляет четыре состояния загрузки (загрузка, ошибка загрузки, пустые данные, успешная загрузка), поддерживает пользовательские состояния.

Демонстрация:

Добавление состояния загрузки к Ability:

Успешная загрузка	Ошибка загрузки Повтор	Успешная загрузка Нет данных	Специальное представление для некоторых страниц

Добавление состояния загрузки к компоненту:

В Slice	В ScrollView	В ListContainer

Предыстория:

Анимация загрузки присутствует почти в каждом Hos Hap.

В ситуациях, когда требуется ожидание пользователя, отображение анимации загрузки позволяет пользователю понять, что приложение загружает данные, вместо того чтобы казаться зависшим, обеспечивая лучший опыт использования.

Аналогично, если данные пусты, отображение соответствующего представления и поддержка возможности повторного запроса после ошибки загрузки обеспечивают более приятный опыт, чем пустой экран.

Стиль представлений для состояний загрузки (успешная загрузка, ошибка загрузки и пустые данные) обычно должен быть согласован на всех страницах приложения.

Традиционный подход:

1. Определить один или несколько компонентов или макетов XML для отображения различных состояний загрузки (например, LoadingComponent).
2. Включить этот компонент в макет каждой страницы.
3. Обернуть логику инициализации и переключения состояний в BaseAbility/BaseSlice и предоставить методы для дочерних классов:
   • void showLoading(); — показать анимацию загрузки;
   • void showLoadFailed(); — отобразить интерфейс ошибки загрузки; — void showEmpty(); — отобразить пустую страницу; — void onClickRetry(); — реализовать метод обратного вызова для повторной попытки после ошибки.
4. Дочерние классы могут легко использовать функции отображения состояний загрузки через обёртку.

Этот подход имеет высокую степень связанности, так как каждая страница должна включать компонент загрузки. Это неудобно в использовании и требует больших усилий при изменении дизайна.

Улучшенный подход:

1. Определить один или несколько компонентов или макетов XML для отображения различных состояний загрузки (например, LoadingComponent).
2. Создать инструмент класса (LoadingUtil) для управления LoadingComponent и отображения разных интерфейсов в зависимости от состояния.
3. Обёрнуть использование LoadingUtil в BaseAbility/BaseSlice, предоставив методы для дочерних классов: — void showLoading(); — показать анимацию загрузки; — void showLoadFailed(); — отобразить интерфейс ошибки загрузки; — void showEmpty(); — отобразить пустую страницу; — void onClickRetry(); — реализовать метод обратного вызова для повторной попытки после ошибки; — <font color=red>абстрактный int getContainerId(); — дочерний класс должен реализовать этот метод, чтобы указать, в какой контейнер будет добавлен динамически созданный LoadingComponent.
4. Дочерние классы могут использовать функции отображения состояний загрузки через обёртку.

Это решение обеспечивает большую гибкость за счёт динамического создания и добавления LoadingComponent в указанный контейнер, позволяя страницам не заботиться о реализации LoadingComponent. Если приложение используется только в одном проекте, этого может быть достаточно.

Однако этот подход всё ещё связан с необходимостью привязки между страницей и используемым LoadingComponent. Для повторного использования в других проектах необходимо отделить страницу от LoadingComponent.

Как решить проблему связанности?

Необходимо реализовать следующие функции:

• Возможность переключения LoadingComponent на странице без изменения кода.
• Указание области отображения LoadingComponent на странице (например, не перекрывать заголовок навигации).
• Поддержка использования в Slice.
• Реализация функции повторной попытки при ошибке загрузки.
• Совместимость с различными интерфейсами на разных страницах (например, разные тексты подсказок).

Использование Gloading для решения проблемы связанности:

Gloading — это лёгкий инструмент, основанный на идее адаптера, который обеспечивает глубокую развязку глобального LoadingComponent (всего один Java-файл, менее 300 строк, включая более 100 комментариев, размер aar-файла — всего 6 КБ).

Для использования Gloading необходимо выполнить следующие шаги:

1. Добавить зависимость:

allprojects{
    repositories{
        mavenCentral()
    }
}
implementation 'io.openharmony.tpc.thirdlib:Gloading:1.0.3'

2. Реализовать адаптер и создать логику для создания различных представлений состояний (загрузки, ошибки, пустых данных и т. д.) в методе getComponent.

Gloading не вмешивается в макет UI, оставляя его полностью на усмотрение пользователя. Перевод текста на русский язык:

1. Метод, возвращающий loadingStatusView:

    public LoadingStatusView createLoadingStatusView(int status) {
        loadingStatusView.setStatus(status);
        return loadingStatusView;
    }

2. Класс GlobalLoadingStatusView, расширяющий DependentLayout:

class GlobalLoadingStatusView extends DependentLayout {

    public GlobalLoadingStatusView(Context context, Runnable retryTask) {
        super(context);
        // Инициализация LoadingComponent
        // Если необходимо поддерживать нажатие для повтора, в подходящий момент добавить событие нажатия к соответствующему элементу управления
    }

    public void setStatus(int status) {
        // Установка текущего состояния загрузки: загрузка, сбой загрузки, пустые данные и т. д.
        // Среди них сбой загрузки может определять текущее подключение к сети и может представлять состояние отсутствия сети
        // Это одна из ветвей состояния сбоя загрузки, можно самостоятельно решить, реализовывать ли её
    }
}

3. Инициализация стандартного адаптера Gloading:

Gloading.initDefault(new GlobalAdapter());

4. Получение держателя Holder в месте, где требуется использовать LoadingComponent:

// В Ability в качестве родительского контейнера используется mLayout
Gloading.Holder holder = Gloading.getDefault().wrap(ability, mLayout);

// Требуется поддержка нажатия для повтора после сбоя загрузки
Gloading.Holder holder = Gloading.getDefault().wrap(ability, mLayout).withRetry(retryTask);

или

// Для отображения определённого компонента состояния загрузки
// Gloading автоматически создаст FrameLayout, который будет содержать компонент, и отобразит LoadingComponent внутри него
Gloading.Holder holder = Gloading.getDefault().wrap(component);

// Требуется поддержка нажатия для повтора после сбоя загрузки
Gloading.Holder holder = Gloading.getDefault().wrap(component).withRetry(retryTask);

4.1 Если родительский контейнер — это DependentLayout, то использование cover позволяет сохранить связь с другими элементами управления того же уровня:

Gloading.Holder holder = Gloading.getDefault().cover(component);
// или
Gloading.Holder holder = Gloading.getDefault().cover(component).withRetry(retryTask);

5. Использование Holder для отображения различных состояний загрузки:

// Отображение состояния загрузки, обычно отображается анимация загрузки
holder.showLoading()

// Отображение успешного состояния загрузки (обычно скрывает LoadingComponent)
holder.showLoadSuccess()

// Отображение состояния сбоя загрузки
holder.showFailed()

// Данные загружены, но данные пусты
holder.showEmpty()

// Если предоставленное по умолчанию состояние не подходит, можно использовать этот метод для вызова других состояний
holder.showLoadingStatus(status)

6. Совместимость повторного использования страниц и компонентов в разных приложениях:

Каждый Hap может иметь свой собственный LoadingComponent, достаточно предоставить разные адаптеры для каждого Hap. Разные приложения могут вызывать разные Gloading.initDefault(new GlobalAdapter()), при этом код конкретной страницы не нужно изменять.

Включение/выключение режима отладки:

// Устанавливает значение true, чтобы Logcat выводил журналы
Gloading.debug(trueOrFalse);

Вызов различий:

Gloading.Holder holder = Gloading.getDefault().wrap(activity);

Изменить на:

// Необходимо передать родительский макет
Gloading.Holder holder = Gloading.getDefault().wrap(ability, mLayout);

Требования к запуску примера entry:

Через DevEco studio и скачав SDK, необходимо изменить версию в файле build.gradle проекта в разделе dependencies → classpath на соответствующую версию (то есть версию, используемую в новом проекте вашей IDE).