保誠-保戶業務員媒合平台
編輯 | 究查 | 歷程 | 原始

Basic Types

Node Addon API consists of a few fundamental data types. These allow a user of
the API to create, convert and introspect fundamental JavaScript types, and
interoperate with their C++ counterparts.

Value

Napi::Value is the base class of Node Addon API's fundamental object type hierarchy.
It represents a JavaScript value of an unknown type. It is a thin wrapper around
the N-API datatype napi_value. Methods on this class can be used to check
the JavaScript type of the underlying N-API napi_value and also to convert to
C++ types.

Constructor

Napi::Value::Value();

Used to create a Node Addon API Napi::Value that represents an empty value.

Napi::Value::Value(napi_env env, napi_value value);
  • [in] env - The napi_env environment in which to construct the Napi::Value
    object.
  • [in] value - The underlying JavaScript value that the Napi::Value instance
    represents.

Returns a Node.js Addon API Napi::Value that represents the napi_value passed
in.

Operators

operator napi_value

Napi::Value::operator napi_value() const;

Returns the underlying N-API napi_value. If the instance is empty, this
returns nullptr.

operator ==

bool Napi::Value::operator ==(const Value& other) const;

Returns true if this value strictly equals another value, or false otherwise.

operator !=

bool Napi::Value::operator !=(const Value& other) const;

Returns false if this value strictly equals another value, or true otherwise.

Methods

From

template <typename T>
static Napi::Value Napi::Value::From(napi_env env, const T& value);
  • [in] env - The napi_env environment in which to construct the Napi::Value object.
  • [in] value - The C++ type to represent in JavaScript.

Returns a Napi::Value representing the input C++ type in JavaScript.

This method is used to convert from a C++ type to a JavaScript value.
Here, value may be any of:
- bool - returns a Napi::Boolean.
- Any integer type - returns a Napi::Number.
- Any floating point type - returns a Napi::Number.
- const char* (encoded using UTF-8, null-terminated) - returns a Napi::String.
- const char16_t* (encoded using UTF-16-LE, null-terminated) - returns a Napi::String.
- std::string (encoded using UTF-8) - returns a Napi::String.
- std::u16string - returns a Napi::String.
- napi::Value - returns a Napi::Value.
- napi_value - returns a Napi::Value.

As

template <typename T> T Napi::Value::As() const;

Returns the Napi::Value cast to a desired C++ type.

Use this when the actual type is known or assumed.

Note:
This conversion does NOT coerce the type. Calling any methods inappropriate for
the actual value type will throw Napi::Error.

StrictEquals

bool Napi::Value::StrictEquals(const Value& other) const;
  • [in] other - The value to compare against.

Returns true if the other Napi::Value is strictly equal to this one.

Env

Napi::Env Napi::Value::Env() const;

Returns the environment that the value is associated with. See
Napi::Env for more details about environments.

IsEmpty

bool Napi::Value::IsEmpty() const;

Returns true if the value is uninitialized.

An empty value is invalid, and most attempts to perform an operation on an
empty value will result in an exception. An empty value is distinct from
JavaScript null or undefined, which are valid values.

When C++ exceptions are disabled at compile time, a method with a Napi::Value
return type may return an empty value to indicate a pending exception. If C++
exceptions are not being used, callers should check the result of
Env::IsExceptionPending before attempting to use the value.

Type

napi_valuetype Napi::Value::Type() const;

Returns the underlying N-API napi_valuetype of the value.

IsUndefined

bool Napi::Value::IsUndefined() const;

Returns true if the underlying value is a JavaScript undefined or false
otherwise.

IsNull

bool Napi::Value::IsNull() const;

Returns true if the underlying value is a JavaScript null or false
otherwise.

IsBoolean

bool Napi::Value::IsBoolean() const;

Returns true if the underlying value is a JavaScript true or JavaScript
false, or false if the value is not a Napi::Boolean value in JavaScript.

IsNumber

bool Napi::Value::IsNumber() const;

Returns true if the underlying value is a JavaScript Napi::Number or false
otherwise.

IsString

bool Napi::Value::IsString() const;

Returns true if the underlying value is a JavaScript Napi::String or false
otherwise.

IsSymbol

bool Napi::Value::IsSymbol() const;

Returns true if the underlying value is a JavaScript Napi::Symbol or false
otherwise.

IsArray

bool Napi::Value::IsArray() const;

Returns true if the underlying value is a JavaScript Napi::Array or false
otherwise.

IsArrayBuffer

bool Napi::Value::IsArrayBuffer() const;

Returns true if the underlying value is a JavaScript Napi::ArrayBuffer or false
otherwise.

IsTypedArray

bool Napi::Value::IsTypedArray() const;

Returns true if the underlying value is a JavaScript Napi::TypedArray or false
otherwise.

IsObject

bool Napi::Value::IsObject() const;

Returns true if the underlying value is a JavaScript Napi::Object or false
otherwise.

IsFunction

bool Napi::Value::IsFunction() const;

Returns true if the underlying value is a JavaScript Napi::Function or false
otherwise.

IsPromise

bool Napi::Value::IsPromise() const;

Returns true if the underlying value is a JavaScript Napi::Promise or false
otherwise.

IsDataView

bool Napi::Value::IsDataView() const;

Returns true if the underlying value is a JavaScript Napi::DataView or false
otherwise.

IsBuffer

bool Napi::Value::IsBuffer() const;

Returns true if the underlying value is a Node.js Napi::Buffer or false
otherwise.

IsExternal

bool Napi::Value::IsExternal() const;

Returns true if the underlying value is a N-API external object or false
otherwise.

ToBoolean

Napi::Boolean Napi::Value::ToBoolean() const;

Returns a Napi::Boolean representing the Napi::Value.

This is a wrapper around napi_coerce_to_boolean. This will throw a JavaScript
exception if the coercion fails. If C++ exceptions are not being used, callers
should check the result of Env::IsExceptionPending before attempting to use
the returned value.

ToNumber

Napi::Number Napi::Value::ToNumber() const;

Returns a Napi::Number representing the Napi::Value.

Note:
This can cause script code to be executed according to JavaScript semantics.
This is a wrapper around napi_coerce_to_number. This will throw a JavaScript
exception if the coercion fails. If C++ exceptions are not being used, callers
should check the result of Env::IsExceptionPending before attempting to use
the returned value.

ToString

Napi::String Napi::Value::ToString() const;

Returns a Napi::String representing the Napi::Value.

Note that this can cause script code to be executed according to JavaScript
semantics. This is a wrapper around napi_coerce_to_string. This will throw a
JavaScript exception if the coercion fails. If C++ exceptions are not being
used, callers should check the result of Env::IsExceptionPending before
attempting to use the returned value.

ToObject

Napi::Object Napi::Value::ToObject() const;

Returns a Napi::Object representing the Napi::Value.

This is a wrapper around napi_coerce_to_object. This will throw a JavaScript
exception if the coercion fails. If C++ exceptions are not being used, callers
should check the result of Env::IsExceptionPending before attempting to use
the returned value.

Name

Names are JavaScript values that can be used as a property name. There are two
specialized types of names supported in Node.js Addon API Napi::String
and Napi::Symbol.

Methods

Constructor

Napi::Name::Name();

Returns an empty Napi::Name.

Napi::Name::Name(napi_env env, napi_value value);
  • [in] env - The environment in which to create the array.
  • [in] value - The primitive to wrap.

Returns a Napi::Name created from the JavaScript primitive.

Note:
The value is not coerced to a string.

Array

Arrays are native representations of JavaScript Arrays. Napi::Array is a wrapper
around napi_value representing a JavaScript Array.

Napi::TypedArray and Napi::ArrayBuffer correspond to JavaScript data
types such as Int32Array and ArrayBuffer, respectively, that can be
used for transferring large amounts of data from JavaScript to the native side.
An example illustrating the use of a JavaScript-provided ArrayBuffer in native
code is available here.

Constructor

Napi::Array::Array();

Returns an empty array.

If an error occurs, a Napi::Error will be thrown. If C++ exceptions are not
being used, callers should check the result of Env::IsExceptionPending before
attempting to use the returned value.

Napi::Array::Array(napi_env env, napi_value value);
  • [in] env - The environment in which to create the array.
  • [in] value - The primitive to wrap.

Returns a Napi::Array wrapping a napi_value.

If an error occurs, a Napi::Error will get thrown. If C++ exceptions are not
being used, callers should check the result of Env::IsExceptionPending before
attempting to use the returned value.

Methods

New

static Napi::Array Napi::Array::New(napi_env env);
  • [in] env - The environment in which to create the array.

Returns a new Napi::Array.

If an error occurs, a Napi::Error will get thrown. If C++ exceptions are not
being used, callers should check the result of Env::IsExceptionPending before
attempting to use the returned value.

New

static Napi::Array Napi::Array::New(napi_env env, size_t length);
  • [in] env - The environment in which to create the array.
  • [in] length - The length of the array.

Returns a new Napi::Array with the given length.

If an error occurs, a Napi::Error will get thrown. If C++ exceptions are not
being used, callers should check the result of Env::IsExceptionPending before
attempting to use the returned value.

Length

uint32_t Napi::Array::Length() const;

Returns the length of the array.

Note:
This can execute JavaScript code implicitly according to JavaScript semantics.
If an error occurs, a Napi::Error will get thrown. If C++ exceptions are not
being used, callers should check the result of Env::IsExceptionPending before
attempting to use the returned value.