Lodash 中文文档

Appearance

Seq (序列) ​

_(value) ​

@lodash/core

创建一个 lodash 对象，将 value 包装在其中，以启用 隐式方法链序列（implicit method chain sequences）。

那些操作并返回数组、集合或函数的方法可以被链式调用。而那些检索单个值或返回原始值的方法会自动结束链式序列，并返回解包后的值。否则，你需要使用 .value() 方法来解包并获取最终结果。

详细说明：

  • 显式链式序列：可以使用 _.chain 开启。
  • 惰性求值 (Lazy Evaluation)：链式方法的执行是惰性的，即直到隐式或显式解包（unwrapped）时才会真正执行。
  • 性能优化：惰性求值允许支持“快捷融合”（shortcut fusion）。这是一种优化，用于合并迭代调用，避免创建中间数组，大大提高执行效率。

参数 ​

  • value (*): 要在 lodash 实例中包装的值。

返回 ​

  • (Object): 返回新的 lodash 包装器实例。

示例 ​

js
function square(n) {
  return n * n;
}

var wrapped = _([1, 2, 3]);

// 返回解包后的值（因为 reduce 返回单个值，自动结束链式调用）
wrapped.reduce(_.add);
// => 6

// 返回包装后的值（因为 map 返回数组，继续保持链式状态）
var squares = wrapped.map(square);

_.isArray(squares);
// => false (它是一个 lodash 包装对象)

_.isArray(squares.value());
// => true (使用 .value() 获取了真实数组)

_.chain(value) ​

引入版本 1.3.0

创建一个 lodash 包装实例，将 value 包装在其中，以启用 显式方法链序列（explicit method chain sequences）。

使用此方法开启链式调用后，序列的结果 必须 使用 _#value（即 .value() 方法）来解包。

参数 ​

  • value (*): 要包装的值。

返回 ​

  • (Object): 返回新的 lodash 包装实例。

示例 ​

js
var users = [
  { user: "barney", age: 36 },
  { user: "fred", age: 40 },
  { user: "pebbles", age: 1 },
];

var youngest = _.chain(users)
  .sortBy("age")
  .map(function (o) {
    return o.user + " is " + o.age;
  })
  .head()
  .value();
// => 'pebbles is 1'

_.tap(value, interceptor) ​

引入版本 0.1.0

此方法调用 interceptor 并返回 value。interceptor 调用时会传入一个参数：(value)。 此方法的目的是“进入”（tap into）方法链序列，以便修改中间结果。

参数 ​

  • value (*): 提供给 interceptor 的值。
  • interceptor (Function): 要调用的函数。

返回 ​

  • (*): 返回 value。

示例 ​

js
_([1, 2, 3])
  .tap(function (array) {
    // 修改输入数组
    array.pop();
  })
  .reverse()
  .value();
// => [2, 1]

_.thru(value, interceptor) ​

引入版本 3.0.0

这个方法类似 _.tap，区别在于它返回 interceptor（拦截器）的执行结果。此方法的目的是“传递”值，用于在方法链序列中替换中间结果。

参数 ​

  • value (*): 提供给 interceptor 的值。
  • interceptor (Function): 要调用的函数。

返回 ​

  • (*): 返回 interceptor 的结果。

示例 ​

js
_("  abc  ")
  .chain()
  .trim()
  .thru(function (value) {
    return [value];
  })
  .value();
// => ['abc']

_.prototype[Symbol.iterator]() ​

引入版本 4.0.0

使 lodash 包装器对象变得可迭代（iterable）。这意味着你可以在包装器对象上使用 for...of 循环或展开运算符。

返回 ​

  • (Object): 返回包装器对象本身。

示例 ​

js
var wrapped = _([1, 2]);

// 包装器实现了迭代器协议
console.log(wrapped[Symbol.iterator]() === wrapped);
// => true

// 可以直接被 Array.from 转换
Array.from(wrapped);
// => [1, 2]

_.prototype.at([paths]) ​

引入版本 1.0.0

这是 _.at 的包装器版本。

参数 ​

  • [paths] (...(string|string[])): 要选取的属性路径。

返回 ​

  • (Object): 返回新的 lodash 包装实例。

示例 ​

js
var object = { a: [{ b: { c: 3 } }, 4] };

_(object).at(["a[0].b.c", "a[1]"]).value();
// => [3, 4]

_.prototype.chain() ​

引入版本 0.1.0

创建一个启用了 显式方法链序列（explicit method chain sequences）的 lodash 包装实例。

返回 ​

  • (Object): 返回新的 lodash 包装实例。

示例 ​

js
var users = [
  { user: "barney", age: 36 },
  { user: "fred", age: 40 },
];

// 一个没有显式链式调用的序列。
_(users).head();
// => { 'user': 'barney', 'age': 36 }

// 一个启用了显式链式调用的序列。
_(users).chain().head().pick("user").value();
// => { 'user': 'barney' }

_.prototype.commit() ​

引入版本 3.2.0

执行链式序列并返回包装后的结果（wrapped result）。

返回 ​

  • (Object): 返回新的 lodash 包装实例。

示例 ​

js
var array = [1, 2];
var wrapped = _(array).push(3);

console.log(array);
// => [1, 2]

wrapped = wrapped.commit();
console.log(array);
// => [1, 2, 3]

wrapped.last();
// => 3

console.log(array);
// => [1, 2, 3]

_.prototype.next() ​

引入版本 4.0.0

获取包装对象中的下一个值，遵循 迭代器协议（iterator protocol）。

返回 ​

  • (Object): 返回下一个迭代器对象（包含 done 和 value 属性）。

示例 ​

js
var wrapped = _([1, 2]);

wrapped.next();
// => { 'done': false, 'value': 1 }

wrapped.next();
// => { 'done': false, 'value': 2 }

wrapped.next();
// => { 'done': true, 'value': undefined }

_.prototype.plant(value) ​

引入版本 3.2.0

创建一个链式序列的克隆，并将 value 作为新的包装值植入其中。（即：复制当前的链式操作序列，但将其应用于新的 value 上，实现复用链式逻辑）。

参数 ​

  • value (*): 要植入的值。

返回 ​

  • (Object): 返回新的 lodash 包装实例。

示例 ​

js
function square(n) {
  return n * n;
}

// 定义一个链式序列：先包装数组，然后映射平方
var wrapped = _([1, 2]).map(square);

// 克隆这个链式序列，但应用在新的数组 [3, 4] 上
var other = wrapped.plant([3, 4]);

other.value();
// => [9, 16]

// 原来的序列不受影响
wrapped.value();
// => [1, 4]

_.prototype.reverse() ​

引入版本 0.1.0

这是 _.reverse 的包装器版本。

注意： 这个方法会 改变（mutate）封装的数组。

返回 ​

  • (Object): 返回新的 lodash 包装实例。

示例 ​

js
var array = [1, 2, 3];

_(array).reverse().value();
// => [3, 2, 1]

console.log(array);
// => [3, 2, 1]

_.prototype.value() ​

引入版本 0.1.0

执行链式序列并提取解包后的值（即获取最终结果）。

别名： _.prototype.toJSON, _.prototype.valueOf

返回 ​

  • (*): 返回解析后的解包值。

示例 ​

js
_([1, 2, 3]).value();
// => [1, 2, 3]