dart:async

Метод onError<E extends Object>

Обрабатывает ошибки в этом будущем.

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

Если ошибка перехвачена, возвращаемое будущее завершается результатом вызова handleError с ошибкой и стеком вызовов. Этот результат должен быть значением того же типа, с которым это будущее могло бы завершиться иначе. Например, если это будущее не может завершиться значением 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 выбрасывает исключение, возвращаемое будущее завершается сброшенной ошибкой и стеком вызовов, за исключением случаев, когда оно снова выбрасывает тот же объект ошибки, в этом случае это считается «перевыбрасыванием», и сохраняется исходный стек вызовов. Это может быть использовано в качестве альтернативы пропуску ошибки в 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.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)));
}