Node.js v18.15.0 文档

util.callbackify(original)#

中英对照

• original <Function> async 函数
• 返回: <Function> 回调风格的函数

采用 async 函数（或返回 Promise 的函数）并返回遵循错误优先回调风格的函数，即将 (err, value) => ... 回调作为最后一个参数。 在回调中，第一个参数将是拒绝原因（如果 Promise 已解决，则为 null），第二个参数将是已解决的值。

const util = require('node:util');

async function fn() {
  return 'hello world';
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  if (err) throw err;
  console.log(ret);
});

将打印：

hello world

回调是异步执行的，并且将具有有限的堆栈跟踪。 如果回调抛出，进程将触发 'uncaughtException' 事件，如果不处理将退出。

由于 null 作为回调的第一个参数有特殊含义，如果封装的函数使用假值为理由来拒绝 Promise，则该值被封装在 Error 中，原始值存储在名为 reason 的字段中。

function fn() {
  return Promise.reject(null);
}
const callbackFunction = util.callbackify(fn);

callbackFunction((err, ret) => {
  // 当 Promise 使用 `null` 拒绝时，它会使用 Error 封装，
  // 原始值存储在 `reason` 中。
  err && Object.hasOwn(err, 'reason') && err.reason === null;  // true
});

util.debuglog(section[, callback])#

中英对照

• section <string> 标识正在为其创建 debuglog 函数的应用程序部分的字符串。
• callback <Function> 第一次调用日志函数时调用的回调函数参数是更优化的日志函数。
• 返回: <Function> 日志函数

util.debuglog() 方法用于创建函数，该函数根据 NODE_DEBUG 环境变量的存在有条件地将调试消息写入 stderr。 如果 section 名称出现在该环境变量的值中，则返回的函数的操作类似于 console.error()。 如果不是，则返回的函数是空操作。

const util = require('node:util');
const debuglog = util.debuglog('foo');

debuglog('hello from foo [%d]', 123);

如果这个程序在环境中与 NODE_DEBUG=foo 一起运行，则它会输出如下内容：

FOO 3245: hello from foo [123]

其中 3245 是进程 ID。 如果它没有使用该环境变量集运行，则它不会打印任何内容。

section 还支持通配符：

const util = require('node:util');
const debuglog = util.debuglog('foo-bar');

debuglog('hi there, it\'s foo-bar [%d]', 2333);

如果它在环境中与 NODE_DEBUG=foo* 一起运行，则它将输出如下内容：

FOO-BAR 3257: hi there, it's foo-bar [2333]

可以在 NODE_DEBUG 环境变量中指定多个逗号分隔的 section 名称：NODE_DEBUG=fs,net,tls。

可选的 callback 参数可用于用一个不同的函数替换日志函数，该函数没有任何初始化或不必要的封装。

const util = require('node:util');
let debuglog = util.debuglog('internals', (debug) => {
  // 如果启用该部分，
  // 则替换为优化测试的日志记录函数
  debuglog = debug;
});

debuglog().enabled#

中英对照

• <boolean>

util.debuglog().enabled 获取器用于基于 NODE_DEBUG 环境变量的存在创建可用于条件的测试。 如果 section 名称出现在该环境变量的值中，则返回值将为 true。 如果不是，则返回值将是 false。

const util = require('node:util');
const enabled = util.debuglog('foo').enabled;
if (enabled) {
  console.log('hello from foo [%d]', 123);
}

如果这个程序在环境中与 NODE_DEBUG=foo 一起运行，则它会输出如下内容：

hello from foo [123]

util.debug(section)#

中英对照

util.debuglog 的别名。 当仅使用 util.debuglog().enabled 时，使用允许可读性并不意味着日志记录。

util.deprecate(fn, msg[, code])#

中英对照

• fn <Function> 被弃用的函数。
• msg <string> 调用弃用的函数时显示的警告消息。
• code <string> 弃用代码。 有关代码的列表，请参阅弃用的 API 列表。
• 返回: <Function> 弃用的函数被封装以触发警告。

util.deprecate() 方法以标记为已弃用的方式封装 fn（可能是函数或类）。

const util = require('node:util');

exports.obsoleteFunction = util.deprecate(() => {
  // 在这里做点事情。
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');

当调用时，util.deprecate() 将返回将使用 'warning' 事件触发 DeprecationWarning 的函数。 第一次调用返回的函数时，警告将触发并打印到 stderr。 触发警告后，将调用封装的函数而不触发警告。

如果在多次调用 util.deprecate() 时提供了相同的可选 code，则该 code 只会触发一次警告。

const util = require('node:util');

const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // 使用代码 DEP0001 触发弃用警告
fn2(); // 不触发弃用警告，因为它具有相同的代码

如果使用 --no-deprecation 或 --no-warnings 命令行标志、或者如果 process.noDeprecation 属性在第一次弃用警告之前设置为 true，则 util.deprecate() 方法不执行任何操作。

如果设置了 --trace-deprecation 或 --trace-warnings 命令行标志、或者 process.traceDeprecation 属性设置为 true，则在第一次调用已弃用的函数时会向 stderr 打印警告和堆栈跟踪。

如果设置了 --throw-deprecation 命令行标志、或者 process.throwDeprecation 属性设置为 true，则在调用已弃用的函数时将抛出异常。

--throw-deprecation 命令行标志和 process.throwDeprecation 属性优先于 --trace-deprecation 和 process.traceDeprecation。

util.format(format[, ...args])#

中英对照

• format <string> 类似 printf 的格式字符串。

util.format() 方法使用第一个参数作为类似 printf 的格式字符串（其可以包含零个或多个格式说明符）来返回格式化的字符串。 每个说明符都替换为来自相应参数的转换后的值。 支持的说明符有：

• %s: String 将用于转换除 BigInt、Object 和 -0 之外的所有值。 BigInt 值将用 n 表示，没有用户定义的 toString 函数的对象使用具有选项 { depth: 0, colors: false, compact: 3 } 的 util.inspect() 进行检查。
• %d: Number 将用于转换除 BigInt 和 Symbol 之外的所有值。
• %i: parseInt(value, 10) 用于除 BigInt 和 Symbol 之外的所有值。
• %f: parseFloat(value) 用于除 Symbol 之外的所有值。
• %j: JSON。 如果参数包含循环引用，则替换为字符串 '[Circular]'。
• %o: Object. 具有通用 JavaScript 对象格式的对象的字符串表示形式。 类似于具有选项 { showHidden: true, showProxy: true } 的 util.inspect()。 这将显示完整的对象，包括不可枚举的属性和代理。
• %O: Object. 具有通用 JavaScript 对象格式的对象的字符串表示形式。 类似于没有选项的 util.inspect()。 这将显示完整的对象，但不包括不可枚举的属性和代理。
• %c: CSS. 此说明符被忽略，将跳过任何传入的 CSS。
• %%: 单个百分号 ('%')。 这不消费参数。
• 返回: <string> 格式化的字符串

如果说明符没有相应的参数，则不会替换它：

util.format('%s:%s', 'foo');
// 返回: 'foo:%s'

如果其类型不是 string，则不属于格式字符串的值将使用 util.inspect() 进行格式化。

如果传给 util.format() 方法的参数多于说明符的数量，则额外的参数将以空格分隔串联到返回的字符串：

util.format('%s:%s', 'foo', 'bar', 'baz');
// 返回: 'foo:bar baz'

如果第一个参数不包含有效的格式说明符，则 util.format() 返回以空格分隔的所有参数的串联的字符串：

util.format(1, 2, 3);
// 返回: '1 2 3'

如果只有一个参数传给 util.format()，则它会按原样返回，不进行任何格式化：

util.format('%% %s');
// 返回: '%% %s'

util.format() 是同步的方法，旨在用作调试工具。 某些输入值可能会产生显着的性能开销，从而阻塞事件循环。 小心使用此函数，切勿在热代码路径中使用。

util.formatWithOptions(inspectOptions, format[, ...args])#

中英对照

• inspectOptions <Object>
• format <string>

此函数与 util.format() 相同，不同之处在于它接受 inspectOptions 参数，该参数指定传给 util.inspect() 的选项。

util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
// 返回 'See object { foo: 42 }'，
// 其中 `42` 在打印到终端时被着色为数字。

util.getSystemErrorName(err)#

中英对照

• err <number>
• 返回: <string>

返回来自 Node.js API 的数字错误码的字符串名称。 错误码和错误名称之间的映射是平台相关的。 有关常见错误的名称，请参阅常见的系统错误。

fs.access('file/that/does/not/exist', (err) => {
  const name = util.getSystemErrorName(err.errno);
  console.error(name);  // ENOENT
});

util.getSystemErrorMap()#

中英对照

• 返回: <Map>

返回来自 Node.js API 的可用的所有系统错误码的映射。 错误码和错误名称之间的映射是平台相关的。 有关常见错误的名称，请参阅常见的系统错误。

fs.access('file/that/does/not/exist', (err) => {
  const errorMap = util.getSystemErrorMap();
  const name = errorMap.get(err.errno);
  console.error(name);  // ENOENT
});

util.inherits(constructor, superConstructor)#

中英对照

• constructor <Function>
• superConstructor <Function>

不鼓励使用 util.inherits()。 请使用 ES6 class 和 extends 关键字来获得语言级别的继承支持。 另请注意，这两种风格在语义上不兼容。

将原型方法从一个构造函数继承到另一个构造函数。 constructor 的原型将被设置为从 superConstructor 创建的新对象。

这主要是在 Object.setPrototypeOf(constructor.prototype, superConstructor.prototype) 之上添加了一些输入验证。 作为额外的便利，superConstructor 将可通过 constructor.super_ 属性访问。

const util = require('node:util');
const EventEmitter = require('node:events');

function MyStream() {
  EventEmitter.call(this);
}

util.inherits(MyStream, EventEmitter);

MyStream.prototype.write = function(data) {
  this.emit('data', data);
};

const stream = new MyStream();

console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('It works!'); // 接收到的数据："It works!"

使用 class 和 extends 的 ES6 示例：

const EventEmitter = require('node:events');

class MyStream extends EventEmitter {
  write(data) {
    this.emit('data', data);
  }
}

const stream = new MyStream();

stream.on('data', (data) => {
  console.log(`Received data: "${data}"`);
});
stream.write('With ES6');

util.inspect(object[, options])#

util.inspect(object[, showHidden[, depth[, colors]]])#

中英对照

• object <any> 任何 JavaScript 原始类型或 Object。
• options <Object>
  • showHidden <boolean> 如果为 true，则 object 的不可枚举符号和属性包含在格式化的结果中。 WeakMap 和 WeakSet 条目以及用户定义的原型属性（不包括方法属性）也包括在内。 默认值: false。
  • depth <number> 指定格式化 object 时递归的次数。 这对于检查大型对象很有用。 要递归到最大调用堆栈大小，则传入 Infinity 或 null。 默认值: 2。
  • colors <boolean> 如果为 true，则输出的样式为 ANSI 颜色代码。 颜色是可自定义的。 参阅自定义 util.inspect 颜色。 默认值: false。
  • customInspect <boolean> 如果为 false，则 [util.inspect.custom](depth, opts, inspect) 函数不被调用。 默认值: true。
  • showProxy <boolean> 如果为 true，则 Proxy 检查包括 target 和 handler 对象。 默认值: false。
  • maxArrayLength <integer> 指定格式化时要包含的 Array、TypedArray、WeakMap 和 WeakSet 元素的最大数量。 设置为 null 或 Infinity 则显示所有元素。 设置为 0 或负数则不显示任何元素。 默认值: 100。
  • maxStringLength <integer> 指定格式化时要包含的最大字符数。 设置为 null 或 Infinity 则显示所有元素。 设置为 0 或负数则不显示字符。 默认值: 10000。
  • breakLength <integer> 输入值在多行中拆分的长度。 设置为 Infinity 则将输入格式化为单行（与设置为 true 或任何数字 >= 1 的 compact 组合）。 默认值: 80。
  • compact <boolean> | <integer> 将此设置为 false 会导致每个对象的键显示在新行上。 它将在比 breakLength 长的文本中换行。 如果设置为数字，则只要所有属性都适合 breakLength，则最多 n 个内部元素将合并在一行中。 短数组元素也组合在一起。 有关更多信息，请参阅下面的示例。 默认值: 3。
  • sorted <boolean> | <Function> 如果设置为 true 或函数，则对象的所有属性以及 Set 和 Map 条目都将在结果字符串中排序。 如果设置为 true，则使用默认的排序。 如果设置为函数，则用作比较函数。
  • getters <boolean> | <string> 如果设置为 true，则检查获取器。 如果设置为 'get'，则只检查没有相应设置器的获取器。 如果设置为 'set'，则只检查具有相应设置器的获取器。 这可能会导致副作用，具体取决于获取器函数。 默认值: false。
  • numericSeparator <boolean> 如果设置为 true，则使用下划线分隔所有 bigint 和数字中的每三个数字。 默认值: false。
• 返回: <string> object 的表示。

util.inspect() 方法返回用于调试的 object 的字符串表示。 util.inspect 的输出可能随时更改，不应以编程方式依赖。 可以传入额外的 options 来改变结果。 util.inspect() 将使用构造函数的名称和/或 @@toStringTag 为检查的值制作可识别的标签。

class Foo {
  get [Symbol.toStringTag]() {
    return 'bar';
  }
}

class Bar {}

const baz = Object.create(null, { [Symbol.toStringTag]: { value: 'foo' } });

util.inspect(new Foo()); // 'Foo [bar] {}'
util.inspect(new Bar()); // 'Bar {}'
util.inspect(baz);       // '[foo] {}'

循环引用通过使用引用索引指向其锚点：

const { inspect } = require('node:util');

const obj = {};
obj.a = [obj];
obj.b = {};
obj.b.inner = obj.b;
obj.b.obj = obj;

console.log(inspect(obj));
// <ref *1> {
//   a: [ [Circular *1] ],
//   b: <ref *2> { inner: [Circular *2], obj: [Circular *1] }
// }

以下示例检查 util 对象的所有属性：

const util = require('node:util');

console.log(util.inspect(util, { showHidden: true, depth: null }));

以下示例高亮了 compact 选项的效果：

const util = require('node:util');

const o = {
  a: [1, 2, [[
    'Lorem ipsum dolor sit amet,\nconsectetur adipiscing elit, sed do ' +
      'eiusmod \ntempor incididunt ut labore et dolore magna aliqua.',
    'test',
    'foo']], 4],
  b: new Map([['za', 1], ['zb', 'test']]),
};
console.log(util.inspect(o, { compact: true, depth: 5, breakLength: 80 }));

// { a:
//   [ 1,
//     2,
//     [ [ 'Lorem ipsum dolor sit amet,\nconsectetur [...]', // A long line
//           'test',
//           'foo' ] ],
//     4 ],
//   b: Map(2) { 'za' => 1, 'zb' => 'test' } }

// 将 `compact` 设置为 false 或整数会创建更友好的输出。
console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 }));

// {
//   a: [
//     1,
//     2,
//     [
//       [
//         'Lorem ipsum dolor sit amet,\n' +
//           'consectetur adipiscing elit, sed do eiusmod \n' +
//           'tempor incididunt ut labore et dolore magna aliqua.',
//         'test',
//         'foo'
//       ]
//     ],
//     4
//   ],
//   b: Map(2) {
//     'za' => 1,
//     'zb' => 'test'
//   }
// }

// 将 `breakLength` 设置为例如 150，
// 则将在一行中打印 "Lorem ipsum" 文本。

showHidden 选项允许检查 WeakMap 和 WeakSet 条目。 如果条目多于 maxArrayLength，则无法保证显示哪些条目。 这意味着两次检索相同的 WeakSet 条目可能会导致不同的输出。 此外，没有剩余强引用的条目可能随时被垃圾回收。

const { inspect } = require('node:util');

const obj = { a: 1 };
const obj2 = { b: 2 };
const weakSet = new WeakSet([obj, obj2]);

console.log(inspect(weakSet, { showHidden: true }));
// WeakSet { { a: 1 }, { b: 2 } }

sorted 选项确保对象的属性插入顺序不会影响 util.inspect() 的结果。

const { inspect } = require('node:util');
const assert = require('node:assert');

const o1 = {
  b: [2, 3, 1],
  a: '`a` comes before `b`',
  c: new Set([2, 3, 1]),
};
console.log(inspect(o1, { sorted: true }));
// { a: '`a` comes before `b`', b: [ 2, 3, 1 ], c: Set(3) { 1, 2, 3 } }
console.log(inspect(o1, { sorted: (a, b) => b.localeCompare(a) }));
// { c: Set(3) { 3, 2, 1 }, b: [ 2, 3, 1 ], a: '`a` comes before `b`' }

const o2 = {
  c: new Set([2, 1, 3]),
  a: '`a` comes before `b`',
  b: [2, 3, 1],
};
assert.strict.equal(
  inspect(o1, { sorted: true }),
  inspect(o2, { sorted: true }),
);

numericSeparator 选项为所有数字每三位添加一个下划线。

const { inspect } = require('node:util');

const thousand = 1_000;
const million = 1_000_000;
const bigNumber = 123_456_789n;
const bigDecimal = 1_234.123_45;

console.log(thousand, million, bigNumber, bigDecimal);
// 1_000 1_000_000 123_456_789n 1_234.123_45

util.inspect() 是用于调试的同步方法。 其最大输出长度约为 128 MiB。 造成更长输出的输入将被截断。

自定义 util.inspect 的颜色#

中英对照

util.inspect 的颜色输出（如果启用）可通过 util.inspect.styles 和 util.inspect.colors 属性全局地自定义。

util.inspect.styles 是将样式名称与来自 util.inspect.colors 的颜色相关联的映射。

默认的样式和相关的颜色为：

• bigint: yellow
• boolean: yellow
• date: magenta
• module: underline
• name: （没有样式）
• null: bold
• number: yellow
• regexp: red
• special: cyan（例如，Proxies）
• string: green
• symbol: green
• undefined: grey

颜色样式使用 ANSI 控制代码，可能并非所有终端都支持。 要验证颜色支持，则使用 tty.hasColors()。

下面列出了预定义的控制代码（分组为“修饰符”、“前景色”和“背景色”）。

修饰符#

中英对照

修饰符的支持因不同的终端而异。 如果不支持，则它们通常会被忽略。

• reset - 将所有（颜色）修饰符重置为其默认值
• bold - 使文本加粗
• italic - 使文本斜体
• underline - 使文本下划线
• strikethrough - 在文本中间放置一条水平线（别名：strikeThrough, crossedout, crossedOut）
• hidden - 打印文本，但使其不可见（别名：conceal）
• dim - 颜色强度降低（别名：faint）
• overlined - 使文本上划线
• blink - 间隔地隐藏和显示文本
• inverse - 交换前景色和背景色（别名：swapcolors、swapColors）
• doubleunderline - 使文本双下划线（别名：doubleUnderline）
• framed - 在文本周围画一个框架

前景颜色#

中英对照

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• gray（别名：grey、blackBright）
• redBright
• greenBright
• yellowBright
• blueBright
• magentaBright
• cyanBright
• whiteBright

背景颜色#

中英对照

• bgBlack
• bgRed
• bgGreen
• bgYellow
• bgBlue
• bgMagenta
• bgCyan
• bgWhite
• bgGray（别名：bgGrey、bgBlackBright）
• bgRedBright
• bgGreenBright
• bgYellowBright
• bgBlueBright
• bgMagentaBright
• bgCyanBright
• bgWhiteBright

对象上的自定义检查函数#

中英对照

对象也可以定义自己的 [util.inspect.custom](depth, opts, inspect) 函数，util.inspect() 将在检查对象时调用并使用其结果。

const util = require('node:util');

class Box {
  constructor(value) {
    this.value = value;
  }

  [util.inspect.custom](depth, options, inspect) {
    if (depth < 0) {
      return options.stylize('[Box]', 'special');
    }

    const newOptions = Object.assign({}, options, {
      depth: options.depth === null ? null : options.depth - 1,
    });

    // 五个空格填充，因为这是“Box<”的大小。
    const padding = ' '.repeat(5);
    const inner = inspect(this.value, newOptions)
                  .replace(/\n/g, `\n${padding}`);
    return `${options.stylize('Box', 'special')}< ${inner} >`;
  }
}

const box = new Box(true);

util.inspect(box);
// 返回: "Box< true >"

自定义的 [util.inspect.custom](depth, opts, inspect) 函数通常返回一个字符串，但也可能返回一个由 util.inspect() 相应格式化的任何类型的值。

const util = require('node:util');

const obj = { foo: 'this will not show up in the inspect() output' };
obj[util.inspect.custom] = (depth) => {
  return { bar: 'baz' };
};

util.inspect(obj);
// 返回: "{ bar: 'baz' }"

util.inspect.custom#

中英对照

• <symbol> 可用于声明自定义的检查函数。

除了可以通过 util.inspect.custom 访问之外，此符号是全局地注册，可以在任何环境中作为 Symbol.for('nodejs.util.inspect.custom') 访问。

使用此允许以可移植方式编写代码，以便在 Node.js 环境中使用自定义检查功能并在浏览器中忽略。 util.inspect() 函数本身作为第三个参数传给自定义检查函数以允许进一步的可移植性。

const customInspectSymbol = Symbol.for('nodejs.util.inspect.custom');

class Password {
  constructor(value) {
    this.value = value;
  }

  toString() {
    return 'xxxxxxxx';
  }

  [customInspectSymbol](depth, inspectOptions, inspect) {
    return `Password <${this.toString()}>`;
  }
}

const password = new Password('r0sebud');
console.log(password);
// 打印 Password <xxxxxxxx>

有关更多详细信息，请参阅对象上的自定义检查函数。

util.inspect.defaultOptions#

中英对照

defaultOptions 值允许自定义 util.inspect 使用的默认选项。 这对于像 console.log 或 util.format 这样隐式调用 util.inspect 的函数很有用。 它应设置为包含一个或多个有效 util.inspect() 选项的对象。 也支持直接设置选项属性。

const util = require('node:util');
const arr = Array(101).fill(0);

console.log(arr); // 记录截断的数组
util.inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // 记录完整的数组

util.isDeepStrictEqual(val1, val2)#

中英对照

• val1 <any>
• val2 <any>
• 返回: <boolean>

如果 val1 和 val2 之间存在深度严格相等，则返回 true。 否则，返回 false。

有关深度严格相等的更多信息，请参见 assert.deepStrictEqual()。

util.MIMEType 类#

中英对照

MIMEType 类 的实现。

按照浏览器的约定，MIMEType 对象的所有属性都被实现为类原型上的获取器和设置器，而不是对象本身的数据属性。

MIME 字符串是包含多个有意义的组件的结构化字符串。 解析后，将返回一个 MIMEType 对象，其中包含每个组件的属性。

Constructor: new MIMEType(input)#

中英对照

• input <string> 要解析的输入 MIME

通过解析 input 创建一个新的 MIMEType 对象。

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/plain');const { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/plain');

如果 input 不是有效的 MIME，将抛出 TypeError。 注意，会将给定的值强制转换为字符串。 例如：

import { MIMEType } from 'node:util';
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// 打印: text/plainconst { MIMEType } = require('node:util');
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// 打印: text/plain

mime.type#

中英对照

• <string>

获取和设置 MIME 的类型部分。

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// 打印: text
myMIME.type = 'application';
console.log(myMIME.type);
// 打印: application
console.log(String(myMIME));
// 打印: application/javascriptconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// 打印: text
myMIME.type = 'application';
console.log(myMIME.type);
// 打印: application
console.log(String(myMIME));
// 打印: application/javascript

mime.subtype#

中英对照

• <string>

获取和设置 MIME 的子类型部分。

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// 打印: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// 打印: javascript
console.log(String(myMIME));
// 打印: text/javascriptconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// 打印: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// 打印: javascript
console.log(String(myMIME));
// 打印: text/javascript

mime.essence#

中英对照

• <string>

获取 MIME 的精髓。 这个属性是只读的。 使用 mime.type 或 mime.subtype 改变 MIME。

import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// 打印: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// 打印: application/javascript
console.log(String(myMIME));
// 打印: application/javascript;key=valueconst { MIMEType } = require('node:util');

const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// 打印: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// 打印: application/javascript
console.log(String(myMIME));
// 打印: application/javascript;key=value

mime.params#

中英对照

• <MIMEParams>

获取表示 MIME 参数的 MIMEParams 对象。 这个属性是只读的。 有关详细信息，请参阅 MIMEParams 文档。

mime.toString()#

中英对照

• 返回: <string>

MIMEType 对象上的 toString() 方法返回序列化的 MIME。

因为符合标准的需要，该方法不允许用户自定义MIME的序列化过程。

mime.toJSON()#

中英对照

• 返回: <string>

mime.toString() 的别名。

当 MIMEType 对象用 JSON.stringify() 序列化时，会自动调用此方法。

import { MIMEType } from 'node:util';

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// 打印: ["image/png", "image/gif"]const { MIMEType } = require('node:util');

const myMIMES = [
  new MIMEType('image/png'),
  new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// 打印: ["image/png", "image/gif"]

util.MIMEParams 类#

中英对照

MIMEParams API 提供对 MIMEType 参数的读写访问。

Constructor: new MIMEParams()#

中英对照

使用空参数创建一个新的 MIMEParams 对象

import { MIMEParams } from 'node:util';

const myParams = new MIMEParams();const { MIMEParams } = require('node:util');

const myParams = new MIMEParams();

mimeParams.delete(name)#

中英对照

• name <string>

删除名称为 name 的所有名称-值对。

mimeParams.entries()#

中英对照

• 返回: <Iterator>

返回参数中每个名称-值对的迭代器。 迭代器的每一项都是 JavaScript Array。 数组的第一项是 name，数组的第二项是 value。

mimeParams.get(name)#

中英对照

• name <string>
• 返回: <string> 或 null，如果给定的 name 没有名称-值对。

返回名称为 name 的第一个名称-值对的值。 如果没有这样的对，则返回 null。

mimeParams.has(name)#

中英对照

• name <string>
• 返回: <boolean>

如果至少有一个名称-值对的名称为 name，则返回 true。

mimeParams.keys()#

中英对照

• 返回: <Iterator>

返回每个名称-值对名称的迭代器。

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
  console.log(name);
}
// 打印:
//   foo
//   barconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
  console.log(name);
}
// 打印:
//   foo
//   bar

mimeParams.set(name, value)#

中英对照

• name <string>
• value <string>

将与 name 关联的 MIMEParams 对象中的值设置为 value。 如果有任何名称为 name 的预先存在的名称-值对，将第一个这样的对的值设置为 value。

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=0;bar=1');
params.set('foo', 'def');
params.set('baz', 'xyz');
console.log(params.toString());
// 打印: foo=def&bar=1&baz=xyzconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=0;bar=1');
params.set('foo', 'def');
params.set('baz', 'xyz');
console.log(params.toString());
// 打印: foo=def&bar=1&baz=xyz

mimeParams.values()#

中英对照

• 返回: <Iterator>

返回每个名称-值对的值的迭代器。

mimeParams[@@iterator]()#

中英对照

• 返回: <Iterator>

mimeParams.entries() 的别名。

import { MIMEType } from 'node:util';

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// 打印:
//   foo bar
//   xyz bazconst { MIMEType } = require('node:util');

const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// 打印:
//   foo bar
//   xyz baz

util.parseArgs([config])#

中英对照

• config <Object> 用于提供解析参数和配置解析器。 config 支持以下属性：

  • args <string[]> 参数字符串数组。 默认值: process.argv 删除了 execPath 和 filename。
  • options <Object> 用于描述解析器已知的参数。 options 的键是选项的长名称，值是 <Object>，接受以下属性：
    • type <string> 参数类型，必须是 boolean 或 string。
    • multiple <boolean> 是否可以多次提供该选项。 如果为 true，则所有的值都会被收集到一个数组中。 如果为 false，则选项的值是最后获胜的。 默认值: false。
    • short <string> 选项的单个字符别名。
    • default <string> | <boolean> | <string[]> | <boolean[]> 未由 args 设置时的默认选项值。 它必须与 type 属性的类型相同。 当 multiple 为 true 时，它必须是一个数组。
  • strict <boolean> 当遇到未知参数时，或者当传入的参数与 options 中配置的 type 不匹配时，是否应该抛出错误。 默认值: true。
  • allowPositionals <boolean> 此命令是否接受位置参数。 默认值: false 如果 strict 是 true，否则 true。
  • tokens <boolean> 返回解析的令牌。 这对于扩展内置行为很有用，从添加额外检查到以不同方式重新处理令牌。 默认值: false。

• 返回: <Object> 解析后的命令行参数：

  • values <Object> 解析的选项名称与其 <string> 或 <boolean> 值的映射。
  • positionals <string[]> 位置参数。
  • tokens <Object[]> | <undefined> 参见 parseArgs 令牌章节。 仅当 config 包含 tokens: true 时才返回。

为命令行参数解析提供比直接与 process.argv 交互更高级别的 API。 采用预期参数的规范并返回带有解析选项和位置的结构化对象。

import { parseArgs } from 'node:util';
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// 打印: [Object: null prototype] { foo: true, bar: 'b' } []const { parseArgs } = require('node:util');
const args = ['-f', '--bar', 'b'];
const options = {
  foo: {
    type: 'boolean',
    short: 'f',
  },
  bar: {
    type: 'string',
  },
};
const {
  values,
  positionals,
} = parseArgs({ args, options });
console.log(values, positionals);
// 打印: [Object: null prototype] { foo: true, bar: 'b' } []

util.parseArgs 是实验性的，行为可能会改变。 加入 pkgjs/parseargs 中的对话，为设计做出贡献。

parseArgs tokens#

中英对照

详细的解析信息可用于通过在配置中指定 tokens: true 添加自定义行为。 返回的令牌具有描述的属性：

• 所有令牌
  • kind <string> 'option'、'positional' 或 'option-terminator' 之一。
  • index <number> args 中包含标记的元素索引。 所以令牌的源参数是 args[token.index]。
• 选项令牌
  • name <string> 选项的长名称。
  • rawName <string> 如何在 args 中使用选项，例如 --foo 的 -f。
  • value <string> | <undefined> 参数中指定的选项值。 布尔选项未定义。
  • inlineValue <boolean> | <undefined> 是否内联指定选项值，如 --foo=bar。
• 位置标记
  • value <string> args 中位置参数的值（即 args[index]）。
• 选项终止令牌

返回的令牌按照输入参数中遇到的顺序。 在 args 中出现多次的选项每次使用都会产生一个令牌。 像 -xy 这样的短选项组扩展为每个选项的令牌。 所以 -xxx 产生了三个令牌。

例如，要使用返回的令牌来添加对 --no-color 等否定选项的支持，可以重新处理令牌以更改为否定选项存储的值。

import { parseArgs } from 'node:util';

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// 重新处理选项令牌并覆盖返回值。
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // 为 --no-foo 存储 foo:false
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // 如果 --foo 和 --no-foo 都保留值，则最后一个获胜。
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });const { parseArgs } = require('node:util');

const options = {
  'color': { type: 'boolean' },
  'no-color': { type: 'boolean' },
  'logfile': { type: 'string' },
  'no-logfile': { type: 'boolean' },
};
const { values, tokens } = parseArgs({ options, tokens: true });

// 重新处理选项令牌并覆盖返回值。
tokens
  .filter((token) => token.kind === 'option')
  .forEach((token) => {
    if (token.name.startsWith('no-')) {
      // 为 --no-foo 存储 foo:false
      const positiveName = token.name.slice(3);
      values[positiveName] = false;
      delete values[token.name];
    } else {
      // 如果 --foo 和 --no-foo 都保留值，则最后一个获胜。
      values[token.name] = token.value ?? true;
    }
  });

const color = values.color;
const logfile = values.logfile ?? 'default.log';

console.log({ logfile, color });

显示否定选项的示例用法，当一个选项以多种方式使用时，最后一个获胜。

$ node negate.js
{ logfile: 'default.log', color: undefined }
$ node negate.js --no-logfile --no-color
{ logfile: false, color: false }
$ node negate.js --logfile=test.log --color
{ logfile: 'test.log', color: true }
$ node negate.js --no-logfile --logfile=test.log --color --no-color
{ logfile: 'test.log', color: false }

util.promisify(original)#

中英对照

• original <Function>
• 返回: <Function>

采用遵循常见的错误优先的回调风格的函数（也就是将 (err, value) => ... 回调作为最后一个参数），并返回一个返回 promise 的版本。

const util = require('node:util');
const fs = require('node:fs');

const stat = util.promisify(fs.stat);
stat('.').then((stats) => {
  // 使用 `stats` 做些事情
}).catch((error) => {
  // 处理错误。
});

或者，等效地使用 async function：

const util = require('node:util');
const fs = require('node:fs');

const stat = util.promisify(fs.stat);

async function callStat() {
  const stats = await stat('.');
  console.log(`This directory is owned by ${stats.uid}`);
}

如果存在 original[util.promisify.custom] 属性，则 promisify 将返回其值，请参阅自定义的 promise 化函数。

promisify() 假设 original 是在所有情况下都将回调作为其最后一个参数的函数。 如果 original 不是函数，则 promisify() 将抛出错误。 如果 original 是函数，但其最后一个参数不是错误优先的回调，则它仍然会被传入错误优先的回调作为其最后一个参数。

除非经过特殊处理，否则在类方法或其他使用 this 的方法上使用 promisify() 可能无法按预期工作：

const util = require('node:util');

class Foo {
  constructor() {
    this.a = 42;
  }

  bar(callback) {
    callback(null, this.a);
  }
}

const foo = new Foo();

const naiveBar = util.promisify(foo.bar);
// TypeError: Cannot read property 'a' of undefined
// naiveBar().then(a => console.log(a));

naiveBar.call(foo).then((a) => console.log(a)); // '42'

const bindBar = naiveBar.bind(foo);
bindBar().then((a) => console.log(a)); // '42'

自定义的 promise 化函数#

中英对照

使用 util.promisify.custom 符号可以覆盖 util.promisify() 的返回值：

const util = require('node:util');

function doSomething(foo, callback) {
  // ...
}

doSomething[util.promisify.custom] = (foo) => {
  return getPromiseSomehow();
};

const promisified = util.promisify(doSomething);
console.log(promisified === doSomething[util.promisify.custom]);
// 打印 'true'

这对于原始函数不遵循将错误优先的回调作为最后一个参数的标准格式的情况很有用。

例如，对于接受 (foo, onSuccessCallback, onErrorCallback) 的函数：

doSomething[util.promisify.custom] = (foo) => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject);
  });
};

如果 promisify.custom 已定义但不是函数，则 promisify() 将抛出错误。

util.promisify.custom#

中英对照

• <symbol> 可用于声明自定义的 promise 化的函数变体，参阅自定义的 promise 化函数。

除了可以通过 util.promisify.custom 访问之外，此符号是全局地注册，可以在任何环境中作为 Symbol.for('nodejs.util.promisify.custom') 访问。

例如，对于接受 (foo, onSuccessCallback, onErrorCallback) 的函数：

const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom');

doSomething[kCustomPromisifiedSymbol] = (foo) => {
  return new Promise((resolve, reject) => {
    doSomething(foo, resolve, reject);
  });
};

util.stripVTControlCharacters(str)#

中英对照

• str <string>
• 返回: <string>

返回已删除任何 ANSI 转义码的 str。

console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
// 打印 "value"

util.TextDecoder 类#

中英对照

WHATWG 编码标准 TextDecoder API 的实现。

const decoder = new TextDecoder();
const u8arr = new Uint8Array([72, 101, 108, 108, 111]);
console.log(decoder.decode(u8arr)); // Hello

WHATWG 支持的编码#

中英对照

根据 WHATWG 编码标准，TextDecoder API 支持的编码在下表中列出。 对于每种编码，可以使用一个或多个别名。

不同的 Node.js 构建配置支持不同的编码集。 （参见国际化）

默认支持的编码（带有完整的 ICU 数据）#

使用 small-icu 选项构建的 Node.js 支持的编码#

当 ICU 被禁用时支持的编码#

中英对照

不支持 WHATWG 编码标准中列出的 'iso-8859-16' 编码。

new TextDecoder([encoding[, options]])#

中英对照

• encoding <string> 标识此 TextDecoder 实例支持的 encoding。 默认值: 'utf-8'。
• options <Object>
  • fatal <boolean> 如果解码失败是致命的，则为 true。 禁用 ICU 时不支持此选项（请参阅国际化）。 默认值: false。
  • ignoreBOM <boolean> 当 true 时，TextDecoder 将在解码结果中包含字节顺序标记。 当 false 时，字节顺序标记将从输出中删除。 此选项仅在 encoding 为 'utf-8'、'utf-16be' 或 'utf-16le' 时使用。 默认值: false。

创建新的 TextDecoder 实例。 encoding 可以指定支持的编码之一或别名。

TextDecoder 类也在全局对象上可用。

textDecoder.decode([input[, options]])#

中英对照

• input <ArrayBuffer> | <DataView> | <TypedArray> 包含编码数据的 ArrayBuffer、DataView 或 TypedArray 实例。
• options <Object>
  • stream <boolean> 如果需要额外的数据块，则为 true。 默认值: false。
• 返回: <string>

解码 input 并返回字符串。 如果 options.stream 是 true，则在 input 末尾出现的任何不完整的字节序列都会在内部缓冲并在下一次调用 textDecoder.decode() 后触发。

如果 textDecoder.fatal 是 true，则发生的解码错误将导致抛出 TypeError。

textDecoder.encoding#

中英对照

• <string>

TextDecoder 实例支持的编码。

textDecoder.fatal#

中英对照

• <boolean>

如果解码错误导致抛出 TypeError，则该值将为 true。

textDecoder.ignoreBOM#

中英对照

• <boolean>

如果解码结果将包含字节顺序标记，则该值将为 true。

util.TextEncoder 类#

中英对照

WHATWG 编码标准 TextEncoder API 的实现。 TextEncoder 的所有实例仅支持 UTF-8 编码。

const encoder = new TextEncoder();
const uint8array = encoder.encode('this is some data');

TextEncoder 类也在全局对象上可用。

textEncoder.encode([input])#

中英对照

• input <string> 要编码的文本。 默认值: 空字符串。
• 返回: <Uint8Array>

对 input 字符串进行 UTF-8 编码并返回包含编码字节的 Uint8Array。

textEncoder.encodeInto(src, dest)#

中英对照

• src <string> 要编码的文本。
• dest <Uint8Array> 保存编码结果的数组。
• 返回: <Object>
  • read <number> 读取的来源的 Unicode 代码单元。
  • written <number> 写入的目标的 UTF-8 字节。

将 src 字符串 UTF-8 编码为 dest Uint8Array 并返回包含读取的 Unicode 代码单元和写入的 UTF-8 字节的对象。

const encoder = new TextEncoder();
const src = 'this is some data';
const dest = new Uint8Array(10);
const { read, written } = encoder.encodeInto(src, dest);

textEncoder.encoding#

中英对照

• <string>

TextEncoder 实例支持的编码。 始终设置为 'utf-8'。

util.toUSVString(string)#

中英对照

• string <string>

在用 Unicode “替换字符” U+FFFD 替换任何代理代码点（或等效地，任何未配对的代理代码单元）后返回 string。

util.transferableAbortController()#

中英对照

创建并返回一个 <AbortController> 实例，其 <AbortSignal> 被标记为可转让，可与 structuredClone() 或 postMessage() 一起使用。

util.transferableAbortSignal(signal)#

中英对照

• signal <AbortSignal>
• 返回: <AbortSignal>

将给定的 <AbortSignal> 标记为可转让，以便它可以与 structuredClone() 和 postMessage() 一起使用。

const signal = transferableAbortSignal(AbortSignal.timeout(100));
const channel = new MessageChannel();
channel.port2.postMessage(signal, [signal]);

util.types#

中英对照

util.types 为不同种类的内置对象提供类型检查。 与 instanceof 或 Object.prototype.toString.call(value) 不同，这些检查不检查可从 JavaScript 访问的对象的属性（如它们的原型），并且通常具有调用 C++ 的开销。

结果通常不会对值在 JavaScript 中公开的属性或行为类型做出任何保证。 它们主要对喜欢在 JavaScript 中进行类型检查的插件开发者有用。

API 可通过 require('node:util').types 或 require('node:util/types') 访问。

util.types.isAnyArrayBuffer(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 ArrayBuffer 或 SharedArrayBuffer 实例，则返回 true。

另见 util.types.isArrayBuffer() 和 util.types.isSharedArrayBuffer()。

util.types.isAnyArrayBuffer(new ArrayBuffer());  // 返回 true
util.types.isAnyArrayBuffer(new SharedArrayBuffer());  // 返回 true

util.types.isArrayBufferView(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是 ArrayBuffer 视图之一的实例，例如类型化数组对象或 DataView，则返回 true。 相当于 ArrayBuffer.isView()。

util.types.isArrayBufferView(new Int8Array());  // true
util.types.isArrayBufferView(Buffer.from('hello world')); // true
util.types.isArrayBufferView(new DataView(new ArrayBuffer(16)));  // true
util.types.isArrayBufferView(new ArrayBuffer());  // false

util.types.isArgumentsObject(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为 arguments 对象，则返回 true。

function foo() {
  util.types.isArgumentsObject(arguments);  // 返回 true
}

util.types.isArrayBuffer(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 ArrayBuffer 实例，则返回 true。 这不包括 SharedArrayBuffer 实例。 通常，最好对两者进行测试；参见 util.types.isAnyArrayBuffer()。

util.types.isArrayBuffer(new ArrayBuffer());  // 返回 true
util.types.isArrayBuffer(new SharedArrayBuffer());  // 返回 false

util.types.isAsyncFunction(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是异步函数，则返回 true。 这只会报告 JavaScript 引擎看到的内容；特别是，如果使用了转译工具，则返回值可能与原始源代码不匹配。

util.types.isAsyncFunction(function foo() {});  // 返回 false
util.types.isAsyncFunction(async function foo() {});  // 返回 true

util.types.isBigInt64Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为 BigInt64Array 实例，则返回 true。

util.types.isBigInt64Array(new BigInt64Array());   // 返回 true
util.types.isBigInt64Array(new BigUint64Array());  // 返回 false

util.types.isBigUint64Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为 BigUint64Array 实例，则返回 true。

util.types.isBigUint64Array(new BigInt64Array());   // 返回 false
util.types.isBigUint64Array(new BigUint64Array());  // 返回 true

util.types.isBooleanObject(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是布尔对象（例如由 new Boolean() 创建），则返回 true。

util.types.isBooleanObject(false);  // 返回 false
util.types.isBooleanObject(true);   // 返回 false
util.types.isBooleanObject(new Boolean(false)); // 返回 true
util.types.isBooleanObject(new Boolean(true));  // 返回 true
util.types.isBooleanObject(Boolean(false)); // 返回 false
util.types.isBooleanObject(Boolean(true));  // 返回 false

util.types.isBoxedPrimitive(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是任何封装的原始对象（例如由 new Boolean()、new String() 或 Object(Symbol()) 创建），则返回 true。

例如：

util.types.isBoxedPrimitive(false); // 返回 false
util.types.isBoxedPrimitive(new Boolean(false)); // 返回 true
util.types.isBoxedPrimitive(Symbol('foo')); // 返回 false
util.types.isBoxedPrimitive(Object(Symbol('foo'))); // 返回 true
util.types.isBoxedPrimitive(Object(BigInt(5))); // 返回 true

util.types.isCryptoKey(value)#

中英对照

• value <Object>
• 返回: <boolean>

如果 value 是 <CryptoKey>，则返回 true，否则返回 false。

util.types.isDataView(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 DataView 实例，则返回 true。

const ab = new ArrayBuffer(20);
util.types.isDataView(new DataView(ab));  // 返回 true
util.types.isDataView(new Float64Array());  // 返回 false

另见 ArrayBuffer.isView()。

util.types.isDate(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Date 实例，则返回 true。

util.types.isDate(new Date());  // 返回 true

util.types.isExternal(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是原生的 External 值，则返回 true。

原生的 External 值是特殊类型的对象，它包含用于从原生代码访问的原始 C++ 指针 (void*)，并且没有其他属性。 此类对象由 Node.js 内部或原生插件创建。 在 JavaScript 中，它们是带有 null 原型的冻结对象。

#include <js_native_api.h>
#include <stdlib.h>
napi_value result;
static napi_value MyNapi(napi_env env, napi_callback_info info) {
  int* raw = (int*) malloc(1024);
  napi_status status = napi_create_external(env, (void*) raw, NULL, NULL, &result);
  if (status != napi_ok) {
    napi_throw_error(env, NULL, "napi_create_external failed");
    return NULL;
  }
  return result;
}
...
DECLARE_NAPI_PROPERTY("myNapi", MyNapi)
...

const native = require('napi_addon.node');
const data = native.myNapi();
util.types.isExternal(data); // 返回 true
util.types.isExternal(0); // 返回 false
util.types.isExternal(new String('foo')); // 返回 false

有关 napi_create_external 的更多信息，请参阅 napi_create_external()。

util.types.isFloat32Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Float32Array 实例，则返回 true。

util.types.isFloat32Array(new ArrayBuffer());  // 返回 false
util.types.isFloat32Array(new Float32Array());  // 返回 true
util.types.isFloat32Array(new Float64Array());  // 返回 false

util.types.isFloat64Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Float64Array 实例，则返回 true。

util.types.isFloat64Array(new ArrayBuffer());  // 返回 false
util.types.isFloat64Array(new Uint8Array());  // 返回 false
util.types.isFloat64Array(new Float64Array());  // 返回 true

util.types.isGeneratorFunction(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是生成器函数，则返回 true。 这只会报告 JavaScript 引擎看到的内容；特别是，如果使用了转译工具，则返回值可能与原始源代码不匹配。

util.types.isGeneratorFunction(function foo() {});  // 返回 false
util.types.isGeneratorFunction(function* foo() {});  // 返回 true

util.types.isGeneratorObject(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是从内置的生成器函数返回的生成器对象，则返回 true。 这只会报告 JavaScript 引擎看到的内容；特别是，如果使用了转译工具，则返回值可能与原始源代码不匹配。

function* foo() {}
const generator = foo();
util.types.isGeneratorObject(generator);  // 返回 true

util.types.isInt8Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Int8Array 实例，则返回 true。

util.types.isInt8Array(new ArrayBuffer());  // 返回 false
util.types.isInt8Array(new Int8Array());  // 返回 true
util.types.isInt8Array(new Float64Array());  // 返回 false

util.types.isInt16Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Int16Array 实例，则返回 true。

util.types.isInt16Array(new ArrayBuffer());  // 返回 false
util.types.isInt16Array(new Int16Array());  // 返回 true
util.types.isInt16Array(new Float64Array());  // 返回 false

util.types.isInt32Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Int32Array 实例，则返回 true。

util.types.isInt32Array(new ArrayBuffer());  // 返回 false
util.types.isInt32Array(new Int32Array());  // 返回 true
util.types.isInt32Array(new Float64Array());  // 返回 false

util.types.isKeyObject(value)#

中英对照

• value <Object>
• 返回: <boolean>

如果 value 是 <KeyObject>，则返回 true，否则返回 false。

util.types.isMap(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Map 实例，则返回 true。

util.types.isMap(new Map());  // 返回 true

util.types.isMapIterator(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是为内置的 Map 实例返回的迭代器，则返回 true。

const map = new Map();
util.types.isMapIterator(map.keys());  // 返回 true
util.types.isMapIterator(map.values());  // 返回 true
util.types.isMapIterator(map.entries());  // 返回 true
util.types.isMapIterator(map[Symbol.iterator]());  // 返回 true

util.types.isModuleNamespaceObject(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是模块命名空间对象的实例，则返回 true。

import * as ns from './a.js';

util.types.isModuleNamespaceObject(ns);  // 返回 true

util.types.isNativeError(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是内置的 Error 类型的实例，则返回 true。

util.types.isNativeError(new Error());  // 返回 true
util.types.isNativeError(new TypeError());  // 返回 true
util.types.isNativeError(new RangeError());  // 返回 true

util.types.isNumberObject(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是数字对象（例如由 new Number() 创建），则返回 true。

util.types.isNumberObject(0);  // 返回 false
util.types.isNumberObject(new Number(0));   // 返回 true

util.types.isPromise(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Promise，则返回 true。

util.types.isPromise(Promise.resolve(42));  // 返回 true

util.types.isProxy(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为 Proxy 实例，则返回 true。

const target = {};
const proxy = new Proxy(target, {});
util.types.isProxy(target);  // 返回 false
util.types.isProxy(proxy);  // 返回 true

util.types.isRegExp(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是正则表达式对象，则返回 true。

util.types.isRegExp(/abc/);  // 返回 true
util.types.isRegExp(new RegExp('abc'));  // 返回 true

util.types.isSet(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Set 实例，则返回 true。

util.types.isSet(new Set());  // 返回 true

util.types.isSetIterator(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是为内置的 Set 实例返回的迭代器，则返回 true。

const set = new Set();
util.types.isSetIterator(set.keys());  // 返回 true
util.types.isSetIterator(set.values());  // 返回 true
util.types.isSetIterator(set.entries());  // 返回 true
util.types.isSetIterator(set[Symbol.iterator]());  // 返回 true

util.types.isSharedArrayBuffer(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 SharedArrayBuffer 实例，则返回 true。 这不包括 ArrayBuffer 实例。 通常，最好对两者进行测试；参见 util.types.isAnyArrayBuffer()。

util.types.isSharedArrayBuffer(new ArrayBuffer());  // 返回 false
util.types.isSharedArrayBuffer(new SharedArrayBuffer());  // 返回 true

util.types.isStringObject(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是字符串对象（例如由 new String() 创建），则返回 true。

util.types.isStringObject('foo');  // 返回 false
util.types.isStringObject(new String('foo'));   // 返回 true

util.types.isSymbolObject(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值是符号对象（通过在 Symbol 原始类型上调用 Object() 创建），则返回 true。

const symbol = Symbol('foo');
util.types.isSymbolObject(symbol);  // 返回 false
util.types.isSymbolObject(Object(symbol));   // 返回 true

util.types.isTypedArray(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 TypedArray 实例，则返回 true。

util.types.isTypedArray(new ArrayBuffer());  // 返回 false
util.types.isTypedArray(new Uint8Array());  // 返回 true
util.types.isTypedArray(new Float64Array());  // 返回 true

另见 ArrayBuffer.isView()。

util.types.isUint8Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Uint8Array 实例，则返回 true。

util.types.isUint8Array(new ArrayBuffer());  // 返回 false
util.types.isUint8Array(new Uint8Array());  // 返回 true
util.types.isUint8Array(new Float64Array());  // 返回 false

util.types.isUint8ClampedArray(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Uint8ClampedArray 实例，则返回 true。

util.types.isUint8ClampedArray(new ArrayBuffer());  // 返回 false
util.types.isUint8ClampedArray(new Uint8ClampedArray());  // 返回 true
util.types.isUint8ClampedArray(new Float64Array());  // 返回 false

util.types.isUint16Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Uint16Array 实例，则返回 true。

util.types.isUint16Array(new ArrayBuffer());  // 返回 false
util.types.isUint16Array(new Uint16Array());  // 返回 true
util.types.isUint16Array(new Float64Array());  // 返回 false

util.types.isUint32Array(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 Uint32Array 实例，则返回 true。

util.types.isUint32Array(new ArrayBuffer());  // 返回 false
util.types.isUint32Array(new Uint32Array());  // 返回 true
util.types.isUint32Array(new Float64Array());  // 返回 false

util.types.isWeakMap(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 WeakMap 实例，则返回 true。

util.types.isWeakMap(new WeakMap());  // 返回 true

util.types.isWeakSet(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 WeakSet 实例，则返回 true。

util.types.isWeakSet(new WeakSet());  // 返回 true

util.types.isWebAssemblyCompiledModule(value)#

中英对照

• value <any>
• 返回: <boolean>

如果值为内置的 WebAssembly.Module 实例，则返回 true。

const module = new WebAssembly.Module(wasmBuffer);
util.types.isWebAssemblyCompiledModule(module);  // 返回 true

弃用的 API#

中英对照

以下 API 已弃用，不应再使用。 应更新现有应用程序和模块以寻找替代方法。

util._extend(target, source)#

中英对照

• target <Object>
• source <Object>

util._extend() 方法从未打算在内部的 Node.js 模块之外使用。 社区无论如何都找到并使用了它。

它已被弃用，不应在新代码中使用。 JavaScript 通过 Object.assign() 提供了非常相似的内置功能。

util.isArray(object)#

中英对照

• object <any>
• 返回: <boolean>

Array.isArray() 的别名。

如果给定的 object 是 Array，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isArray([]);
// 返回: true
util.isArray(new Array());
// 返回: true
util.isArray({});
// 返回: false

util.isBoolean(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 Boolean，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isBoolean(1);
// 返回: false
util.isBoolean(0);
// 返回: false
util.isBoolean(false);
// 返回: true

util.isBuffer(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 Buffer，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isBuffer({ length: 0 });
// 返回: false
util.isBuffer([]);
// 返回: false
util.isBuffer(Buffer.from('hello world'));
// 返回: true

util.isDate(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 Date，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isDate(new Date());
// 返回: true
util.isDate(Date());
// false（没有 'new' 返回字符串）
util.isDate({});
// 返回: false

util.isError(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 Error，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isError(new Error());
// 返回: true
util.isError(new TypeError());
// 返回: true
util.isError({ name: 'Error', message: 'an error occurred' });
// 返回: false

此方法依赖于 Object.prototype.toString() 行为。 当 object 参数操作 @@toStringTag 时，可能会得到错误的结果。

const util = require('node:util');
const obj = { name: 'Error', message: 'an error occurred' };

util.isError(obj);
// 返回: false
obj[Symbol.toStringTag] = 'Error';
util.isError(obj);
// 返回: true

util.isFunction(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 Function，则返回 true。 否则，返回 false。

const util = require('node:util');

function Foo() {}
const Bar = () => {};

util.isFunction({});
// 返回: false
util.isFunction(Foo);
// 返回: true
util.isFunction(Bar);
// 返回: true

util.isNull(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 严格为 null，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isNull(0);
// 返回: false
util.isNull(undefined);
// 返回: false
util.isNull(null);
// 返回: true

util.isNullOrUndefined(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 null 或 undefined，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isNullOrUndefined(0);
// 返回: false
util.isNullOrUndefined(undefined);
// 返回: true
util.isNullOrUndefined(null);
// 返回: true

util.isNumber(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 Number，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isNumber(false);
// 返回: false
util.isNumber(Infinity);
// 返回: true
util.isNumber(0);
// 返回: true
util.isNumber(NaN);
// 返回: true

util.isObject(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 严格来说是 Object 而不是 Function（即使函数是 JavaScript 中的对象），则返回 true。 否则，返回 false。

const util = require('node:util');

util.isObject(5);
// 返回: false
util.isObject(null);
// 返回: false
util.isObject({});
// 返回: true
util.isObject(() => {});
// 返回: false

util.isPrimitive(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是原始类型，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isPrimitive(5);
// 返回: true
util.isPrimitive('foo');
// 返回: true
util.isPrimitive(false);
// 返回: true
util.isPrimitive(null);
// 返回: true
util.isPrimitive(undefined);
// 返回: true
util.isPrimitive({});
// 返回: false
util.isPrimitive(() => {});
// 返回: false
util.isPrimitive(/^$/);
// 返回: false
util.isPrimitive(new Date());
// 返回: false

util.isRegExp(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 RegExp，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isRegExp(/some regexp/);
// 返回: true
util.isRegExp(new RegExp('another regexp'));
// 返回: true
util.isRegExp({});
// 返回: false

util.isString(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 string，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isString('');
// 返回: true
util.isString('foo');
// 返回: true
util.isString(String('foo'));
// 返回: true
util.isString(5);
// 返回: false

util.isSymbol(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 Symbol，则返回 true。 否则，返回 false。

const util = require('node:util');

util.isSymbol(5);
// 返回: false
util.isSymbol('foo');
// 返回: false
util.isSymbol(Symbol('foo'));
// 返回: true

util.isUndefined(object)#

中英对照

• object <any>
• 返回: <boolean>

如果给定的 object 是 undefined，则返回 true。 否则，返回 false。

const util = require('node:util');

const foo = undefined;
util.isUndefined(5);
// 返回: false
util.isUndefined(foo);
// 返回: true
util.isUndefined(null);
// 返回: false

util.log(string)#

中英对照

• string <string>

util.log() 方法使用包含的时间戳打印给定的 string 到 stdout。

const util = require('node:util');

util.log('Timestamped message.');