Node.js v25.0.0 文件

node-gyp#

node-gyp 是一個基於 Google 的 GYP 工具的 gyp-next 分支的構建系統，並與 npm 捆綁在一起。GYP，因此 node-gyp，要求安裝 Python。

歷史上，node-gyp 一直是構建原生外掛的首選工具。它得到了廣泛的採用和文件支援。然而，一些開發人員在使用 node-gyp 時遇到了限制。

CMake.js#

CMake.js 是一個基於 CMake 的替代構建系統。

CMake.js 是已經使用 CMake 的專案或受 node-gyp 限制影響的開發人員的不錯選擇。build_with_cmake 是一個基於 CMake 的原生外掛專案示例。

node-pre-gyp#

node-pre-gyp 是一個基於 node-gyp 的工具，增加了將二進位制檔案上傳到開發人員選擇的伺服器的能力。node-pre-gyp 對上傳二進位制檔案到 Amazon S3 有特別好的支援。

prebuild#

prebuild 是一個支援使用 node-gyp 或 CMake.js 進行構建的工具。與支援各種伺服器的 node-pre-gyp 不同，prebuild 只將二進位制檔案上傳到 GitHub releases。prebuild 是使用 CMake.js 的 GitHub 專案的不錯選擇。

prebuildify#

prebuildify 是一個基於 node-gyp 的工具。prebuildify 的優點是，當原生外掛上傳到 npm 時，構建的二進位制檔案會與原生外掛捆綁在一起。二進位制檔案從 npm 下載，並在安裝原生外掛時立即可供模組使用者使用。

napi_handle_scope#

這是一種抽象，用於控制和修改在特定作用域內建立的物件的生命週期。通常，Node-API 值是在控制代碼作用域的上下文中建立的。當從 JavaScript 呼叫原生方法時，將存在一個預設控制代碼作用域。如果使用者未顯式建立新的控制代碼作用域，Node-API 值將在預設控制代碼作用域中建立。對於原生方法執行之外的任何程式碼呼叫（例如，在 libuv 回撥呼叫期間），模組必須在呼叫任何可能導致建立 JavaScript 值的函式之前建立一個作用域。

控制代碼作用域使用 napi_open_handle_scope 建立，並使用 napi_close_handle_scope 銷燬。關閉作用域可以向垃圾回收器指示，在控制代碼作用域生命週期內建立的所有 napi_values 不再從當前棧幀中引用。

有關更多詳細資訊，請查閱物件生命週期管理。

napi_escapable_handle_scope#

可逃逸控制代碼作用域是一種特殊型別的控制代碼作用域，用於將特定控制代碼作用域內建立的值返回到父作用域。

napi_ref#

這是用於引用 napi_value 的抽象。這允許使用者管理 JavaScript 值的生命週期，包括顯式定義其最短生命週期。

有關更多詳細資訊，請查閱物件生命週期管理。

napi_type_tag#

一個 128 位的值，儲存為兩個無符號的 64 位整數。它用作 UUID，可用於“標記”JavaScript 物件或外部物件，以確保它們是特定型別。這比napi_instanceof更強的檢查，因為後者如果物件的原型被操作可能會報告誤報。型別標記與napi_wrap結合使用最有用，因為它確保從包裝物件檢索到的指標可以安全地轉換為與之前應用於 JavaScript 物件的型別標記相對應的原生型別。

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag; copy

napi_async_cleanup_hook_handle#

由 napi_add_async_cleanup_hook 返回的不透明值。當非同步清理事件鏈完成時，必須將其傳遞給 napi_remove_async_cleanup_hook。

napi_callback_info#

傳遞給回撥函式的不透明資料型別。它可用於獲取有關呼叫回撥的上下文的附加資訊。

napi_callback#

函式指標型別，用於透過 Node-API 公開給 JavaScript 的使用者提供的原生函式。回撥函式應滿足以下簽名：

typedef napi_value (*napi_callback)(napi_env, napi_callback_info); copy

除非出於物件生命週期管理中討論的原因，否則在 napi_callback 內部建立控制代碼和/或回撥作用域不是必需的。

node_api_basic_finalize#

外掛提供的函式指標型別，允許使用者在外部擁有的資料準備好被清理時收到通知，因為與其關聯的物件已被垃圾回收。使用者必須提供一個滿足以下簽名的函式，該函式將在物件被回收時呼叫。目前，node_api_basic_finalize 可用於發現何時回收具有外部資料的物件。

typedef void (*node_api_basic_finalize)(node_api_basic_env env,
                                      void* finalize_data,
                                      void* finalize_hint); copy

除非出於物件生命週期管理中討論的原因，否則在函式體內部建立控制代碼和/或回撥作用域不是必需的。

由於這些函式可能在 JavaScript 引擎處於無法執行 JavaScript 程式碼的狀態下呼叫，因此只能呼叫接受 node_api_basic_env 作為其第一個引數的 Node-API。在當前垃圾回收週期完成後，可以使用 node_api_post_finalizer 來安排需要訪問 JavaScript 引擎狀態的 Node-API 呼叫執行。

在node_api_create_external_string_latin1和node_api_create_external_string_utf16的情況下，env引數可能為null，因為外部字串可以在環境關閉的後期被收集。

變更歷史

• 實驗性 (NAPI_EXPERIMENTAL)

  只能呼叫接受 node_api_basic_env 作為其第一個引數的 Node-API，否則應用程式將以適當的錯誤訊息終止。此功能可以透過定義 NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT 來關閉。

napi_finalize#

外掛提供的函式指標型別，允許使用者在垃圾回收事件響應中，在垃圾回收週期完成後，安排一組對 Node-API 的呼叫。這些函式指標可以與 node_api_post_finalizer 一起使用。

typedef void (*napi_finalize)(napi_env env,
                              void* finalize_data,
                              void* finalize_hint); copy

變更歷史

• 實驗性 (已定義 NAPI_EXPERIMENTAL)

  這種型別的函式可能不再用作終結器，除了與 node_api_post_finalizer 一起使用。必須改用 node_api_basic_finalize。此功能可以透過定義 NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT 來關閉。

napi_async_execute_callback#

與支援非同步操作的函式一起使用的函式指標。回撥函式必須滿足以下簽名：

typedef void (*napi_async_execute_callback)(napi_env env, void* data); copy

此函式的實現必須避免進行執行 JavaScript 或與 JavaScript 物件互動的 Node-API 呼叫。Node-API 呼叫應改在 napi_async_complete_callback 中。請勿使用 napi_env 引數，因為它很可能導致 JavaScript 的執行。

napi_async_complete_callback#

與支援非同步操作的函式一起使用的函式指標。回撥函式必須滿足以下簽名：

typedef void (*napi_async_complete_callback)(napi_env env,
                                             napi_status status,
                                             void* data); copy

除非出於物件生命週期管理中討論的原因，否則在函式體內部建立控制代碼和/或回撥作用域不是必需的。

napi_threadsafe_function_call_js#

與非同步執行緒安全函式呼叫一起使用的函式指標。回撥將在主執行緒上呼叫。其目的是使用從輔助執行緒透過佇列到達的資料項來構建呼叫 JavaScript 所需的引數，通常透過 napi_call_function，然後進行 JavaScript 呼叫。

透過佇列從輔助執行緒到達的資料在 data 引數中給出，要呼叫的 JavaScript 函式在 js_callback 引數中給出。

Node-API 在呼叫此回撥之前設定環境，因此透過 napi_call_function 而不是透過 napi_make_callback 呼叫 JavaScript 函式就足夠了。

回撥函式必須滿足以下簽名：

typedef void (*napi_threadsafe_function_call_js)(napi_env env,
                                                 napi_value js_callback,
                                                 void* context,
                                                 void* data); copy

• [in] env: 用於 API 呼叫的環境，如果執行緒安全函式正在銷燬且 data 可能需要釋放，則為 NULL。
• [in] js_callback: 要呼叫的 JavaScript 函式，如果執行緒安全函式正在銷燬且 data 可能需要釋放，則為 NULL。如果建立執行緒安全函式時沒有 js_callback，它也可以是 NULL。
• [in] context: 建立執行緒安全函式時使用的可選資料。
• [in] data: 由輔助執行緒建立的資料。回撥負責將此原生資料轉換為 JavaScript 值（使用 Node-API 函式），這些值可以在呼叫 js_callback 時作為引數傳遞。此指標完全由執行緒和此回撥管理。因此，此回撥應釋放資料。

除非出於物件生命週期管理中討論的原因，否則在函式體內部建立控制代碼和/或回撥作用域不是必需的。

napi_cleanup_hook#

與 napi_add_env_cleanup_hook 一起使用的函式指標。當環境被銷燬時將呼叫它。

回撥函式必須滿足以下簽名：

typedef void (*napi_cleanup_hook)(void* data); copy

• [in] data: 傳遞給 napi_add_env_cleanup_hook 的資料。

napi_async_cleanup_hook#

與 napi_add_async_cleanup_hook 一起使用的函式指標。當環境被銷燬時將呼叫它。

回撥函式必須滿足以下簽名：

typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
                                        void* data); copy

• [in] handle: 在非同步清理完成後必須傳遞給 napi_remove_async_cleanup_hook 的控制代碼。
• [in] data: 傳遞給 napi_add_async_cleanup_hook 的資料。

函式體應啟動非同步清理操作，在非同步清理完成後，必須將 handle 傳遞給 napi_remove_async_cleanup_hook。

napi_get_last_error_info#

napi_status
napi_get_last_error_info(node_api_basic_env env,
                         const napi_extended_error_info** result); copy

• [in] env: 呼叫 API 的環境。
• [out] result: 包含更多錯誤資訊的 napi_extended_error_info 結構。

如果 API 成功，則返回 napi_ok。

此 API 檢索包含上次發生錯誤資訊的 napi_extended_error_info 結構。

返回的 napi_extended_error_info 的內容僅在對同一 env 呼叫 Node-API 函式之前有效。這包括對 napi_is_exception_pending 的呼叫，因此通常需要複製資訊以便以後使用。error_message 中返回的指標指向一個靜態定義的字串，因此如果在呼叫另一個 Node-API 函式之前已將其從 error_message 欄位（將被覆蓋）中複製出來，則使用該指標是安全的。

不要依賴任何擴充套件資訊的內容或格式，因為它不受 SemVer 約束，並且可能隨時更改。它僅用於日誌記錄目的。

即使有待處理的 JavaScript 異常，也可以呼叫此 API。

napi_throw#

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); copy

• [in] env: 呼叫 API 的環境。
• [in] error: 要丟擲的 JavaScript 值。

如果 API 成功，則返回 napi_ok。

此 API 丟擲提供的 JavaScript 值。

napi_throw_error#

NAPI_EXTERN napi_status napi_throw_error(napi_env env,
                                         const char* code,
                                         const char* msg); copy

• [in] env: 呼叫 API 的環境。
• [in] code: 要在錯誤上設定的可選錯誤程式碼。
• [in] msg: 表示與錯誤關聯文字的 C 字串。

如果 API 成功，則返回 napi_ok。

此 API 丟擲帶有提供的文字的 JavaScript Error。

napi_throw_type_error#

NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
                                              const char* code,
                                              const char* msg); copy

• [in] env: 呼叫 API 的環境。
• [in] code: 要在錯誤上設定的可選錯誤程式碼。
• [in] msg: 表示與錯誤關聯文字的 C 字串。

如果 API 成功，則返回 napi_ok。

此 API 丟擲帶有提供的文字的 JavaScript TypeError。

napi_throw_range_error#

NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
                                               const char* code,
                                               const char* msg); copy

• [in] env: 呼叫 API 的環境。
• [in] code: 要在錯誤上設定的可選錯誤程式碼。
• [in] msg: 表示與錯誤關聯文字的 C 字串。

如果 API 成功，則返回 napi_ok。

此 API 丟擲帶有提供的文字的 JavaScript RangeError。

node_api_throw_syntax_error#

NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
                                                    const char* code,
                                                    const char* msg); copy

• [in] env: 呼叫 API 的環境。
• [in] code: 要在錯誤上設定的可選錯誤程式碼。
• [in] msg: 表示與錯誤關聯文字的 C 字串。

如果 API 成功，則返回 napi_ok。

此 API 丟擲帶有提供的文字的 JavaScript SyntaxError。

napi_is_error#

NAPI_EXTERN napi_status napi_is_error(napi_env env,
                                      napi_value value,
                                      bool* result); copy

• [in] env: 呼叫 API 的環境。
• [in] value: 要檢查的 napi_value。
• [out] result: 如果 napi_value 表示錯誤，則設定為 true 的布林值，否則為 false。

如果 API 成功，則返回 napi_ok。

此 API 查詢 napi_value 以檢查它是否表示錯誤物件。

napi_create_error#

NAPI_EXTERN napi_status napi_create_error(napi_env env,
                                          napi_value code,
                                          napi_value msg,
                                          napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] code: 可選的 napi_value，包含要與錯誤關聯的錯誤程式碼字串。
• [in] msg: 引用 JavaScript string 的 napi_value，用作 Error 的訊息。
• [out] result: 表示已建立錯誤的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回帶有提供的文字的 JavaScript Error。

napi_create_type_error#

NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
                                               napi_value code,
                                               napi_value msg,
                                               napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] code: 可選的 napi_value，包含要與錯誤關聯的錯誤程式碼字串。
• [in] msg: 引用 JavaScript string 的 napi_value，用作 Error 的訊息。
• [out] result: 表示已建立錯誤的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回帶有提供的文字的 JavaScript TypeError。

napi_create_range_error#

NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
                                                napi_value code,
                                                napi_value msg,
                                                napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] code: 可選的 napi_value，包含要與錯誤關聯的錯誤程式碼字串。
• [in] msg: 引用 JavaScript string 的 napi_value，用作 Error 的訊息。
• [out] result: 表示已建立錯誤的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回帶有提供的文字的 JavaScript RangeError。

node_api_create_syntax_error#

NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
                                                     napi_value code,
                                                     napi_value msg,
                                                     napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] code: 可選的 napi_value，包含要與錯誤關聯的錯誤程式碼字串。
• [in] msg: 引用 JavaScript string 的 napi_value，用作 Error 的訊息。
• [out] result: 表示已建立錯誤的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回帶有提供的文字的 JavaScript SyntaxError。

napi_get_and_clear_last_exception#

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [out] result: 如果有異常待處理，則為異常，否則為 NULL。

如果 API 成功，則返回 napi_ok。

即使有待處理的 JavaScript 異常，也可以呼叫此 API。

napi_is_exception_pending#

napi_status napi_is_exception_pending(napi_env env, bool* result); copy

• [in] env: 呼叫 API 的環境。
• [out] result: 如果有異常待處理，則設定為 true 的布林值。

如果 API 成功，則返回 napi_ok。

即使有待處理的 JavaScript 異常，也可以呼叫此 API。

napi_fatal_exception#

napi_status napi_fatal_exception(napi_env env, napi_value err); copy

• [in] env: 呼叫 API 的環境。
• [in] err: 傳遞給 'uncaughtException' 的錯誤。

在 JavaScript 中觸發一個 'uncaughtException'。如果非同步回撥丟擲異常且無法恢復，此功能非常有用。

napi_fatal_error#

NAPI_NO_RETURN void napi_fatal_error(const char* location,
                                     size_t location_len,
                                     const char* message,
                                     size_t message_len); copy

• [in] location: 發生錯誤的可選位置。
• [in] location_len: 位置的位元組長度，如果以 null 結尾，則為 NAPI_AUTO_LENGTH。
• [in] message: 與錯誤關聯的訊息。
• [in] message_len: 訊息的位元組長度，如果以 null 結尾，則為 NAPI_AUTO_LENGTH。

函式呼叫不返回，程序將終止。

即使有待處理的 JavaScript 異常，也可以呼叫此 API。

napi_open_handle_scope#

NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
                                               napi_handle_scope* result); copy

• [in] env: 呼叫 API 的環境。
• [out] result: 表示新作用域的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 開啟一個新的作用域。

napi_close_handle_scope#

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope); copy

• [in] env: 呼叫 API 的環境。
• [in] scope: 表示要關閉的作用域的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 關閉傳入的作用域。作用域必須按照建立的相反順序關閉。

即使有待處理的 JavaScript 異常，也可以呼叫此 API。

napi_open_escapable_handle_scope#

NAPI_EXTERN napi_status
    napi_open_escapable_handle_scope(napi_env env,
                                     napi_handle_scope* result); copy

• [in] env: 呼叫 API 的環境。
• [out] result: 表示新作用域的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 開啟一個新作用域，其中一個物件可以被提升到外部作用域。

napi_close_escapable_handle_scope#

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope); copy

• [in] env: 呼叫 API 的環境。
• [in] scope: 表示要關閉的作用域的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 關閉傳入的作用域。作用域必須按照建立的相反順序關閉。

即使有待處理的 JavaScript 異常，也可以呼叫此 API。

napi_escape_handle#

napi_status napi_escape_handle(napi_env env,
                               napi_escapable_handle_scope scope,
                               napi_value escapee,
                               napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] scope: 表示當前作用域的 napi_value。
• [in] escapee: 表示要逃逸的 JavaScript Object 的 napi_value。
• [out] result: 表示外部作用域中逃逸 Object 控制代碼的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 提升 JavaScript 物件的控制代碼，使其在外部作用域的生命週期內有效。每個作用域只能呼叫一次。如果呼叫多次，將返回錯誤。

即使有待處理的 JavaScript 異常，也可以呼叫此 API。

napi_create_reference#

NAPI_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              uint32_t initial_refcount,
                                              napi_ref* result); copy

• [in] env: 呼叫 API 的環境。
• [in] value: 正在為其建立引用的 napi_value。
• [in] initial_refcount: 新引用的初始引用計數。
• [out] result: 指向新引用的 napi_ref。

如果 API 成功，則返回 napi_ok。

此 API 建立一個新引用，其引用計數為指定值，指向傳入的值。

napi_delete_reference#

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); copy

• [in] env: 呼叫 API 的環境。
• [in] ref: 要刪除的 napi_ref。

如果 API 成功，則返回 napi_ok。

此 API 刪除傳入的引用。

即使有待處理的 JavaScript 異常，也可以呼叫此 API。

napi_reference_ref#

NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
                                           napi_ref ref,
                                           uint32_t* result); copy

• [in] env: 呼叫 API 的環境。
• [in] ref: 引用計數將遞增的 napi_ref。
• [out] result: 新的引用計數。

如果 API 成功，則返回 napi_ok。

此 API 遞增傳入引用的引用計數並返回結果引用計數。

napi_reference_unref#

NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
                                             napi_ref ref,
                                             uint32_t* result); copy

• [in] env: 呼叫 API 的環境。
• [in] ref: 引用計數將遞減的 napi_ref。
• [out] result: 新的引用計數。

如果 API 成功，則返回 napi_ok。

此 API 遞減傳入引用的引用計數並返回結果引用計數。

napi_get_reference_value#

NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
                                                 napi_ref ref,
                                                 napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] ref: 正在請求其對應值的 napi_ref。
• [out] result: 由 napi_ref 引用的 napi_value。

如果 API 成功，則返回 napi_ok。

如果仍然有效，此 API 返回表示與 napi_ref 關聯的 JavaScript 值的 napi_value。否則，result 將為 NULL。

napi_add_env_cleanup_hook#

NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
                                                  napi_cleanup_hook fun,
                                                  void* arg); copy

註冊 fun 作為噹噹前 Node.js 環境退出時，使用 arg 引數執行的函式。

可以安全地多次指定具有不同 arg 值的函式。在這種情況下，它也將被多次呼叫。多次提供相同的 fun 和 arg 值是不允許的，會導致程序中止。

鉤子將以相反的順序呼叫，即最近新增的鉤子將首先呼叫。

可以使用 napi_remove_env_cleanup_hook 移除此鉤子。通常，當新增此鉤子的資源被拆除時，就會發生這種情況。

對於非同步清理，可以使用 napi_add_async_cleanup_hook。

napi_remove_env_cleanup_hook#

NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
                                                     void (*fun)(void* arg),
                                                     void* arg); copy

登出 fun 作為噹噹前 Node.js 環境退出時，使用 arg 引數執行的函式。引數和函式值都必須完全匹配。

該函式必須最初透過 napi_add_env_cleanup_hook 註冊，否則程序將中止。

napi_add_async_cleanup_hook#

NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
    node_api_basic_env env,
    napi_async_cleanup_hook hook,
    void* arg,
    napi_async_cleanup_hook_handle* remove_handle); copy

• [in] env: 呼叫 API 的環境。
• [in] hook: 環境拆除時要呼叫的函式指標。
• [in] arg: 呼叫 hook 時要傳遞給它的指標。
• [out] remove_handle: 可選控制代碼，指向非同步清理鉤子。

註冊 hook（型別為 napi_async_cleanup_hook 的函式），作為噹噹前 Node.js 環境退出時，使用 remove_handle 和 arg 引數執行的函式。

與 napi_add_env_cleanup_hook 不同，該鉤子允許是非同步的。

否則，行為通常與 napi_add_env_cleanup_hook 匹配。

如果 remove_handle 不為 NULL，則會儲存一個不透明值，以後必須將其傳遞給 napi_remove_async_cleanup_hook，無論鉤子是否已被呼叫。通常，當新增此鉤子的資源被拆除時，就會發生這種情況。

napi_remove_async_cleanup_hook#

NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
    napi_async_cleanup_hook_handle remove_handle); copy

• [in] remove_handle: 使用 napi_add_async_cleanup_hook 建立的非同步清理鉤子的控制代碼。

登出與 remove_handle 對應的清理鉤子。這將阻止鉤子執行，除非它已經開始執行。對於從 napi_add_async_cleanup_hook 獲取的任何 napi_async_cleanup_hook_handle 值，都必須呼叫此函式。

napi_key_collection_mode#

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode; copy

描述 Keys/Properties 過濾器列舉

napi_key_collection_mode 限制了收集屬性的範圍。

napi_key_own_only 僅將收集的屬性限制為給定物件。napi_key_include_prototypes 也會包含物件原型鏈中的所有鍵。

napi_key_filter#

typedef enum {
  napi_key_all_properties = 0,
  napi_key_writable = 1,
  napi_key_enumerable = 1 << 1,
  napi_key_configurable = 1 << 2,
  napi_key_skip_strings = 1 << 3,
  napi_key_skip_symbols = 1 << 4
} napi_key_filter; copy

屬性過濾器位標誌。這與位運算子一起使用以構建複合過濾器。

napi_key_conversion#

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion; copy

napi_key_numbers_to_strings 會將整數索引轉換為字串。napi_key_keep_numbers 會為整數索引返回數字。

napi_valuetype#

typedef enum {
  // ES6 types (corresponds to typeof)
  napi_undefined,
  napi_null,
  napi_boolean,
  napi_number,
  napi_string,
  napi_symbol,
  napi_object,
  napi_function,
  napi_external,
  napi_bigint,
} napi_valuetype; copy

描述 napi_value 的型別。這通常對應於 ECMAScript 語言規範 的 第語言型別 一節中描述的型別。除了該節中的型別之外，napi_valuetype 還可以表示帶有外部資料的 Function 和 Object。

型別為 napi_external 的 JavaScript 值在 JavaScript 中表現為普通物件，不能在其上設定任何屬性，也沒有原型。

napi_typedarray_type#

typedef enum {
  napi_int8_array,
  napi_uint8_array,
  napi_uint8_clamped_array,
  napi_int16_array,
  napi_uint16_array,
  napi_int32_array,
  napi_uint32_array,
  napi_float32_array,
  napi_float64_array,
  napi_bigint64_array,
  napi_biguint64_array,
} napi_typedarray_type; copy

這表示 TypedArray 的底層二進位制標量資料型別。此列舉的元素對應於 ECMAScript 語言規範 的 第 TypedArray 物件 一節。

napi_create_array#

napi_status napi_create_array(napi_env env, napi_value* result) copy

• [in] env: 呼叫 Node-API 的環境。
• [out] result: 表示 JavaScript Array 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回對應於 JavaScript Array 型別的 Node-API 值。JavaScript 陣列在 ECMAScript 語言規範 的 第 Array 物件 一節中進行了描述。

napi_create_array_with_length#

napi_status napi_create_array_with_length(napi_env env,
                                          size_t length,
                                          napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] length: Array 的初始長度。
• [out] result: 表示 JavaScript Array 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回對應於 JavaScript Array 型別的 Node-API 值。Array 的長度屬性設定為傳入的 length 引數。但是，不保證在建立陣列時 VM 會預分配底層緩衝區。該行為留給底層 VM 實現。如果緩衝區必須是一個可以被 C 直接讀寫 contiguous block of memory，請考慮使用 napi_create_external_arraybuffer。

JavaScript 陣列在 ECMAScript 語言規範 的 第 Array 物件 一節中進行了描述。

napi_create_arraybuffer#

napi_status napi_create_arraybuffer(napi_env env,
                                    size_t byte_length,
                                    void** data,
                                    napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] length: 要建立的陣列緩衝區的長度（以位元組為單位）。
• [out] data: 指向 ArrayBuffer 底層位元組緩衝區的指標。可以透過傳遞 NULL 來選擇忽略 data。
• [out] result: 表示 JavaScript ArrayBuffer 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回對應於 JavaScript ArrayBuffer 的 Node-API 值。ArrayBuffer 用於表示固定長度的二進位制資料緩衝區。它們通常用作 TypedArray 物件的後端緩衝區。分配的 ArrayBuffer 將具有一個底層位元組緩衝區，其大小由傳入的 length 引數確定。如果呼叫者希望直接操作緩衝區，則可選地將底層緩衝區返回給呼叫者。此緩衝區只能從原生程式碼直接寫入。要從 JavaScript 寫入此緩衝區，需要建立型別化陣列或 DataView 物件。

JavaScript ArrayBuffer 物件在 ECMAScript 語言規範 的 第 ArrayBuffer 物件 一節中進行了描述。

napi_create_buffer#

napi_status napi_create_buffer(napi_env env,
                               size_t size,
                               void** data,
                               napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] size: 底層緩衝區的大小（以位元組為單位）。
• [out] data: 指向底層緩衝區的原始指標。可以透過傳遞 NULL 來選擇忽略 data。
• [out] result: 表示 node::Buffer 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 分配一個 node::Buffer 物件。雖然這仍然是一個完全支援的資料結構，但在大多數情況下，使用 TypedArray 就足夠了。

napi_create_buffer_copy#

napi_status napi_create_buffer_copy(napi_env env,
                                    size_t length,
                                    const void* data,
                                    void** result_data,
                                    napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] size: 輸入緩衝區的大小（以位元組為單位）（應與新緩衝區的大小相同）。
• [in] data: 指向要複製的底層緩衝區的原始指標。
• [out] result_data: 指向新 Buffer 的底層資料緩衝區的指標。可以透過傳遞 NULL 來選擇忽略 result_data。
• [out] result: 表示 node::Buffer 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 分配一個 node::Buffer 物件，並使用從傳入緩衝區複製的資料對其進行初始化。雖然這仍然是一個完全支援的資料結構，但在大多數情況下，使用 TypedArray 就足夠了。

napi_create_date#

napi_status napi_create_date(napi_env env,
                             double time,
                             napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] time: ECMAScript 時間值，自 1970 年 1 月 1 日 UTC 起的毫秒數。
• [out] result: 表示 JavaScript Date 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 不觀察閏秒；它們被忽略，因為 ECMAScript 與 POSIX 時間規範保持一致。

此 API 分配一個 JavaScript Date 物件。

JavaScript Date 物件在 ECMAScript 語言規範 的 第 Date 物件 一節中進行了描述。

napi_create_external#

napi_status napi_create_external(napi_env env,
                                 void* data,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] data: 指向外部資料的原始指標。
• [in] finalize_cb: 可選回撥，當外部值被收集時呼叫。napi_finalize 提供了更多詳細資訊。
• [in] finalize_hint: 在收集期間傳遞給終結回撥的可選提示。
• [out] result: 表示外部值的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 分配一個附加了外部資料的 JavaScript 值。這用於透過 JavaScript 程式碼傳遞外部資料，以便以後可以透過使用 napi_get_value_external 的原生程式碼檢索。

API 添加了一個 napi_finalize 回撥，該回調將在剛剛建立的 JavaScript 物件被垃圾回收時呼叫。

建立的值不是物件，因此不支援額外的屬性。它被認為是一種不同的值型別：使用外部值呼叫 napi_typeof() 會產生 napi_external。

napi_create_external_arraybuffer#

napi_status
napi_create_external_arraybuffer(napi_env env,
                                 void* external_data,
                                 size_t byte_length,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] external_data: 指向 ArrayBuffer 底層位元組緩衝區的指標。
• [in] byte_length: 底層緩衝區的長度（以位元組為單位）。
• [in] finalize_cb: 可選回撥，當 ArrayBuffer 被收集時呼叫。napi_finalize 提供了更多詳細資訊。
• [in] finalize_hint: 在收集期間傳遞給終結回撥的可選提示。
• [out] result: 表示 JavaScript ArrayBuffer 的 napi_value。

如果 API 成功，則返回 napi_ok。

除了 Node.js 之外的一些執行時已放棄對外部緩衝區的支援。在 Node.js 之外的執行時上，此方法可能返回 napi_no_external_buffers_allowed 以指示不支援外部緩衝區。其中一個執行時是 Electron，如 issue electron/issues/35801 中所述。

為了保持與所有執行時的最廣泛相容性，您可以在包含 node-api 標頭檔案之前在您的外掛中定義 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED。這樣做將隱藏建立外部緩衝區的兩個函式。這將確保如果您不小心使用了這些方法之一，會發生編譯錯誤。

此 API 返回對應於 JavaScript ArrayBuffer 的 Node-API 值。ArrayBuffer 的底層位元組緩衝區是外部分配和管理的。呼叫者必須確保位元組緩衝區在終結回撥被呼叫之前保持有效。

API 添加了一個 napi_finalize 回撥，該回調將在剛剛建立的 JavaScript 物件被垃圾回收時呼叫。

JavaScript ArrayBuffer 在 ECMAScript 語言規範 的 第 ArrayBuffer 物件 一節中進行了描述。

napi_create_external_buffer#

napi_status napi_create_external_buffer(napi_env env,
                                        size_t length,
                                        void* data,
                                        napi_finalize finalize_cb,
                                        void* finalize_hint,
                                        napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] length: 輸入緩衝區的大小（以位元組為單位）（應與新緩衝區的大小相同）。
• [in] data: 指向要暴露給 JavaScript 的底層緩衝區的原始指標。
• [in] finalize_cb: 可選回撥，當 ArrayBuffer 被收集時呼叫。napi_finalize 提供了更多詳細資訊。
• [in] finalize_hint: 在收集期間傳遞給終結回撥的可選提示。
• [out] result: 表示 node::Buffer 的 napi_value。

如果 API 成功，則返回 napi_ok。

除了 Node.js 之外的一些執行時已放棄對外部緩衝區的支援。在 Node.js 之外的執行時上，此方法可能返回 napi_no_external_buffers_allowed 以指示不支援外部緩衝區。其中一個執行時是 Electron，如 issue electron/issues/35801 中所述。

為了保持與所有執行時的最廣泛相容性，您可以在包含 node-api 標頭檔案之前在您的外掛中定義 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED。這樣做將隱藏建立外部緩衝區的兩個函式。這將確保如果您不小心使用了這些方法之一，會發生編譯錯誤。

此 API 分配一個 node::Buffer 物件，並使用傳入緩衝區支援的資料對其進行初始化。雖然這仍然是一個完全支援的資料結構，但在大多數情況下，使用 TypedArray 就足夠了。

API 添加了一個 napi_finalize 回撥，該回調將在剛剛建立的 JavaScript 物件被垃圾回收時呼叫。

對於 Node.js >=4，Buffers 是 Uint8Array。

napi_create_object#

napi_status napi_create_object(napi_env env, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [out] result: 表示 JavaScript Object 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 分配一個預設的 JavaScript Object。它等同於在 JavaScript 中執行 new Object()。

JavaScript Object 型別在 ECMAScript 語言規範 的 第 object 型別 一節中進行了描述。

napi_create_symbol#

napi_status napi_create_symbol(napi_env env,
                               napi_value description,
                               napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] description: 可選的 napi_value，指向一個 JavaScript string，作為符號的描述。
• [out] result: 表示 JavaScript symbol 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 從 UTF8 編碼的 C 字串建立 JavaScript symbol 值。

JavaScript symbol 型別在 ECMAScript 語言規範 的 第 symbol 型別 一節中進行了描述。

node_api_symbol_for#

napi_status node_api_symbol_for(napi_env env,
                                const char* utf8description,
                                size_t length,
                                napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] utf8description: UTF-8 C 字串，表示用作符號描述的文字。
• [in] length: 描述字串的長度（以位元組為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [out] result: 表示 JavaScript symbol 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 在全域性登錄檔中搜索具有給定描述的現有符號。如果符號已存在，則返回該符號，否則將在登錄檔中建立一個新符號。

JavaScript symbol 型別在 ECMAScript 語言規範 的 第 symbol 型別 一節中進行了描述。

napi_create_typedarray#

napi_status napi_create_typedarray(napi_env env,
                                   napi_typedarray_type type,
                                   size_t length,
                                   napi_value arraybuffer,
                                   size_t byte_offset,
                                   napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] type: TypedArray 中元素的標量資料型別。
• [in] length: TypedArray 中的元素數量。
• [in] arraybuffer: 型別化陣列底層的 ArrayBuffer。
• [in] byte_offset: ArrayBuffer 中開始投影 TypedArray 的位元組偏移量。
• [out] result: 表示 JavaScript TypedArray 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 在現有 ArrayBuffer 上建立 JavaScript TypedArray 物件。TypedArray 物件提供了一個類似陣列的檢視，位於底層資料緩衝區之上，其中每個元素都具有相同的底層二進位制標量資料型別。

要求 (length * size_of_element) + byte_offset 應該小於或等於傳入陣列的位元組大小。如果不是，則會引發 RangeError 異常。

JavaScript TypedArray 物件在 ECMAScript 語言規範 的 第 TypedArray 物件 一節中進行了描述。

node_api_create_buffer_from_arraybuffer#

napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
                                                              napi_value arraybuffer,
                                                              size_t byte_offset,
                                                              size_t byte_length,
                                                              napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] arraybuffer: 將從中建立緩衝區的 ArrayBuffer。
• [in] byte_offset: ArrayBuffer 中開始建立緩衝區的位元組偏移量。
• [in] byte_length: 將從 ArrayBuffer 建立的緩衝區的長度（以位元組為單位）。
• [out] result: 表示建立的 JavaScript Buffer 物件的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 從現有 ArrayBuffer 建立 JavaScript Buffer 物件。Buffer 物件是 Node.js 特有的類，它提供了一種直接在 JavaScript 中處理二進位制資料的方法。

位元組範圍 [byte_offset, byte_offset + byte_length) 必須在 ArrayBuffer 的邊界內。如果 byte_offset + byte_length 超過 ArrayBuffer 的大小，則會引發 RangeError 異常。

napi_create_dataview#

napi_status napi_create_dataview(napi_env env,
                                 size_t byte_length,
                                 napi_value arraybuffer,
                                 size_t byte_offset,
                                 napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] length: DataView 中的元素數量。
• [in] arraybuffer: DataView 底層的 ArrayBuffer。
• [in] byte_offset: ArrayBuffer 中開始投影 DataView 的位元組偏移量。
• [out] result: 表示 JavaScript DataView 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 在現有 ArrayBuffer 上建立 JavaScript DataView 物件。DataView 物件提供了一個類似陣列的檢視，位於底層資料緩衝區之上，但允許 ArrayBuffer 中具有不同大小和型別的項。

要求 byte_length + byte_offset 小於或等於傳入陣列的位元組大小。如果不是，則會引發 RangeError 異常。

JavaScript DataView 物件在 ECMAScript 語言規範 的 第 DataView 物件 一節中進行了描述。

napi_create_int32#

napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 要在 JavaScript 中表示的整數值。
• [out] result: 表示 JavaScript number 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 用於將 C int32_t 型別轉換為 JavaScript number 型別。

JavaScript number 型別在 ECMAScript 語言規範 的 第 number 型別 一節中進行了描述。

napi_create_uint32#

napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 要在 JavaScript 中表示的無符號整數值。
• [out] result: 表示 JavaScript number 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 用於將 C uint32_t 型別轉換為 JavaScript number 型別。

JavaScript number 型別在 ECMAScript 語言規範 的 第 number 型別 一節中進行了描述。

napi_create_int64#

napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 要在 JavaScript 中表示的整數值。
• [out] result: 表示 JavaScript number 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 用於將 C int64_t 型別轉換為 JavaScript number 型別。

JavaScript number 型別在 ECMAScript 語言規範 的 第 number 型別 一節中進行了描述。請注意，int64_t 的完整範圍不能在 JavaScript 中以完全精度表示。超出 Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) 範圍的整數值將失去精度。

napi_create_double#

napi_status napi_create_double(napi_env env, double value, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 要在 JavaScript 中表示的雙精度值。
• [out] result: 表示 JavaScript number 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 用於將 C double 型別轉換為 JavaScript number 型別。

JavaScript number 型別在 ECMAScript 語言規範 的 第 number 型別 一節中進行了描述。

napi_create_bigint_int64#

napi_status napi_create_bigint_int64(napi_env env,
                                     int64_t value,
                                     napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] value: 要在 JavaScript 中表示的整數值。
• [out] result: 表示 JavaScript BigInt 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 將 C int64_t 型別轉換為 JavaScript BigInt 型別。

napi_create_bigint_uint64#

napi_status napi_create_bigint_uint64(napi_env env,
                                      uint64_t value,
                                      napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] value: 要在 JavaScript 中表示的無符號整數值。
• [out] result: 表示 JavaScript BigInt 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 將 C uint64_t 型別轉換為 JavaScript BigInt 型別。

napi_create_bigint_words#

napi_status napi_create_bigint_words(napi_env env,
                                     int sign_bit,
                                     size_t word_count,
                                     const uint64_t* words,
                                     napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] sign_bit: 確定結果 BigInt 是正數還是負數。
• [in] word_count: words 陣列的長度。
• [in] words: uint64_t 小端 64 位字的陣列。
• [out] result: 表示 JavaScript BigInt 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 將無符號 64 位字陣列轉換為單個 BigInt 值。

結果 BigInt 計算為: (–1)^sign_bit (words[0] × (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)

napi_create_string_latin1#

napi_status napi_create_string_latin1(napi_env env,
                                      const char* str,
                                      size_t length,
                                      napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] str: 表示 ISO-8859-1 編碼字串的字元緩衝區。
• [in] length: 字串的長度（以位元組為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [out] result: 表示 JavaScript string 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 從 ISO-8859-1 編碼的 C 字串建立 JavaScript string 值。原生字串被複制。

JavaScript string 型別在 ECMAScript 語言規範 的 第 string 型別 一節中進行了描述。

node_api_create_external_string_latin1#

napi_status
node_api_create_external_string_latin1(napi_env env,
                                       char* str,
                                       size_t length,
                                       napi_finalize finalize_callback,
                                       void* finalize_hint,
                                       napi_value* result,
                                       bool* copied); copy

• [in] env: 呼叫 API 的環境。
• [in] str: 表示 ISO-8859-1 編碼字串的字元緩衝區。
• [in] length: 字串的長度（以位元組為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [in] finalize_callback: 當字串被收集時要呼叫的函式。該函式將使用以下引數呼叫
  • [in] env: 外掛執行的環境。如果字串作為 worker 或主 Node.js 例項終止的一部分而被收集，則此值可能為 null。
  • [in] data: 這是 str 的值，作為 void* 指標。
  • [in] finalize_hint: 這是提供給 API 的 finalize_hint 值。napi_finalize 提供了更多詳細資訊。此引數是可選的。傳遞空值意味著當相應的 JavaScript 字串被收集時，外掛不需要收到通知。
• [in] finalize_hint: 在收集期間傳遞給終結回撥的可選提示。
• [out] result: 表示 JavaScript string 的 napi_value。
• [out] copied: 字串是否被複制。如果已複製，則終結器將已呼叫以銷燬 str。

如果 API 成功，則返回 napi_ok。

此 API 從 ISO-8859-1 編碼的 C 字串建立 JavaScript string 值。原生字串可能未被複制，因此必須在 JavaScript 值的整個生命週期中存在。

JavaScript string 型別在 ECMAScript 語言規範 的 第 string 型別 一節中進行了描述。

napi_create_string_utf16#

napi_status napi_create_string_utf16(napi_env env,
                                     const char16_t* str,
                                     size_t length,
                                     napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] str: 表示 UTF16-LE 編碼字串的字元緩衝區。
• [in] length: 字串的長度（以雙位元組程式碼單元為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [out] result: 表示 JavaScript string 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 從 UTF16-LE 編碼的 C 字串建立 JavaScript string 值。原生字串被複制。

JavaScript string 型別在 ECMAScript 語言規範 的 第 string 型別 一節中進行了描述。

node_api_create_external_string_utf16#

napi_status
node_api_create_external_string_utf16(napi_env env,
                                      char16_t* str,
                                      size_t length,
                                      napi_finalize finalize_callback,
                                      void* finalize_hint,
                                      napi_value* result,
                                      bool* copied); copy

• [in] env: 呼叫 API 的環境。
• [in] str: 表示 UTF16-LE 編碼字串的字元緩衝區。
• [in] length: 字串的長度（以雙位元組程式碼單元為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [in] finalize_callback: 當字串被收集時要呼叫的函式。該函式將使用以下引數呼叫
  • [in] env: 外掛執行的環境。如果字串作為 worker 或主 Node.js 例項終止的一部分而被收集，則此值可能為 null。
  • [in] data: 這是 str 的值，作為 void* 指標。
  • [in] finalize_hint: 這是提供給 API 的 finalize_hint 值。napi_finalize 提供了更多詳細資訊。此引數是可選的。傳遞空值意味著當相應的 JavaScript 字串被收集時，外掛不需要收到通知。
• [in] finalize_hint: 在收集期間傳遞給終結回撥的可選提示。
• [out] result: 表示 JavaScript string 的 napi_value。
• [out] copied: 字串是否被複制。如果已複製，則終結器將已呼叫以銷燬 str。

如果 API 成功，則返回 napi_ok。

此 API 從 UTF16-LE 編碼的 C 字串建立 JavaScript string 值。原生字串可能未被複制，因此必須在 JavaScript 值的整個生命週期中存在。

JavaScript string 型別在 ECMAScript 語言規範 的 第 string 型別 一節中進行了描述。

napi_create_string_utf8#

napi_status napi_create_string_utf8(napi_env env,
                                    const char* str,
                                    size_t length,
                                    napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] str: 表示 UTF8 編碼字串的字元緩衝區。
• [in] length: 字串的長度（以位元組為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [out] result: 表示 JavaScript string 的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 從 UTF8 編碼的 C 字串建立 JavaScript string 值。原生字串被複制。

JavaScript string 型別在 ECMAScript 語言規範 的 第 string 型別 一節中進行了描述。

node_api_create_property_key_latin1#

napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
                                                           const char* str,
                                                           size_t length,
                                                           napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] str: 表示 ISO-8859-1 編碼字串的字元緩衝區。
• [in] length: 字串的長度（以位元組為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [out] result: 表示最佳化 JavaScript string 的 napi_value，用作物件的屬性鍵。

如果 API 成功，則返回 napi_ok。

此 API 從 ISO-8859-1 編碼的 C 字串建立最佳化 JavaScript string 值，用作物件的屬性鍵。原生字串被複制。與 napi_create_string_latin1 不同，隨後使用相同的 str 指標呼叫此函式可能會從所請求的 napi_value 的建立中受益於加速，具體取決於引擎。

JavaScript string 型別在 ECMAScript 語言規範 的 第 string 型別 一節中進行了描述。

node_api_create_property_key_utf16#

napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
                                                          const char16_t* str,
                                                          size_t length,
                                                          napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] str: 表示 UTF16-LE 編碼字串的字元緩衝區。
• [in] length: 字串的長度（以雙位元組程式碼單元為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [out] result: 表示最佳化 JavaScript string 的 napi_value，用作物件的屬性鍵。

如果 API 成功，則返回 napi_ok。

此 API 從 UTF16-LE 編碼的 C 字串建立最佳化 JavaScript string 值，用作物件的屬性鍵。原生字串被複制。

JavaScript string 型別在 ECMAScript 語言規範 的 第 string 型別 一節中進行了描述。

node_api_create_property_key_utf8#

napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
                                                         const char* str,
                                                         size_t length,
                                                         napi_value* result); copy

• [in] env: 呼叫 API 的環境。
• [in] str: 表示 UTF8 編碼字串的字元緩衝區。
• [in] length: 字串的長度（以雙位元組程式碼單元為單位），如果為 null 終止，則為 NAPI_AUTO_LENGTH。
• [out] result: 表示最佳化 JavaScript string 的 napi_value，用作物件的屬性鍵。

如果 API 成功，則返回 napi_ok。

此 API 從 UTF8 編碼的 C 字串建立最佳化 JavaScript string 值，用作物件的屬性鍵。原生字串被複制。

JavaScript string 型別在 ECMAScript 語言規範 的 第 string 型別 一節中進行了描述。

napi_get_array_length#

napi_status napi_get_array_length(napi_env env,
                                  napi_value value,
                                  uint32_t* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示正在查詢長度的 JavaScript Array 的 napi_value。
• [out] result: 表示陣列長度的 uint32。

如果 API 成功，則返回 napi_ok。

此 API 返回陣列的長度。

Array 長度在 ECMAScript 語言規範 的 第 Array 例項長度 一節中進行了描述。

napi_get_arraybuffer_info#

napi_status napi_get_arraybuffer_info(napi_env env,
                                      napi_value arraybuffer,
                                      void** data,
                                      size_t* byte_length) copy

• [in] env: 呼叫 API 的環境。
• [in] arraybuffer: 表示正在查詢的 ArrayBuffer 或 SharedArrayBuffer 的 napi_value。
• [out] data: ArrayBuffer 或 SharedArrayBuffer 的底層資料緩衝區為 0，這可以是 NULL 或任何其他指標值。
• [out] byte_length: 底層資料緩衝區的長度（以位元組為單位）。

如果 API 成功，則返回 napi_ok。

此 API 用於檢索 ArrayBuffer 或 SharedArrayBuffer 的底層資料緩衝區及其長度。

警告: 使用此 API 時請務必小心。底層資料緩衝區的生命週期由 ArrayBuffer 或 SharedArrayBuffer 管理，即使在返回後也是如此。使用此 API 的一種可能的安全方法是結合 napi_create_reference 使用，該方法可用於保證對 ArrayBuffer 或 SharedArrayBuffer 生命週期的控制。只要沒有呼叫可能觸發 GC 的其他 API，在同一回撥中使用返回的資料緩衝區也是安全的。

napi_get_buffer_info#

napi_status napi_get_buffer_info(napi_env env,
                                 napi_value value,
                                 void** data,
                                 size_t* length) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示正在查詢的 node::Buffer 或 Uint8Array 的 napi_value。
• [out] data: node::Buffer 或 Uint8Array 的底層資料緩衝區。如果長度為 0，這可以是 NULL 或任何其他指標值。
• [out] length: 底層資料緩衝區的長度（以位元組為單位）。

如果 API 成功，則返回 napi_ok。

此方法返回與 napi_get_typedarray_info 相同的 data 和 byte_length。並且 napi_get_typedarray_info 也接受 node::Buffer (一個 Uint8Array) 作為值。

此 API 用於檢索 node::Buffer 的底層資料緩衝區及其長度。

警告: 使用此 API 時請務必小心，因為如果底層資料緩衝區由 VM 管理，則其生命週期無法保證。

napi_get_prototype#

napi_status napi_get_prototype(napi_env env,
                               napi_value object,
                               napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] object: 表示要返回其原型的 JavaScript Object 的 napi_value。這返回與 Object.getPrototypeOf 等效的值（與函式的 prototype 屬性不同）。
• [out] result: 表示給定物件原型的 napi_value。

如果 API 成功，則返回 napi_ok。

napi_get_typedarray_info#

napi_status napi_get_typedarray_info(napi_env env,
                                     napi_value typedarray,
                                     napi_typedarray_type* type,
                                     size_t* length,
                                     void** data,
                                     napi_value* arraybuffer,
                                     size_t* byte_offset) copy

• [in] env: 呼叫 API 的環境。
• [in] typedarray: 表示要查詢其屬性的 TypedArray 的 napi_value。
• [out] type: TypedArray 中元素的標量資料型別。
• [out] length: TypedArray 中的元素數量。
• [out] data: TypedArray 的底層資料緩衝區，已透過 byte_offset 值調整，使其指向 TypedArray 中的第一個元素。如果陣列長度為 0，則此值可能為 NULL 或任何其他指標值。
• [out] arraybuffer: TypedArray 底層的 ArrayBuffer。
• [out] byte_offset: 底層原生陣列中第一個元素所在位置的位元組偏移量。資料引數的值已經過調整，因此資料指向陣列中的第一個元素。因此，原生陣列的第一個位元組將位於 data - byte_offset。

如果 API 成功，則返回 napi_ok。

此 API 返回型別化陣列的各種屬性。

如果不需要某個屬性，則任何輸出引數都可以是 NULL。

警告: 使用此 API 時請務必小心，因為底層資料緩衝區由 VM 管理。

napi_get_dataview_info#

napi_status napi_get_dataview_info(napi_env env,
                                   napi_value dataview,
                                   size_t* byte_length,
                                   void** data,
                                   napi_value* arraybuffer,
                                   size_t* byte_offset) copy

• [in] env: 呼叫 API 的環境。
• [in] dataview: 表示要查詢其屬性的 DataView 的 napi_value。
• [out] byte_length: DataView 中的位元組數。
• [out] data: DataView 的底層資料緩衝區。如果 byte_length 為 0，則此值可能為 NULL 或任何其他指標值。
• [out] arraybuffer: DataView 底層的 ArrayBuffer。
• [out] byte_offset: 資料緩衝區中開始投影 DataView 的位元組偏移量。

如果 API 成功，則返回 napi_ok。

如果不需要某個屬性，則任何輸出引數都可以是 NULL。

此 API 返回 DataView 的各種屬性。

napi_get_date_value#

napi_status napi_get_date_value(napi_env env,
                                napi_value value,
                                double* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript Date 的 napi_value。
• [out] result: 時間值，表示自 1970 年 1 月 1 日 UTC 午夜以來的毫秒數，以 double 表示。

此 API 不觀察閏秒；它們被忽略，因為 ECMAScript 與 POSIX 時間規範保持一致。

如果 API 成功，則返回 napi_ok。如果傳入非日期 napi_value，則返回 napi_date_expected。

此 API 返回給定 JavaScript Date 的時間值的 C 雙精度原始值。

napi_get_value_bool#

napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript Boolean 的 napi_value。
• [out] result: 給定 JavaScript Boolean 的 C 布林原始等效值。

如果 API 成功，則返回 napi_ok。如果傳入非布林 napi_value，則返回 napi_boolean_expected。

此 API 返回給定 JavaScript Boolean 的 C 布林原始等效值。

napi_get_value_double#

napi_status napi_get_value_double(napi_env env,
                                  napi_value value,
                                  double* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript number 的 napi_value。
• [out] result: 給定 JavaScript number 的 C 雙精度原始等效值。

如果 API 成功，則返回 napi_ok。如果傳入非數字 napi_value，則返回 napi_number_expected。

此 API 返回給定 JavaScript number 的 C 雙精度原始等效值。

napi_get_value_bigint_int64#

napi_status napi_get_value_bigint_int64(napi_env env,
                                        napi_value value,
                                        int64_t* result,
                                        bool* lossless); copy

• [in] env: 呼叫 API 的環境
• [in] value: 表示 JavaScript BigInt 的 napi_value。
• [out] result: 給定 JavaScript BigInt 的 C int64_t 原始等效值。
• [out] lossless: 指示 BigInt 值是否無損轉換。

如果 API 成功，則返回 napi_ok。如果傳入非 BigInt，則返回 napi_bigint_expected。

此 API 返回給定 JavaScript BigInt 的 C int64_t 原始等效值。如果需要，它將截斷該值，並將 lossless 設定為 false。

napi_get_value_bigint_uint64#

napi_status napi_get_value_bigint_uint64(napi_env env,
                                        napi_value value,
                                        uint64_t* result,
                                        bool* lossless); copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript BigInt 的 napi_value。
• [out] result: 給定 JavaScript BigInt 的 C uint64_t 原始等效值。
• [out] lossless: 指示 BigInt 值是否無損轉換。

如果 API 成功，則返回 napi_ok。如果傳入非 BigInt，則返回 napi_bigint_expected。

此 API 返回給定 JavaScript BigInt 的 C uint64_t 原始等效值。如果需要，它將截斷該值，並將 lossless 設定為 false。

napi_get_value_bigint_words#

napi_status napi_get_value_bigint_words(napi_env env,
                                        napi_value value,
                                        int* sign_bit,
                                        size_t* word_count,
                                        uint64_t* words); copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript BigInt 的 napi_value。
• [out] sign_bit: 表示 JavaScript BigInt 是正數還是負數的整數。
• [in/out] word_count: 必須初始化為 words 陣列的長度。返回時，它將設定為儲存此 BigInt 所需的實際字數。
• [out] words: 指向預分配的 64 位字陣列的指標。

如果 API 成功，則返回 napi_ok。

此 API 將單個 BigInt 值轉換為符號位、64 位小端陣列以及陣列中的元素數量。sign_bit 和 words 都可以設定為 NULL，以便只獲取 word_count。

napi_get_value_external#

napi_status napi_get_value_external(napi_env env,
                                    napi_value value,
                                    void** result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript 外部值的 napi_value。
• [out] result: 指向 JavaScript 外部值包裝的資料的指標。

如果 API 成功，則返回 napi_ok。如果傳入非外部 napi_value，則返回 napi_invalid_arg。

此 API 檢索先前傳遞給 napi_create_external() 的外部資料指標。

napi_get_value_int32#

napi_status napi_get_value_int32(napi_env env,
                                 napi_value value,
                                 int32_t* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript number 的 napi_value。
• [out] result: 給定 JavaScript number 的 C int32 原始等效值。

如果 API 成功，則返回 napi_ok。如果傳入非數字 napi_value，則返回 napi_number_expected。

此 API 返回給定 JavaScript number 的 C int32 原始等效值。

如果數字超出 32 位整數的範圍，則結果將被截斷為等效的低 32 位。如果值大於 2³¹ - 1，這可能導致較大的正數變為負數。

非有限數字值（NaN、+Infinity 或 -Infinity）將結果設定為零。

napi_get_value_int64#

napi_status napi_get_value_int64(napi_env env,
                                 napi_value value,
                                 int64_t* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript number 的 napi_value。
• [out] result: 給定 JavaScript number 的 C int64 原始等效值。

如果 API 成功，則返回 napi_ok。如果傳入非數字 napi_value，則返回 napi_number_expected。

此 API 返回給定 JavaScript number 的 C int64 原始等效值。

超出 Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) 範圍的 number 值將失去精度。

非有限數字值（NaN、+Infinity 或 -Infinity）將結果設定為零。

napi_get_value_string_latin1#

napi_status napi_get_value_string_latin1(napi_env env,
                                         napi_value value,
                                         char* buf,
                                         size_t bufsize,
                                         size_t* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript 字串的 napi_value。
• [in] buf: 寫入 ISO-8859-1 編碼字串的緩衝區。如果傳入 NULL，則字串的長度（以位元組為單位，不包括空終止符）將在 result 中返回。
• [in] bufsize: 目標緩衝區的大小。當此值不足時，返回的字串將被截斷並以空終止。如果此值為零，則不返回字串，並且不對緩衝區進行任何更改。
• [out] result: 複製到緩衝區中的位元組數，不包括空終止符。

如果 API 成功，則返回 napi_ok。如果傳入非 string napi_value，則返回 napi_string_expected。

此 API 返回與傳入值對應的 ISO-8859-1 編碼字串。

napi_get_value_string_utf8#

napi_status napi_get_value_string_utf8(napi_env env,
                                       napi_value value,
                                       char* buf,
                                       size_t bufsize,
                                       size_t* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript 字串的 napi_value。
• [in] buf: 寫入 UTF8 編碼字串的緩衝區。如果傳入 NULL，則字串的長度（以位元組為單位，不包括空終止符）將在 result 中返回。
• [in] bufsize: 目標緩衝區的大小。當此值不足時，返回的字串將被截斷並以空終止。如果此值為零，則不返回字串，並且不對緩衝區進行任何更改。
• [out] result: 複製到緩衝區中的位元組數，不包括空終止符。

如果 API 成功，則返回 napi_ok。如果傳入非 string napi_value，則返回 napi_string_expected。

此 API 返回與傳入值對應的 UTF8 編碼字串。

napi_get_value_string_utf16#

napi_status napi_get_value_string_utf16(napi_env env,
                                        napi_value value,
                                        char16_t* buf,
                                        size_t bufsize,
                                        size_t* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript 字串的 napi_value。
• [in] buf: 寫入 UTF16-LE 編碼字串的緩衝區。如果傳入 NULL，則字串的長度（以 2 位元組程式碼單元為單位，不包括空終止符）將返回。
• [in] bufsize: 目標緩衝區的大小。當此值不足時，返回的字串將被截斷並以空終止。如果此值為零，則不返回字串，並且不對緩衝區進行任何更改。
• [out] result: 複製到緩衝區中的 2 位元組程式碼單元數，不包括空終止符。

如果 API 成功，則返回 napi_ok。如果傳入非 string napi_value，則返回 napi_string_expected。

此 API 返回與傳入值對應的 UTF16 編碼字串。

napi_get_value_uint32#

napi_status napi_get_value_uint32(napi_env env,
                                  napi_value value,
                                  uint32_t* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 表示 JavaScript number 的 napi_value。
• [out] result: 給定 napi_value 的 C 原始等效值，作為 uint32_t。

如果 API 成功，則返回 napi_ok。如果傳入非數字 napi_value，則返回 napi_number_expected。

此 API 返回給定 napi_value 的 C 原始等效值，作為 uint32_t。

napi_get_boolean#

napi_status napi_get_boolean(napi_env env, bool value, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [in] value: 要檢索的布林值。
• [out] result: 表示要檢索的 JavaScript Boolean 單例的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 用於返回用於表示給定布林值的 JavaScript 單例物件。

napi_get_global#

napi_status napi_get_global(napi_env env, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [out] result: 表示 JavaScript global 物件的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回 global 物件。

napi_get_null#

napi_status napi_get_null(napi_env env, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [out] result: 表示 JavaScript null 物件的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回 null 物件。

napi_get_undefined#

napi_status napi_get_undefined(napi_env env, napi_value* result) copy

• [in] env: 呼叫 API 的環境。
• [out] result: 表示 JavaScript Undefined 值的 napi_value。

如果 API 成功，則返回 napi_ok。

此 API 返回 Undefined 物件。

napi_property_attributes#

typedef enum {
  napi_default = 0,
  napi_writable = 1 << 0,
  napi_enumerable = 1 << 1,
  napi_configurable = 1 << 2,

  // Used with napi_define_class to distinguish static properties
  // from instance properties. Ignored by napi_define_properties.
  napi_static = 1 << 10,

  // Default for class methods.
  napi_default_method = napi_writable | napi_configurable,

  // Default for object properties, like in JS obj[prop].
  napi_default_jsproperty = napi_writable |
                          napi_enumerable |
                          napi_configurable,
} napi_property_attributes; copy

napi_property_attributes 是用於控制 JavaScript 物件上設定屬性行為的位標誌。除了 napi_static 之外，它們對應於 ECMAScript 語言規範 的 第 property attributes 一節中列出的屬性。它們可以是一個或多個以下位標誌

• napi_default: 屬性上未設定顯式屬性。預設情況下，屬性是隻讀的，不可列舉且不可配置。
• napi_writable: 屬性是可寫的。
• napi_enumerable: 屬性是可列舉的。
• napi_configurable: 屬性是可配置的，如 ECMAScript 語言規範 的 第 property attributes 一節中定義。
• napi_static: 屬性將定義為類的靜態屬性，而不是例項屬性（這是預設值）。這僅由 napi_define_class 使用。它被 napi_define_properties 忽略。
• napi_default_method: 類似於 JS 類中的方法，屬性是可配置和可寫的，但不可列舉。
• napi_default_jsproperty: 類似於透過 JavaScript 中的賦值設定的屬性，屬性是可寫、可列舉和可配置的。

napi_property_descriptor#

typedef struct {
  // One of utf8name or name should be NULL.
  const char* utf8name;
  napi_value name;

  napi_callback method;
  napi_callback getter;
  napi_callback setter;
  napi_value value;

  napi_property_attributes attributes;
  void* data;
} napi_property_descriptor; copy

• utf8name: 描述屬性鍵的可選字串，以 UTF8 編碼。屬性必須提供 utf8name 或 name 之一。
• name: 可選的 napi_value，指向用作屬性鍵的 JavaScript 字串或符號。屬性必須提供 utf8name 或 name 之一。
• value: 如果屬性是資料屬性，則透過 get 訪問屬性檢索到的值。如果傳入此值，則將 getter、setter、method 和 data 設定為 NULL（因為這些成員不會被使用）。
• getter: 執行屬性的 get 訪問時呼叫的函式。如果傳入此值，則將 value 和 method 設定為 NULL（因為這些成員不會被使用）。當從 JavaScript 程式碼訪問屬性（或使用 Node-API 呼叫對屬性執行 get 操作）時，執行時會隱式呼叫給定函式。napi_callback 提供了更多詳細資訊。
• setter: 執行屬性的 set 訪問時呼叫的函式。如果傳入此值，則將 value 和 method 設定為 NULL（因為這些成員不會被使用）。當從 JavaScript 程式碼設定屬性（或使用 Node-API 呼叫對屬性執行 set 操作）時，執行時會隱式呼叫給定函式。napi_callback 提供了更多詳細資訊。
• method: 設定此項以使屬性描述符物件的 value 屬性成為由 method 表示的 JavaScript 函式。如果傳入此值，則將 value、getter 和 setter 設定為 NULL（因為這些成員不會被使用）。napi_callback 提供了更多詳細資訊。
• attributes: 與特定屬性關聯的屬性。請參閱 napi_property_attributes。
• data: 如果此函式被呼叫，則傳入 method、getter 和 setter 的回撥資料。

napi_get_property_names#

napi_status napi_get_property_names(napi_env env,
                                    napi_value object,
                                    napi_value* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object: 從中檢索屬性的物件。
• [out] result: 表示 JavaScript 值陣列的 napi_value，這些值表示物件的屬性名稱。API 可以使用 napi_get_array_length 和 napi_get_element 遍歷 result。

如果 API 成功，則返回 napi_ok。

此 API 返回 object 的可列舉屬性的名稱作為字串陣列。鍵為符號的 object 屬性將不包含在內。

napi_get_all_property_names#

napi_get_all_property_names(napi_env env,
                            napi_value object,
                            napi_key_collection_mode key_mode,
                            napi_key_filter key_filter,
                            napi_key_conversion key_conversion,
                            napi_value* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object: 從中檢索屬性的物件。
• [in] key_mode: 是否也檢索原型屬性。
• [in] key_filter: 要檢索哪些屬性（可列舉/可讀/可寫）。
• [in] key_conversion: 是否將編號屬性鍵轉換為字串。
• [out] result：一個 napi_value，表示一個 JavaScript 值陣列，這些值表示物件的屬性名。napi_get_array_length 和 napi_get_element 可用於迭代 result。

如果 API 成功，則返回 napi_ok。

此 API 返回一個數組，其中包含此物件的可用屬性的名稱。

napi_set_property#

napi_status napi_set_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value value); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要設定屬性的物件。
• [in] key：要設定的屬性的名稱。
• [in] value：屬性值。

如果 API 成功，則返回 napi_ok。

此 API 在傳入的 Object 上設定一個屬性。

napi_get_property#

napi_status napi_get_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：從中檢索屬性的物件。
• [in] key：要檢索的屬性的名稱。
• [out] result：屬性的值。

如果 API 成功，則返回 napi_ok。

此 API 從傳入的 Object 中獲取請求的屬性。

napi_has_property#

napi_status napi_has_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              bool* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要查詢的物件。
• [in] key：要檢查其是否存在屬性的名稱。
• [out] result：屬性是否存在於物件上。

如果 API 成功，則返回 napi_ok。

此 API 檢查傳入的 Object 是否具有指定名稱的屬性。

napi_delete_property#

napi_status napi_delete_property(napi_env env,
                                 napi_value object,
                                 napi_value key,
                                 bool* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要查詢的物件。
• [in] key：要刪除的屬性的名稱。
• [out] result：屬性刪除是否成功。可以透過傳入 NULL 來選擇性地忽略 result。

如果 API 成功，則返回 napi_ok。

此 API 嘗試從 object 中刪除 key 自己的屬性。

napi_has_own_property#

napi_status napi_has_own_property(napi_env env,
                                  napi_value object,
                                  napi_value key,
                                  bool* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要查詢的物件。
• [in] key：要檢查其是否存在自身屬性的名稱。
• [out] result：自身屬性是否存在於物件上。

如果 API 成功，則返回 napi_ok。

此 API 檢查傳入的 Object 是否具有指定名稱的自身屬性。key 必須是 string 或 symbol，否則將丟擲錯誤。Node-API 不會執行任何資料型別之間的轉換。

napi_set_named_property#

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要設定屬性的物件。
• [in] utf8Name：要設定的屬性的名稱。
• [in] value：屬性值。

如果 API 成功，則返回 napi_ok。

此方法等同於呼叫 napi_set_property，其中 napi_value 是由作為 utf8Name 傳入的字串建立的。

napi_get_named_property#

napi_status napi_get_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：從中檢索屬性的物件。
• [in] utf8Name：要獲取的屬性的名稱。
• [out] result：屬性的值。

如果 API 成功，則返回 napi_ok。

此方法等同於呼叫 napi_get_property，其中 napi_value 是由作為 utf8Name 傳入的字串建立的。

napi_has_named_property#

napi_status napi_has_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    bool* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要查詢的物件。
• [in] utf8Name：要檢查其是否存在屬性的名稱。
• [out] result：屬性是否存在於物件上。

如果 API 成功，則返回 napi_ok。

此方法等同於呼叫 napi_has_property，其中 napi_value 是由作為 utf8Name 傳入的字串建立的。

napi_set_element#

napi_status napi_set_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value value); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要設定屬性的物件。
• [in] index：要設定的屬性的索引。
• [in] value：屬性值。

如果 API 成功，則返回 napi_ok。

此 API 在傳入的 Object 上設定一個元素。

napi_get_element#

napi_status napi_get_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：從中檢索屬性的物件。
• [in] index：要獲取的屬性的索引。
• [out] result：屬性的值。

如果 API 成功，則返回 napi_ok。

此 API 獲取請求索引處的元素。

napi_has_element#

napi_status napi_has_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             bool* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要查詢的物件。
• [in] index：要檢查其是否存在屬性的索引。
• [out] result：屬性是否存在於物件上。

如果 API 成功，則返回 napi_ok。

此 API 返回傳入的 Object 是否在請求的索引處有一個元素。

napi_delete_element#

napi_status napi_delete_element(napi_env env,
                                napi_value object,
                                uint32_t index,
                                bool* result); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要查詢的物件。
• [in] index：要刪除的屬性的索引。
• [out] result：元素刪除是否成功。可以透過傳入 NULL 來選擇性地忽略 result。

如果 API 成功，則返回 napi_ok。

此 API 嘗試從 object 中刪除指定的 index。

napi_define_properties#

napi_status napi_define_properties(napi_env env,
                                   napi_value object,
                                   size_t property_count,
                                   const napi_property_descriptor* properties); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object: 從中檢索屬性的物件。
• [in] property_count：properties 陣列中的元素數量。
• [in] properties：屬性描述符陣列。

如果 API 成功，則返回 napi_ok。

此方法允許在給定物件上高效定義多個屬性。屬性使用屬性描述符定義（請參閱 napi_property_descriptor）。給定此類屬性描述符陣列，此 API 將根據 DefineOwnProperty()（在 ECMA-262 規範的 DefineOwnProperty 部分 中描述）定義，一次設定物件上的屬性。

napi_object_freeze#

napi_status napi_object_freeze(napi_env env,
                               napi_value object); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要凍結的物件。

如果 API 成功，則返回 napi_ok。

此方法凍結給定物件。這會阻止向其新增新屬性、刪除現有屬性、更改現有屬性的可列舉性、可配置性或可寫性，以及更改現有屬性的值。它還會阻止更改物件的原型。這在 ECMA-262 規範的 第 19.1.2.6 節 中有所描述。

napi_object_seal#

napi_status napi_object_seal(napi_env env,
                             napi_value object); copy

• [in] env: 呼叫 Node-API 的環境。
• [in] object：要密封的物件。

如果 API 成功，則返回 napi_ok。

此方法密封給定物件。這會阻止向其新增新屬性，並將其所有現有屬性標記為不可配置。這在 ECMA-262 規範的 第 19.1.2.20 節 中有所描述。

node_api_post_finalizer#

napi_status node_api_post_finalizer(node_api_basic_env env,
                                    napi_finalize finalize_cb,
                                    void* finalize_data,
                                    void* finalize_hint); copy

• [in] env: 呼叫 API 的環境。
• [in] finalize_cb：原生回撥，當 JavaScript 物件被垃圾回收時將用於釋放原生資料。napi_finalize 提供了更多詳細資訊。
• [in] finalize_data：可選資料，將傳遞給 finalize_cb。
• [in] finalize_hint：傳遞給終結器回撥的可選上下文提示。

如果 API 成功，則返回 napi_ok。

安排在事件迴圈中非同步呼叫 napi_finalize 回撥。

通常，終結器在 GC（垃圾回收器）收集物件時被呼叫。此時，任何可能導致 GC 狀態更改的 Node-API 呼叫都將被停用，並將導致 Node.js 崩潰。

node_api_post_finalizer 透過允許外掛將此類 Node-API 的呼叫推遲到 GC 終結之外的時間點，從而幫助解決此限制。