Promise.prototype.catch()

Метод catch() экземпляров Promise планирует вызов функции, когда промис отклоняется (отвергается). Он немедленно возвращает другой объект Promise, позволяя вам составлять цепочки вызовов других методов промиса. Это сокращение для then(undefined, onRejected).

Попробовать

const promise = new Promise((resolve, reject) => {
  throw new Error("Uh-oh!");
});

promise.catch((error) => {
  console.error(error);
});
// Expected output: Error: Uh-oh!

Синтаксис

promiseInstance.catch(onRejected)

Параметры

onRejected

Функция для асинхронного выполнения, когда этот промис становится отклоненным (отвергнутым). Её возвращаемое значение становится значением исполнения промиса, возвращенного catch(). Функция вызывается со следующими аргументами:

reason

Значение, с которым был отклонен промис.

Возвращаемое значение

Возвращает новый Promise. Этот новый промис всегда находится в состоянии ожидания (pending) при возврате, независимо от статуса текущего промиса. Если вызывается onRejected, возвращенный промис будет разрешен (resolved) на основе возвращаемого значения этого вызова или отклонен (rejected) с ошибкой, выброшенной этим вызовом. Если текущий промис исполняется (fulfills), onRejected не вызывается, и возвращенный промис исполняется с тем же значением.

Описание

Метод catch используется для обработки ошибок в композиции промисов. Поскольку он возвращает Promise, его можно использовать в цепочке так же, как и его родственный метод, then().

Если промис отклоняется, и нет обработчиков отклонения для вызова (обработчик может быть присоединен через любой из then(), catch() или finally()), то событие отклонения выводится хостом. В браузере это приводит к событию unhandledrejection. Если обработчик присоединен к отклоненному промису, отклонение которого уже вызвало необработанное событие отклонения, то запускается еще одно событие rejectionhandled.

catch() внутренне вызывает then() для объекта, на котором он был вызван, передавая undefined и onRejected в качестве аргументов. Значение этого вызова возвращается напрямую. Это можно наблюдать, если вы обернете методы.

// overriding original Promise.prototype.then/catch just to add some logs
((Promise) => {
  const originalThen = Promise.prototype.then;
  const originalCatch = Promise.prototype.catch;

  Promise.prototype.then = function (...args) {
    console.log("Called .then on %o with arguments: %o", this, args);
    return originalThen.apply(this, args);
  };
  Promise.prototype.catch = function (...args) {
    console.error("Called .catch on %o with arguments: %o", this, args);
    return originalCatch.apply(this, args);
  };
})(Promise);

// calling catch on an already resolved promise
Promise.resolve().catch(function XXX() {});

// Logs:
// Called .catch on Promise{} with arguments: Arguments{1} [0: function XXX()]
// Called .then on Promise{} with arguments: Arguments{2} [0: undefined, 1: function XXX()]

Это означает, что передача undefined по-прежнему приводит к отклонению возвращаемого промиса, и вам нужно передать функцию, чтобы предотвратить отклонение финального промиса.

Поскольку catch() просто вызывает then(), он поддерживает создание подклассов.

Примеры

Использование и создание цепочки метода catch()

const p1 = new Promise((resolve, reject) => {
  resolve("Success");
});

p1.then((value) => {
  console.log(value); // "Success!"
  throw new Error("oh, no!");
})
  .catch((e) => {
    console.error(e.message); // "oh, no!"
  })
  .then(
    () => console.log("after a catch the chain is restored"), // "after a catch the chain is restored"
    () => console.log("Not fired due to the catch"),
  );

// The following behaves the same as above
p1.then((value) => {
  console.log(value); // "Success!"
  return Promise.reject(new Error("oh, no!"));
})
  .catch((e) => {
    console.error(e); // Error: oh, no!
  })
  .then(
    () => console.log("after a catch the chain is restored"), // "after a catch the chain is restored"
    () => console.log("Not fired due to the catch"),
  );

Подводные камни при выбрасывании ошибок

Выбрасывание ошибки в большинстве случаев вызовет метод catch():

const p1 = new Promise((resolve, reject) => {
  throw new Error("Uh-oh!");
});

p1.catch((e) => {
  console.error(e); // "Uh-oh!"
});

Ошибки, выброшенные внутри асинхронных функций, будут действовать как необработанные ошибки:

const p2 = new Promise((resolve, reject) => {
  setTimeout(() => {
    throw new Error("Uncaught Exception!");
  }, 1000);
});

p2.catch((e) => {
  console.error(e); // This is never called
});

Ошибки, выброшенные после вызова resolve, будут подавлены:

const p3 = new Promise((resolve, reject) => {
  resolve();
  throw new Error("Silenced Exception!");
});

p3.catch((e) => {
  console.error(e); // This is never called
});

catch() не вызывается, если промис исполнен

// Create a promise which would not call onReject
const p1 = Promise.resolve("calling next");

const p2 = p1.catch((reason) => {
  // This is never called
  console.error("catch p1!");
  console.error(reason);
});

p2.then(
  (value) => {
    console.log("next promise's onFulfilled");
    console.log(value); // calling next
  },
  (reason) => {
    console.log("next promise's onRejected");
    console.log(reason);
  },
);

Спецификации

Совместимость с браузерами

См. также

• Promise
• Promise.prototype.then()
• Promise.prototype.finally()