模組util

util 模組提供了資料型別的判斷、物件屬性的複製、模版字串的解析、事件處理等實用的工具函數

以下是具體的介紹和範例：

判斷資料類型-util.is[type] 此模組內提供了諸如isDate、isRegExp、isError等判斷傳入參數資料類型的方法，例如：

1
2
3
var util = require('util');
console.log(util.isDate(new Date()));
console.log(util.isRegExp(/some regexp/));

物件屬性複製-util.inherits() 該方法可以選擇將一個建構函式繼承自另一個，從而實現原型繼承。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var util = require('util');

function Animal() {
    this.name = 'Animal';
    this.sleep = function() {
        console.log(this.name + '正在睡觉！');
    }
}
Animal.prototype.eat = function(food) {
    console.log(this.name + '正在吃：' + food);
};

function Cat() {
    this.name = 'cat';
}
util.inherits(Cat, Animal);

使用Cat這個建構子繼承了Animal的實例屬性和原型屬性，印出Cat的實例的屬性和方法

1
2
3
4
var cat = new Cat();
console.log(cat.name);
console.log(cat.eat('fish'));
console.log(cat.sleep());

util.format() 格式化輸出模版

1
2
3
4
5
const util = require('util');
const str1 = util.format('%s:%s', 'foo');
const str2 = util.format('%s:%s', 'foo', 'bar', 'baz');
console.log(str1) // => 'foo:%s'
console.log(str2) // => 'foo:bar baz'

以上是util模組的一些常用方法，常常可以用來簡化實際開發過程。

物件

LruCache

LRU(least recently used) 快取對象，參見LruCache對象。

1LruCache util.LruCache;

TextDecoder

TextDecoder解碼對象，參見TextDecoder對象。

1TextDecoder util.TextDecoder;

TextEncoder

TextEncoder編碼對象，參見TextEncoder對象。

1TextEncoder util.TextEncoder;

types

types模組提供了對資料類型判斷的工具函數。

1types util.types;

靜態函數

format

按照指定的格式格式化變數

1
2
static String util.format(String fmt,
    ...args);

呼叫參數:

fmt: String, 格式化字串
args: ..., 可選參數列表

回傳結果:

String, 返回格式化後的字串

格式格式化變數

1
static String util.format(...args);

呼叫參數:

args: ..., 可選參數列表

回傳結果:

String, 返回格式化後的字串

inherits

從一個建構函式constructor 繼承原型函式到另一個。建構函數的原型將被設定為一個新的從超類別（superConstructor）建立的物件。

1
2
static util.inherits(Value constructor,
    Value superConstructor);

呼叫參數:

constructor: Value, 初始的建構函數
superConstructor: Value, 被繼承的超類

inspect

函數傳回obj 的字串表示，主要用於調試。附加的options 可用於變更格式化字串的某些方面。

1
2
static String util.inspect(Value obj,
    Object options = {});

呼叫參數:

obj: Value, 指定需要處理的對象
options: Object, 指定格式控制選項

回傳結果:

String, 返回格式化後的字串

支援以下參數:

1
2
3
4
5
6
7
8
9{
    "colors": false, // specify if output should be colorized, defaults to false
    "depth": 2, // specify the max depth of the output, defaults to 2
    "table": false, // specify if output should be a table, defaults to false
    "encode_string": true, // specify if string should be encoded, defaults to true
    "maxArrayLength": 100, // specify max number of array elements to show, set to 0 or negative to show no elements, defaults to 100
    "maxStringLength": 10000, // specify max string length to output, set to 0 or negative to show no strings, defaults to 10000
    "fields": [], // specify the fields to be displayed, defaults to all
}

deprecate

封裝給定的函數，本函數僅為相容，且不輸出警告

1
2
3
static Function util.deprecate(Function fn,
    String msg,
    String code = "");

呼叫參數:

fn: Function, 給定需要封裝的函數
msg: String, 給定警告訊息
code: String, 給定警告編號

回傳結果:

Function, 如果封裝結果

isEmpty

偵測給定的變數是否不包含任何值(沒有可列舉的屬性)

1
static Boolean util.isEmpty(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果為空則回傳True

isArray

檢測給定的變數是否為數組

1
static Boolean util.isArray(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是數組則回傳True

isBoolean

檢測給定的變數是否為Boolean

1
static Boolean util.isBoolean(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Boolean 則回傳True

isNull

檢測給定的變數是否為Null

1
static Boolean util.isNull(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Null 則回傳True

isNullOrUndefined

檢測給定的變數是否是Null 或Undefined

1
static Boolean util.isNullOrUndefined(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Null 或Undefined 則回傳True

isNumber

檢測給定的變數是否為數字

1
static Boolean util.isNumber(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是數字則回傳True

isBigInt

檢測給定的變數是否為BigInt

1
static Boolean util.isBigInt(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是數字則回傳True

isString

檢測給定的變數是否為字串

1
static Boolean util.isString(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是字串則傳回True

isUndefined

檢測給定的變數是否為Undefined

1
static Boolean util.isUndefined(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Undefined 則回傳True

isRegExp

檢測給定的變數是否為正規對象

1
static Boolean util.isRegExp(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是正規物件則回傳True

isObject

檢測給定的變數是否為對象

1
static Boolean util.isObject(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是物件則回傳True

isDate

檢測給定的變數是否為日期對象

1
static Boolean util.isDate(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是日期物件則回傳True

isNativeError

檢測給定的變數是否為錯誤對象

1
static Boolean util.isNativeError(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是錯誤物件則回傳True

isPrimitive

檢測給定的變數是否為原始類型

1
static Boolean util.isPrimitive(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是原始型別則傳回True

isSymbol

檢測給定的變數是否為Symbol類型

1
static Boolean util.isSymbol(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Symbol類型則回傳True

isDataView

偵測給定的變數是否為DataView 類型

1
static Boolean util.isDataView(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是DataView 類型則傳回True

isExternal

偵測給定的變數是否為External 類型

1
static Boolean util.isExternal(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是External 類型則傳回True

isMap

檢測給定的變數是否為Map 類型

1
static Boolean util.isMap(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Map 類型則傳回True

isMapIterator

偵測給定的變數是否為MapIterator 類型

1
static Boolean util.isMapIterator(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是MapIterator 類型則傳回True

isPromise

檢測給定的變數是否為Promise 類型

1
static Boolean util.isPromise(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Promise 類型則回傳True

isAsyncFunction

檢測給定的變數是否為AsyncFunction 類型

1
static Boolean util.isAsyncFunction(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是AsyncFunction 類型則傳回True

isSet

檢測給定的變數是否為Set 類型

1
static Boolean util.isSet(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Set 類型則回傳True

isSetIterator

檢測給定的變數是否為SetIterator 類型

1
static Boolean util.isSetIterator(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是SetIterator 類型則傳回True

isTypedArray

檢測給定的變數是否為TypedArray 類型

1
static Boolean util.isTypedArray(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是TypedArray 類型則傳回True

isUint8Array

檢測給定的變數是否為Uint8Array 類型

1
static Boolean util.isUint8Array(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是Uint8Array 類型則傳回True

isFunction

檢測給定的變數是否為函數對象

1
static Boolean util.isFunction(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是函數物件則回傳True

isBuffer

檢測給定的變數是否為函數Buffer物件

1
static Boolean util.isBuffer(Value v);

呼叫參數:

v: Value, 給定需要檢測的變數

回傳結果:

Boolean, 如果是函數Buffer物件則回傳True

isDeepEqual

測試數值深度等於預期值

1
2
static Boolean util.isDeepEqual(Value actual,
    Value expected);

呼叫參數:

actual: Value, 要測試的數值
expected: Value, 預期的數值

回傳結果:

Boolean, 若深度相等則傳回True

has

查詢指定物件是否包含給定的鍵

1
2
static Boolean util.has(Value v,
    String key);

呼叫參數:

v: Value, 給定需要查詢的對象
key: String, 指定需要查詢的鍵

回傳結果:

Boolean, 傳回物件的全部鍵數組

keys

查詢指定物件的全部鍵數組

1
static Array util.keys(Value v);

呼叫參數:

v: Value, 給定需要查詢的對象

回傳結果:

Array, 傳回物件的全部鍵數組

values

查詢指定物件的全部值數組

1
static Array util.values(Value v);

呼叫參數:

v: Value, 給定需要查詢的對象

回傳結果:

Array, 傳回物件的全部值數組

clone

克隆給定變量，如果是對像或數組，則複製內容到新對象

1
static Value util.clone(Value v);

呼叫參數:

v: Value, 給定要克隆的變數

回傳結果:

Value, 返回克隆結果

deepFreeze

深度凍結一個對象，凍結後的對象及其包含的對像都將不允許修改

1
static util.deepFreeze(Value v);

呼叫參數:

v: Value, 指定要凍結的對象

extend

將一個或多個物件的鍵值擴展到指定對象

1
2
static Value util.extend(Value v,
    ...objs);

呼叫參數:

v: Value, 指定要擴充的對象
objs: ..., 指定一個或多個用於擴展的對象

回傳結果:

Value, 返回擴展的結果

_extend

將一個或多個對象的鍵值擴展到指定對象，是extend 的別名

1
2
static Value util._extend(Value v,
    ...objs);

呼叫參數:

v: Value, 指定要擴充的對象
objs: ..., 指定一個或多個用於擴展的對象

回傳結果:

Value, 返回擴展的結果

pick

返回一個object副本，只過濾出指定鍵的屬性值

1
2
static Object util.pick(Value v,
    ...objs);

呼叫參數:

v: Value, 指定要過濾的對象
objs: ..., 指定一個或多個用於選擇的鍵

回傳結果:

Object, 返回過濾的結果

omit

返回一個object副本，只排除指定鍵的屬性值

1
2
static Object util.omit(Value v,
    ...keys);

呼叫參數:

v: Value, 指定要過濾的對象
keys: ..., 指定一個或多個用於排除的鍵

回傳結果:

Object, 回傳排除的結果

first

取得數組的第一個元素

1
static Value util.first(Value v);

呼叫參數:

v: Value, 給定要取得的數組

回傳結果:

Value, 返回獲取的元素

取得數組的開始多個元素

1
2
static Value util.first(Value v,
    Integer n);

呼叫參數:

v: Value, 給定要取得的數組
n: Integer, 指定要取得的元素個數

回傳結果:

Value, 傳回所獲取的元素數組

last

取得數組的第後一個元素

1
static Value util.last(Value v);

呼叫參數:

v: Value, 給定要取得的數組

回傳結果:

Value, 返回獲取的元素

取得數組的結尾多個元素

1
2
static Value util.last(Value v,
    Integer n);

呼叫參數:

v: Value, 給定要取得的數組
n: Integer, 指定要取得的元素個數

回傳結果:

Value, 傳回所獲取的元素數組

unique

取得數組的元素去重後的副本

1
2
static Array util.unique(Value v,
    Boolean sorted = false);

呼叫參數:

v: Value, 給定要去重的數組
sorted: Boolean, 指定數組是否排序，如果指定數組排序，將使用快速演算法

回傳結果:

Array, 傳回去重元素後的陣列

union

將一個或多個數組的值合併成一個值唯一的數組

1
static Array util.union(...arrs);

呼叫參數:

arrs: ..., 指定一個或多個用於合併的陣列

回傳結果:

Array, 回傳合併的結果

intersection

傳回一個包含arr 數組中排除一個或多個數組元素的交集

1
static Array util.intersection(...arrs);

呼叫參數:

arrs: ..., 指定一個或多個用於計算交集的陣列

回傳結果:

Array, 傳回計算交集的結果

flatten

將一個巢狀多層的陣列(巢狀可以是任何層數)轉換為只有一層的陣列。如果你傳遞shallow 參數，數組將只減少一維的巢狀。

1
2
static Array util.flatten(Value arr,
    Boolean shallow = false);

呼叫參數:

arr: Value, 指定需要轉換的陣列
shallow: Boolean, 指定是否只減少一維的嵌套，缺省為false

回傳結果:

Array, 回傳轉換的結果

without

傳回一個包含arr 數組中排除一個或多個元素後的數組

1
2
static Array util.without(Value arr,
    ...els);

呼叫參數:

arr: Value, 指定需要排除的數組
els: ..., 指定一個或多個用於排除的元素

回傳結果:

Array, 回傳排除的結果

difference

傳回一個包含arr 數組中排除without 數組元素之後的數組

1
2
static Array util.difference(Array list,
    ...arrs);

呼叫參數:

list: Array, 指定需要排除的數組
arrs: ..., 指定用於排除的一個或多個數組

回傳結果:

Array, 回傳排除的結果

each

遍歷list 中的所有元素，依序以遍歷輸出每個元素。如果傳遞了context 參數，則把iterator 綁定到context 物件上。每次呼叫iterator 都會傳遞三個參數：(element, index, list)

1
2
3
static Value util.each(Value list,
    Function iterator,
    Value context = undefined);

呼叫參數:

list: Value, 指定需要遍歷的清單或對象
iterator: Function, 指定用於遍歷的回呼函數
context: Value, 指定呼叫iterator 時綁定的context 對象

回傳結果:

Value, 返回list 本身

map

透過變換函數（iterator迭代器）把list 中的每個值映射到一個新的陣列中。如果傳遞了context 參數，則把iterator 綁定到context 物件上。每次呼叫iterator 都會傳遞三個參數：(element, index, list)

1
2
3
static Array util.map(Value list,
    Function iterator,
    Value context = undefined);

呼叫參數:

list: Value, 指定需要變換的清單或對象
iterator: Function, 指定用於變換的回呼函數
context: Value, 指定呼叫iterator 時綁定的context 對象

回傳結果:

Array, 返回變換的結果

reduce

把list中元素歸結為一個單獨的數值。如果傳遞了context 參數，則把iterator 綁定到context 物件上。每次呼叫iterator 都會傳遞三個參數：(memo, element, index, list)

1
2
3
4
static Value util.reduce(Value list,
    Function iterator,
    Value memo,
    Value context = undefined);

呼叫參數:

list: Value, 指定需要歸結的清單或對象
iterator: Function, 指定用於歸結的回呼函數
memo: Value, 指定歸結的初始值
context: Value, 指定呼叫iterator 時綁定的context 對象

回傳結果:

Value, 返回歸結的結果

parseArgs

解析命令列字串返回參數列表

1
static NArray util.parseArgs(String command);

呼叫參數:

command: String, 指定要解析的命令列字串

回傳結果:

NArray, 傳回解析出的參數列表

compile

編譯腳本為二進位程式碼

1
2
3
static Buffer util.compile(String srcname,
    String script,
    Integer mode = 0);

呼叫參數:

srcname: String, 指定要新增的腳本名稱
script: String, 指定要編譯的腳本程式碼
mode: Integer, 編譯模式，0: module, 1: script, 2: worker，預設為 0

回傳結果:

Buffer, 返回編譯出的二進位程式碼

util.compile可以將腳本編譯為v8 內部運行資料塊(非機器執行程式碼)。編譯以後的程式碼，儲存為*.jsc 後，可以由run 和require 直接載入執行。

由於編譯之後，目標程式碼將無法逆向取得原始程式碼，依賴Function.toString 的程式將無法正常運作。

sync

包裹callback 或async 函數為同步調用

1
2
static Function util.sync(Function func,
    Boolean async_func = false);

呼叫參數:

func: Function, 給定需要包裹的函數
async_func: Boolean, 指定以async 函式方式處理func，為false 則自動判斷

回傳結果:

Function, 返回同步運行的函數

util.sync將callback 函數或async 函數處理為sync 函數，以方便呼叫。

callback 範例如下：

1
2
3
4
5
6
7
8
9
10
11
// callback
var util = require('util');

function cb_test(a, b, cb) {
    setTimeout(() => {
        cb(null, a + b);
    }, 100);
}

var fn_sync = util.sync(cb_test);
console.log(fn_sync(100, 200));

async 範例如下：

1
2
3
4
5
6
7
8
9
// async/await
var util = require('util');

async function async_test(a, b) {
    return a + b;
}

var fn_sync = util.sync(async_test);
console.log(fn_sync(100, 200));

對於未標記為async 的傳回promise 的函數，可以手動指定sync 模式：

1
2
3
4
5
6
7
8
9
10
11
// async/await
var util = require('util');

function async_test(a, b) {
    return new Promise(function(resolve, reject) {
        resolve(a + b);
    });
}

var fn_sync = util.sync(async_test, true);
console.log(fn_sync(100, 200));

promisify

包裹callback 函數為async 呼叫

1
static Function util.promisify(Function func);

呼叫參數:

func: Function, 給定需要包裹的函數

回傳結果:

Function, 返回async 函數

util.promisify將callback 函數處理為async 函數，以方便呼叫。

callback 範例如下：

1
2
3
4
5
6
7
8
9
10
11
// callback
var util = require('util');

function cb_test(a, b, cb) {
    setTimeout(() => {
        cb(null, a + b);
    }, 100);
}

var fn_sync = util.promisify(cb_test);
console.log(async fn_sync(100, 200));

callbackify

包裹async 函數為callback 呼叫

1
static Function util.callbackify(Function func);

呼叫參數:

func: Function, 給定需要包裹的函數

回傳結果:

Function, 返回callback 函數

util.callbackify將async 函數處理為callback 函數，以方便呼叫。

async 範例如下：

1
2
3
4
5
6
7
8
9
10
11
12
// async
var util = require('util');

async function async_test(a, b) {
    return a + b;
}

var fn_callback = util.callbackify(async_test);

fn_callback(100, 200, (err, result) => {
    console.log(result);
});

buildInfo

查詢當前引擎及各組件版本信息

1
static Object util.buildInfo();

回傳結果:

Object, 傳回元件版本對象

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24{
    "fibjs": "0.25.0",
    "clang": "9.1",
    "date": "Jun 12 2018 07:22:40",
    "vender": {
        "ev": "4.24",
        "expat": "2.2.5",
        "gd": "2.2.4",
        "jpeg": "8.3",
        "leveldb": "1.17",
        "mongo": "0.7",
        "pcre": "8.21",
        "png": "1.5.4",
        "mbedtls": "2.6.1",
        "snappy": "1.1.2",
        "sqlite": "3.23.0",
        "tiff": "3.9.5",
        "uuid": "1.6.2",
        "v8": "6.7.288.20",
        "v8-snapshot": true,
        "zlib": "1.2.7",
        "zmq": "3.1"
    }
}

開發指南

基礎模組

內建對象

社群模組

模組util

物件

LruCache

TextDecoder

TextEncoder

types

靜態函數

format

inherits

inspect

deprecate

isEmpty

isArray

isBoolean

isNull

isNullOrUndefined

isNumber

isBigInt

isString

isUndefined

isRegExp

isObject

isDate

isNativeError

isPrimitive

isSymbol

isDataView

isExternal

isMap

isMapIterator

isPromise

isAsyncFunction

isSet

isSetIterator

isTypedArray

isUint8Array

isFunction

isBuffer

isDeepEqual

has

keys

values

clone

deepFreeze

extend

_extend

pick

omit

first

last

unique

union

intersection

flatten

without

difference

each

map

reduce

parseArgs

compile

sync

promisify

callbackify

buildInfo