Utilities · io.js API 中文文檔

### 穩定度: 2 - 穩定這些功能在模塊`'util'`中，通過`require('util')`來使用它們。 `util`模塊主要的設計意圖是滿足`io.js`內部API的需要。但是許多工具對于你的程序也十分有用。如果你發現這些功能不能滿足你的需要，那么鼓勵你編寫自己的工具集。我們對任何`io.js`內部功能不需要的功能，都不感興趣。 #### util.debuglog(section) - section String 需要被調試的程序節點 - Returns: Function 日志處理函數這個方法被用來在`NODE_DEBUG`環境變量存在的情況下，創建一個有條件寫入`stderr`的函數。如果`section`名出現在環境變量中，那么返回的函數與`console.error()`類似。否則，返回空函數。例子： ~~~ var debuglog = util.debuglog('foo'); var bar = 123; debuglog('hello from foo [%d]', bar); ~~~ 如果程序在`NODE_DEBUG=foo`環境下運行，那么輸出將是： ~~~ FOO 3245: hello from foo [123] ~~~ `3245`是進程id。如果這個環境變量沒有設置，那么將不會打印任何東西。你可以通過逗號設置多個`NODE_DEBUG`環境變量。例如，`NODE_DEBUG=fs,net,tls`。 #### util.format(format[, ...]) 使用第一個參數，像`printf`一樣的格式輸出格式化字符串。第一個參數是一個包含了0個或更多占位符的字符串。每個占位符都被其后的參數所替換。支持的占位符有： - %s - 字符串 - %d - 數字（整數和浮點數） - %j - JSON。如果參數包含循環引用，則返回字符串`'[Circular]'`。 - %% - 單獨的百分比符號（`'%'`），它不消耗一個參數。如果占位符沒有對應的參數，那么占位符將不被替換。 ~~~ util.format('%s:%s', 'foo'); // 'foo:%s' ~~~ 如果參數多余占位符，那么額外的參數會被轉換成字符串（對于對象和鏈接，使用`util.inspect()`），并且以空格連接。 ~~~ util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz' ~~~ 如果第一個參數不是格式化字符串，那么`util.format()`將會返回一個以空格連接的所有參數的字符串。每一個參數都被調用`util.inspect()`來轉換成字符串。 ~~~ util.format(1, 2, 3); // '1 2 3' ~~~ #### util.log(string) 在控制臺輸出帶有時間戳的信息。 ~~~ require('util').log('Timestamped message.'); ~~~ #### util.inspect(object[, options]) 返回一個代表了`object`的字符串，在調試時很有用。一個可選的`options`對象可以被傳遞以下屬性來影響字符串的格式： - showHidden - 如果設置為`true`，那么對象的不可枚舉屬性也會被顯示。默認為`false`。 - depth - 告訴`inspect`格式化對象時需要遞歸的次數。這對于巨大的復雜對象十分有用。默認為`2`。傳遞`null`表示無限遞歸。 - colors - 如果為`true`，那么輸出會帶有ANSI顏色代碼風格。默認為`false`。顏色是可以自定義的，參閱下文。 - customInspect - 如果為`false`，那么定義在被檢查對象上的`inspect(depth, opts)`函數將不會被調用。默認為`false`。一個檢查`util`對象所有屬性的例子： ~~~ var util = require('util'); console.log(util.inspect(util, { showHidden: true, depth: null })); ~~~ 參數值可以提供了它們自己的`inspect(depth, opts)`函數，當被調用時它們會收到當前的遞歸深度值，以及其他傳遞給`util.inspect()`的選項。 ##### 自定義`util.inspect`顏色 `util.inspect`的有顏色的輸出（如果啟用）可以全局的通過`util.inspect.styles`和`util.inspect.colors`對象來自定義。 `util.inspect.styles`是通過`util.inspect.colors`設置每個風格一個顏色的映射。高亮風格和它們的默認值為`number (yellow) boolean (yellow) string (green) date (magenta) regexp (red) null (bold) undefined (grey) special`。這時的唯一方法(cyan) * `name (intentionally no styling)`。預定義顏色有`white, grey, black, blue, cyan, green, magenta, red 和 yellow`。他們都是`bold`，`italic`，`underline`和`inverse`代碼。 ##### 自定義對象的`inspect()`函數對象也可以自己定義`inspect(depth)`函數，`util.inspect()`將會調用它，并且輸出它的結果： ~~~ var util = require('util'); var obj = { name: 'nate' }; obj.inspect = function(depth) { return '{' + this.name + '}'; }; util.inspect(obj); // "{nate}" ~~~ 你也可以完全返回另一個對象，并且返回的字符串是由這個返回對象格式化而來的，這也`JSON.stringify()`相似： ~~~ var obj = { foo: 'this will not show up in the inspect() output' }; obj.inspect = function(depth) { return { bar: 'baz' }; }; util.inspect(obj); // "{ bar: 'baz' }" ~~~ #### util.isArray(object) `Array.isArray`的內部別名。如果`object`是一個數組則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isArray([]) // true util.isArray(new Array) // true util.isArray({}) // false ~~~ #### util.isRegExp(object) 如果`object`是一個正則表達式則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isRegExp(/some regexp/) // true util.isRegExp(new RegExp('another regexp')) // true util.isRegExp({}) // false ~~~ #### util.isDate(object) 如果`object`是一個日期則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isDate(new Date()) // true util.isDate(Date()) // false (without 'new' returns a String) util.isDate({}) // false ~~~ #### util.isError(object) 如果`object`是一個錯誤對象則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isError(new Error()) // true util.isError(new TypeError()) // true util.isError({ name: 'Error', message: 'an error occurred' }) // false ~~~ #### util.isBoolean(object) 如果`object`是一個布爾值則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isBoolean(1) // false util.isBoolean(0) // false util.isBoolean(false) // true ~~~ #### util.isNull(object) 如果`object`是嚴格的`null`則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isNull(0) // false util.isNull(undefined) // false util.isNull(null) // true ~~~ #### util.isNullOrUndefined(object) 如果`object`是一`null`或`undefined`則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isNullOrUndefined(0) // false util.isNullOrUndefined(undefined) // true util.isNullOrUndefined(null) // true ~~~ #### util.isNumber(object) 如果`object`是一個數字則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isNumber(false) // false util.isNumber(Infinity) // true util.isNumber(0) // true util.isNumber(NaN) // true ~~~ #### util.isString(object) 如果`object`是一個字符串則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isString('') // true util.isString('foo') // true util.isString(String('foo')) // true util.isString(5) // false ~~~ #### util.isSymbol(object) 如果`object`是一個`Symbol`則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isSymbol(5) // false util.isSymbol('foo') // false util.isSymbol(Symbol('foo')) // true ~~~ #### util.isUndefined(object) 如果`object`是`undefined`則返回`true`，否則返回`false`。 ~~~ var util = require('util'); var foo; util.isUndefined(5) // false util.isUndefined(foo) // true util.isUndefined(null) // false ~~~ #### util.isObject(object) 如果`object`嚴格的是一個對象而不是一個函數，則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isObject(5) // false util.isObject(null) // false util.isObject({}) // true util.isObject(function(){}) // false ~~~ #### util.isFunction(object) 如果`object`是一個函數則返回`true`，否則返回`false`。 ~~~ var util = require('util'); function Foo() {} var Bar = function() {}; util.isFunction({}) // false util.isFunction(Foo) // true util.isFunction(Bar) // true ~~~ #### util.isPrimitive(object) 如果`object`是一個基本值則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isPrimitive(5) // true util.isPrimitive('foo') // true util.isPrimitive(false) // true util.isPrimitive(null) // true util.isPrimitive(undefined) // true util.isPrimitive({}) // false util.isPrimitive(function() {}) // false util.isPrimitive(/^$/) // false util.isPrimitive(new Date()) // false ~~~ #### util.isBuffer(object) 如果`object`是一個`buffer`則返回`true`，否則返回`false`。 ~~~ var util = require('util'); util.isBuffer({ length: 0 }) // false util.isBuffer([]) // false util.isBuffer(new Buffer('hello world')) // true ~~~ #### util.inherits(constructor, superConstructor) 將一個構造函數所有的原型方法繼承到到另一個中。構造函數的原型將會被設置為一個超類創建的新對象。為了方便起見，超類可以通過`constructor.super_`來訪問。 ~~~ var util = require("util"); var events = require("events"); function MyStream() { events.EventEmitter.call(this); } util.inherits(MyStream, events.EventEmitter); MyStream.prototype.write = function(data) { this.emit("data", data); } var stream = new MyStream(); console.log(stream instanceof events.EventEmitter); // true console.log(MyStream.super_ === events.EventEmitter); // true stream.on("data", function(data) { console.log('Received data: "' + data + '"'); }) stream.write("It works!"); // Received data: "It works!" ~~~ #### util.deprecate(function, string) 標記一個方法為不應再使用。 ~~~ var util = require('util'); exports.puts = util.deprecate(function() { for (var i = 0, len = arguments.length; i < len; ++i) { process.stdout.write(arguments[i] + '\n'); } }, 'util.puts: Use console.log instead'); ~~~ 默認返回一個被運行時會發出一次警告的，修改后的函數。如果`--no-deprecation`被設置，那么這個函數將為空。可以在運行時通過`process.noDeprecation`布爾值配置（只有在模塊被加載前設置，才會有效）。如果`--trace-deprecation`被設置，當被棄用的API第一次被使用時，會向控制臺打印一個警告和堆棧信息。可以在運行時通過`process.traceDeprecation`布爾值配置。如果`--throw-deprecation`被設置，那么當被棄用的API被使用時，應用會拋出一個錯誤。可以在運行時通過`process.throwDeprecation`布爾值配置。 `process.throwDeprecation`的優先級高于`process.traceDeprecation`。 #### util.debug(string) > 穩定度: 0 - 棄用: 使用`console.error()`代替。被棄用，`console.error`的前身。 #### util.error([...]) > 穩定度: 0 - 棄用: 使用`console.error()`代替。被棄用，`console.error`的前身。 #### util.puts([...]) > 穩定度: 0 - 棄用: 使用`console.log()`代替。被棄用，`console.log`的前身。 #### util.print([...]) > 穩定度: 0 - 棄用: 使用`console.log()`代替。被棄用，`console.log`的前身。 #### util.pump(readableStream, writableStream[, callback]) > 穩定度: 0 - 棄用: 使用`readableStream.pipe(writableStream)`代替。被棄用，`stream.pipe()`的前身。