- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
Node.js v18.20.0 文档
- Node.js v18.20.0
-
目录
- 实用工具
util.callbackify(original)
util.debuglog(section[, callback])
util.debug(section)
util.deprecate(fn, msg[, code])
util.format(format[, ...args])
util.formatWithOptions(inspectOptions, format[, ...args])
util.getSystemErrorName(err)
util.getSystemErrorMap()
util.inherits(constructor, superConstructor)
util.inspect(object[, options])
util.inspect(object[, showHidden[, depth[, colors]]])
util.isDeepStrictEqual(val1, val2)
- 类:
util.MIMEType
- 类:
util.MIMEParams
util.parseArgs([config])
util.promisify(original)
util.stripVTControlCharacters(str)
- 类:
util.TextDecoder
- 类:
util.TextEncoder
util.toUSVString(string)
util.transferableAbortController()
util.transferableAbortSignal(signal)
util.aborted(signal, resource)
util.types
util.types.isAnyArrayBuffer(value)
util.types.isArrayBufferView(value)
util.types.isArgumentsObject(value)
util.types.isArrayBuffer(value)
util.types.isAsyncFunction(value)
util.types.isBigInt64Array(value)
util.types.isBigUint64Array(value)
util.types.isBooleanObject(value)
util.types.isBoxedPrimitive(value)
util.types.isCryptoKey(value)
util.types.isDataView(value)
util.types.isDate(value)
util.types.isExternal(value)
util.types.isFloat32Array(value)
util.types.isFloat64Array(value)
util.types.isGeneratorFunction(value)
util.types.isGeneratorObject(value)
util.types.isInt8Array(value)
util.types.isInt16Array(value)
util.types.isInt32Array(value)
util.types.isKeyObject(value)
util.types.isMap(value)
util.types.isMapIterator(value)
util.types.isModuleNamespaceObject(value)
util.types.isNativeError(value)
util.types.isNumberObject(value)
util.types.isPromise(value)
util.types.isProxy(value)
util.types.isRegExp(value)
util.types.isSet(value)
util.types.isSetIterator(value)
util.types.isSharedArrayBuffer(value)
util.types.isStringObject(value)
util.types.isSymbolObject(value)
util.types.isTypedArray(value)
util.types.isUint8Array(value)
util.types.isUint8ClampedArray(value)
util.types.isUint16Array(value)
util.types.isUint32Array(value)
util.types.isWeakMap(value)
util.types.isWeakSet(value)
util.types.isWebAssemblyCompiledModule(value)
- 弃用的 API
util._extend(target, source)
util.isArray(object)
util.isBoolean(object)
util.isBuffer(object)
util.isDate(object)
util.isError(object)
util.isFunction(object)
util.isNull(object)
util.isNullOrUndefined(object)
util.isNumber(object)
util.isObject(object)
util.isPrimitive(object)
util.isRegExp(object)
util.isString(object)
util.isSymbol(object)
util.isUndefined(object)
util.log(string)
- 实用工具
-
导航
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- 其他版本
实用工具#
¥Util
¥Stability: 2 - Stable
源代码: lib/util.js
node:util
模块支持 Node.js 内部 API 的需求。许多实用工具对应用和模块开发者也很有用。要访问它:
¥The node:util
module supports the needs of Node.js internal APIs. Many of the
utilities are useful for application and module developers as well. To access
it:
const util = require('node:util');
util.callbackify(original)
#
-
original
<Function>async
函数¥
original
<Function> Anasync
function -
返回:<Function> 回调风格的函数
¥Returns: <Function> a callback style function
采用 async
函数(或返回 Promise
的函数)并返回遵循错误优先回调风格的函数,即将 (err, value) => ...
回调作为最后一个参数。在回调中,第一个参数将是拒绝原因(如果 Promise
已解决,则为 null
),第二个参数将是已解决的值。
¥Takes an async
function (or a function that returns a Promise
) and returns a
function following the error-first callback style, i.e. taking
an (err, value) => ...
callback as the last argument. In the callback, the
first argument will be the rejection reason (or null
if the Promise
resolved), and the second argument will be the resolved value.
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);
});
将打印:
¥Will print:
hello world
回调是异步执行的,并且将具有有限的堆栈跟踪。如果回调抛出,进程将触发 'uncaughtException'
事件,如果不处理将退出。
¥The callback is executed asynchronously, and will have a limited stack trace.
If the callback throws, the process will emit an 'uncaughtException'
event, and if not handled will exit.
由于 null
作为回调的第一个参数有特殊含义,如果封装的函数使用假值为理由来拒绝 Promise
,则该值被封装在 Error
中,原始值存储在名为 reason
的字段中。
¥Since null
has a special meaning as the first argument to a callback, if a
wrapped function rejects a Promise
with a falsy value as a reason, the value
is wrapped in an Error
with the original value stored in a field named
reason
.
function fn() {
return Promise.reject(null);
}
const callbackFunction = util.callbackify(fn);
callbackFunction((err, ret) => {
// When the Promise was rejected with `null` it is wrapped with an Error and
// the original value is stored in `reason`.
err && Object.hasOwn(err, 'reason') && err.reason === null; // true
});
util.debuglog(section[, callback])
#
-
section
<string> 标识正在为其创建debuglog
函数的应用部分的字符串。¥
section
<string> A string identifying the portion of the application for which thedebuglog
function is being created. -
callback
<Function> 第一次调用日志函数时调用的回调函数参数是更优化的日志函数。¥
callback
<Function> A callback invoked the first time the logging function is called with a function argument that is a more optimized logging function. -
返回:<Function> 日志函数
¥Returns: <Function> The logging function
util.debuglog()
方法用于创建函数,该函数根据 NODE_DEBUG
环境变量的存在有条件地将调试消息写入 stderr
。如果 section
名称出现在该环境变量的值中,则返回的函数的操作类似于 console.error()
。如果不是,则返回的函数是空操作。
¥The util.debuglog()
method is used to create a function that conditionally
writes debug messages to stderr
based on the existence of the NODE_DEBUG
environment variable. If the section
name appears within the value of that
environment variable, then the returned function operates similar to
console.error()
. If not, then the returned function is a no-op.
const util = require('node:util');
const debuglog = util.debuglog('foo');
debuglog('hello from foo [%d]', 123);
如果这个程序在环境中与 NODE_DEBUG=foo
一起运行,则它会输出如下内容:
¥If this program is run with NODE_DEBUG=foo
in the environment, then
it will output something like:
FOO 3245: hello from foo [123]
其中 3245
是进程 ID。如果它没有使用该环境变量集运行,则它不会打印任何内容。
¥where 3245
is the process id. If it is not run with that
environment variable set, then it will not print anything.
section
还支持通配符:
¥The section
supports wildcard also:
const util = require('node:util');
const debuglog = util.debuglog('foo-bar');
debuglog('hi there, it\'s foo-bar [%d]', 2333);
如果它在环境中与 NODE_DEBUG=foo*
一起运行,则它将输出如下内容:
¥if it is run with NODE_DEBUG=foo*
in the environment, then it will output
something like:
FOO-BAR 3257: hi there, it's foo-bar [2333]
可以在 NODE_DEBUG
环境变量中指定多个以逗号分隔的 section
名称:NODE_DEBUG=fs,net,tls
。
¥Multiple comma-separated section
names may be specified in the NODE_DEBUG
environment variable: NODE_DEBUG=fs,net,tls
.
可选的 callback
参数可用于用一个不同的函数替换日志函数,该函数没有任何初始化或不必要的封装。
¥The optional callback
argument can be used to replace the logging function
with a different function that doesn't have any initialization or
unnecessary wrapping.
const util = require('node:util');
let debuglog = util.debuglog('internals', (debug) => {
// Replace with a logging function that optimizes out
// testing if the section is enabled
debuglog = debug;
});
debuglog().enabled
#
util.debuglog().enabled
获取器用于基于 NODE_DEBUG
环境变量的存在创建可用于条件的测试。如果 section
名称出现在该环境变量的值中,则返回值将为 true
。如果不是,则返回值将是 false
。
¥The util.debuglog().enabled
getter is used to create a test that can be used
in conditionals based on the existence of the NODE_DEBUG
environment variable.
If the section
name appears within the value of that environment variable,
then the returned value will be true
. If not, then the returned value will be
false
.
const util = require('node:util');
const enabled = util.debuglog('foo').enabled;
if (enabled) {
console.log('hello from foo [%d]', 123);
}
如果这个程序在环境中与 NODE_DEBUG=foo
一起运行,则它会输出如下内容:
¥If this program is run with NODE_DEBUG=foo
in the environment, then it will
output something like:
hello from foo [123]
util.debug(section)
#
util.debuglog
的别名。当仅使用 util.debuglog().enabled
时,使用允许可读性并不意味着日志记录。
¥Alias for util.debuglog
. Usage allows for readability of that doesn't imply
logging when only using util.debuglog().enabled
.
util.deprecate(fn, msg[, code])
#
-
fn
<Function> 被弃用的函数。¥
fn
<Function> The function that is being deprecated. -
msg
<string> 调用弃用的函数时显示的警告消息。¥
msg
<string> A warning message to display when the deprecated function is invoked. -
code
<string> 弃用代码。有关代码列表,请参见 弃用的 API 列表。¥
code
<string> A deprecation code. See the list of deprecated APIs for a list of codes. -
返回:<Function> 弃用的函数被封装以触发警告。
¥Returns: <Function> The deprecated function wrapped to emit a warning.
util.deprecate()
方法以标记为已弃用的方式封装 fn
(可能是函数或类)。
¥The util.deprecate()
method wraps fn
(which may be a function or class) in
such a way that it is marked as deprecated.
const util = require('node:util');
exports.obsoleteFunction = util.deprecate(() => {
// Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');
当调用时,util.deprecate()
将返回将使用 'warning'
事件触发 DeprecationWarning
的函数。第一次调用返回的函数时,警告将触发并打印到 stderr
。触发警告后,将调用封装的函数而不触发警告。
¥When called, util.deprecate()
will return a function that will emit a
DeprecationWarning
using the 'warning'
event. The warning will
be emitted and printed to stderr
the first time the returned function is
called. After the warning is emitted, the wrapped function is called without
emitting a warning.
如果在多次调用 util.deprecate()
时提供了相同的可选 code
,则该 code
只会触发一次警告。
¥If the same optional code
is supplied in multiple calls to util.deprecate()
,
the warning will be emitted only once for that code
.
const util = require('node:util');
const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001');
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001');
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code
如果使用 --no-deprecation
或 --no-warnings
命令行标志,或者如果在第一次弃用警告之前将 process.noDeprecation
属性设置为 true
,则 util.deprecate()
方法不执行任何操作。
¥If either the --no-deprecation
or --no-warnings
command-line flags are
used, or if the process.noDeprecation
property is set to true
prior to
the first deprecation warning, the util.deprecate()
method does nothing.
如果设置了 --trace-deprecation
或 --trace-warnings
命令行标志、或者 process.traceDeprecation
属性设置为 true
,则在第一次调用已弃用的函数时会向 stderr
打印警告和堆栈跟踪。
¥If the --trace-deprecation
or --trace-warnings
command-line flags are set,
or the process.traceDeprecation
property is set to true
, a warning and a
stack trace are printed to stderr
the first time the deprecated function is
called.
如果设置了 --throw-deprecation
命令行标志、或者 process.throwDeprecation
属性设置为 true
,则在调用已弃用的函数时将抛出异常。
¥If the --throw-deprecation
command-line flag is set, or the
process.throwDeprecation
property is set to true
, then an exception will be
thrown when the deprecated function is called.
--throw-deprecation
命令行标志和 process.throwDeprecation
属性优先于 --trace-deprecation
和 process.traceDeprecation
。
¥The --throw-deprecation
command-line flag and process.throwDeprecation
property take precedence over --trace-deprecation
and
process.traceDeprecation
.
util.format(format[, ...args])
#
util.format()
方法使用第一个参数作为类似 printf
的格式字符串(其可以包含零个或多个格式说明符)来返回格式化的字符串。每个说明符都替换为来自相应参数的转换后的值。支持的说明符有:
¥The util.format()
method returns a formatted string using the first argument
as a printf
-like format string which can contain zero or more format
specifiers. Each specifier is replaced with the converted value from the
corresponding argument. Supported specifiers are:
-
%s
:String
将用于转换除BigInt
、Object
和-0
之外的所有值。BigInt
值将用n
表示,没有用户定义的toString
函数的对象使用具有选项{ depth: 0, colors: false, compact: 3 }
的util.inspect()
进行检查。¥
%s
:String
will be used to convert all values exceptBigInt
,Object
and-0
.BigInt
values will be represented with ann
and Objects that have no user definedtoString
function are inspected usingutil.inspect()
with options{ depth: 0, colors: false, compact: 3 }
. -
%d
:Number
将用于转换除BigInt
和Symbol
之外的所有值。¥
%d
:Number
will be used to convert all values exceptBigInt
andSymbol
. -
%i
:parseInt(value, 10)
用于除BigInt
和Symbol
之外的所有值。¥
%i
:parseInt(value, 10)
is used for all values exceptBigInt
andSymbol
. -
%f
:parseFloat(value)
用于除Symbol
之外的所有值。¥
%f
:parseFloat(value)
is used for all values expectSymbol
. -
%j
:JSON.如果参数包含循环引用,则替换为字符串'[Circular]'
。¥
%j
: JSON. Replaced with the string'[Circular]'
if the argument contains circular references. -
%o
:Object
。具有通用 JavaScript 对象格式的对象的字符串表示形式。类似于具有选项{ showHidden: true, showProxy: true }
的util.inspect()
。这将显示完整的对象,包括不可枚举的属性和代理。¥
%o
:Object
. A string representation of an object with generic JavaScript object formatting. Similar toutil.inspect()
with options{ showHidden: true, showProxy: true }
. This will show the full object including non-enumerable properties and proxies. -
%O
:Object
。具有通用 JavaScript 对象格式的对象的字符串表示形式。类似于没有选项的util.inspect()
。这将显示完整的对象,但不包括不可枚举的属性和代理。¥
%O
:Object
. A string representation of an object with generic JavaScript object formatting. Similar toutil.inspect()
without options. This will show the full object not including non-enumerable properties and proxies. -
%c
:CSS
。此说明符被忽略,将跳过任何传入的 CSS。¥
%c
:CSS
. This specifier is ignored and will skip any CSS passed in. -
%%
:单个百分号 ('%'
)。这不消费参数。¥
%%
: single percent sign ('%'
). This does not consume an argument. -
返回:<string> 格式化的字符串
¥Returns: <string> The formatted string
如果说明符没有相应的参数,则不会替换它:
¥If a specifier does not have a corresponding argument, it is not replaced:
util.format('%s:%s', 'foo');
// Returns: 'foo:%s'
如果其类型不是 string
,则不属于格式字符串的值将使用 util.inspect()
进行格式化。
¥Values that are not part of the format string are formatted using
util.inspect()
if their type is not string
.
如果传给 util.format()
方法的参数多于说明符的数量,则额外的参数将以空格分隔串联到返回的字符串:
¥If there are more arguments passed to the util.format()
method than the
number of specifiers, the extra arguments are concatenated to the returned
string, separated by spaces:
util.format('%s:%s', 'foo', 'bar', 'baz');
// Returns: 'foo:bar baz'
如果第一个参数不包含有效的格式说明符,则 util.format()
返回以空格分隔的所有参数的串联的字符串:
¥If the first argument does not contain a valid format specifier, util.format()
returns a string that is the concatenation of all arguments separated by spaces:
util.format(1, 2, 3);
// Returns: '1 2 3'
如果只有一个参数传给 util.format()
,则它会按原样返回,不进行任何格式化:
¥If only one argument is passed to util.format()
, it is returned as it is
without any formatting:
util.format('%% %s');
// Returns: '%% %s'
util.format()
是同步的方法,旨在用作调试工具。某些输入值可能会产生显着的性能开销,从而阻塞事件循环。小心使用此函数,切勿在热代码路径中使用。
¥util.format()
is a synchronous method that is intended as a debugging tool.
Some input values can have a significant performance overhead that can block the
event loop. Use this function with care and never in a hot code path.
util.formatWithOptions(inspectOptions, format[, ...args])
#
此函数与 util.format()
相同,不同之处在于它接受 inspectOptions
参数,该参数指定传给 util.inspect()
的选项。
¥This function is identical to util.format()
, except in that it takes
an inspectOptions
argument which specifies options that are passed along to
util.inspect()
.
util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
// Returns 'See object { foo: 42 }', where `42` is colored as a number
// when printed to a terminal.
util.getSystemErrorName(err)
#
返回来自 Node.js API 的数字错误码的字符串名称。错误码和错误名称之间的映射是平台相关的。常见错误名称见 常见系统错误。
¥Returns the string name for a numeric error code that comes from a Node.js API. The mapping between error codes and error names is platform-dependent. See Common System Errors for the names of common errors.
fs.access('file/that/does/not/exist', (err) => {
const name = util.getSystemErrorName(err.errno);
console.error(name); // ENOENT
});
util.getSystemErrorMap()
#
返回来自 Node.js API 的可用的所有系统错误码的映射。错误码和错误名称之间的映射是平台相关的。常见错误名称见 常见系统错误。
¥Returns a Map of all system error codes available from the Node.js API. The mapping between error codes and error names is platform-dependent. See Common System Errors for the names of common errors.
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)
#
extends
关键字。¥Stability: 3 - Legacy: Use ES2015 class syntax and extends
keyword instead.
-
constructor
<Function> -
superConstructor
<Function>
不鼓励使用 util.inherits()
。请使用 ES6 class
和 extends
关键字来获得语言级别的继承支持。另请注意,这两种款式都是 语义上不兼容。
¥Usage of util.inherits()
is discouraged. Please use the ES6 class
and
extends
keywords to get language level inheritance support. Also note
that the two styles are semantically incompatible.
将原型方法从一个 构造函数 继承到另一个。constructor
的原型将被设置为从 superConstructor
创建的新对象。
¥Inherit the prototype methods from one constructor into another. The
prototype of constructor
will be set to a new object created from
superConstructor
.
这主要是在 Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)
之上添加了一些输入验证。作为额外的便利,superConstructor
将可通过 constructor.super_
属性访问。
¥This mainly adds some input validation on top of
Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)
.
As an additional convenience, superConstructor
will be accessible
through the constructor.super_
property.
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!'); // Received data: "It works!"
使用 class
和 extends
的 ES6 示例:
¥ES6 example using class
and extends
:
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
。¥
object
<any> Any JavaScript primitive orObject
. -
options
<Object>-
showHidden
<boolean> 如果为true
,则object
的不可枚举符号和属性包含在格式化的结果中。WeakMap
和WeakSet
条目以及用户定义的原型属性(不包括方法属性)也包括在内。默认值:false
。¥
showHidden
<boolean> Iftrue
,object
's non-enumerable symbols and properties are included in the formatted result.WeakMap
andWeakSet
entries are also included as well as user defined prototype properties (excluding method properties). Default:false
. -
depth
<number> 指定格式化object
时递归的次数。这对于检查大型对象很有用。要递归到最大调用堆栈大小,则传入Infinity
或null
。默认值:2
。¥
depth
<number> Specifies the number of times to recurse while formattingobject
. This is useful for inspecting large objects. To recurse up to the maximum call stack size passInfinity
ornull
. Default:2
. -
colors
<boolean> 如果为true
,则输出的样式为 ANSI 颜色代码。颜色是可自定义的。参见 自定义util.inspect
颜色。默认值:false
。¥
colors
<boolean> Iftrue
, the output is styled with ANSI color codes. Colors are customizable. See Customizingutil.inspect
colors. Default:false
. -
customInspect
<boolean> 如果为false
,则[util.inspect.custom](depth, opts, inspect)
函数不被调用。默认值:true
。¥
customInspect
<boolean> Iffalse
,[util.inspect.custom](depth, opts, inspect)
functions are not invoked. Default:true
. -
showProxy
<boolean> 如果true
,Proxy
检查包括target
和handler
对象。默认值:false
。¥
showProxy
<boolean> Iftrue
,Proxy
inspection includes thetarget
andhandler
objects. Default:false
. -
maxArrayLength
<integer> 指定格式化时要包括的Array
、TypedArray
、WeakMap
和WeakSet
元素的最大数量。设置为null
或Infinity
则显示所有元素。设置为0
或负数则不显示任何元素。默认值:100
。¥
maxArrayLength
<integer> Specifies the maximum number ofArray
,TypedArray
,WeakMap
, andWeakSet
elements to include when formatting. Set tonull
orInfinity
to show all elements. Set to0
or negative to show no elements. Default:100
. -
maxStringLength
<integer> 指定格式化时要包含的最大字符数。设置为null
或Infinity
则显示所有元素。设置为0
或负数则不显示字符。默认值:10000
。¥
maxStringLength
<integer> Specifies the maximum number of characters to include when formatting. Set tonull
orInfinity
to show all elements. Set to0
or negative to show no characters. Default:10000
. -
breakLength
<integer> 输入值在多行中拆分的长度。设置为Infinity
以将输入格式化为单行(结合compact
设置为true
或任何数字 >=1
)。默认值:80
。¥
breakLength
<integer> The length at which input values are split across multiple lines. Set toInfinity
to format the input as a single line (in combination withcompact
set totrue
or any number >=1
). Default:80
. -
compact
<boolean> | <integer> 将此设置为false
会导致每个对象的键显示在新行上。它将在比breakLength
长的文本中换行。如果设置为数字,则只要所有属性都适合breakLength
,则最多n
个内部元素将合并在一行中。短数组元素也组合在一起。有关更多信息,请参阅下面的示例。默认值:3
。¥
compact
<boolean> | <integer> Setting this tofalse
causes each object key to be displayed on a new line. It will break on new lines in text that is longer thanbreakLength
. If set to a number, the mostn
inner elements are united on a single line as long as all properties fit intobreakLength
. Short array elements are also grouped together. For more information, see the example below. Default:3
. -
sorted
<boolean> | <Function> 如果设置为true
或函数,则对象的所有属性以及Set
和Map
条目都将在结果字符串中排序。如果设置为true
,则使用 默认排序。如果设置为函数,则用作 比较函数。¥
sorted
<boolean> | <Function> If set totrue
or a function, all properties of an object, andSet
andMap
entries are sorted in the resulting string. If set totrue
the default sort is used. If set to a function, it is used as a compare function. -
getters
<boolean> | <string> 如果设置为true
,则检查获取器。如果设置为'get'
,则只检查没有相应设置器的获取器。如果设置为'set'
,则只检查具有相应设置器的获取器。这可能会导致副作用,具体取决于获取器函数。默认值:false
。¥
getters
<boolean> | <string> If set totrue
, getters are inspected. If set to'get'
, only getters without a corresponding setter are inspected. If set to'set'
, only getters with a corresponding setter are inspected. This might cause side effects depending on the getter function. Default:false
. -
numericSeparator
<boolean> 如果设置为true
,则使用下划线分隔所有 bigint 和数字中的每三个数字。默认值:false
。¥
numericSeparator
<boolean> If set totrue
, an underscore is used to separate every three digits in all bigints and numbers. Default:false
.
-
-
返回:<string>
object
的表示。¥Returns: <string> The representation of
object
.
util.inspect()
方法返回用于调试的 object
的字符串表示。util.inspect
的输出可能随时更改,不应以编程方式依赖。可以传入额外的 options
来改变结果。util.inspect()
将使用构造函数的名称和/或 @@toStringTag
为检查的值制作可识别的标签。
¥The util.inspect()
method returns a string representation of object
that is
intended for debugging. The output of util.inspect
may change at any time
and should not be depended upon programmatically. Additional options
may be
passed that alter the result.
util.inspect()
will use the constructor's name and/or @@toStringTag
to make
an identifiable tag for an inspected value.
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] {}'
循环引用通过使用引用索引指向其锚点:
¥Circular references point to their anchor by using a reference index:
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
对象的所有属性:
¥The following example inspects all properties of the util
object:
const util = require('node:util');
console.log(util.inspect(util, { showHidden: true, depth: null }));
以下示例高亮了 compact
选项的效果:
¥The following example highlights the effect of the compact
option:
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' } }
// Setting `compact` to false or an integer creates more reader friendly output.
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'
// }
// }
// Setting `breakLength` to e.g. 150 will print the "Lorem ipsum" text in a
// single line.
showHidden
选项允许检查 WeakMap
和 WeakSet
条目。如果条目多于 maxArrayLength
,则无法保证显示哪些条目。这意味着两次检索相同的 WeakSet
条目可能会导致不同的输出。此外,没有剩余强引用的条目可能随时被垃圾回收。
¥The showHidden
option allows WeakMap
and WeakSet
entries to be
inspected. If there are more entries than maxArrayLength
, there is no
guarantee which entries are displayed. That means retrieving the same
WeakSet
entries twice may result in different output. Furthermore, entries
with no remaining strong references may be garbage collected at any time.
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()
的结果。
¥The sorted
option ensures that an object's property insertion order does not
impact the result of 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
选项为所有数字每三位添加一个下划线。
¥The numericSeparator
option adds an underscore every three digits to all
numbers.
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()
is a synchronous method intended for debugging. Its maximum
output length is approximately 128 MiB. Inputs that result in longer output will
be truncated.
自定义 util.inspect
颜色#
¥Customizing util.inspect
colors
util.inspect
的颜色输出(如果启用)可通过 util.inspect.styles
和 util.inspect.colors
属性全局地自定义。
¥Color output (if enabled) of util.inspect
is customizable globally
via the util.inspect.styles
and util.inspect.colors
properties.
util.inspect.styles
是将样式名称与来自 util.inspect.colors
的颜色相关联的映射。
¥util.inspect.styles
is a map associating a style name to a color from
util.inspect.colors
.
默认的样式和相关的颜色为:
¥The default styles and associated colors are:
-
bigint
:yellow
-
boolean
:yellow
-
date
:magenta
-
module
:underline
-
name
:(没有样式)¥
name
: (no styling) -
null
:bold
-
number
:yellow
-
regexp
:red
-
special
:cyan
(例如,Proxies
)¥
special
:cyan
(e.g.,Proxies
) -
string
:green
-
symbol
:green
-
undefined
:grey
颜色样式使用 ANSI 控制代码,可能并非所有终端都支持。要验证颜色支持,则使用 tty.hasColors()
。
¥Color styling uses ANSI control codes that may not be supported on all
terminals. To verify color support use tty.hasColors()
.
下面列出了预定义的控制代码(分组为 "修饰符"、"前景色" 和 "背景颜色")。
¥Predefined control codes are listed below (grouped as "Modifiers", "Foreground colors", and "Background colors").
修饰符#
¥Modifiers
修饰符的支持因不同的终端而异。如果不支持,则它们通常会被忽略。
¥Modifier support varies throughout different terminals. They will mostly be ignored, if not supported.
-
reset
- 将所有(颜色)修改器重置为其默认值¥
reset
- Resets all (color) modifiers to their defaults -
bold - 将文本设为粗体
¥bold - Make text bold
-
italic - 将文本设置为斜体
¥italic - Make text italic
-
underline - 给字面加下划线
¥underline - Make text underlined
-
strikethrough- 在文本中心放置一条水平线(别名:strikeThrough
、crossedout
、crossedOut
)¥
strikethrough- Puts a horizontal line through the center of the text (Alias:strikeThrough
,crossedout
,crossedOut
) -
hidden
- 打印文本,但使其不可见(别名:隐藏)¥
hidden
- Prints the text, but makes it invisible (Alias: conceal) -
dim - 颜色强度降低(别名:
faint
)¥dim - Decreased color intensity (Alias:
faint
) -
overlined - 使字面上划线
¥overlined - Make text overlined
-
blink - 以一定间隔隐藏和显示文本
¥blink - Hides and shows the text in an interval
-
inverse - 交换前景色和背景色(别名:
swapcolors
、swapColors
)¥inverse - Swap foreground and background colors (Alias:
swapcolors
,swapColors
) -
doubleunderline - 使文本加双下划线(别名:
doubleUnderline
)¥doubleunderline - Make text double underlined (Alias:
doubleUnderline
) -
framed - 在文本周围画一个框
¥framed - Draw a frame around the text
前景色#
¥Foreground colors
-
black
-
red
-
green
-
yellow
-
blue
-
magenta
-
cyan
-
white
-
gray
(别名:grey
、blackBright
)¥
gray
(alias:grey
,blackBright
) -
redBright
-
greenBright
-
yellowBright
-
blueBright
-
magentaBright
-
cyanBright
-
whiteBright
背景颜色#
¥Background colors
-
bgBlack
-
bgRed
-
bgGreen
-
bgYellow
-
bgBlue
-
bgMagenta
-
bgCyan
-
bgWhite
-
bgGray
(别名:bgGrey
、bgBlackBright
)¥
bgGray
(alias:bgGrey
,bgBlackBright
) -
bgRedBright
-
bgGreenBright
-
bgYellowBright
-
bgBlueBright
-
bgMagentaBright
-
bgCyanBright
-
bgWhiteBright
对象的自定义检查函数#
¥Custom inspection functions on objects
对象也可以定义自己的 [util.inspect.custom](depth, opts, inspect)
函数,util.inspect()
将在检查对象时调用并使用其结果。
¥Objects may also define their own
[util.inspect.custom](depth, opts, inspect)
function,
which util.inspect()
will invoke and use the result of when inspecting
the object.
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,
});
// Five space padding because that's the size of "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);
// Returns: "Box< true >"
自定义的 [util.inspect.custom](depth, opts, inspect)
函数通常返回一个字符串,但也可能返回一个由 util.inspect()
相应格式化的任何类型的值。
¥Custom [util.inspect.custom](depth, opts, inspect)
functions typically return
a string but may return a value of any type that will be formatted accordingly
by 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);
// Returns: "{ bar: 'baz' }"
util.inspect.custom
#
除了可以通过 util.inspect.custom
访问外,这个符号是 全局注册,在任何环境下都可以作为 Symbol.for('nodejs.util.inspect.custom')
访问。
¥In addition to being accessible through util.inspect.custom
, this
symbol is registered globally and can be
accessed in any environment as Symbol.for('nodejs.util.inspect.custom')
.
使用此允许以可移植方式编写代码,以便在 Node.js 环境中使用自定义检查功能并在浏览器中忽略。util.inspect()
函数本身作为第三个参数传给自定义检查函数以允许进一步的可移植性。
¥Using this allows code to be written in a portable fashion, so that the custom
inspect function is used in an Node.js environment and ignored in the browser.
The util.inspect()
function itself is passed as third argument to the custom
inspect function to allow further portability.
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);
// Prints Password <xxxxxxxx>
有关详细信息,请参阅 对象的自定义检查函数。
¥See Custom inspection functions on Objects for more details.
util.inspect.defaultOptions
#
defaultOptions
值允许自定义 util.inspect
使用的默认选项。这对于像 console.log
或 util.format
这样隐式调用 util.inspect
的函数很有用。它应设置为包含一个或多个有效 util.inspect()
选项的对象。也支持直接设置选项属性。
¥The defaultOptions
value allows customization of the default options used by
util.inspect
. This is useful for functions like console.log
or
util.format
which implicitly call into util.inspect
. It shall be set to an
object containing one or more valid util.inspect()
options. Setting
option properties directly is also supported.
const util = require('node:util');
const arr = Array(101).fill(0);
console.log(arr); // Logs the truncated array
util.inspect.defaultOptions.maxArrayLength = null;
console.log(arr); // logs the full array
util.isDeepStrictEqual(val1, val2)
#
如果 val1
和 val2
之间存在深度严格相等,则返回 true
。否则,返回 false
。
¥Returns true
if there is deep strict equality between val1
and val2
.
Otherwise, returns false
.
有关深度严格相等的更多信息,请参见 assert.deepStrictEqual()
。
¥See assert.deepStrictEqual()
for more information about deep strict
equality.
类:util.MIMEType
#
¥Class: util.MIMEType
¥Stability: 1 - Experimental
MIMEType 类 的实现。
¥An implementation of the MIMEType class.
按照浏览器的约定,MIMEType
对象的所有属性都被实现为类原型上的获取器和设置器,而不是对象本身的数据属性。
¥In accordance with browser conventions, all properties of MIMEType
objects
are implemented as getters and setters on the class prototype, rather than as
data properties on the object itself.
MIME 字符串是包含多个有意义的组件的结构化字符串。解析后,将返回一个 MIMEType
对象,其中包含每个组件的属性。
¥A MIME string is a structured string containing multiple meaningful
components. When parsed, a MIMEType
object is returned containing
properties for each of these components.
构造器:new MIMEType(input)
#
¥Constructor: new MIMEType(input)
通过解析 input
创建一个新的 MIMEType
对象。
¥Creates a new MIMEType
object by parsing the input
.
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
。注意,会将给定的值强制转换为字符串。例如:
¥A TypeError
will be thrown if the input
is not a valid MIME. Note
that an effort will be made to coerce the given values into strings. For
instance:
import { MIMEType } from 'node:util';
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plain
const { MIMEType } = require('node:util');
const myMIME = new MIMEType({ toString: () => 'text/plain' });
console.log(String(myMIME));
// Prints: text/plain
mime.type
#
获取和设置 MIME 的类型部分。
¥Gets and sets the type portion of the MIME.
import { MIMEType } from 'node:util';
const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascript
const { MIMEType } = require('node:util');
const myMIME = new MIMEType('text/javascript');
console.log(myMIME.type);
// Prints: text
myMIME.type = 'application';
console.log(myMIME.type);
// Prints: application
console.log(String(myMIME));
// Prints: application/javascript
mime.subtype
#
获取和设置 MIME 的子类型部分。
¥Gets and sets the subtype portion of the MIME.
import { MIMEType } from 'node:util';
const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascript
const { MIMEType } = require('node:util');
const myMIME = new MIMEType('text/ecmascript');
console.log(myMIME.subtype);
// Prints: ecmascript
myMIME.subtype = 'javascript';
console.log(myMIME.subtype);
// Prints: javascript
console.log(String(myMIME));
// Prints: text/javascript
mime.essence
#
获取 MIME 的精髓。这个属性是只读的。使用 mime.type
或 mime.subtype
改变 MIME。
¥Gets the essence of the MIME. This property is read only.
Use mime.type
or mime.subtype
to alter the MIME.
import { MIMEType } from 'node:util';
const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=value
const { MIMEType } = require('node:util');
const myMIME = new MIMEType('text/javascript;key=value');
console.log(myMIME.essence);
// Prints: text/javascript
myMIME.type = 'application';
console.log(myMIME.essence);
// Prints: application/javascript
console.log(String(myMIME));
// Prints: application/javascript;key=value
mime.params
#
获取表示 MIME 参数的 MIMEParams
对象。这个属性是只读的。有关详细信息,请参阅 MIMEParams
文档。
¥Gets the MIMEParams
object representing the
parameters of the MIME. This property is read-only. See
MIMEParams
documentation for details.
mime.toString()
#
MIMEType
对象上的 toString()
方法返回序列化的 MIME。
¥The toString()
method on the MIMEType
object returns the serialized MIME.
因为符合标准的需要,该方法不允许用户自定义 MIME 的序列化过程。
¥Because of the need for standard compliance, this method does not allow users to customize the serialization process of the MIME.
mime.toJSON()
#
mime.toString()
的别名。
¥Alias for mime.toString()
.
当 MIMEType
对象用 JSON.stringify()
序列化时,会自动调用此方法。
¥This method is automatically called when an MIMEType
object is serialized
with JSON.stringify()
.
import { MIMEType } from 'node:util';
const myMIMES = [
new MIMEType('image/png'),
new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]
const { MIMEType } = require('node:util');
const myMIMES = [
new MIMEType('image/png'),
new MIMEType('image/gif'),
];
console.log(JSON.stringify(myMIMES));
// Prints: ["image/png", "image/gif"]
类:util.MIMEParams
#
¥Class: util.MIMEParams
MIMEParams
API 提供对 MIMEType
参数的读写访问。
¥The MIMEParams
API provides read and write access to the parameters of a
MIMEType
.
构造器:new MIMEParams()
#
¥Constructor: new MIMEParams()
使用空参数创建一个新的 MIMEParams
对象
¥Creates a new MIMEParams
object by with empty parameters
import { MIMEParams } from 'node:util';
const myParams = new MIMEParams();
const { MIMEParams } = require('node:util');
const myParams = new MIMEParams();
mimeParams.delete(name)
#
name
<string>
删除名称为 name
的所有名称-值对。
¥Remove all name-value pairs whose name is name
.
mimeParams.entries()
#
-
返回:<Iterator>
¥Returns: <Iterator>
返回参数中每个名称-值对的迭代器。迭代器的每一项都是 JavaScript Array
。数组的第一项是 name
,数组的第二项是 value
。
¥Returns an iterator over each of the name-value pairs in the parameters.
Each item of the iterator is a JavaScript Array
. The first item of the array
is the name
, the second item of the array is the value
.
mimeParams.get(name)
#
-
name
<string> -
返回:<string> 或
null
(如果不存在具有给定name
的名称-值对)。¥Returns: <string> or
null
if there is no name-value pair with the givenname
.
返回名称为 name
的第一个名称-值对的值。如果没有这样的对,则返回 null
。
¥Returns the value of the first name-value pair whose name is name
. If there
are no such pairs, null
is returned.
mimeParams.has(name)
#
如果至少有一个名称-值对的名称为 name
,则返回 true
。
¥Returns true
if there is at least one name-value pair whose name is name
.
mimeParams.keys()
#
-
返回:<Iterator>
¥Returns: <Iterator>
返回每个名称-值对名称的迭代器。
¥Returns an iterator over the names of each name-value pair.
import { MIMEType } from 'node:util';
const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
console.log(name);
}
// Prints:
// foo
// bar
const { MIMEType } = require('node:util');
const { params } = new MIMEType('text/plain;foo=0;bar=1');
for (const name of params.keys()) {
console.log(name);
}
// Prints:
// foo
// bar
mimeParams.set(name, value)
#
将与 name
关联的 MIMEParams
对象中的值设置为 value
。如果有任何名称为 name
的预先存在的名称-值对,将第一个这样的对的值设置为 value
。
¥Sets the value in the MIMEParams
object associated with name
to
value
. If there are any pre-existing name-value pairs whose names are name
,
set the first such pair's value to 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());
// Prints: foo=def&bar=1&baz=xyz
const { 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());
// Prints: foo=def&bar=1&baz=xyz
mimeParams.values()
#
-
返回:<Iterator>
¥Returns: <Iterator>
返回每个名称-值对的值的迭代器。
¥Returns an iterator over the values of each name-value pair.
mimeParams[@@iterator]()
#
-
返回:<Iterator>
¥Returns: <Iterator>
mimeParams.entries()
的别名。
¥Alias for 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);
}
// Prints:
// foo bar
// xyz baz
const { MIMEType } = require('node:util');
const { params } = new MIMEType('text/plain;foo=bar;xyz=baz');
for (const [name, value] of params) {
console.log(name, value);
}
// Prints:
// foo bar
// xyz baz
util.parseArgs([config])
#
¥Stability: 1 - Experimental
-
config
<Object> 用于提供解析参数和配置解析器。config
支持以下属性:¥
config
<Object> Used to provide arguments for parsing and to configure the parser.config
supports the following properties:-
args
<string[]> 参数字符串数组。默认值:process.argv
删除了execPath
和filename
。¥
args
<string[]> array of argument strings. Default:process.argv
withexecPath
andfilename
removed. -
options
<Object> 用于描述解析器已知的参数。options
的键是选项的长名称,值是 <Object>,接受以下属性:¥
options
<Object> Used to describe arguments known to the parser. Keys ofoptions
are the long names of options and values are an <Object> accepting the following properties:-
type
<string> 参数类型,必须是boolean
或string
。¥
type
<string> Type of argument, which must be eitherboolean
orstring
. -
multiple
<boolean> 是否可以多次提供该选项。如果为true
,则所有的值都会被收集到一个数组中。如果为false
,则选项的值是最后获胜的。默认值:false
。¥
multiple
<boolean> Whether this option can be provided multiple times. Iftrue
, all values will be collected in an array. Iffalse
, values for the option are last-wins. Default:false
. -
short
<string> 选项的单个字符别名。¥
short
<string> A single character alias for the option. -
default
<string> | <boolean> | <string[]> | <boolean[]> 未由 args 设置时的默认选项值。它必须与type
属性的类型相同。当multiple
为true
时,它必须是一个数组。¥
default
<string> | <boolean> | <string[]> | <boolean[]> The default option value when it is not set by args. It must be of the same type as thetype
property. Whenmultiple
istrue
, it must be an array.
-
-
strict
<boolean> 当遇到未知参数时,或者当传入的参数与options
中配置的type
不匹配时,是否应该抛出错误。默认值:true
。¥
strict
<boolean> Should an error be thrown when unknown arguments are encountered, or when arguments are passed that do not match thetype
configured inoptions
. Default:true
. -
allowPositionals
<boolean> 此命令是否接受位置参数。默认值:如果strict
是true
,则为false
,否则为true
。¥
allowPositionals
<boolean> Whether this command accepts positional arguments. Default:false
ifstrict
istrue
, otherwisetrue
. -
tokens
<boolean> 返回解析的令牌。这对于扩展内置行为很有用,从添加额外检查到以不同方式重新处理令牌。默认值:false
。¥
tokens
<boolean> Return the parsed tokens. This is useful for extending the built-in behavior, from adding additional checks through to reprocessing the tokens in different ways. Default:false
.
-
-
返回:<Object> 解析后的命令行参数:
¥Returns: <Object> The parsed command line arguments:
-
values
<Object> 解析的选项名称与其 <string> 或 <boolean> 值的映射。¥
values
<Object> A mapping of parsed option names with their <string> or <boolean> values. -
positionals
<string[]> 位置参数。¥
positionals
<string[]> Positional arguments. -
tokens
<Object[]> | <undefined> 参见 parseArgs 标记 部分。仅当config
包含tokens: true
时才返回。¥
tokens
<Object[]> | <undefined> See parseArgs tokens section. Only returned ifconfig
includestokens: true
.
-
为命令行参数解析提供比直接与 process.argv
交互更高级别的 API。采用预期参数的规范并返回带有解析选项和位置的结构化对象。
¥Provides a higher level API for command-line argument parsing than interacting
with process.argv
directly. Takes a specification for the expected arguments
and returns a structured object with the parsed options and positionals.
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);
// Prints: [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);
// Prints: [Object: null prototype] { foo: true, bar: 'b' } []
util.parseArgs
是实验性的,行为可能会改变。加入 pkgjs/parseargs 中的对话,为设计做出贡献。
¥util.parseArgs
is experimental and behavior may change. Join the
conversation in pkgjs/parseargs to contribute to the design.
parseArgs
tokens
#
详细的解析信息可用于通过在配置中指定 tokens: true
添加自定义行为。返回的令牌具有描述的属性:
¥Detailed parse information is available for adding custom behaviors by
specifying tokens: true
in the configuration.
The returned tokens have properties describing:
-
所有令牌
¥all tokens
-
kind
<string> '选项'、'positional' 或 'option-terminator' 之一。¥
kind
<string> One of 'option', 'positional', or 'option-terminator'. -
index
<number>args
中包含标记的元素索引。所以令牌的源参数是args[token.index]
。¥
index
<number> Index of element inargs
containing token. So the source argument for a token isargs[token.index]
.
-
-
选项令牌
¥option tokens
-
name
<string> 选项的长名称。¥
name
<string> Long name of option. -
rawName
<string> 如何在 args 中使用选项,例如--foo
的-f
。¥
rawName
<string> How option used in args, like-f
of--foo
. -
value
<string> | <undefined> 参数中指定的选项值。布尔选项未定义。¥
value
<string> | <undefined> Option value specified in args. Undefined for boolean options. -
inlineValue
<boolean> | <undefined> 是否内联指定选项值,如--foo=bar
。¥
inlineValue
<boolean> | <undefined> Whether option value specified inline, like--foo=bar
.
-
-
位置标记
¥positional tokens
-
选项终止令牌
¥option-terminator token
返回的令牌按照输入参数中遇到的顺序。在 args 中出现多次的选项每次使用都会产生一个令牌。像 -xy
这样的短选项组扩展为每个选项的令牌。所以 -xxx
产生了三个令牌。
¥The returned tokens are in the order encountered in the input args. Options
that appear more than once in args produce a token for each use. Short option
groups like -xy
expand to a token for each option. So -xxx
produces
three tokens.
例如,要使用返回的令牌来添加对 --no-color
等否定选项的支持,可以重新处理令牌以更改为否定选项存储的值。
¥For example to use the returned tokens to add support for a negated option
like --no-color
, the tokens can be reprocessed to change the value stored
for the negated option.
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 });
// Reprocess the option tokens and overwrite the returned values.
tokens
.filter((token) => token.kind === 'option')
.forEach((token) => {
if (token.name.startsWith('no-')) {
// Store foo:false for --no-foo
const positiveName = token.name.slice(3);
values[positiveName] = false;
delete values[token.name];
} else {
// Resave value so last one wins if both --foo and --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 });
// Reprocess the option tokens and overwrite the returned values.
tokens
.filter((token) => token.kind === 'option')
.forEach((token) => {
if (token.name.startsWith('no-')) {
// Store foo:false for --no-foo
const positiveName = token.name.slice(3);
values[positiveName] = false;
delete values[token.name];
} else {
// Resave value so last one wins if both --foo and --no-foo.
values[token.name] = token.value ?? true;
}
});
const color = values.color;
const logfile = values.logfile ?? 'default.log';
console.log({ logfile, color });
显示否定选项的示例用法,当一个选项以多种方式使用时,最后一个获胜。
¥Example usage showing negated options, and when an option is used multiple ways then last one wins.
$ 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>
¥Returns: <Function>
采用遵循常见的错误优先的回调风格的函数(也就是将 (err, value) => ...
回调作为最后一个参数),并返回一个返回 promise 的版本。
¥Takes a function following the common error-first callback style, i.e. taking
an (err, value) => ...
callback as the last argument, and returns a version
that returns promises.
const util = require('node:util');
const fs = require('node:fs');
const stat = util.promisify(fs.stat);
stat('.').then((stats) => {
// Do something with `stats`
}).catch((error) => {
// Handle the error.
});
或者,等效地使用 async function
:
¥Or, equivalently using async function
s:
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 化函数。
¥If there is an original[util.promisify.custom]
property present, promisify
will return its value, see Custom promisified functions.
promisify()
假设 original
是在所有情况下都将回调作为其最后一个参数的函数。如果 original
不是函数,则 promisify()
将抛出错误。如果 original
是函数,但其最后一个参数不是错误优先的回调,则它仍然会被传入错误优先的回调作为其最后一个参数。
¥promisify()
assumes that original
is a function taking a callback as its
final argument in all cases. If original
is not a function, promisify()
will throw an error. If original
is a function but its last argument is not
an error-first callback, it will still be passed an error-first
callback as its last argument.
除非经过特殊处理,否则在类方法或其他使用 this
的方法上使用 promisify()
可能无法按预期工作:
¥Using promisify()
on class methods or other methods that use this
may not
work as expected unless handled specially:
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 化函数#
¥Custom promisified functions
使用 util.promisify.custom
符号可以覆盖 util.promisify()
的返回值:
¥Using the util.promisify.custom
symbol one can override the return value of
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]);
// prints 'true'
这对于原始函数不遵循将错误优先的回调作为最后一个参数的标准格式的情况很有用。
¥This can be useful for cases where the original function does not follow the standard format of taking an error-first callback as the last argument.
例如,对于接受 (foo, onSuccessCallback, onErrorCallback)
的函数:
¥For example, with a function that takes in
(foo, onSuccessCallback, onErrorCallback)
:
doSomething[util.promisify.custom] = (foo) => {
return new Promise((resolve, reject) => {
doSomething(foo, resolve, reject);
});
};
如果 promisify.custom
已定义但不是函数,则 promisify()
将抛出错误。
¥If promisify.custom
is defined but is not a function, promisify()
will
throw an error.
util.promisify.custom
#
-
<symbol> 可用于声明函数的自定义 Promisified 变体,请参阅 自定义 promise 化函数。
¥<symbol> that can be used to declare custom promisified variants of functions, see Custom promisified functions.
除了可以通过 util.promisify.custom
访问外,这个符号是 全局注册,在任何环境下都可以作为 Symbol.for('nodejs.util.promisify.custom')
访问。
¥In addition to being accessible through util.promisify.custom
, this
symbol is registered globally and can be
accessed in any environment as Symbol.for('nodejs.util.promisify.custom')
.
例如,对于接受 (foo, onSuccessCallback, onErrorCallback)
的函数:
¥For example, with a function that takes in
(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)
#
返回已删除任何 ANSI 转义码的 str
。
¥Returns str
with any ANSI escape codes removed.
console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
// Prints "value"
类:util.TextDecoder
#
¥Class: util.TextDecoder
WHATWG 编码标准 TextDecoder
API 的实现。
¥An implementation of the WHATWG Encoding Standard TextDecoder
API.
const decoder = new TextDecoder();
const u8arr = new Uint8Array([72, 101, 108, 108, 111]);
console.log(decoder.decode(u8arr)); // Hello
WHATWG 支持的编码#
¥WHATWG supported encodings
根据 WHATWG 编码标准,下表概述了 TextDecoder
API 支持的编码。对于每种编码,可以使用一个或多个别名。
¥Per the WHATWG Encoding Standard, the encodings supported by the
TextDecoder
API are outlined in the tables below. For each encoding,
one or more aliases may be used.
不同的 Node.js 构建配置支持不同的编码集。(见 国际化)
¥Different Node.js build configurations support different sets of encodings. (see Internationalization)
默认支持的编码(具有完整的 ICU 数据)#
¥Encodings supported by default (with full ICU data)
编码 | 别名 |
---|---|
'ibm866' | '866' , 'cp866' , 'csibm866' |
'iso-8859-2' | 'csisolatin2' , 'iso-ir-101' , 'iso8859-2' , 'iso88592' , 'iso_8859-2' , 'iso_8859-2:1987' , 'l2' , 'latin2' |
'iso-8859-3' | 'csisolatin3' , 'iso-ir-109' , 'iso8859-3' , 'iso88593' , 'iso_8859-3' , 'iso_8859-3:1988' , 'l3' , 'latin3' |
'iso-8859-4' | 'csisolatin4' , 'iso-ir-110' , 'iso8859-4' , 'iso88594' , 'iso_8859-4' , 'iso_8859-4:1988' , 'l4' , 'latin4' |
'iso-8859-5' | 'csisolatincyrillic' , 'cyrillic' , 'iso-ir-144' , 'iso8859-5' , 'iso88595' , 'iso_8859-5' , 'iso_8859-5:1988' |
'iso-8859-6' | 'arabic' , 'asmo-708' , 'csiso88596e' , 'csiso88596i' , 'csisolatinarabic' , 'ecma-114' , 'iso-8859-6-e' , 'iso-8859-6-i' , 'iso-ir-127' , 'iso8859-6' , 'iso88596' , 'iso_8859-6' , 'iso_8859-6:1987' |
'iso-8859-7' | 'csisolatingreek' , 'ecma-118' , 'elot_928' , 'greek' , 'greek8' , 'iso-ir-126' , 'iso8859-7' , 'iso88597' , 'iso_8859-7' , 'iso_8859-7:1987' , 'sun_eu_greek' |
'iso-8859-8' | 'csiso88598e' , 'csisolatinhebrew' , 'hebrew' , 'iso-8859-8-e' , 'iso-ir-138' , 'iso8859-8' , 'iso88598' , 'iso_8859-8' , 'iso_8859-8:1988' , 'visual' |
'iso-8859-8-i' | 'csiso88598i' , 'logical' |
'iso-8859-10' | 'csisolatin6' , 'iso-ir-157' , 'iso8859-10' , 'iso885910' , 'l6' , 'latin6' |
'iso-8859-13' | 'iso8859-13' , 'iso885913' |
'iso-8859-14' | 'iso8859-14' , 'iso885914' |
'iso-8859-15' | 'csisolatin9' , 'iso8859-15' , 'iso885915' , 'iso_8859-15' , 'l9' |
'koi8-r' | 'cskoi8r' , 'koi' , 'koi8' , 'koi8_r' |
'koi8-u' | 'koi8-ru' |
'macintosh' | 'csmacintosh' , 'mac' , 'x-mac-roman' |
'windows-874' | 'dos-874' , 'iso-8859-11' , 'iso8859-11' , 'iso885911' , 'tis-620' |
'windows-1250' | 'cp1250' , 'x-cp1250' |
'windows-1251' | 'cp1251' , 'x-cp1251' |
'windows-1252' | 'ansi_x3.4-1968' , 'ascii' , 'cp1252' , 'cp819' , 'csisolatin1' , 'ibm819' , 'iso-8859-1' , 'iso-ir-100' , 'iso8859-1' , 'iso88591' , 'iso_8859-1' , 'iso_8859-1:1987' , 'l1' , 'latin1' , 'us-ascii' , 'x-cp1252' |
'windows-1253' | 'cp1253' , 'x-cp1253' |
'windows-1254' | 'cp1254' , 'csisolatin5' , 'iso-8859-9' , 'iso-ir-148' , 'iso8859-9' , 'iso88599' , 'iso_8859-9' , 'iso_8859-9:1989' , 'l5' , 'latin5' , 'x-cp1254' |
'windows-1255' | 'cp1255' , 'x-cp1255' |
'windows-1256' | 'cp1256' , 'x-cp1256' |
'windows-1257' | 'cp1257' , 'x-cp1257' |
'windows-1258' | 'cp1258' , 'x-cp1258' |
'x-mac-cyrillic' | 'x-mac-ukrainian' |
'gbk' | 'chinese' , 'csgb2312' , 'csiso58gb231280' , 'gb2312' , 'gb_2312' , 'gb_2312-80' , 'iso-ir-58' , 'x-gbk' |
'gb18030' | |
'big5' | 'big5-hkscs' , 'cn-big5' , 'csbig5' , 'x-x-big5' |
'euc-jp' | 'cseucpkdfmtjapanese' , 'x-euc-jp' |
'iso-2022-jp' | 'csiso2022jp' |
'shift_jis' | 'csshiftjis' , 'ms932' , 'ms_kanji' , 'shift-jis' , 'sjis' , 'windows-31j' , 'x-sjis' |
'euc-kr' | 'cseuckr' , 'csksc56011987' , 'iso-ir-149' , 'korean' , 'ks_c_5601-1987' , 'ks_c_5601-1989' , 'ksc5601' , 'ksc_5601' , 'windows-949' |
使用 small-icu
选项构建 Node.js 时支持的编码#
¥Encodings supported when Node.js is built with the small-icu
option
编码 | 别名 |
---|---|
'utf-8' | 'unicode-1-1-utf-8' , 'utf8' |
'utf-16le' | 'utf-16' |
'utf-16be' |
禁用 ICU 时支持的编码#
¥Encodings supported when ICU is disabled
编码 | 别名 |
---|---|
'utf-8' | 'unicode-1-1-utf-8' , 'utf8' |
'utf-16le' | 'utf-16' |
不支持 WHATWG 编码标准 中列出的 'iso-8859-16'
编码。
¥The 'iso-8859-16'
encoding listed in the WHATWG Encoding Standard
is not supported.
new TextDecoder([encoding[, options]])
#
-
encoding
<string> 标识此TextDecoder
实例支持的encoding
。默认值:'utf-8'
。¥
encoding
<string> Identifies theencoding
that thisTextDecoder
instance supports. Default:'utf-8'
. -
options
<Object>-
fatal
<boolean> 如果解码失败是致命的,则为true
。禁用 ICU 时不支持此选项(请参阅 国际化)。默认值:false
。¥
fatal
<boolean>true
if decoding failures are fatal. This option is not supported when ICU is disabled (see Internationalization). Default:false
. -
ignoreBOM
<boolean> 当true
时,TextDecoder
将在解码结果中包含字节顺序标记。当false
时,字节顺序标记将从输出中删除。此选项仅在encoding
为'utf-8'
、'utf-16be'
或'utf-16le'
时使用。默认值:false
。¥
ignoreBOM
<boolean> Whentrue
, theTextDecoder
will include the byte order mark in the decoded result. Whenfalse
, the byte order mark will be removed from the output. This option is only used whenencoding
is'utf-8'
,'utf-16be'
, or'utf-16le'
. Default:false
.
-
创建新的 TextDecoder
实例。encoding
可以指定支持的编码之一或别名。
¥Creates a new TextDecoder
instance. The encoding
may specify one of the
supported encodings or an alias.
TextDecoder
类也在全局对象上可用。
¥The TextDecoder
class is also available on the global object.
textDecoder.decode([input[, options]])
#
-
input
<ArrayBuffer> | <DataView> | <TypedArray> 包含编码数据的ArrayBuffer
、DataView
或TypedArray
实例。¥
input
<ArrayBuffer> | <DataView> | <TypedArray> AnArrayBuffer
,DataView
, orTypedArray
instance containing the encoded data. -
options
<Object> -
返回:<string>
¥Returns: <string>
解码 input
并返回字符串。如果 options.stream
是 true
,则在 input
末尾出现的任何不完整的字节序列都会在内部缓冲并在下一次调用 textDecoder.decode()
后触发。
¥Decodes the input
and returns a string. If options.stream
is true
, any
incomplete byte sequences occurring at the end of the input
are buffered
internally and emitted after the next call to textDecoder.decode()
.
如果 textDecoder.fatal
是 true
,则发生的解码错误将导致抛出 TypeError
。
¥If textDecoder.fatal
is true
, decoding errors that occur will result in a
TypeError
being thrown.
textDecoder.encoding
#
TextDecoder
实例支持的编码。
¥The encoding supported by the TextDecoder
instance.
textDecoder.fatal
#
如果解码错误导致抛出 TypeError
,则该值将为 true
。
¥The value will be true
if decoding errors result in a TypeError
being
thrown.
textDecoder.ignoreBOM
#
如果解码结果将包含字节顺序标记,则该值将为 true
。
¥The value will be true
if the decoding result will include the byte order
mark.
类:util.TextEncoder
#
¥Class: util.TextEncoder
WHATWG 编码标准 TextEncoder
API 的实现。TextEncoder
的所有实例仅支持 UTF-8 编码。
¥An implementation of the WHATWG Encoding Standard TextEncoder
API. All
instances of TextEncoder
only support UTF-8 encoding.
const encoder = new TextEncoder();
const uint8array = encoder.encode('this is some data');
TextEncoder
类也在全局对象上可用。
¥The TextEncoder
class is also available on the global object.
textEncoder.encode([input])
#
-
input
<string> 要编码的文本。默认值:一个空字符串。¥
input
<string> The text to encode. Default: an empty string. -
返回:<Uint8Array>
¥Returns: <Uint8Array>
对 input
字符串进行 UTF-8 编码并返回包含编码字节的 Uint8Array
。
¥UTF-8 encodes the input
string and returns a Uint8Array
containing the
encoded bytes.
textEncoder.encodeInto(src, dest)
#
-
src
<string> 要编码的文本。¥
src
<string> The text to encode. -
dest
<Uint8Array> 保存编码结果的数组。¥
dest
<Uint8Array> The array to hold the encode result. -
返回:<Object>
¥Returns: <Object>
将 src
字符串 UTF-8 编码为 dest
Uint8Array 并返回包含读取的 Unicode 代码单元和写入的 UTF-8 字节的对象。
¥UTF-8 encodes the src
string to the dest
Uint8Array and returns an object
containing the read Unicode code units and written UTF-8 bytes.
const encoder = new TextEncoder();
const src = 'this is some data';
const dest = new Uint8Array(10);
const { read, written } = encoder.encodeInto(src, dest);
textEncoder.encoding
#
TextEncoder
实例支持的编码。始终设置为 'utf-8'
。
¥The encoding supported by the TextEncoder
instance. Always set to 'utf-8'
.
util.toUSVString(string)
#
string
<string>
在用 Unicode "替换字符" U+FFFD 替换任何代理代码点(或等效地,任何未配对的代理代码单元)后返回 string
。
¥Returns the string
after replacing any surrogate code points
(or equivalently, any unpaired surrogate code units) with the
Unicode "replacement character" U+FFFD.
util.transferableAbortController()
#
¥Stability: 1 - Experimental
创建并返回一个 <AbortController> 实例,其 <AbortSignal> 被标记为可转让,可与 structuredClone()
或 postMessage()
一起使用。
¥Creates and returns an <AbortController> instance whose <AbortSignal> is marked
as transferable and can be used with structuredClone()
or postMessage()
.
util.transferableAbortSignal(signal)
#
¥Stability: 1 - Experimental
-
signal
<AbortSignal> -
¥Returns: <AbortSignal>
将给定的 <AbortSignal> 标记为可转让,以便它可以与 structuredClone()
和 postMessage()
一起使用。
¥Marks the given <AbortSignal> as transferable so that it can be used with
structuredClone()
and postMessage()
.
const signal = transferableAbortSignal(AbortSignal.timeout(100));
const channel = new MessageChannel();
channel.port2.postMessage(signal, [signal]);
util.aborted(signal, resource)
#
¥Stability: 1 - Experimental
-
signal
<AbortSignal> -
resource
<Object> 任何非空实体,对其的引用是弱引用的。¥
resource
<Object> Any non-null entity, reference to which is held weakly. -
返回:<Promise>
¥Returns: <Promise>
在提供的 signal
上监听中止事件,并返回在 signal
中止时履行的 promise。如果传递的 resource
在 signal
中止之前被垃圾收集,则返回的 promise 将无限期地保持挂起状态。
¥Listens to abort event on the provided signal
and
returns a promise that is fulfilled when the signal
is
aborted. If the passed resource
is garbage collected before the signal
is
aborted, the returned promise shall remain pending indefinitely.
const { aborted } = require('node:util');
const dependent = obtainSomethingAbortable();
aborted(dependent.signal, dependent).then(() => {
// Do something when dependent is aborted.
});
dependent.on('event', () => {
dependent.abort();
});
import { aborted } from 'node:util';
const dependent = obtainSomethingAbortable();
aborted(dependent.signal, dependent).then(() => {
// Do something when dependent is aborted.
});
dependent.on('event', () => {
dependent.abort();
});
util.types
#
util.types
为不同种类的内置对象提供类型检查。与 instanceof
或 Object.prototype.toString.call(value)
不同,这些检查不检查可从 JavaScript 访问的对象的属性(如它们的原型),并且通常具有调用 C++ 的开销。
¥util.types
provides type checks for different kinds of built-in objects.
Unlike instanceof
or Object.prototype.toString.call(value)
, these checks do
not inspect properties of the object that are accessible from JavaScript (like
their prototype), and usually have the overhead of calling into C++.
结果通常不会对值在 JavaScript 中公开的属性或行为类型做出任何保证。它们主要对喜欢在 JavaScript 中进行类型检查的插件开发者有用。
¥The result generally does not make any guarantees about what kinds of properties or behavior a value exposes in JavaScript. They are primarily useful for addon developers who prefer to do type checking in JavaScript.
API 可通过 require('node:util').types
或 require('node:util/types')
访问。
¥The API is accessible via require('node:util').types
or require('node:util/types')
.
util.types.isAnyArrayBuffer(value)
#
如果值为内置的 ArrayBuffer
或 SharedArrayBuffer
实例,则返回 true
。
¥Returns true
if the value is a built-in ArrayBuffer
or
SharedArrayBuffer
instance.
另见 util.types.isArrayBuffer()
和 util.types.isSharedArrayBuffer()
。
¥See also util.types.isArrayBuffer()
and
util.types.isSharedArrayBuffer()
.
util.types.isAnyArrayBuffer(new ArrayBuffer()); // Returns true
util.types.isAnyArrayBuffer(new SharedArrayBuffer()); // Returns true
util.types.isArrayBufferView(value)
#
如果值是 ArrayBuffer
视图之一的实例,例如类型化数组对象或 DataView
,则返回 true
。相当于 ArrayBuffer.isView()
。
¥Returns true
if the value is an instance of one of the ArrayBuffer
views, such as typed array objects or DataView
. Equivalent to
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)
#
如果值为 arguments
对象,则返回 true
。
¥Returns true
if the value is an arguments
object.
function foo() {
util.types.isArgumentsObject(arguments); // Returns true
}
util.types.isArrayBuffer(value)
#
如果值为内置的 ArrayBuffer
实例,则返回 true
。这不包括 SharedArrayBuffer
个实例。通常,最好对两者都进行测试;参见 util.types.isAnyArrayBuffer()
。
¥Returns true
if the value is a built-in ArrayBuffer
instance.
This does not include SharedArrayBuffer
instances. Usually, it is
desirable to test for both; See util.types.isAnyArrayBuffer()
for that.
util.types.isArrayBuffer(new ArrayBuffer()); // Returns true
util.types.isArrayBuffer(new SharedArrayBuffer()); // Returns false
util.types.isAsyncFunction(value)
#
如果值为 异步函数,则返回 true
。这只会报告 JavaScript 引擎看到的内容;特别是,如果使用了转译工具,返回值可能与原始源代码不匹配。
¥Returns true
if the value is an async function.
This only reports back what the JavaScript engine is seeing;
in particular, the return value may not match the original source code if
a transpilation tool was used.
util.types.isAsyncFunction(function foo() {}); // Returns false
util.types.isAsyncFunction(async function foo() {}); // Returns true
util.types.isBigInt64Array(value)
#
如果值为 BigInt64Array
实例,则返回 true
。
¥Returns true
if the value is a BigInt64Array
instance.
util.types.isBigInt64Array(new BigInt64Array()); // Returns true
util.types.isBigInt64Array(new BigUint64Array()); // Returns false
util.types.isBigUint64Array(value)
#
如果值为 BigUint64Array
实例,则返回 true
。
¥Returns true
if the value is a BigUint64Array
instance.
util.types.isBigUint64Array(new BigInt64Array()); // Returns false
util.types.isBigUint64Array(new BigUint64Array()); // Returns true
util.types.isBooleanObject(value)
#
如果值是布尔对象(例如由 new Boolean()
创建),则返回 true
。
¥Returns true
if the value is a boolean object, e.g. created
by new Boolean()
.
util.types.isBooleanObject(false); // Returns false
util.types.isBooleanObject(true); // Returns false
util.types.isBooleanObject(new Boolean(false)); // Returns true
util.types.isBooleanObject(new Boolean(true)); // Returns true
util.types.isBooleanObject(Boolean(false)); // Returns false
util.types.isBooleanObject(Boolean(true)); // Returns false
util.types.isBoxedPrimitive(value)
#
如果值是任何封装的原始对象(例如由 new Boolean()
、new String()
或 Object(Symbol())
创建),则返回 true
。
¥Returns true
if the value is any boxed primitive object, e.g. created
by new Boolean()
, new String()
or Object(Symbol())
.
例如:
¥For example:
util.types.isBoxedPrimitive(false); // Returns false
util.types.isBoxedPrimitive(new Boolean(false)); // Returns true
util.types.isBoxedPrimitive(Symbol('foo')); // Returns false
util.types.isBoxedPrimitive(Object(Symbol('foo'))); // Returns true
util.types.isBoxedPrimitive(Object(BigInt(5))); // Returns true
util.types.isCryptoKey(value)
#
如果 value
是 <CryptoKey>,则返回 true
,否则返回 false
。
¥Returns true
if value
is a <CryptoKey>, false
otherwise.
util.types.isDataView(value)
#
如果值为内置的 DataView
实例,则返回 true
。
¥Returns true
if the value is a built-in DataView
instance.
const ab = new ArrayBuffer(20);
util.types.isDataView(new DataView(ab)); // Returns true
util.types.isDataView(new Float64Array()); // Returns false
¥See also ArrayBuffer.isView()
.
util.types.isDate(value)
#
如果值为内置的 Date
实例,则返回 true
。
¥Returns true
if the value is a built-in Date
instance.
util.types.isDate(new Date()); // Returns true
util.types.isExternal(value)
#
如果值是原生的 External
值,则返回 true
。
¥Returns true
if the value is a native External
value.
原生的 External
值是特殊类型的对象,它包含用于从原生代码访问的原始 C++ 指针 (void*
),并且没有其他属性。此类对象由 Node.js 内部或原生插件创建。在 JavaScript 中,它们是具有 null
原型的 frozen 对象。
¥A native External
value is a special type of object that contains a
raw C++ pointer (void*
) for access from native code, and has no other
properties. Such objects are created either by Node.js internals or native
addons. In JavaScript, they are frozen objects with a
null
prototype.
#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); // returns true
util.types.isExternal(0); // returns false
util.types.isExternal(new String('foo')); // returns false
有关 napi_create_external
的更多信息,请参阅 napi_create_external()
。
¥For further information on napi_create_external
, refer to
napi_create_external()
.
util.types.isFloat32Array(value)
#
如果值为内置的 Float32Array
实例,则返回 true
。
¥Returns true
if the value is a built-in Float32Array
instance.
util.types.isFloat32Array(new ArrayBuffer()); // Returns false
util.types.isFloat32Array(new Float32Array()); // Returns true
util.types.isFloat32Array(new Float64Array()); // Returns false
util.types.isFloat64Array(value)
#
如果值为内置的 Float64Array
实例,则返回 true
。
¥Returns true
if the value is a built-in Float64Array
instance.
util.types.isFloat64Array(new ArrayBuffer()); // Returns false
util.types.isFloat64Array(new Uint8Array()); // Returns false
util.types.isFloat64Array(new Float64Array()); // Returns true
util.types.isGeneratorFunction(value)
#
如果值是生成器函数,则返回 true
。这只会报告 JavaScript 引擎看到的内容;特别是,如果使用了转译工具,返回值可能与原始源代码不匹配。
¥Returns true
if the value is a generator function.
This only reports back what the JavaScript engine is seeing;
in particular, the return value may not match the original source code if
a transpilation tool was used.
util.types.isGeneratorFunction(function foo() {}); // Returns false
util.types.isGeneratorFunction(function* foo() {}); // Returns true
util.types.isGeneratorObject(value)
#
如果值是从内置的生成器函数返回的生成器对象,则返回 true
。这只会报告 JavaScript 引擎看到的内容;特别是,如果使用了转译工具,返回值可能与原始源代码不匹配。
¥Returns true
if the value is a generator object as returned from a
built-in generator function.
This only reports back what the JavaScript engine is seeing;
in particular, the return value may not match the original source code if
a transpilation tool was used.
function* foo() {}
const generator = foo();
util.types.isGeneratorObject(generator); // Returns true
util.types.isInt8Array(value)
#
如果值为内置的 Int8Array
实例,则返回 true
。
¥Returns true
if the value is a built-in Int8Array
instance.
util.types.isInt8Array(new ArrayBuffer()); // Returns false
util.types.isInt8Array(new Int8Array()); // Returns true
util.types.isInt8Array(new Float64Array()); // Returns false
util.types.isInt16Array(value)
#
如果值为内置的 Int16Array
实例,则返回 true
。
¥Returns true
if the value is a built-in Int16Array
instance.
util.types.isInt16Array(new ArrayBuffer()); // Returns false
util.types.isInt16Array(new Int16Array()); // Returns true
util.types.isInt16Array(new Float64Array()); // Returns false
util.types.isInt32Array(value)
#
如果值为内置的 Int32Array
实例,则返回 true
。
¥Returns true
if the value is a built-in Int32Array
instance.
util.types.isInt32Array(new ArrayBuffer()); // Returns false
util.types.isInt32Array(new Int32Array()); // Returns true
util.types.isInt32Array(new Float64Array()); // Returns false
util.types.isKeyObject(value)
#
如果 value
是 <KeyObject>,则返回 true
,否则返回 false
。
¥Returns true
if value
is a <KeyObject>, false
otherwise.
util.types.isMap(value)
#
如果值为内置的 Map
实例,则返回 true
。
¥Returns true
if the value is a built-in Map
instance.
util.types.isMap(new Map()); // Returns true
util.types.isMapIterator(value)
#
如果值是为内置的 Map
实例返回的迭代器,则返回 true
。
¥Returns true
if the value is an iterator returned for a built-in
Map
instance.
const map = new Map();
util.types.isMapIterator(map.keys()); // Returns true
util.types.isMapIterator(map.values()); // Returns true
util.types.isMapIterator(map.entries()); // Returns true
util.types.isMapIterator(map[Symbol.iterator]()); // Returns true
util.types.isModuleNamespaceObject(value)
#
如果值是 模块命名空间对象 的实例,则返回 true
。
¥Returns true
if the value is an instance of a Module Namespace Object.
import * as ns from './a.js';
util.types.isModuleNamespaceObject(ns); // Returns true
util.types.isNativeError(value)
#
如果值由 内置 Error
类型 的构造函数返回,则返回 true
。
¥Returns true
if the value was returned by the constructor of a
built-in Error
type.
console.log(util.types.isNativeError(new Error())); // true
console.log(util.types.isNativeError(new TypeError())); // true
console.log(util.types.isNativeError(new RangeError())); // true
原生错误类型的子类也是原生错误:
¥Subclasses of the native error types are also native errors:
class MyError extends Error {}
console.log(util.types.isNativeError(new MyError())); // true
作为原生错误类的 instanceof
值不等同于 isNativeError()
为该值返回 true
。isNativeError()
为来自不同 realm 的错误返回 true
,而 instanceof Error
为这些错误返回 false
:
¥A value being instanceof
a native error class is not equivalent to isNativeError()
returning true
for that value. isNativeError()
returns true
for errors
which come from a different realm while instanceof Error
returns false
for these errors:
const vm = require('node:vm');
const context = vm.createContext({});
const myError = vm.runInContext('new Error()', context);
console.log(util.types.isNativeError(myError)); // true
console.log(myError instanceof Error); // false
相反,对于原生错误的构造函数未返回的所有对象,isNativeError()
返回 false
。这包括 instanceof
原生错误的值:
¥Conversely, isNativeError()
returns false
for all objects which were not
returned by the constructor of a native error. That includes values
which are instanceof
native errors:
const myError = { __proto__: Error.prototype };
console.log(util.types.isNativeError(myError)); // false
console.log(myError instanceof Error); // true
util.types.isNumberObject(value)
#
如果值是数字对象(例如由 new Number()
创建),则返回 true
。
¥Returns true
if the value is a number object, e.g. created
by new Number()
.
util.types.isNumberObject(0); // Returns false
util.types.isNumberObject(new Number(0)); // Returns true
util.types.isPromise(value)
#
如果值为内置的 Promise
,则返回 true
。
¥Returns true
if the value is a built-in Promise
.
util.types.isPromise(Promise.resolve(42)); // Returns true
util.types.isProxy(value)
#
如果值为 Proxy
实例,则返回 true
。
¥Returns true
if the value is a Proxy
instance.
const target = {};
const proxy = new Proxy(target, {});
util.types.isProxy(target); // Returns false
util.types.isProxy(proxy); // Returns true
util.types.isRegExp(value)
#
如果值是正则表达式对象,则返回 true
。
¥Returns true
if the value is a regular expression object.
util.types.isRegExp(/abc/); // Returns true
util.types.isRegExp(new RegExp('abc')); // Returns true
util.types.isSet(value)
#
如果值为内置的 Set
实例,则返回 true
。
¥Returns true
if the value is a built-in Set
instance.
util.types.isSet(new Set()); // Returns true
util.types.isSetIterator(value)
#
如果值是为内置的 Set
实例返回的迭代器,则返回 true
。
¥Returns true
if the value is an iterator returned for a built-in
Set
instance.
const set = new Set();
util.types.isSetIterator(set.keys()); // Returns true
util.types.isSetIterator(set.values()); // Returns true
util.types.isSetIterator(set.entries()); // Returns true
util.types.isSetIterator(set[Symbol.iterator]()); // Returns true
util.types.isSharedArrayBuffer(value)
#
如果值为内置的 SharedArrayBuffer
实例,则返回 true
。这不包括 ArrayBuffer
个实例。通常,最好对两者都进行测试;参见 util.types.isAnyArrayBuffer()
。
¥Returns true
if the value is a built-in SharedArrayBuffer
instance.
This does not include ArrayBuffer
instances. Usually, it is
desirable to test for both; See util.types.isAnyArrayBuffer()
for that.
util.types.isSharedArrayBuffer(new ArrayBuffer()); // Returns false
util.types.isSharedArrayBuffer(new SharedArrayBuffer()); // Returns true
util.types.isStringObject(value)
#
如果值是字符串对象(例如由 new String()
创建),则返回 true
。
¥Returns true
if the value is a string object, e.g. created
by new String()
.
util.types.isStringObject('foo'); // Returns false
util.types.isStringObject(new String('foo')); // Returns true
util.types.isSymbolObject(value)
#
如果值是符号对象(通过在 Symbol
原始类型上调用 Object()
创建),则返回 true
。
¥Returns true
if the value is a symbol object, created
by calling Object()
on a Symbol
primitive.
const symbol = Symbol('foo');
util.types.isSymbolObject(symbol); // Returns false
util.types.isSymbolObject(Object(symbol)); // Returns true
util.types.isTypedArray(value)
#
如果值为内置的 TypedArray
实例,则返回 true
。
¥Returns true
if the value is a built-in TypedArray
instance.
util.types.isTypedArray(new ArrayBuffer()); // Returns false
util.types.isTypedArray(new Uint8Array()); // Returns true
util.types.isTypedArray(new Float64Array()); // Returns true
¥See also ArrayBuffer.isView()
.
util.types.isUint8Array(value)
#
如果值为内置的 Uint8Array
实例,则返回 true
。
¥Returns true
if the value is a built-in Uint8Array
instance.
util.types.isUint8Array(new ArrayBuffer()); // Returns false
util.types.isUint8Array(new Uint8Array()); // Returns true
util.types.isUint8Array(new Float64Array()); // Returns false
util.types.isUint8ClampedArray(value)
#
如果值为内置的 Uint8ClampedArray
实例,则返回 true
。
¥Returns true
if the value is a built-in Uint8ClampedArray
instance.
util.types.isUint8ClampedArray(new ArrayBuffer()); // Returns false
util.types.isUint8ClampedArray(new Uint8ClampedArray()); // Returns true
util.types.isUint8ClampedArray(new Float64Array()); // Returns false
util.types.isUint16Array(value)
#
如果值为内置的 Uint16Array
实例,则返回 true
。
¥Returns true
if the value is a built-in Uint16Array
instance.
util.types.isUint16Array(new ArrayBuffer()); // Returns false
util.types.isUint16Array(new Uint16Array()); // Returns true
util.types.isUint16Array(new Float64Array()); // Returns false
util.types.isUint32Array(value)
#
如果值为内置的 Uint32Array
实例,则返回 true
。
¥Returns true
if the value is a built-in Uint32Array
instance.
util.types.isUint32Array(new ArrayBuffer()); // Returns false
util.types.isUint32Array(new Uint32Array()); // Returns true
util.types.isUint32Array(new Float64Array()); // Returns false
util.types.isWeakMap(value)
#
如果值为内置的 WeakMap
实例,则返回 true
。
¥Returns true
if the value is a built-in WeakMap
instance.
util.types.isWeakMap(new WeakMap()); // Returns true
util.types.isWeakSet(value)
#
如果值为内置的 WeakSet
实例,则返回 true
。
¥Returns true
if the value is a built-in WeakSet
instance.
util.types.isWeakSet(new WeakSet()); // Returns true
util.types.isWebAssemblyCompiledModule(value)
#
value instanceof WebAssembly.Module
。¥Stability: 0 - Deprecated: Use value instanceof WebAssembly.Module
instead.
如果值为内置的 WebAssembly.Module
实例,则返回 true
。
¥Returns true
if the value is a built-in WebAssembly.Module
instance.
const module = new WebAssembly.Module(wasmBuffer);
util.types.isWebAssemblyCompiledModule(module); // Returns true
弃用的 API#
¥Deprecated APIs
以下 API 已弃用,不应再使用。应更新现有应用和模块以寻找替代方法。
¥The following APIs are deprecated and should no longer be used. Existing applications and modules should be updated to find alternative approaches.
util._extend(target, source)
#
util._extend()
方法从未打算在内部的 Node.js 模块之外使用。社区无论如何都找到并使用了它。
¥The util._extend()
method was never intended to be used outside of internal
Node.js modules. The community found and used it anyway.
它已被弃用,不应在新代码中使用。JavaScript 通过 Object.assign()
提供了非常相似的内置功能。
¥It is deprecated and should not be used in new code. JavaScript comes with very
similar built-in functionality through Object.assign()
.
util.isArray(object)
#
Array.isArray()
的别名。
¥Alias for Array.isArray()
.
如果给定的 object
是 Array
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is an Array
. Otherwise, returns false
.
const util = require('node:util');
util.isArray([]);
// Returns: true
util.isArray(new Array());
// Returns: true
util.isArray({});
// Returns: false
util.isBoolean(object)
#
typeof value === 'boolean'
。¥Stability: 0 - Deprecated: Use typeof value === 'boolean'
instead.
如果给定的 object
是 Boolean
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a Boolean
. Otherwise, returns false
.
const util = require('node:util');
util.isBoolean(1);
// Returns: false
util.isBoolean(0);
// Returns: false
util.isBoolean(false);
// Returns: true
util.isBuffer(object)
#
如果给定的 object
是 Buffer
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a Buffer
. Otherwise, returns false
.
const util = require('node:util');
util.isBuffer({ length: 0 });
// Returns: false
util.isBuffer([]);
// Returns: false
util.isBuffer(Buffer.from('hello world'));
// Returns: true
util.isDate(object)
#
如果给定的 object
是 Date
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a Date
. Otherwise, returns false
.
const util = require('node:util');
util.isDate(new Date());
// Returns: true
util.isDate(Date());
// false (without 'new' returns a String)
util.isDate({});
// Returns: false
util.isError(object)
#
util.types.isNativeError()
。¥Stability: 0 - Deprecated: Use util.types.isNativeError()
instead.
如果给定的 object
是 Error
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is an Error
. Otherwise, returns
false
.
const util = require('node:util');
util.isError(new Error());
// Returns: true
util.isError(new TypeError());
// Returns: true
util.isError({ name: 'Error', message: 'an error occurred' });
// Returns: false
此方法依赖于 Object.prototype.toString()
行为。当 object
参数操作 @@toStringTag
时,可能会得到错误的结果。
¥This method relies on Object.prototype.toString()
behavior. It is
possible to obtain an incorrect result when the object
argument manipulates
@@toStringTag
.
const util = require('node:util');
const obj = { name: 'Error', message: 'an error occurred' };
util.isError(obj);
// Returns: false
obj[Symbol.toStringTag] = 'Error';
util.isError(obj);
// Returns: true
util.isFunction(object)
#
typeof value === 'function'
。¥Stability: 0 - Deprecated: Use typeof value === 'function'
instead.
如果给定的 object
是 Function
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a Function
. Otherwise, returns
false
.
const util = require('node:util');
function Foo() {}
const Bar = () => {};
util.isFunction({});
// Returns: false
util.isFunction(Foo);
// Returns: true
util.isFunction(Bar);
// Returns: true
util.isNull(object)
#
如果给定的 object
严格为 null
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is strictly null
. Otherwise, returns
false
.
const util = require('node:util');
util.isNull(0);
// Returns: false
util.isNull(undefined);
// Returns: false
util.isNull(null);
// Returns: true
util.isNullOrUndefined(object)
#
value === undefined || value === null
。¥Stability: 0 - Deprecated: Use
value === undefined || value === null
instead.
如果给定的 object
是 null
或 undefined
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is null
or undefined
. Otherwise,
returns false
.
const util = require('node:util');
util.isNullOrUndefined(0);
// Returns: false
util.isNullOrUndefined(undefined);
// Returns: true
util.isNullOrUndefined(null);
// Returns: true
util.isNumber(object)
#
typeof value === 'number'
。¥Stability: 0 - Deprecated: Use typeof value === 'number'
instead.
如果给定的 object
是 Number
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a Number
. Otherwise, returns false
.
const util = require('node:util');
util.isNumber(false);
// Returns: false
util.isNumber(Infinity);
// Returns: true
util.isNumber(0);
// Returns: true
util.isNumber(NaN);
// Returns: true
util.isObject(object)
#
value !== null && typeof value === 'object'
。¥Stability: 0 - Deprecated:
Use value !== null && typeof value === 'object'
instead.
如果给定的 object
严格来说是 Object
而不是 Function
(即使函数是 JavaScript 中的对象),则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is strictly an Object
and not a
Function
(even though functions are objects in JavaScript).
Otherwise, returns false
.
const util = require('node:util');
util.isObject(5);
// Returns: false
util.isObject(null);
// Returns: false
util.isObject({});
// Returns: true
util.isObject(() => {});
// Returns: false
util.isPrimitive(object)
#
(typeof value !== 'object' && typeof value !== 'function') || value === null
。¥Stability: 0 - Deprecated: Use
(typeof value !== 'object' && typeof value !== 'function') || value === null
instead.
如果给定的 object
是原始类型,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a primitive type. Otherwise, returns
false
.
const util = require('node:util');
util.isPrimitive(5);
// Returns: true
util.isPrimitive('foo');
// Returns: true
util.isPrimitive(false);
// Returns: true
util.isPrimitive(null);
// Returns: true
util.isPrimitive(undefined);
// Returns: true
util.isPrimitive({});
// Returns: false
util.isPrimitive(() => {});
// Returns: false
util.isPrimitive(/^$/);
// Returns: false
util.isPrimitive(new Date());
// Returns: false
util.isRegExp(object)
#
¥Stability: 0 - Deprecated
如果给定的 object
是 RegExp
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a RegExp
. Otherwise, returns false
.
const util = require('node:util');
util.isRegExp(/some regexp/);
// Returns: true
util.isRegExp(new RegExp('another regexp'));
// Returns: true
util.isRegExp({});
// Returns: false
util.isString(object)
#
typeof value === 'string'
。¥Stability: 0 - Deprecated: Use typeof value === 'string'
instead.
如果给定的 object
是 string
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a string
. Otherwise, returns false
.
const util = require('node:util');
util.isString('');
// Returns: true
util.isString('foo');
// Returns: true
util.isString(String('foo'));
// Returns: true
util.isString(5);
// Returns: false
util.isSymbol(object)
#
typeof value === 'symbol'
。¥Stability: 0 - Deprecated: Use typeof value === 'symbol'
instead.
如果给定的 object
是 Symbol
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is a Symbol
. Otherwise, returns false
.
const util = require('node:util');
util.isSymbol(5);
// Returns: false
util.isSymbol('foo');
// Returns: false
util.isSymbol(Symbol('foo'));
// Returns: true
util.isUndefined(object)
#
如果给定的 object
是 undefined
,则返回 true
。否则,返回 false
。
¥Returns true
if the given object
is undefined
. Otherwise, returns false
.
const util = require('node:util');
const foo = undefined;
util.isUndefined(5);
// Returns: false
util.isUndefined(foo);
// Returns: true
util.isUndefined(null);
// Returns: false
util.log(string)
#
¥Stability: 0 - Deprecated: Use a third party module instead.
string
<string>
util.log()
方法使用包含的时间戳打印给定的 string
到 stdout
。
¥The util.log()
method prints the given string
to stdout
with an included
timestamp.
const util = require('node:util');
util.log('Timestamped message.');