dart:async

onError<E extends Object> method

Обрабатывает ошибки в этом future.

Перехватывает ошибки типа E, с которыми завершается этот future. Если задан test, перехватываются только ошибки типа E, для которых test возвращает true. Если E — это Object, потенциально перехватываются все ошибки; результат зависит только от заданного test.toString()

Если ошибка перехвачена, возвращаемый future завершается результатом вызова handleError с ошибкой и трассировкой стека. Этот результат должен иметь тот же тип, что и значение, с которым этот future мог бы завершиться в ином случае. Например, если этот future не может завершиться с null, то handleError также не может вернуть null. Пример:

Future<T> retryOperation<T>(Future<T> operation(), T onFailure()) =>
    operation().onError<RetryException>((e, s) {
      if (e.canRetry) {
        return retryOperation(operation, onFailure);
      }
      return onFailure();
    });

Если handleError выбрасывает исключение, возвращаемый future завершается с выброшенной ошибкой и трассировкой стека. Однако если снова выбрасывается тот же объект ошибки, это считается повторным выбрасыванием («rethrow»), и исходная трассировка стека сохраняется. Это можно использовать как альтернативу пропуску ошибки в test. Пример:

// Unwraps an an exceptions cause, if it has one.
someFuture.onError<SomeException>((e, _) {
  throw e.cause ?? e;
});
// vs.
someFuture.onError<SomeException>((e, _) {
  throw e.cause!;
}, test: (e) => e.cause != null);

Если ошибка не перехвачена, возвращаемый future завершается с тем же результатом, значением или ошибкой, что и этот future.

По сути, этот метод представляет собой более точно типизированную версию Future.catchError. С его помощью удобно перехватывать ошибки определённых типов; он требует обработчик ошибок с корректным типом, а не просто Function. Поэтому обработчики ошибок должны принимать аргумент трассировки стека.

Реализация

Future<T> onError<E extends Object>(
    FutureOr<T> handleError(E error, StackTrace stackTrace),
    {bool test(E error)?}) {
  // There are various ways to optimize this to avoid the double is E/as E
  // type check, but for now we are not optimizing the error path.
  return this.catchError(
      (Object error, StackTrace stackTrace) =>
          handleError(error as E, stackTrace),
      test: (Object error) => error is E && (test == null || test(error)));
}