# #[napi] 属性

#[napi] 宏用于导出 Rust 项，并控制它们在 JavaScript 运行时的行为以及生成的 TypeScript 声明。本页涵盖 napi-derive v3 接受的全部公开选项，包括两个只能在参数和枚举变体上解析的上下文特定选项。

use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi(js_name = "addOne", strict)]
pub fn add_one(value: u32) -> u32 {
  value + 1
}

# 支持的目标

在下表中：

• 函数是指导出的自由函数。
• 方法包括实例方法、静态方法、工厂方法、构造函数、getter 和 setter（前提是相应选项在该处有意义）。
• 类是指以类身份导出的结构体。object、array 或 transparent 结构体属于值形状，而不是类。
• 字段是指结构体字段或结构化枚举变体的字段。

启用默认的 napi-derive/strict 特性时，如果解析器接受了某个选项，但该选项没有用在对应种类的项上，编译就会报错。请优先使用本页记录的组合，不要依赖关闭 strict 后的行为。

# 命名与导出

内联 Rust 模块可以转换为 JavaScript 命名空间。只有同样带有 #[napi] 的子项会被导出，并且不支持嵌套 napi 模块。

#[napi(js_name = "math")]
mod arithmetic {
  #[napi]
  pub fn add(a: u32, b: u32) -> u32 {
    a + b
  }
}

export namespace math {
  export function add(a: number, b: number): number
}

# module_exports

回调必须是非泛型自由函数。它只能接收 Env、Object 或它们的引用，并且只能返回 () 或 Result<()>。它不能与 constructor、factory、getter、setter、js_name、strict、return_if_invalid 或 no_export 组合使用。

#[napi(module_exports)]
pub fn initialize(mut exports: Object) -> Result<()> {
  exports.set("build", "release")?;
  Ok(())
}

如果初始化不需要 exports 对象，请参阅模块初始化。

# 函数与方法

strict 与 return_if_invalid 互斥。它们校验 Rust 类型的 ValidateNapiValue 实现；不会执行任意的 schema 校验。嵌套 Vec<T> 的元素会逐个转换，即使最初的数组检查已通过，转换仍可能失败。

校验在生成的 JavaScript 回调中执行，早于异步 Rust future 的创建。 因此对于异步导出，strict 可能同步抛出异常，而 return_if_invalid 会对无效输入同步返回 undefined，而不是 Promise。这些属性不会改变生成的 异步返回类型，因此应明确记录这条特殊路径。

# 类与值形状

方向控制是编译期控制：禁用一个方向会移除相应转换 trait 的实现。这适用于包含回调的仅输入形状，或包含无法从 JavaScript 读取的数据的仅输出形状。

#[napi(object, object_to_js = false)]
pub struct Request {
  pub path: String,
  pub on_chunk: ThreadsafeFunction<Buffer>,
}

#[napi(transparent)]
pub struct UserId(pub String);

#[napi(array)]
pub struct Point(pub f64, pub f64);

对于 object 或结构化枚举字段，默认模式会把缺失属性作为 None，并在输出时省略 None。已有属性会按内部类型 T 转换，所以并非所有 T 都接受 null 或 undefined。启用 use_nullable = true 后，属性变为必需；Option<T> 转换会把 null 作为 None，输出则使用 null，但仍会拒绝缺失或值为 undefined 的属性。array 对缺失元组索引与包含 null 的必需索引采用同样区别。对于类，访问器和结构体简写构造函数参数本来就使用普通 Option<T> 转换，getter 会为 None 返回 null；use_nullable 只改变生成的 TypeScript 形状。

# 字段

对于普通类，skip 会移除生成的 JavaScript 访问器，而 skip_typescript 会保留运行时访问器，只隐藏声明。对于 object、array 或结构化枚举，skip 和 readonly 会影响生成的声明，但运行时转换仍会处理该字段。不要将 skip 与 #[napi(constructor)] 结构体简写组合使用：生成的构造函数仍会消费所有字段，但 TypeScript 签名中没有被跳过的字段。

# 枚举

接受的大小写名称为 lowercase、UPPERCASE、PascalCase、camelCase、snake_case、UPPER_SNAKE、kebab-case 和 UPPER-KEBAB-CASE。

#[napi(string_enum = "kebab-case")]
pub enum Mode {
  ReadOnly,
  #[napi(value = "read-write")]
  Writable,
}

#[napi(discriminant = "kind", discriminant_case = "camelCase")]
pub enum Event {
  Ready,
  FileChanged { path: String },
  Progress(u32, u32),
}

string_enum 只接受无字段变体，并且不能与显式 Rust 判别值组合使用。只要枚举包含任何携带数据的变体，它就是结构化枚举；每个变体都会成为带有判别字段及其自身字段的对象。JavaScript 名称与判别字段相同的字段会被拒绝。

# TypeScript 覆盖

#[napi(
  ts_generic_types = "T",
  ts_args_type = "value: T",
  ts_return_type = "T"
)]
pub fn identity<'env>(value: Unknown<'env>) -> Unknown<'env> {
  value
}

#[napi(ts_type = "(operation: 'add' | 'subtract', a: number, b: number): number")]
pub fn calculate(operation: String, a: i32, b: i32) -> i32 {
  match operation.as_str() {
    "add" => a + b,
    "subtract" => a - b,
    _ => 0,
  }
}

这些字符串会直接插入生成的声明；napi-rs 不会把它们解析为 TypeScript，也不会验证它们是否描述了真实的运行时行为。请以运行时转换为准，并测试生成的 .d.ts 文件。

# 迭代器

iterator 与 async_iterator 互斥。生成器类不能暴露名为 next、return 或 throw 的公开字段，因为 napi-rs 会安装这些协议方法。有关所需 trait 和生命周期约束，请参阅迭代器与异步迭代器。

# 选项索引

通用解析器接受以下选项：

catch_unwind、async_runtime、module_exports、js_name、constructor、factory、getter、setter、readonly、enumerable、writable、configurable、skip、strict、return_if_invalid、object、object_from_js、object_to_js、custom_finalize、namespace、iterator、async_iterator、ts_args_type、ts_return_type、ts_type、ts_generic_types、string_enum、use_nullable、discriminant、discriminant_case、transparent、array、no_export 和 skip_typescript。

上下文特定解析器还接受函数参数上的 ts_arg_type，以及字符串枚举变体上的 value。