Promise

Promise

Napi::Promise 类继承自 Napi::Object 类。

Napi::Promise 类与其内部的 Napi::Promise::Deferred 类配合，实现了创建、解析（resolve）和拒绝（reject）Promise 对象的能力。

基本使用方式是：创建一个 Napi::Promise::Deferred 延迟对象，将该对象的 Napi::Promise::Deferred::Promise 方法返回值返回给调用方。示例如下：

Napi::Value YourFunction(const Napi::CallbackInfo& info) {
  // 业务逻辑代码写在这里...
  Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(info.Env());
  // 需保证 deferred 对象在当前调用结束后仍能存活...
  return deferred.Promise();
}

后续当异步流程完成时，调用此前创建的 Napi::Promise::Deferred 对象的 Resolve 或 Reject 方法：

  deferred.Resolve(String::New(info.Env(), "OK"));

Promise::Deferred 方法

工厂方法（Factory Method）

static Napi::Promise::Deferred Napi::Promise::Deferred::New(napi_env env);

• [in] env：用于创建 Napi::Promise::Deferred 对象的 napi_env 运行环境。

构造函数（Constructor）

Napi::Promise::Deferred(napi_env env);

• [in] env：用于构造 Napi::Promise::Deferred 对象的 napi_env 运行环境。

Env

Napi::Env Napi::Promise::Deferred::Env() const;

返回当前 Napi::Promise::Deferred 对象关联的 Napi::Env 运行环境。

Promise

Napi::Promise Napi::Promise::Deferred::Promise() const;

返回 Napi::Promise::Deferred 对象持有的 Napi::Promise 对象。

Resolve

void Napi::Promise::Deferred::Resolve(napi_value value) const;

解析（resolve）Napi::Promise::Deferred 对象持有的 Napi::Promise 对象。

• [in] value：用于解析该 Napi::Promise 的 Node-API 原始值。

Reject

void Napi::Promise::Deferred::Reject(napi_value value) const;

拒绝（reject）Napi::Promise::Deferred 对象持有的 Napi::Promise 对象。

• [in] value：用于拒绝该 Napi::Promise 的 Node-API 原始值。

Promise 方法

Then

Napi::Promise Napi::Promise::Then(napi_value onFulfilled) const;
Napi::Promise Napi::Promise::Then(const Function& onFulfilled) const;

为 Promise 附加成功回调函数，并返回一个新的 Promise。

参数：

• [in] onFulfilled：Promise 成功时的回调函数，支持以下类型：
  • napi_value – Promise 解析成功时调用的 JavaScript 函数。
  • const Function& – Promise 解析成功时调用的 Napi::Function 对象。

返回值：一个新的 Napi::Promise，其解析 / 拒绝状态由回调函数的执行结果决定。

Then

Napi::Promise Napi::Promise::Then(napi_value onFulfilled, napi_value onRejected) const;
Napi::Promise Napi::Promise::Then(const Function& onFulfilled,
                                  const Function& onRejected) const;

为 Promise 同时附加成功和失败回调函数，并返回一个新的 Promise。

参数：

• [in] onFulfilled：Promise 成功时的回调函数，支持以下类型：
  • napi_value – Promise 解析成功时调用的 JavaScript 函数。
  • const Function& – Promise 解析成功时调用的 Napi::Function 对象。
• [in] onRejected（可选）：Promise 失败时的回调函数，支持以下类型：
  • napi_value – Promise 被拒绝时调用的 JavaScript 函数。
  • const Function& – Promise 被拒绝时调用的 Napi::Function 对象。

Catch

Napi::Promise Napi::Promise::Catch(napi_value onRejected) const;
Napi::Promise Napi::Promise::Catch(const Function& onRejected) const;

为 Promise 附加失败回调函数，并返回一个新的 Promise。

参数：

• [in] onRejected：Promise 失败时的回调函数，支持以下类型：
  • napi_value – Promise 被拒绝时调用的 JavaScript 函数。
  • const Function& – Promise 被拒绝时调用的 Napi::Function 对象。

返回值：一个用于处理拒绝场景的新 Napi::Promise。