Util
[Stable: 2 - Stable]
Stable: 2 Stabilität: 2 - Stabil
Quellcode: lib/util.js
Das Modul node:util
unterstützt die Anforderungen der internen Node.js-APIs. Viele der Dienstprogramme sind auch für Anwendungs- und Modulentwickler nützlich. So greifen Sie darauf zu:
const util = require('node:util')
util.callbackify(original)
Hinzugefügt in: v8.2.0
original
<Function> Eineasync
-Funktion- Gibt zurück: <Function> eine Callback-artige Funktion
Nimmt eine async
-Funktion (oder eine Funktion, die ein Promise
zurückgibt) und gibt eine Funktion zurück, die dem Fehler-zuerst-Callback-Stil folgt, d.h. einen (err, value) => ...
-Callback als letztes Argument nimmt. Im Callback ist das erste Argument der Ablehnungsgrund (oder null
, wenn das Promise
aufgelöst wurde), und das zweite Argument ist der aufgelöste Wert.
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)
})
Gibt aus:
hello world
Der Callback wird asynchron ausgeführt und hat eine eingeschränkte Stack-Trace. Wenn der Callback eine Exception wirft, sendet der Prozess ein ['uncaughtException'
]-Ereignis(/api/process#event-uncaughtexception), und wenn es nicht behandelt wird, wird das Programm beendet.
Da null
als erstes Argument eines Callbacks eine besondere Bedeutung hat, wird, wenn eine umschlossene Funktion ein Promise
mit einem Falsy-Wert als Grund ablehnt, der Wert in ein Error
mit dem ursprünglichen Wert in einem Feld namens reason
gespeichert.
function fn() {
return Promise.reject(null)
}
const callbackFunction = util.callbackify(fn)
callbackFunction((err, ret) => {
// Wenn das Promise mit `null` abgelehnt wurde, wird es mit einem Error umschlossen und
// der ursprüngliche Wert in `reason` gespeichert.
err && Object.hasOwn(err, 'reason') && err.reason === null // true
})
util.debuglog(section[, callback])
Hinzugefügt in: v0.11.3
section
<string> Eine Zeichenkette, die den Teil der Anwendung identifiziert, für den diedebuglog
-Funktion erstellt wird.callback
<Funktion> Ein Callback, der beim ersten Aufruf der Protokollierungsfunktion mit einem Funktionsargument aufgerufen wird, das eine optimiertere Protokollierungsfunktion ist.- Gibt zurück: <Funktion> Die Protokollierungsfunktion
Die Methode util.debuglog()
wird verwendet, um eine Funktion zu erstellen, die bedingt Debug-Meldungen nach stderr
schreibt, basierend auf dem Vorhandensein der Umgebungsvariable NODE_DEBUG
. Wenn der Name section
innerhalb des Wertes dieser Umgebungsvariable erscheint, dann arbeitet die zurückgegebene Funktion ähnlich wie console.error()
. Wenn nicht, dann ist die zurückgegebene Funktion eine No-Op.
const util = require('node:util')
const debuglog = util.debuglog('foo')
debuglog('Hallo von foo [%d]', 123)
Wenn dieses Programm mit NODE_DEBUG=foo
in der Umgebung ausgeführt wird, wird etwa Folgendes ausgegeben:
FOO 3245: Hallo von foo [123]
wobei 3245
die Prozess-ID ist. Wenn es nicht mit dieser gesetzten Umgebungsvariable ausgeführt wird, wird nichts ausgegeben.
Der section
unterstützt auch Wildcards:
const util = require('node:util')
const debuglog = util.debuglog('foo-bar')
debuglog('Hallo, es ist foo-bar [%d]', 2333)
Wenn es mit NODE_DEBUG=foo*
in der Umgebung ausgeführt wird, wird etwa Folgendes ausgegeben:
FOO-BAR 3257: Hallo, es ist foo-bar [2333]
In der Umgebungsvariable NODE_DEBUG
können mehrere, durch Komma getrennte section
-Namen angegeben werden: NODE_DEBUG=fs,net,tls
.
Das optionale Argument callback
kann verwendet werden, um die Protokollierungsfunktion durch eine andere Funktion zu ersetzen, die keine Initialisierung oder unnötige Umhüllung hat.
const util = require('node:util')
let debuglog = util.debuglog('internals', debug => {
// Ersetzen durch eine Protokollierungsfunktion, die optimiert
// die Prüfung, ob der Abschnitt aktiviert ist, entfernt
debuglog = debug
})
debuglog().enabled
Hinzugefügt in: v14.9.0
Der Getter util.debuglog().enabled
wird verwendet, um einen Test zu erstellen, der in Bedingungen basierend auf der Existenz der Umgebungsvariablen NODE_DEBUG
verwendet werden kann. Wenn der section
-Name im Wert dieser Umgebungsvariablen vorkommt, ist der zurückgegebene Wert true
. Andernfalls ist der zurückgegebene Wert false
.
const util = require('node:util')
const enabled = util.debuglog('foo').enabled
if (enabled) {
console.log('hallo von foo [%d]', 123)
}
Wenn dieses Programm mit NODE_DEBUG=foo
in der Umgebung ausgeführt wird, wird etwa Folgendes ausgegeben:
hallo von foo [123]
util.debug(section)
Hinzugefügt in: v14.9.0
Alias für util.debuglog
. Die Verwendung ermöglicht eine Lesbarkeit, die kein Logging impliziert, wenn nur util.debuglog().enabled
verwendet wird.
util.deprecate(fn, msg[, code])
[Verlauf]
Version | Änderungen |
---|---|
v10.0.0 | Veraltungswarnungen werden nur einmal für jeden Code ausgegeben. |
v0.8.0 | Hinzugefügt in: v0.8.0 |
fn
<Funktion> Die Funktion, die als veraltet markiert wird.msg
<string> Eine Warnmeldung, die angezeigt wird, wenn die veraltete Funktion aufgerufen wird.code
<string> Ein Veraltungscode. Eine Liste der Codes finden Sie in der Liste der veralteten APIs.- Gibt zurück: <Funktion> Die veraltete Funktion, die umhüllt ist, um eine Warnung auszugeben.
Die Methode util.deprecate()
umhüllt fn
(was eine Funktion oder Klasse sein kann) auf eine Weise, dass sie als veraltet markiert wird.
const util = require('node:util')
exports.obsoleteFunction = util.deprecate(() => {
// Hier etwas tun.
}, 'obsoleteFunction() ist veraltet. Verwenden Sie stattdessen newShinyFunction().')
Wenn util.deprecate()
aufgerufen wird, gibt es eine Funktion zurück, die ein DeprecationWarning
mit dem Ereignis 'warning'
ausgibt. Die Warnung wird ausgegeben und das erste Mal, wenn die zurückgegebene Funktion aufgerufen wird, auf stderr
gedruckt. Nachdem die Warnung ausgegeben wurde, wird die umhüllte Funktion aufgerufen, ohne eine Warnung auszugeben.
Wenn derselbe optionale code
in mehreren Aufrufen von util.deprecate()
angegeben wird, wird die Warnung für diesen code
nur einmal ausgegeben.
const util = require('node:util')
const fn1 = util.deprecate(someFunction, someMessage, 'DEP0001')
const fn2 = util.deprecate(someOtherFunction, someOtherMessage, 'DEP0001')
fn1() // Gibt eine Veraltungswarnung mit dem Code DEP0001 aus
fn2() // Gibt keine Veraltungswarnung aus, da sie denselben Code hat
Wenn entweder die Befehlszeilenflags --no-deprecation
oder --no-warnings
verwendet werden oder die Eigenschaft process.noDeprecation
vor der ersten Veraltungswarnung auf true
gesetzt wird, tut die Methode util.deprecate()
nichts.
Wenn die Befehlszeilenflags --trace-deprecation
oder --trace-warnings
gesetzt sind oder die Eigenschaft process.traceDeprecation
auf true
gesetzt ist, werden eine Warnung und ein Stack-Trace das erste Mal, wenn die veraltete Funktion aufgerufen wird, auf stderr
gedruckt.
Wenn das Befehlszeilenflag --throw-deprecation
gesetzt ist oder die Eigenschaft process.throwDeprecation
auf true
gesetzt ist, wird eine Ausnahme ausgelöst, wenn die veraltete Funktion aufgerufen wird.
Das Befehlszeilenflag --throw-deprecation
und die Eigenschaft process.throwDeprecation
haben Vorrang vor --trace-deprecation
und process.traceDeprecation
.
util.format(format[, ...args])
[Historie]
Version | Änderungen |
---|---|
v12.11.0 | Der %c -Bezeichner wird jetzt ignoriert. |
v12.0.0 | Das format -Argument wird jetzt nur als solches betrachtet, wenn es tatsächlich Formatbezeichner enthält. |
v12.0.0 | Wenn das format -Argument keine Formatzeichenkette ist, hängt die Formatierung der Ausgabestring nicht mehr vom Typ des ersten Arguments ab. Diese Änderung entfernt zuvor vorhandene Anführungszeichen von Strings, die ausgegeben wurden, wenn das erste Argument kein String war. |
v11.4.0 | Die %d -, %f - und %i -Bezeichner unterstützen jetzt Symbole korrekt. |
v11.4.0 | Die Tiefe des %o -Bezeichners hat wieder eine Standardtiefe von 4. |
v11.0.0 | Die depth -Option des %o -Bezeichners wird jetzt auf die Standardtiefe zurückgreifen. |
v10.12.0 | Die %d - und %i -Bezeichner unterstützen jetzt BigInt. |
v8.4.0 | Die %o - und %O -Bezeichner werden jetzt unterstützt. |
v0.5.3 | Hinzugefügt in: v0.5.3 |
format
<string> Eineprintf
-ähnliche Formatzeichenkette.
Die Methode util.format()
gibt eine formatierte Zeichenkette zurück, wobei das erste Argument als printf
-ähnliche Formatzeichenkette verwendet wird, die null oder mehr Formatbezeichner enthalten kann. Jeder Bezeichner wird durch den konvertierten Wert des entsprechenden Arguments ersetzt. Unterstützte Bezeichner sind:
%s
:String
wird verwendet, um alle Werte außerBigInt
,Object
und-0
zu konvertieren.BigInt
-Werte werden mit einemn
dargestellt und Objekte, die keine benutzerdefiniertetoString
-Funktion haben, werden mitutil.inspect()
mit den Optionen{ depth: 0, colors: false, compact: 3 }
untersucht.%d
:Number
wird verwendet, um alle Werte außerBigInt
undSymbol
zu konvertieren.%i
:parseInt(value, 10)
wird für alle Werte außerBigInt
undSymbol
verwendet.%f
:parseFloat(value)
wird für alle Werte außerSymbol
verwendet.%j
: JSON. Wird durch den String'[Circular]'
ersetzt, wenn das Argument zirkuläre Referenzen enthält.%o
:Object
. Eine Stringdarstellung eines Objekts mit generischer JavaScript-Objektformatierung. Ähnlich wieutil.inspect()
mit den Optionen{ showHidden: true, showProxy: true }
. Dies zeigt das vollständige Objekt einschließlich nicht aufzählbarer Eigenschaften und Proxys.%O
:Object
. Eine Stringdarstellung eines Objekts mit generischer JavaScript-Objektformatierung. Ähnlich wieutil.inspect()
ohne Optionen. Dies zeigt das vollständige Objekt ohne nicht aufzählbare Eigenschaften und Proxys.%c
:CSS
. Dieser Bezeichner wird ignoriert und überspringt jegliches übergebenes CSS.%%
: einzelnes Prozentzeichen ('%'
). Dies verbraucht kein Argument.- Gibt zurück: <string> Die formatierte Zeichenkette
Wenn ein Bezeichner kein entsprechendes Argument hat, wird er nicht ersetzt:
util.format('%s:%s', 'foo')
// Gibt zurück: 'foo:%s'
Werte, die nicht Teil der Formatzeichenkette sind, werden mit util.inspect()
formatiert, wenn ihr Typ nicht string
ist.
Wenn der Methode util.format()
mehr Argumente übergeben werden als die Anzahl der Bezeichner, werden die zusätzlichen Argumente durch Leerzeichen getrennt an die zurückgegebene Zeichenkette angehängt:
util.format('%s:%s', 'foo', 'bar', 'baz')
// Gibt zurück: 'foo:bar baz'
Wenn das erste Argument keinen gültigen Formatbezeichner enthält, gibt util.format()
eine Zeichenkette zurück, die die Verkettung aller Argumente getrennt durch Leerzeichen ist:
util.format(1, 2, 3)
// Gibt zurück: '1 2 3'
Wenn nur ein Argument an util.format()
übergeben wird, wird es unverändert ohne Formatierung zurückgegeben:
util.format('%% %s')
// Gibt zurück: '%% %s'
util.format()
ist eine synchrone Methode, die als Debugging-Tool gedacht ist. Einige Eingabewerte können einen erheblichen Leistungsaufwand verursachen, der die Ereignisschleife blockieren kann. Verwenden Sie diese Funktion mit Vorsicht und niemals in einem kritischen Codepfad.
util.formatWithOptions(inspectOptions, format[, ...args])
Hinzugefügt in: v10.0.0
Diese Funktion ist identisch mit util.format()
, außer dass sie ein inspectOptions
-Argument entgegennimmt, das Optionen angibt, die an util.inspect()
weitergegeben werden.
util.formatWithOptions({ colors: true }, 'Siehe Objekt %O', { foo: 42 })
// Gibt 'Siehe Objekt { foo: 42 }' zurück, wobei `42` als Zahl farbig
// dargestellt wird, wenn sie auf einem Terminal ausgegeben wird.
util.getCallSites(frameCountOrOptions, [options])
[Stabil: 1 - Experimentell]
Stabil: 1 Stabilität: 1.1 - Aktive Entwicklung
[Verlauf]
Version | Änderungen |
---|---|
v23.3.0 | Die API wird von util.getCallSite in util.getCallSites() umbenannt. |
v22.9.0 | Hinzugefügt in: v22.9.0 |
frameCount
<number> Optionale Anzahl von Frames, die als Call-Site-Objekte erfasst werden sollen. Standard:10
. Der zulässige Bereich liegt zwischen 1 und 200.options
<Object> OptionalsourceMap
<boolean> Rekonstruiert den ursprünglichen Speicherort im Stacktrace aus der Source-Map. Standardmäßig mit dem Flag--enable-source-maps
aktiviert.
Gibt zurück: <Object[]> Ein Array von Call-Site-Objekten
functionName
<string> Gibt den Namen der Funktion zurück, die dieser Call-Site zugeordnet ist.scriptName
<string> Gibt den Namen der Ressource zurück, die das Skript für die Funktion für diese Call-Site enthält.lineNumber
<number> Gibt die Nummer, beginnend mit 1, der Zeile für den zugehörigen Funktionsaufruf zurück.column
<number> Gibt den 1-basierten Spaltenoffset in der Zeile für den zugehörigen Funktionsaufruf zurück.
Gibt ein Array von Call-Site-Objekten zurück, die den Stack der aufrufenden Funktion enthalten.
const util = require('node:util')
function exampleFunction() {
const callSites = util.getCallSites()
console.log('Call Sites:')
callSites.forEach((callSite, index) => {
console.log(`CallSite ${index + 1}:`)
console.log(`Funktionsname: ${callSite.functionName}`)
console.log(`Skriptname: ${callSite.scriptName}`)
console.log(`Zeilennummer: ${callSite.lineNumber}`)
console.log(`Spaltennummer: ${callSite.column}`)
})
// CallSite 1:
// Funktionsname: exampleFunction
// Skriptname: /home/example.js
// Zeilennummer: 5
// Spaltennummer: 26
// CallSite 2:
// Funktionsname: anotherFunction
// Skriptname: /home/example.js
// Zeilennummer: 22
// Spaltennummer: 3
// ...
}
// Eine Funktion, um eine weitere Stackebene zu simulieren
function anotherFunction() {
exampleFunction()
}
anotherFunction()
Es ist möglich, die ursprünglichen Speicherorte zu rekonstruieren, indem die Option sourceMap
auf true
gesetzt wird. Wenn die Source-Map nicht verfügbar ist, ist der ursprüngliche Speicherort derselbe wie der aktuelle Speicherort. Wenn das Flag --enable-source-maps
aktiviert ist, z. B. bei Verwendung von --experimental-transform-types
, ist sourceMap
standardmäßig true
.
import util from 'node:util'
interface Foo {
foo: string
}
const callSites = util.getCallSites({ sourceMap: true })
// Mit SourceMap:
// Funktionsname: ''
// Skriptname: example.js
// Zeilennummer: 7
// Spaltennummer: 26
// Ohne SourceMap:
// Funktionsname: ''
// Skriptname: example.js
// Zeilennummer: 2
// Spaltennummer: 26
util.getSystemErrorName(err)
Hinzugefügt in: v9.7.0
Gibt den Stringnamen für einen numerischen Fehlercode zurück, der von einer Node.js-API stammt. Die Zuordnung zwischen Fehlercodes und Fehlernamen ist plattformabhängig. Siehe Allgemeine Systemfehler für die Namen allgemeiner Fehler.
fs.access('file/that/does/not/exist', err => {
const name = util.getSystemErrorName(err.errno)
console.error(name) // ENOENT
})
util.getSystemErrorMap()
Hinzugefügt in: v16.0.0, v14.17.0
- Gibt zurück: <Map>
Gibt eine Map aller Systemfehlercodes zurück, die von der Node.js-API verfügbar sind. Die Zuordnung zwischen Fehlercodes und Fehlernamen ist plattformabhängig. Siehe Allgemeine Systemfehler für die Namen allgemeiner Fehler.
fs.access('file/that/does/not/exist', err => {
const errorMap = util.getSystemErrorMap()
const name = errorMap.get(err.errno)
console.error(name) // ENOENT
})
util.getSystemErrorMessage(err)
Hinzugefügt in: v23.1.0
Gibt die Stringmeldung für einen numerischen Fehlercode zurück, der von einer Node.js-API stammt. Die Zuordnung zwischen Fehlercodes und Stringmeldungen ist plattformabhängig.
fs.access('file/that/does/not/exist', err => {
const name = util.getSystemErrorMessage(err.errno)
console.error(name) // No such file or directory
})
util.inherits(constructor, superConstructor)
[Verlauf]
Version | Änderungen |
---|---|
v5.0.0 | Der constructor -Parameter kann sich jetzt auf eine ES6-Klasse beziehen. |
v0.3.0 | Hinzugefügt in: v0.3.0 |
[Stabil: 3 - Legacy]
Stabil: 3 Stabilität: 3 - Legacy: Verwenden Sie stattdessen die ES2015-Klassensyntax und das extends
-Schlüsselwort.
constructor
<Function>superConstructor
<Function>
Die Verwendung von util.inherits()
wird nicht empfohlen. Bitte verwenden Sie die ES6-Schlüsselwörter class
und extends
, um Unterstützung für die Vererbung auf Sprachebene zu erhalten. Beachten Sie auch, dass die beiden Stile semantisch inkompatibel sind.
Vererben Sie die Prototypmethoden von einem Konstruktor in einen anderen. Der Prototyp von constructor
wird auf ein neues Objekt gesetzt, das aus superConstructor
erstellt wurde.
Dies fügt hauptsächlich einige Eingabevalidierungen zusätzlich zu Object.setPrototypeOf(constructor.prototype, superConstructor.prototype)
hinzu. Als zusätzliche Bequemlichkeit ist superConstructor
über die Eigenschaft constructor.super_
zugänglich.
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!"
ES6-Beispiel mit class
und 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]]])
[Verlauf]
Version | Änderungen |
---|---|
v16.18.0 | Unterstützung für maxArrayLength beim Untersuchen von Set und Map hinzugefügt. |
v17.3.0, v16.14.0 | Die Option numericSeparator wird jetzt unterstützt. |
v13.0.0 | Zirkuläre Referenzen enthalten jetzt eine Markierung für die Referenz. |
v14.6.0, v12.19.0 | Wenn object aus einem anderen vm.Context stammt, empfängt eine benutzerdefinierte Inspektionsfunktion dafür keine kontextspezifischen Argumente mehr. |
v13.13.0, v12.17.0 | Die Option maxStringLength wird jetzt unterstützt. |
v13.5.0, v12.16.0 | Benutzerdefinierte Prototyp-Eigenschaften werden untersucht, falls showHidden true ist. |
v12.0.0 | Der Standardwert der Option compact wurde auf 3 geändert und der Standardwert der Option breakLength wurde auf 80 geändert. |
v12.0.0 | Interne Eigenschaften erscheinen nicht mehr im Kontextargument einer benutzerdefinierten Inspektionsfunktion. |
v11.11.0 | Die Option compact akzeptiert Zahlen für einen neuen Ausgabemodus. |
v11.7.0 | ArrayBuffers zeigen jetzt auch ihren binären Inhalt an. |
v11.5.0 | Die Option getters wird jetzt unterstützt. |
v11.4.0 | Der Standardwert für depth wurde wieder auf 2 geändert. |
v11.0.0 | Der Standardwert für depth wurde auf 20 geändert. |
v11.0.0 | Die Inspektionsausgabe ist jetzt auf etwa 128 MiB begrenzt. Daten über dieser Größe werden nicht vollständig inspiziert. |
v10.12.0 | Die Option sorted wird jetzt unterstützt. |
v10.6.0 | Die Inspektion von verketteten Listen und ähnlichen Objekten ist jetzt bis zur maximalen Aufrufstapelgröße möglich. |
v10.0.0 | Die Einträge von WeakMap und WeakSet können jetzt ebenfalls inspiziert werden. |
v9.9.0 | Die Option compact wird jetzt unterstützt. |
v6.6.0 | Benutzerdefinierte Inspektionsfunktionen können jetzt this zurückgeben. |
v6.3.0 | Die Option breakLength wird jetzt unterstützt. |
v6.1.0 | Die Option maxArrayLength wird jetzt unterstützt; insbesondere werden lange Arrays standardmäßig abgeschnitten. |
v6.1.0 | Die Option showProxy wird jetzt unterstützt. |
v0.3.0 | Hinzugefügt in: v0.3.0 |
object
<any> Ein beliebiger JavaScript-Primitiv oder einObject
.options
<Object>showHidden
<boolean> Wenntrue
, werden nicht aufzählbare Symbole und Eigenschaften vonobject
in das formatierte Ergebnis aufgenommen. Einträge vonWeakMap
undWeakSet
werden ebenfalls aufgenommen, ebenso wie benutzerdefinierte Prototyp-Eigenschaften (ausgenommen Methodeneigenschaften). Standard:false
.depth
<number> Gibt die Anzahl der Rekursionen beim Formatieren vonobject
an. Dies ist nützlich, um große Objekte zu untersuchen. Um bis zur maximalen Aufrufstapelgröße zu rekursieren, übergeben SieInfinity
odernull
. Standard:2
.colors
<boolean> Wenntrue
, wird die Ausgabe mit ANSI-Farbcodes formatiert. Farben sind anpassbar. Siehe Anpassen vonutil.inspect
-Farben. Standard:false
.customInspect
<boolean> Wennfalse
, werden[util.inspect.custom](depth, opts, inspect)
-Funktionen nicht aufgerufen. Standard:true
.showProxy
<boolean> Wenntrue
, enthält dieProxy
-Inspektion dietarget
- undhandler
-Objekte. Standard:false
.maxArrayLength
<integer> Gibt die maximale Anzahl von Elementen vonArray
,TypedArray
,Map
,Set
,WeakMap
undWeakSet
an, die beim Formatieren aufgenommen werden sollen. Setzen Sie dies aufnull
oderInfinity
, um alle Elemente anzuzeigen. Setzen Sie dies auf0
oder einen negativen Wert, um keine Elemente anzuzeigen. Standard:100
.maxStringLength
<integer> Gibt die maximale Anzahl von Zeichen an, die beim Formatieren aufgenommen werden sollen. Setzen Sie dies aufnull
oderInfinity
, um alle Elemente anzuzeigen. Setzen Sie dies auf0
oder einen negativen Wert, um keine Zeichen anzuzeigen. Standard:10000
.breakLength
<integer> Die Länge, bei der Eingabewerte auf mehrere Zeilen aufgeteilt werden. Setzen Sie dies aufInfinity
, um die Eingabe als einzelne Zeile zu formatieren (in Kombination mitcompact
, das auftrue
oder eine beliebige Zahl >=1
gesetzt ist). Standard:80
.compact
<boolean> | <integer> Wenn dies auffalse
gesetzt ist, wird jeder Objektschlüssel in einer neuen Zeile angezeigt. Es wird bei neuen Zeilen in Text, der länger alsbreakLength
ist, umgebrochen. Wenn es auf eine Zahl gesetzt ist, werden dien
innersten Elemente auf einer einzigen Zeile zusammengefasst, solange alle Eigenschaften inbreakLength
passen. Kurze Array-Elemente werden ebenfalls zusammengefasst. Weitere Informationen finden Sie im folgenden Beispiel. Standard:3
.sorted
<boolean> | <Function> Wenn dies auftrue
oder eine Funktion gesetzt ist, werden alle Eigenschaften eines Objekts sowieSet
- undMap
-Einträge im resultierenden String sortiert. Wenn dies auftrue
gesetzt ist, wird die Standard-Sortierung verwendet. Wenn dies auf eine Funktion gesetzt ist, wird sie als Vergleichsfunktion verwendet.getters
<boolean> | <string> Wenn dies auftrue
gesetzt ist, werden Getter untersucht. Wenn dies auf'get'
gesetzt ist, werden nur Getter ohne einen entsprechenden Setter untersucht. Wenn dies auf'set'
gesetzt ist, werden nur Getter mit einem entsprechenden Setter untersucht. Dies kann je nach Getter-Funktion zu Seiteneffekten führen. Standard:false
.numericSeparator
<boolean> Wenn dies auftrue
gesetzt ist, wird ein Unterstrich verwendet, um alle drei Ziffern in allen Bigints und Zahlen zu trennen. Standard:false
.
Rückgabe: <string> Die Darstellung von
object
.
Die Methode util.inspect()
gibt eine String-Darstellung von object
zurück, die für das Debuggen gedacht ist. Die Ausgabe von util.inspect
kann sich jederzeit ändern und sollte nicht programmatisch verwendet werden. Es können zusätzliche options
übergeben werden, die das Ergebnis verändern. util.inspect()
verwendet den Namen des Konstruktors und/oder @@toStringTag
, um ein identifizierbares Tag für einen inspizierten Wert zu erstellen.
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] {}'
Zirkuläre Referenzen verweisen mit einem Referenzindex auf ihren Anker:
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] }
// }
Das folgende Beispiel untersucht alle Eigenschaften des util
-Objekts:
const util = require('node:util')
console.log(util.inspect(util, { showHidden: true, depth: null }))
Das folgende Beispiel verdeutlicht die Auswirkung der Option 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 [...]', // Eine lange Zeile
// 'test',
// 'foo' ] ],
// 4 ],
// b: Map(2) { 'za' => 1, 'zb' => 'test' } }
// Wenn `compact` auf false oder eine ganze Zahl gesetzt wird, wird eine lesefreundlichere Ausgabe erzeugt.
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'
// }
// }
// Wenn `breakLength` auf z. B. 150 gesetzt wird, wird der Text "Lorem ipsum" in einer
// einzigen Zeile ausgegeben.
Die Option showHidden
ermöglicht das Untersuchen von WeakMap
- und WeakSet
-Einträgen. Wenn mehr Einträge als maxArrayLength
vorhanden sind, gibt es keine Garantie, welche Einträge angezeigt werden. Das bedeutet, dass das zweimalige Abrufen derselben WeakSet
-Einträge zu unterschiedlichen Ausgaben führen kann. Darüber hinaus können Einträge ohne verbleibende starke Referenzen jederzeit durch die Garbage Collection entfernt werden.
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 } }
Die Option sorted
stellt sicher, dass die Reihenfolge des Einfügens von Eigenschaften eines Objekts das Ergebnis von util.inspect()
nicht beeinflusst.
const { inspect } = require('node:util')
const assert = require('node:assert')
const o1 = {
b: [2, 3, 1],
a: '`a` kommt vor `b`',
c: new Set([2, 3, 1]),
}
console.log(inspect(o1, { sorted: true }))
// { a: '`a` kommt vor `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` kommt vor `b`' }
const o2 = {
c: new Set([2, 1, 3]),
a: '`a` kommt vor `b`',
b: [2, 3, 1],
}
assert.strict.equal(inspect(o1, { sorted: true }), inspect(o2, { sorted: true }))
Die Option numericSeparator
fügt allen Zahlen alle drei Ziffern einen Unterstrich hinzu.
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(inspect(thousand, { numericSeparator: true }))
// 1_000
console.log(inspect(million, { numericSeparator: true }))
// 1_000_000
console.log(inspect(bigNumber, { numericSeparator: true }))
// 123_456_789n
console.log(inspect(bigDecimal, { numericSeparator: true }))
// 1_234.123_45
util.inspect()
ist eine synchrone Methode, die zum Debuggen gedacht ist. Die maximale Ausgabelänge beträgt ca. 128 MiB. Eingaben, die zu einer längeren Ausgabe führen, werden abgeschnitten.
Anpassen der util.inspect
-Farben
Die Farbausgabe (falls aktiviert) von util.inspect
ist global über die Eigenschaften util.inspect.styles
und util.inspect.colors
anpassbar.
util.inspect.styles
ist eine Zuordnung, die einen Stilnamen mit einer Farbe aus util.inspect.colors
verknüpft.
Die Standardstile und zugehörigen Farben sind:
bigint
:yellow
boolean
:yellow
date
:magenta
module
:underline
name
: (keine Formatierung)null
:bold
number
:yellow
regexp
:red
special
:cyan
(z. B.Proxies
)string
:green
symbol
:green
undefined
:grey
Die Farbgestaltung verwendet ANSI-Steuercodes, die möglicherweise nicht von allen Terminals unterstützt werden. Um die Farbsupport zu überprüfen, verwenden Sie tty.hasColors()
.
Vordefinierte Steuercodes sind unten aufgeführt (gruppiert als "Modifizierer", "Vordergrundfarben" und "Hintergrundfarben").
Modifizierer
Die Unterstützung von Modifizierern ist in verschiedenen Terminals unterschiedlich. Sie werden meist ignoriert, wenn sie nicht unterstützt werden.
reset
- Setzt alle (Farb-)Modifizierer auf ihre Standardwerte zurück- bold - Macht Text fett
- italic - Macht Text kursiv
- underline - Macht Text unterstrichen
strikethrough- Zieht eine horizontale Linie durch die Mitte des Textes (Alias:strikeThrough
,crossedout
,crossedOut
)hidden
- Gibt den Text aus, macht ihn aber unsichtbar (Alias: conceal)- dim - Verringerte Farbintensität (Alias:
faint
) - overlined - Macht Text überstrichen
- blink - Verbirgt und zeigt den Text in einem Intervall
- inverse - Tauscht Vorder- und Hintergrundfarben (Alias:
swapcolors
,swapColors
) - doubleunderline - Macht Text doppelt unterstrichen (Alias:
doubleUnderline
) - framed - Zeichnet einen Rahmen um den Text
Vordergrundfarben
black
red
green
yellow
blue
magenta
cyan
white
gray
(Alias:grey
,blackBright
)redBright
greenBright
yellowBright
blueBright
magentaBright
cyanBright
whiteBright
Hintergrundfarben
bgBlack
bgRed
bgGreen
bgYellow
bgBlue
bgMagenta
bgCyan
bgWhite
bgGray
(Alias:bgGrey
,bgBlackBright
)bgRedBright
bgGreenBright
bgYellowBright
bgBlueBright
bgMagentaBright
bgCyanBright
bgWhiteBright
Benutzerdefinierte Inspektionsfunktionen für Objekte
[Historie]
Version | Änderungen |
---|---|
v17.3.0, v16.14.0 | Das Argument inspect wurde für mehr Interoperabilität hinzugefügt. |
v0.1.97 | Hinzugefügt in: v0.1.97 |
Objekte können auch ihre eigene Funktion [util.inspect.custom](depth, opts, inspect)
definieren, die util.inspect()
aufruft und deren Ergebnis bei der Inspektion des Objekts verwendet.
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,
})
// Fünf Leerzeichen Padding, weil das die Größe von "Box< " ist.
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)
// Gibt zurück: "Box< true >"
Benutzerdefinierte [util.inspect.custom](depth, opts, inspect)
Funktionen geben typischerweise einen String zurück, können aber einen Wert von jedem Typ zurückgeben, der von util.inspect()
entsprechend formatiert wird.
const util = require('node:util')
const obj = { foo: 'dies wird in der inspect() Ausgabe nicht angezeigt' }
obj[util.inspect.custom] = depth => {
return { bar: 'baz' }
}
util.inspect(obj)
// Gibt zurück: "{ bar: 'baz' }"
util.inspect.custom
[Historie]
Version | Änderungen |
---|---|
v10.12.0 | Dies ist nun als gemeinsames Symbol definiert. |
v6.6.0 | Hinzugefügt in: v6.6.0 |
- <symbol>, das verwendet werden kann, um benutzerdefinierte Inspektionsfunktionen zu deklarieren.
Zusätzlich dazu, dass dieses Symbol über util.inspect.custom
zugänglich ist, ist es global registriert und kann in jeder Umgebung als Symbol.for('nodejs.util.inspect.custom')
aufgerufen werden.
Die Verwendung dieses Symbols ermöglicht es, Code auf portable Weise zu schreiben, sodass die benutzerdefinierte Inspektionsfunktion in einer Node.js-Umgebung verwendet und im Browser ignoriert wird. Die Funktion util.inspect()
selbst wird als drittes Argument an die benutzerdefinierte Inspektionsfunktion übergeben, um eine weitere Portabilität zu ermöglichen.
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)
// Gibt Password <xxxxxxxx> aus
Weitere Informationen finden Sie unter Benutzerdefinierte Inspektionsfunktionen für Objekte.
util.inspect.defaultOptions
Hinzugefügt in: v6.4.0
Der Wert defaultOptions
ermöglicht die Anpassung der Standardoptionen, die von util.inspect
verwendet werden. Dies ist nützlich für Funktionen wie console.log
oder util.format
, die implizit util.inspect
aufrufen. Er muss auf ein Objekt gesetzt werden, das eine oder mehrere gültige util.inspect()
-Optionen enthält. Das direkte Setzen von Optionen-Eigenschaften wird ebenfalls unterstützt.
const util = require('node:util')
const arr = Array(101).fill(0)
console.log(arr) // Protokolliert das gekürzte Array
util.inspect.defaultOptions.maxArrayLength = null
console.log(arr) // Protokolliert das vollständige Array
util.isDeepStrictEqual(val1, val2)
Hinzugefügt in: v9.0.0
Gibt true
zurück, wenn eine tiefe strikte Gleichheit zwischen val1
und val2
besteht. Andernfalls wird false
zurückgegeben.
Weitere Informationen zur tiefen strikten Gleichheit finden Sie unter assert.deepStrictEqual()
.
Klasse: util.MIMEType
Hinzugefügt in: v19.1.0, v18.13.0
[Stabil: 1 - Experimentell]
Stabil: 1 Stabilität: 1 - Experimentell
Eine Implementierung der MIMEType-Klasse.
In Übereinstimmung mit den Browserkonventionen werden alle Eigenschaften von MIMEType
-Objekten als Getter und Setter auf dem Klassenprototyp implementiert und nicht als Dateneigenschaften auf dem Objekt selbst.
Eine MIME-Zeichenkette ist eine strukturierte Zeichenkette, die mehrere aussagekräftige Komponenten enthält. Wenn sie geparst wird, wird ein MIMEType
-Objekt zurückgegeben, das Eigenschaften für jede dieser Komponenten enthält.
Konstruktor: new MIMEType(input)
input
<string> Die zu parsenden Eingabe-MIME
Erstellt ein neues MIMEType
-Objekt durch Parsen der input
.
import { MIMEType } from 'node:util'
const myMIME = new MIMEType('text/plain')
const { MIMEType } = require('node:util')
const myMIME = new MIMEType('text/plain')
Ein TypeError
wird ausgelöst, wenn die input
keine gültige MIME ist. Beachten Sie, dass versucht wird, die angegebenen Werte in Strings zu konvertieren. Zum Beispiel:
import { MIMEType } from 'node:util'
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// Gibt aus: text/plain
const { MIMEType } = require('node:util')
const myMIME = new MIMEType({ toString: () => 'text/plain' })
console.log(String(myMIME))
// Gibt aus: text/plain
mime.type
Ruft den Typteil des MIME ab und legt ihn fest.
import { MIMEType } from 'node:util'
const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// Gibt aus: text
myMIME.type = 'application'
console.log(myMIME.type)
// Gibt aus: application
console.log(String(myMIME))
// Gibt aus: application/javascript
const { MIMEType } = require('node:util')
const myMIME = new MIMEType('text/javascript')
console.log(myMIME.type)
// Gibt aus: text
myMIME.type = 'application'
console.log(myMIME.type)
// Gibt aus: application
console.log(String(myMIME))
// Gibt aus: application/javascript
mime.subtype
Ruft den Subtyppteil des MIME ab und legt ihn fest.
import { MIMEType } from 'node:util'
const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// Gibt aus: ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// Gibt aus: javascript
console.log(String(myMIME))
// Gibt aus: text/javascript
const { MIMEType } = require('node:util')
const myMIME = new MIMEType('text/ecmascript')
console.log(myMIME.subtype)
// Gibt aus: ecmascript
myMIME.subtype = 'javascript'
console.log(myMIME.subtype)
// Gibt aus: javascript
console.log(String(myMIME))
// Gibt aus: text/javascript
mime.essence
Ruft die Essenz des MIME ab. Diese Eigenschaft ist schreibgeschützt. Verwenden Sie mime.type
oder mime.subtype
, um den MIME zu ändern.
import { MIMEType } from 'node:util'
const myMIME = new MIMEType('text/javascript;key=value')
console.log(myMIME.essence)
// Gibt aus: text/javascript
myMIME.type = 'application'
console.log(myMIME.essence)
// Gibt aus: application/javascript
console.log(String(myMIME))
// Gibt aus: application/javascript;key=value
const { MIMEType } = require('node:util')
const myMIME = new MIMEType('text/javascript;key=value')
console.log(myMIME.essence)
// Gibt aus: text/javascript
myMIME.type = 'application'
console.log(myMIME.essence)
// Gibt aus: application/javascript
console.log(String(myMIME))
// Gibt aus: application/javascript;key=value
mime.params
Ruft das MIMEParams
-Objekt ab, das die Parameter des MIME darstellt. Diese Eigenschaft ist schreibgeschützt. Weitere Informationen finden Sie in der MIMEParams
-Dokumentation.
mime.toString()
- Gibt zurück: <string>
Die toString()
-Methode des MIMEType
-Objekts gibt den serialisierten MIME zurück.
Aufgrund der Notwendigkeit der Standardkonformität erlaubt diese Methode den Benutzern nicht, den Serialisierungsprozess des MIME anzupassen.
mime.toJSON()
- Gibt zurück: <string>
Alias für mime.toString()
.
Diese Methode wird automatisch aufgerufen, wenn ein MIMEType
-Objekt mit JSON.stringify()
serialisiert wird.
import { MIMEType } from 'node:util'
const myMIMES = [new MIMEType('image/png'), new MIMEType('image/gif')]
console.log(JSON.stringify(myMIMES))
// Gibt aus: ["image/png", "image/gif"]
const { MIMEType } = require('node:util')
const myMIMES = [new MIMEType('image/png'), new MIMEType('image/gif')]
console.log(JSON.stringify(myMIMES))
// Gibt aus: ["image/png", "image/gif"]
Klasse: util.MIMEParams
Hinzugefügt in: v19.1.0, v18.13.0
Die MIMEParams
-API bietet Lese- und Schreibzugriff auf die Parameter eines MIMEType
.
Konstruktor: new MIMEParams()
Erstellt ein neues MIMEParams
-Objekt mit leeren Parametern.
import { MIMEParams } from 'node:util'
const myParams = new MIMEParams()
const { MIMEParams } = require('node:util')
const myParams = new MIMEParams()
mimeParams.delete(name)
name
<string>
Entfernt alle Name-Wert-Paare, deren Name name
ist.
mimeParams.entries()
- Gibt zurück: <Iterator>
Gibt einen Iterator über jedes Name-Wert-Paar in den Parametern zurück. Jedes Element des Iterators ist ein JavaScript Array
. Das erste Element des Arrays ist der Name
, das zweite Element des Arrays ist der Wert
.
mimeParams.get(name)
name
<string>- Gibt zurück: <string> | <null> Ein String oder
null
, wenn kein Name-Wert-Paar mit dem gegebenenName
existiert.
Gibt den Wert des ersten Name-Wert-Paares zurück, dessen Name name
ist. Wenn es keine solchen Paare gibt, wird null
zurückgegeben.
mimeParams.has(name)
Gibt true
zurück, wenn es mindestens ein Name-Wert-Paar gibt, dessen Name name
ist.
mimeParams.keys()
- Gibt zurück: <Iterator>
Gibt einen Iterator über die Namen jedes Name-Wert-Paares zurück.
import { MIMEType } from 'node:util'
const { params } = new MIMEType('text/plain;foo=0;bar=1')
for (const name of params.keys()) {
console.log(name)
}
// Gibt aus:
// 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)
}
// Gibt aus:
// foo
// bar
mimeParams.set(name, value)
Setzt den Wert im MIMEParams
-Objekt, das mit name
verknüpft ist, auf value
. Wenn es bereits Name-Wert-Paare gibt, deren Namen name
sind, setze den Wert des ersten solchen Paares auf 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())
// Gibt aus: 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())
// Gibt aus: foo=def;bar=1;baz=xyz
mimeParams.values()
- Gibt zurück: <Iterator>
Gibt einen Iterator über die Werte jedes Name-Wert-Paares zurück.
mimeParams[@@iterator]()
- Gibt zurück: <Iterator>
Alias für 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)
}
// Gibt aus:
// 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)
}
// Gibt aus:
// foo bar
// xyz baz
util.parseArgs([config])
[Verlauf]
Version | Änderungen |
---|---|
v22.4.0, v20.16.0 | Unterstützung für negative Optionen in der Eingabe config hinzugefügt. |
v20.0.0 | Die API ist nicht mehr experimentell. |
v18.11.0, v16.19.0 | Unterstützung für Standardwerte in der Eingabe config hinzugefügt. |
v18.7.0, v16.17.0 | Unterstützung für die Rückgabe detaillierter Parsinformationen mithilfe von tokens in der Eingabe config und zurückgegebenen Eigenschaften hinzugefügt. |
v18.3.0, v16.17.0 | Hinzugefügt in: v18.3.0, v16.17.0 |
config
<Object> Wird verwendet, um Argumente für das Parsen bereitzustellen und den Parser zu konfigurieren.config
unterstützt die folgenden Eigenschaften:args
<string[]> Array von Argument-Strings. Standard:process.argv
mitexecPath
undfilename
entfernt.options
<Object> Wird verwendet, um Argumente zu beschreiben, die dem Parser bekannt sind. Die Schlüssel vonoptions
sind die langen Namen von Optionen und die Werte sind ein <Object>, das die folgenden Eigenschaften akzeptiert:type
<string> Typ des Arguments, der entwederboolean
oderstring
sein muss.multiple
<boolean> Ob diese Option mehrfach angegeben werden kann. Wenntrue
, werden alle Werte in einem Array gesammelt. Wennfalse
, sind die Werte für die Option Last-Wins. Standard:false
.short
<string> Ein einzelnes Zeichen-Alias für die Option.default
<string> | <boolean> | <string[]> | <boolean[]> Der Standardoptionswert, wenn er nicht durch Argumente gesetzt wird. Er muss vom gleichen Typ wie die Eigenschafttype
sein. Wennmultiple
true
ist, muss es ein Array sein.strict
<boolean> Soll ein Fehler ausgelöst werden, wenn unbekannte Argumente angetroffen werden oder wenn Argumente übergeben werden, die nicht mit dem inoptions
konfiguriertentype
übereinstimmen? Standard:true
.allowPositionals
<boolean> Ob dieser Befehl Positionsargumente akzeptiert. Standard:false
, wennstrict
true
ist, andernfallstrue
.allowNegative
<boolean> Wenntrue
, erlaubt es, boolesche Optionen explizit auffalse
zu setzen, indem dem Optionsnamen--no-
vorangestellt wird. Standard:false
.tokens
<boolean> Gibt die geparsten Token zurück. Dies ist nützlich, um das integrierte Verhalten zu erweitern, von zusätzlichen Prüfungen bis hin zur erneuten Verarbeitung der Token auf verschiedene Arten. Standard:false
.
- Gibt zurück: <Object> Die geparsten Befehlszeilenargumente:
values
<Object> Eine Zuordnung von geparsten Optionsnamen mit ihren <string>- oder <boolean>-Werten.positionals
<string[]> Positionsargumente.tokens
<Object[]> | <undefined> Siehe Abschnitt parseArgs-Token. Wird nur zurückgegeben, wennconfig
tokens: true
enthält.
Bietet eine API auf höherer Ebene für das Parsen von Befehlszeilenargumenten als die direkte Interaktion mit process.argv
. Nimmt eine Spezifikation für die erwarteten Argumente entgegen und gibt ein strukturiertes Objekt mit den geparsten Optionen und Positionsargumenten zurück.
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)
// Gibt aus: [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)
// Gibt aus: [Object: null prototype] { foo: true, bar: 'b' } []
parseArgs
tokens
Detaillierte Parsing-Informationen stehen für das Hinzufügen von benutzerdefiniertem Verhalten zur Verfügung, indem tokens: true
in der Konfiguration angegeben wird. Die zurückgegebenen Token haben Eigenschaften, die Folgendes beschreiben:
Alle Token
Options-Token
name
<string> Langer Name der Option.rawName
<string> Wie die Option in args verwendet wird, z. B.-f
von--foo
.value
<string> | <undefined> Optionswert, der in args angegeben ist. Nicht definiert für boolesche Optionen.inlineValue
<boolean> | <undefined> Ob der Optionswert inline angegeben wurde, z. B.--foo=bar
.
Positionale Token
value
<string> Der Wert des positionalen Arguments in args (d. h.args[index]
).
Option-Terminator-Token
Die zurückgegebenen Token sind in der Reihenfolge, in der sie in den Eingabe-Args angetroffen werden. Optionen, die mehr als einmal in Args erscheinen, erzeugen für jede Verwendung ein Token. Kurze Optionsgruppen wie -xy
werden zu einem Token für jede Option erweitert. So erzeugt -xxx
drei Token.
Um beispielsweise Unterstützung für eine negierte Option wie --no-color
hinzuzufügen (die allowNegative
unterstützt, wenn die Option vom Typ boolean
ist), können die zurückgegebenen Token erneut verarbeitet werden, um den Wert zu ändern, der für die negierte Option gespeichert ist.
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 })
// Die Options-Token erneut verarbeiten und die zurückgegebenen Werte überschreiben.
tokens
.filter(token => token.kind === 'option')
.forEach(token => {
if (token.name.startsWith('no-')) {
// foo:false für --no-foo speichern
const positiveName = token.name.slice(3)
values[positiveName] = false
delete values[token.name]
} else {
// Wert erneut speichern, sodass der letzte gewinnt, wenn sowohl --foo als auch --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 })
// Die Options-Token erneut verarbeiten und die zurückgegebenen Werte überschreiben.
tokens
.filter(token => token.kind === 'option')
.forEach(token => {
if (token.name.startsWith('no-')) {
// foo:false für --no-foo speichern
const positiveName = token.name.slice(3)
values[positiveName] = false
delete values[token.name]
} else {
// Wert erneut speichern, sodass der letzte gewinnt, wenn sowohl --foo als auch --no-foo.
values[token.name] = token.value ?? true
}
})
const color = values.color
const logfile = values.logfile ?? 'default.log'
console.log({ logfile, color })
Beispielhafte Verwendung, die negierte Optionen zeigt und wann eine Option auf mehrere Arten verwendet wird, dann gewinnt die letzte.
$ 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.parseEnv(content)
Hinzugefügt in: v21.7.0, v20.12.0
content
<string>
Der Rohinhalt einer .env
-Datei.
- Gibt zurück: <Object>
Gegeben eine Beispiel .env
-Datei:
const { parseEnv } = require('node:util')
parseEnv('HELLO=world\nHELLO=oh my\n')
// Gibt zurück: { HELLO: 'oh my' }
import { parseEnv } from 'node:util'
parseEnv('HELLO=world\nHELLO=oh my\n')
// Gibt zurück: { HELLO: 'oh my' }
util.promisify(original)
[Geschichte]
Version | Änderungen |
---|---|
v20.8.0 | Das Aufrufen von promisify für eine Funktion, die eine Promise zurückgibt, ist veraltet. |
v8.0.0 | Hinzugefügt in: v8.0.0 |
original
<Function>- Gibt zurück: <Function>
Nimmt eine Funktion, die dem üblichen Fehler-First-Callback-Stil folgt, d.h. ein (err, value) => ...
-Callback als letztes Argument nimmt, und gibt eine Version zurück, die Promises zurückgibt.
const util = require('node:util')
const fs = require('node:fs')
const stat = util.promisify(fs.stat)
stat('.')
.then(stats => {
// Tue etwas mit `stats`
})
.catch(error => {
// Behandle den Fehler.
})
Oder, äquivalent mit 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(`Dieses Verzeichnis gehört ${stats.uid}`)
}
callStat()
Wenn eine original[util.promisify.custom]
-Eigenschaft vorhanden ist, gibt promisify
ihren Wert zurück, siehe Benutzerdefinierte promisifizierte Funktionen.
promisify()
geht davon aus, dass original
in allen Fällen eine Funktion ist, die einen Callback als letztes Argument nimmt. Wenn original
keine Funktion ist, wirft promisify()
einen Fehler. Wenn original
eine Funktion ist, aber ihr letztes Argument kein Fehler-First-Callback ist, wird ihr trotzdem ein Fehler-First-Callback als letztes Argument übergeben.
Die Verwendung von promisify()
auf Klassenmethoden oder anderen Methoden, die this
verwenden, funktioniert möglicherweise nicht wie erwartet, es sei denn, sie werden speziell behandelt:
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'
Benutzerdefinierte promisifizierte Funktionen
Mit dem Symbol util.promisify.custom
kann der Rückgabewert von util.promisify()
überschrieben werden:
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])
// gibt 'true' aus
Dies kann in Fällen nützlich sein, in denen die ursprüngliche Funktion nicht dem Standardformat entspricht, das eine Fehler-First-Callback-Funktion als letztes Argument verwendet.
Zum Beispiel mit einer Funktion, die (foo, onSuccessCallback, onErrorCallback)
verwendet:
doSomething[util.promisify.custom] = foo => {
return new Promise((resolve, reject) => {
doSomething(foo, resolve, reject)
})
}
Wenn promisify.custom
definiert, aber keine Funktion ist, wirft promisify()
einen Fehler.
util.promisify.custom
[Verlauf]
Version | Änderungen |
---|---|
v13.12.0, v12.16.2 | Dies ist nun als gemeinsames Symbol definiert. |
v8.0.0 | Hinzugefügt in: v8.0.0 |
- <Symbol>, das verwendet werden kann, um benutzerdefinierte promisifizierte Varianten von Funktionen zu deklarieren, siehe Benutzerdefinierte promisifizierte Funktionen.
Dieses Symbol ist nicht nur über util.promisify.custom
zugänglich, sondern auch global registriert und kann in jeder Umgebung als Symbol.for('nodejs.util.promisify.custom')
aufgerufen werden.
Zum Beispiel mit einer Funktion, die (foo, onSuccessCallback, onErrorCallback)
verwendet:
const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom')
doSomething[kCustomPromisifiedSymbol] = foo => {
return new Promise((resolve, reject) => {
doSomething(foo, resolve, reject)
})
}
util.stripVTControlCharacters(str)
Hinzugefügt in: v16.11.0
Gibt str
zurück, wobei alle ANSI-Escape-Codes entfernt wurden.
console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'))
// Gibt "value" aus
util.styleText(format, text[, options])
[Stabil: 2 - Stabil]
Stabil: 2 Stabilität: 2 - Stabil.
[Verlauf]
Version | Änderungen |
---|---|
v23.5.0 | styleText ist jetzt stabil. |
v22.8.0, v20.18.0 | Berücksichtigt isTTY und Umgebungsvariablen wie NO_COLORS, NODE_DISABLE_COLORS und FORCE_COLOR. |
v21.7.0, v20.12.0 | Hinzugefügt in: v21.7.0, v20.12.0 |
format
<string> | <Array> Ein Textformat oder ein Array von Textformaten, die inutil.inspect.colors
definiert sind.text
<string> Der zu formatierende Text.options
<Object>
Diese Funktion gibt einen formatierten Text unter Berücksichtigung des übergebenen format
für die Ausgabe in einem Terminal zurück. Sie ist sich der Fähigkeiten des Terminals bewusst und verhält sich gemäß der Konfiguration, die über die Umgebungsvariablen NO_COLORS
, NODE_DISABLE_COLORS
und FORCE_COLOR
festgelegt wurde.
import { styleText } from 'node:util'
import { stderr } from 'node:process'
const successMessage = styleText('green', 'Erfolg!')
console.log(successMessage)
const errorMessage = styleText(
'red',
'Fehler! Fehler!',
// Prüfen, ob process.stderr TTY hat
{ stream: stderr }
)
console.error(successMessage)
const { styleText } = require('node:util')
const { stderr } = require('node:process')
const successMessage = styleText('green', 'Erfolg!')
console.log(successMessage)
const errorMessage = styleText(
'red',
'Fehler! Fehler!',
// Prüfen, ob process.stderr TTY hat
{ stream: stderr }
)
console.error(successMessage)
util.inspect.colors
bietet auch Textformate wie italic
und underline
an und Sie können beide kombinieren:
console.log(util.styleText(['underline', 'italic'], 'Meine kursive unterstrichene Nachricht'))
Wenn ein Array von Formaten übergeben wird, wird die Reihenfolge der angewendeten Formate von links nach rechts festgelegt, sodass der folgende Stil den vorherigen überschreiben kann.
console.log(
util.styleText(['red', 'green'], 'text') // grün
)
Die vollständige Liste der Formate finden Sie unter Modifikatoren.
Klasse: util.TextDecoder
[Verlauf]
Version | Änderungen |
---|---|
v11.0.0 | Die Klasse ist nun im globalen Objekt verfügbar. |
v8.3.0 | Hinzugefügt in: v8.3.0 |
Eine Implementierung der WHATWG Encoding Standard TextDecoder
API.
const decoder = new TextDecoder()
const u8arr = new Uint8Array([72, 101, 108, 108, 111])
console.log(decoder.decode(u8arr)) // Hello
Von WHATWG unterstützte Kodierungen
Gemäß dem WHATWG Encoding Standard sind die von der TextDecoder
API unterstützten Kodierungen in den nachstehenden Tabellen aufgeführt. Für jede Kodierung können ein oder mehrere Aliase verwendet werden.
Verschiedene Node.js-Build-Konfigurationen unterstützen unterschiedliche Sätze von Kodierungen. (siehe Internationalisierung)
Standardmäßig unterstützte Kodierungen (mit vollständigen ICU-Daten)
Kodierung | Aliase |
---|---|
'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' |
Kodierungen, die unterstützt werden, wenn Node.js mit der Option small-icu
gebaut wird
Kodierung | Aliase |
---|---|
'utf-8' | 'unicode-1-1-utf-8' , 'utf8' |
'utf-16le' | 'utf-16' |
'utf-16be' |
Kodierungen, die unterstützt werden, wenn ICU deaktiviert ist
Kodierung | Aliase |
---|---|
'utf-8' | 'unicode-1-1-utf-8' , 'utf8' |
'utf-16le' | 'utf-16' |
Die im WHATWG-Kodierungsstandard aufgeführte Kodierung 'iso-8859-16'
wird nicht unterstützt.
new TextDecoder([encoding[, options]])
encoding
<string> Identifiziert dieencoding
, die dieseTextDecoder
-Instanz unterstützt. Standard:'utf-8'
.options
<Object>fatal
<boolean>true
, wenn Dekodierungsfehler schwerwiegend sind. Diese Option wird nicht unterstützt, wenn ICU deaktiviert ist (siehe Internationalisierung). Standard:false
.ignoreBOM
<boolean> Wenntrue
, enthält derTextDecoder
die Byte-Order-Markierung im dekodierten Ergebnis. Wennfalse
, wird die Byte-Order-Markierung aus der Ausgabe entfernt. Diese Option wird nur verwendet, wennencoding
'utf-8'
,'utf-16be'
oder'utf-16le'
ist. Standard:false
.
Erstellt eine neue TextDecoder
-Instanz. Die encoding
kann eine der unterstützten Kodierungen oder einen Alias angeben.
Die TextDecoder
-Klasse ist auch im globalen Objekt verfügbar.
textDecoder.decode([input[, options]])
input
<ArrayBuffer> | <DataView> | <TypedArray> EineArrayBuffer
-,DataView
- oderTypedArray
-Instanz, die die kodierten Daten enthält.options
<Object>stream
<boolean>true
, wenn zusätzliche Datenblöcke erwartet werden. Standard:false
.
Gibt zurück: <string>
Dekodiert die input
und gibt einen String zurück. Wenn options.stream
true
ist, werden alle unvollständigen Byte-Sequenzen, die am Ende der input
auftreten, intern gepuffert und nach dem nächsten Aufruf von textDecoder.decode()
ausgegeben.
Wenn textDecoder.fatal
true
ist, führen auftretende Dekodierungsfehler dazu, dass ein TypeError
ausgelöst wird.
textDecoder.encoding
Die von der TextDecoder
-Instanz unterstützte Kodierung.
textDecoder.fatal
Der Wert ist true
, wenn Dekodierungsfehler dazu führen, dass ein TypeError
ausgelöst wird.
textDecoder.ignoreBOM
Der Wert ist true
, wenn das Dekodierungsergebnis die Byte Order Mark enthält.
Klasse: util.TextEncoder
[Verlauf]
Version | Änderungen |
---|---|
v11.0.0 | Die Klasse ist jetzt im globalen Objekt verfügbar. |
v8.3.0 | Hinzugefügt in: v8.3.0 |
Eine Implementierung der WHATWG Encoding Standard TextEncoder
API. Alle Instanzen von TextEncoder
unterstützen nur die UTF-8-Kodierung.
const encoder = new TextEncoder()
const uint8array = encoder.encode('this is some data')
Die TextEncoder
-Klasse ist auch im globalen Objekt verfügbar.
textEncoder.encode([input])
input
<string> Der zu kodierende Text. Standard: eine leere Zeichenkette.- Gibt zurück: <Uint8Array>
UTF-8-kodiert die input
-Zeichenkette und gibt ein Uint8Array
mit den kodierten Bytes zurück.
textEncoder.encodeInto(src, dest)
Hinzugefügt in: v12.11.0
src
<string> Der zu kodierende Text.dest
<Uint8Array> Das Array zur Aufnahme des Kodierungsergebnisses.- Gibt zurück: <Object>
UTF-8-kodiert die src
-Zeichenkette in das dest
Uint8Array und gibt ein Objekt mit den gelesenen Unicode-Codeeinheiten und den geschriebenen UTF-8-Bytes zurück.
const encoder = new TextEncoder()
const src = 'this is some data'
const dest = new Uint8Array(10)
const { read, written } = encoder.encodeInto(src, dest)
textEncoder.encoding
Die von der TextEncoder
-Instanz unterstützte Kodierung. Immer auf 'utf-8'
gesetzt.
util.toUSVString(string)
Hinzugefügt in: v16.8.0, v14.18.0
string
<string>
Gibt den string
zurück, nachdem alle Ersatzcodepunkte (oder gleichwertig alle ungepaarten Ersatzcodeeinheiten) durch das Unicode "Ersatzzeichen" U+FFFD ersetzt wurden.
util.transferableAbortController()
Hinzugefügt in: v18.11.0
[Stabil: 1 - Experimentell]
Stabil: 1 Stabilität: 1 - Experimentell
Erstellt und gibt eine <AbortController>-Instanz zurück, deren <AbortSignal> als übertragbar markiert ist und mit structuredClone()
oder postMessage()
verwendet werden kann.
util.transferableAbortSignal(signal)
Hinzugefügt in: v18.11.0
[Stabil: 1 - Experimentell]
Stabil: 1 Stabilität: 1 - Experimentell
signal
<AbortSignal>- Gibt zurück: <AbortSignal>
Markiert das angegebene <AbortSignal> als übertragbar, sodass es mit structuredClone()
und postMessage()
verwendet werden kann.
const signal = transferableAbortSignal(AbortSignal.timeout(100))
const channel = new MessageChannel()
channel.port2.postMessage(signal, [signal])
util.aborted(signal, resource)
Hinzugefügt in: v19.7.0, v18.16.0
[Stabil: 1 - Experimentell]
Stabil: 1 Stabilität: 1 - Experimentell
signal
<AbortSignal>resource
<Object> Ein beliebiges nicht-null-Objekt, das an die abbrechbare Operation gebunden und schwach gehalten wird. Wennresource
vom Garbage Collector erfasst wird, bevorsignal
abbricht, bleibt das Promise ausstehend, wodurch Node.js die Verfolgung beenden kann. Dies hilft, Speicherlecks bei lang andauernden oder nicht abbrechbaren Operationen zu verhindern.- Gibt zurück: <Promise>
Lauscht auf das Abort-Ereignis des bereitgestellten signal
und gibt ein Promise zurück, das aufgelöst wird, wenn das signal
abgebrochen wird. Wenn resource
bereitgestellt wird, referenziert es schwach das zugehörige Objekt der Operation. Wenn resource
vom Garbage Collector erfasst wird, bevor das signal
abbricht, bleibt das zurückgegebene Promise ausstehend. Dies verhindert Speicherlecks bei lang andauernden oder nicht abbrechbaren Operationen.
const { aborted } = require('node:util')
// Rufe ein Objekt mit einem abbrechbaren Signal ab, wie eine benutzerdefinierte Ressource oder Operation.
const dependent = obtainSomethingAbortable()
// Übergebe `dependent` als Ressource, die angibt, dass das Promise nur aufgelöst werden soll,
// wenn `dependent` noch im Speicher ist, wenn das Signal abgebrochen wird.
aborted(dependent.signal, dependent).then(() => {
// Dieser Code wird ausgeführt, wenn `dependent` abgebrochen wird.
console.log('Die abhängige Ressource wurde abgebrochen.')
})
// Simuliere ein Ereignis, das den Abbruch auslöst.
dependent.on('event', () => {
dependent.abort() // Dies führt dazu, dass das `aborted`-Promise aufgelöst wird.
})
import { aborted } from 'node:util'
// Rufe ein Objekt mit einem abbrechbaren Signal ab, wie eine benutzerdefinierte Ressource oder Operation.
const dependent = obtainSomethingAbortable()
// Übergebe `dependent` als Ressource, die angibt, dass das Promise nur aufgelöst werden soll,
// wenn `dependent` noch im Speicher ist, wenn das Signal abgebrochen wird.
aborted(dependent.signal, dependent).then(() => {
// Dieser Code wird ausgeführt, wenn `dependent` abgebrochen wird.
console.log('Die abhängige Ressource wurde abgebrochen.')
})
// Simuliere ein Ereignis, das den Abbruch auslöst.
dependent.on('event', () => {
dependent.abort() // Dies führt dazu, dass das `aborted`-Promise aufgelöst wird.
})
util.types
[Historie]
Version | Änderungen |
---|---|
v15.3.0 | Als require('util/types') verfügbar gemacht. |
v10.0.0 | Hinzugefügt in: v10.0.0 |
util.types
bietet Typüberprüfungen für verschiedene Arten von integrierten Objekten. Im Gegensatz zu instanceof
oder Object.prototype.toString.call(value)
untersuchen diese Überprüfungen nicht die Eigenschaften des Objekts, die von JavaScript aus zugänglich sind (wie z. B. dessen Prototyp), und haben normalerweise den Overhead, in C++ aufzurufen.
Das Ergebnis macht im Allgemeinen keine Zusicherungen darüber, welche Arten von Eigenschaften oder Verhaltensweisen ein Wert in JavaScript aufweist. Sie sind hauptsächlich für Add-on-Entwickler nützlich, die Typüberprüfungen lieber in JavaScript durchführen möchten.
Die API ist über require('node:util').types
oder require('node:util/types')
zugänglich.
util.types.isAnyArrayBuffer(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine integrierte ArrayBuffer
oder SharedArrayBuffer
-Instanz ist.
Siehe auch util.types.isArrayBuffer()
und util.types.isSharedArrayBuffer()
.
util.types.isAnyArrayBuffer(new ArrayBuffer()) // Gibt true zurück
util.types.isAnyArrayBuffer(new SharedArrayBuffer()) // Gibt true zurück
util.types.isArrayBufferView(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine Instanz einer der ArrayBuffer
-Ansichten ist, wie z. B. typisierte Array-Objekte oder DataView
. Entspricht 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)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert ein arguments
-Objekt ist.
function foo() {
util.types.isArgumentsObject(arguments) // Gibt true zurück
}
util.types.isArrayBuffer(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute ArrayBuffer
-Instanz ist. Dies schließt nicht SharedArrayBuffer
-Instanzen ein. In der Regel ist es wünschenswert, beides zu testen; siehe util.types.isAnyArrayBuffer()
dafür.
util.types.isArrayBuffer(new ArrayBuffer()) // Gibt true zurück
util.types.isArrayBuffer(new SharedArrayBuffer()) // Gibt false zurück
util.types.isAsyncFunction(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine async function ist. Dies gibt nur das zurück, was die JavaScript-Engine sieht; insbesondere kann der Rückgabewert nicht mit dem ursprünglichen Quellcode übereinstimmen, wenn ein Transpilationswerkzeug verwendet wurde.
util.types.isAsyncFunction(function foo() {}) // Gibt false zurück
util.types.isAsyncFunction(async function foo() {}) // Gibt true zurück
util.types.isBigInt64Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine BigInt64Array
-Instanz ist.
util.types.isBigInt64Array(new BigInt64Array()) // Gibt true zurück
util.types.isBigInt64Array(new BigUint64Array()) // Gibt false zurück
util.types.isBigIntObject(value)
Hinzugefügt in: v10.4.0
Gibt true
zurück, wenn der Wert ein BigInt-Objekt ist, z. B. erstellt durch Object(BigInt(123))
.
util.types.isBigIntObject(Object(BigInt(123))) // Gibt true zurück
util.types.isBigIntObject(BigInt(123)) // Gibt false zurück
util.types.isBigIntObject(123) // Gibt false zurück
util.types.isBigUint64Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine BigUint64Array
-Instanz ist.
util.types.isBigUint64Array(new BigInt64Array()) // Gibt false zurück
util.types.isBigUint64Array(new BigUint64Array()) // Gibt true zurück
util.types.isBooleanObject(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert ein Boolesches Objekt ist, z. B. erstellt durch new Boolean()
.
util.types.isBooleanObject(false) // Gibt false zurück
util.types.isBooleanObject(true) // Gibt false zurück
util.types.isBooleanObject(new Boolean(false)) // Gibt true zurück
util.types.isBooleanObject(new Boolean(true)) // Gibt true zurück
util.types.isBooleanObject(Boolean(false)) // Gibt false zurück
util.types.isBooleanObject(Boolean(true)) // Gibt false zurück
util.types.isBoxedPrimitive(value)
Hinzugefügt in: v10.11.0
Gibt true
zurück, wenn der Wert ein beliebiger gepackter primitiver Objekt ist, z. B. erstellt durch new Boolean()
, new String()
oder Object(Symbol())
.
Zum Beispiel:
util.types.isBoxedPrimitive(false) // Gibt false zurück
util.types.isBoxedPrimitive(new Boolean(false)) // Gibt true zurück
util.types.isBoxedPrimitive(Symbol('foo')) // Gibt false zurück
util.types.isBoxedPrimitive(Object(Symbol('foo'))) // Gibt true zurück
util.types.isBoxedPrimitive(Object(BigInt(5))) // Gibt true zurück
util.types.isCryptoKey(value)
Hinzugefügt in: v16.2.0
Gibt true
zurück, wenn value
ein <CryptoKey> ist, andernfalls false
.
util.types.isDataView(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute DataView
-Instanz ist.
const ab = new ArrayBuffer(20)
util.types.isDataView(new DataView(ab)) // Gibt true zurück
util.types.isDataView(new Float64Array()) // Gibt false zurück
Siehe auch ArrayBuffer.isView()
.
util.types.isDate(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute Date
-Instanz ist.
util.types.isDate(new Date()) // Gibt true zurück
util.types.isExternal(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert ein nativer External
-Wert ist.
Ein nativer External
-Wert ist ein spezieller Objekttyp, der einen rohen C++-Zeiger (void*
) für den Zugriff aus nativem Code enthält und keine anderen Eigenschaften besitzt. Solche Objekte werden entweder von Node.js-Interna oder nativen Add-ons erstellt. In JavaScript sind sie eingefrorene Objekte mit einem null
-Prototyp.
#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) // gibt true zurück
util.types.isExternal(0) // gibt false zurück
util.types.isExternal(new String('foo')) // gibt false zurück
Weitere Informationen zu napi_create_external
finden Sie unter napi_create_external()
.
util.types.isFloat32Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine integrierte Float32Array
-Instanz ist.
util.types.isFloat32Array(new ArrayBuffer()) // Gibt false zurück
util.types.isFloat32Array(new Float32Array()) // Gibt true zurück
util.types.isFloat32Array(new Float64Array()) // Gibt false zurück
util.types.isFloat64Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute Float64Array
-Instanz ist.
util.types.isFloat64Array(new ArrayBuffer()) // Gibt false zurück
util.types.isFloat64Array(new Uint8Array()) // Gibt false zurück
util.types.isFloat64Array(new Float64Array()) // Gibt true zurück
util.types.isGeneratorFunction(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine Generatorfunktion ist. Dies gibt nur zurück, was die JavaScript-Engine sieht; insbesondere kann der Rückgabewert nicht mit dem ursprünglichen Quellcode übereinstimmen, wenn ein Transpilationswerkzeug verwendet wurde.
util.types.isGeneratorFunction(function foo() {}) // Gibt false zurück
util.types.isGeneratorFunction(function* foo() {}) // Gibt true zurück
util.types.isGeneratorObject(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert ein Generatorobjekt ist, wie von einer eingebauten Generatorfunktion zurückgegeben. Dies gibt nur zurück, was die JavaScript-Engine sieht; insbesondere kann der Rückgabewert nicht mit dem ursprünglichen Quellcode übereinstimmen, wenn ein Transpilationswerkzeug verwendet wurde.
function* foo() {}
const generator = foo()
util.types.isGeneratorObject(generator) // Gibt true zurück
util.types.isInt8Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute Int8Array
-Instanz ist.
util.types.isInt8Array(new ArrayBuffer()) // Gibt false zurück
util.types.isInt8Array(new Int8Array()) // Gibt true zurück
util.types.isInt8Array(new Float64Array()) // Gibt false zurück
util.types.isInt16Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine integrierte Int16Array
-Instanz ist.
util.types.isInt16Array(new ArrayBuffer()) // Gibt false zurück
util.types.isInt16Array(new Int16Array()) // Gibt true zurück
util.types.isInt16Array(new Float64Array()) // Gibt false zurück
util.types.isInt32Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine integrierte Int32Array
-Instanz ist.
util.types.isInt32Array(new ArrayBuffer()) // Gibt false zurück
util.types.isInt32Array(new Int32Array()) // Gibt true zurück
util.types.isInt32Array(new Float64Array()) // Gibt false zurück
util.types.isKeyObject(value)
Hinzugefügt in: v16.2.0
Gibt true
zurück, wenn value
ein <KeyObject> ist, andernfalls false
.
util.types.isMap(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine integrierte Map
-Instanz ist.
util.types.isMap(new Map()) // Gibt true zurück
util.types.isMapIterator(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert ein Iterator ist, der für eine integrierte Map
-Instanz zurückgegeben wurde.
const map = new Map()
util.types.isMapIterator(map.keys()) // Gibt true zurück
util.types.isMapIterator(map.values()) // Gibt true zurück
util.types.isMapIterator(map.entries()) // Gibt true zurück
util.types.isMapIterator(map[Symbol.iterator]()) // Gibt true zurück
util.types.isModuleNamespaceObject(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine Instanz eines Modul-Namespace-Objekts ist.
import * as ns from './a.js'
util.types.isModuleNamespaceObject(ns) // Gibt true zurück
util.types.isNativeError(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert vom Konstruktor eines integrierten Error
-Typs zurückgegeben wurde.
console.log(util.types.isNativeError(new Error())) // true
console.log(util.types.isNativeError(new TypeError())) // true
console.log(util.types.isNativeError(new RangeError())) // true
Subklassen der nativen Fehlertypen sind ebenfalls native Fehler:
class MyError extends Error {}
console.log(util.types.isNativeError(new MyError())) // true
Ein Wert, der instanceof
einer nativen Fehlerklasse ist, ist nicht gleichbedeutend damit, dass isNativeError()
für diesen Wert true
zurückgibt. isNativeError()
gibt true
für Fehler zurück, die aus einem anderen Realm stammen, während instanceof Error
für diese Fehler false
zurückgibt:
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
Umgekehrt gibt isNativeError()
für alle Objekte false
zurück, die nicht vom Konstruktor eines nativen Fehlers zurückgegeben wurden. Das schließt Werte ein, die instanceof
native Fehler sind:
const myError = { __proto__: Error.prototype }
console.log(util.types.isNativeError(myError)) // false
console.log(myError instanceof Error) // true
util.types.isNumberObject(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert ein Zahlenobjekt ist, z. B. erstellt mit new Number()
.
util.types.isNumberObject(0) // Gibt false zurück
util.types.isNumberObject(new Number(0)) // Gibt true zurück
util.types.isPromise(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert ein eingebautes Promise
ist.
util.types.isPromise(Promise.resolve(42)) // Gibt true zurück
util.types.isProxy(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert eine Proxy
-Instanz ist.
const target = {}
const proxy = new Proxy(target, {})
util.types.isProxy(target) // Gibt false zurück
util.types.isProxy(proxy) // Gibt true zurück
util.types.isRegExp(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert ein reguläres Ausdrucksobjekt ist.
util.types.isRegExp(/abc/) // Gibt true zurück
util.types.isRegExp(new RegExp('abc')) // Gibt true zurück
util.types.isSet(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute Set
-Instanz ist.
util.types.isSet(new Set()) // Gibt true zurück
util.types.isSetIterator(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert ein Iterator ist, der für eine eingebaute Set
-Instanz zurückgegeben wird.
const set = new Set()
util.types.isSetIterator(set.keys()) // Gibt true zurück
util.types.isSetIterator(set.values()) // Gibt true zurück
util.types.isSetIterator(set.entries()) // Gibt true zurück
util.types.isSetIterator(set[Symbol.iterator]()) // Gibt true zurück
util.types.isSharedArrayBuffer(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute SharedArrayBuffer
-Instanz ist. Dies schließt nicht ArrayBuffer
-Instanzen ein. Normalerweise ist es wünschenswert, auf beides zu testen; Siehe util.types.isAnyArrayBuffer()
dafür.
util.types.isSharedArrayBuffer(new ArrayBuffer()) // Gibt false zurück
util.types.isSharedArrayBuffer(new SharedArrayBuffer()) // Gibt true zurück
util.types.isStringObject(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert ein String-Objekt ist, z. B. erstellt durch new String()
.
util.types.isStringObject('foo') // Gibt false zurück
util.types.isStringObject(new String('foo')) // Gibt true zurück
util.types.isSymbolObject(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert ein Symbolobjekt ist, das durch Aufrufen von Object()
auf einem Symbol
-Primitiv erstellt wurde.
const symbol = Symbol('foo')
util.types.isSymbolObject(symbol) // Gibt false zurück
util.types.isSymbolObject(Object(symbol)) // Gibt true zurück
util.types.isTypedArray(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert eine eingebaute TypedArray
-Instanz ist.
util.types.isTypedArray(new ArrayBuffer()) // Gibt false zurück
util.types.isTypedArray(new Uint8Array()) // Gibt true zurück
util.types.isTypedArray(new Float64Array()) // Gibt true zurück
Siehe auch ArrayBuffer.isView()
.
util.types.isUint8Array(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert eine eingebaute Uint8Array
-Instanz ist.
util.types.isUint8Array(new ArrayBuffer()) // Gibt false zurück
util.types.isUint8Array(new Uint8Array()) // Gibt true zurück
util.types.isUint8Array(new Float64Array()) // Gibt false zurück
util.types.isUint8ClampedArray(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute Uint8ClampedArray
-Instanz ist.
util.types.isUint8ClampedArray(new ArrayBuffer()) // Gibt false zurück
util.types.isUint8ClampedArray(new Uint8ClampedArray()) // Gibt true zurück
util.types.isUint8ClampedArray(new Float64Array()) // Gibt false zurück
util.types.isUint16Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute Uint16Array
-Instanz ist.
util.types.isUint16Array(new ArrayBuffer()) // Gibt false zurück
util.types.isUint16Array(new Uint16Array()) // Gibt true zurück
util.types.isUint16Array(new Float64Array()) // Gibt false zurück
util.types.isUint32Array(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute Uint32Array
-Instanz ist.
util.types.isUint32Array(new ArrayBuffer()) // Gibt false zurück
util.types.isUint32Array(new Uint32Array()) // Gibt true zurück
util.types.isUint32Array(new Float64Array()) // Gibt false zurück
util.types.isWeakMap(value)
Hinzugefügt in: v10.0.0
Gibt true
zurück, wenn der Wert eine eingebaute WeakMap
-Instanz ist.
util.types.isWeakMap(new WeakMap()) // Gibt true zurück
util.types.isWeakSet(value)
Hinzugefügt in: v10.0.0
value
<beliebig>- Gibt zurück: <boolean>
Gibt true
zurück, wenn der Wert eine eingebaute WeakSet
-Instanz ist.
util.types.isWeakSet(new WeakSet()) // Gibt true zurück
Veraltete APIs
Die folgenden APIs sind veraltet und sollten nicht mehr verwendet werden. Vorhandene Anwendungen und Module sollten aktualisiert werden, um alternative Ansätze zu finden.
util._extend(target, source)
Hinzugefügt in: v0.7.5
Veraltet seit: v6.0.0
[Stabil: 0 - Veraltet]
Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen Object.assign()
.
Die Methode util._extend()
war nie für die Verwendung außerhalb interner Node.js-Module vorgesehen. Die Community hat sie trotzdem gefunden und verwendet.
Sie ist veraltet und sollte nicht in neuem Code verwendet werden. JavaScript verfügt über eine sehr ähnliche integrierte Funktionalität durch Object.assign()
.
util.isArray(object)
Hinzugefügt in: v0.6.0
Veraltet seit: v4.0.0
[Stabil: 0 - Veraltet]
Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen Array.isArray()
.
object
<beliebig>- Gibt zurück: <boolean>
Alias für Array.isArray()
.
Gibt true
zurück, wenn das gegebene object
ein Array
ist. Andernfalls wird false
zurückgegeben.
const util = require('node:util')
util.isArray([])
// Gibt zurück: true
util.isArray(new Array())
// Gibt zurück: true
util.isArray({})
// Gibt zurück: false