迭代协议 - JavaScript | MDN

切换侧边栏

主题

跟随系统
浅色
深色

中文 (简体)

记住语言了解更多

迭代协议

迭代协议并不是新的内置实现或语法，而是协议。这些协议可以被任何遵循某些约定的对象来实现。

迭代协议具体分为两个协议：可迭代协议和迭代器协议。

本文内容

可迭代协议

可迭代协议允许 JavaScript 对象定义或定制它们的迭代行为，例如，在一个 for..of 结构中，哪些值可以被遍历到。一些内置类型同时是内置的可迭代对象，并且有默认的迭代行为，比如 Array 或者 Map，而其他内置类型则不是（比如 Object）。

要成为可迭代对象，该对象必须实现 [Symbol.iterator]() 方法，这意味着对象（或者它原型链上的某个对象）必须有一个键为 [Symbol.iterator] 的属性，可通过常量 Symbol.iterator 访问该属性：

[Symbol.iterator]

一个无参数的函数，其返回值为一个符合迭代器协议的对象。

当一个对象需要被迭代的时候（比如被置入一个 for...of 循环时），首先，会不带参数调用它的 [Symbol.iterator]() 方法，然后使用此方法返回的迭代器获得要迭代的值。

值得注意的是调用此无参数函数时，它将作为对可迭代对象的方法进行调用。因此，在函数内部，this 关键字可用于访问可迭代对象的属性，以决定在迭代过程中提供什么。

此函数可以是普通函数，也可以是生成器函数，以便在调用时返回迭代器对象。在此生成器函数的内部，可以使用 yield 提供每个条目。

迭代器协议

迭代器协议定义了产生一系列值（无论是有限个还是无限个）的标准方式，当值为有限个时，所有的值都被迭代完毕后，则会返回一个默认返回值。

只有实现了一个拥有以下语义（semantic）的 next() 方法，一个对象才能成为迭代器：

next()

无参数或者接受一个参数的函数，并返回符合 IteratorResult 接口的对象（见下文）。如果在使用迭代器内置的语言特征（例如 for...of）时，得到一个非对象返回值（例如 false 或 undefined），将会抛出 TypeError（"iterator.next() returned a non-object value"）。

所有迭代器协议的方法（next()、return() 和 throw()）都应返回实现 IteratorResult 接口的对象。它必须有以下属性：

done 可选

如果迭代器能够生成序列中的下一个值，则返回 false 布尔值。（这等价于没有指定 done 这个属性。）

如果迭代器已将序列迭代完毕，则为 true。这种情况下，value 是可选的，如果它依然存在，即为迭代结束之后的默认返回值。

value 可选

迭代器返回的任何 JavaScript 值。done 为 true 时可省略。

实际上，两者都不是严格要求的；如果返回没有任何属性的对象，则实际上等价于 { done: false, value: undefined }。

如果一个迭代器返回一个 done: true 的结果，则对任何 next() 的后续调用也返回 done: true，尽管这在语言层面不是强制的。

next 方法可以接受一个值，该值将提供给方法体。任何内置的语言特征都将不会传递任何值。传递给生成器 next 方法的值将成为相应 yield 表达式的值。

可选地，迭代器也实现了 return(value) 和 throw(exception) 方法，这些方法在调用时告诉迭代器，调用者已经完成迭代，并且可以执行任何必要的清理（例如关闭数据库连接）。

return(value) 可选

无参数或者接受一个参数的函数，并返回符合 IteratorResult 接口的对象，其 value 通常等价于传递的 value，并且 done 等于 true。调用这个方法表明迭代器的调用者不打算调用更多的 next()，并且可以进行清理工作。

throw(exception) 可选

无参数或者接受一个参数的函数，并返回符合 IteratorResult 接口的对象，通常 done 等于 true。调用这个方法表明迭代器的调用者监测到错误的状况，并且 exception 通常是一个 Error 实例。

备注：无法通过反射的方法确定（例如，没有实际调用 next() 并验证返回的结果）一个特定的对象是否实现了迭代器协议。

很容易使一个迭代器也可迭代：只需实现 [Symbol.iterator]() 方法，并返回它的 this。

js
// Satisfies both the Iterator Protocol and Iterable
const myIterator = {
  next() {
    // ...
  },
  [Symbol.iterator]() {
    return this;
  },
};

这种对象被称为可迭代迭代器。这样做可以让期望可迭代对象的各类语法使用此类迭代器——因此，在不实现可迭代协议的情况下，仅实现迭代器协议的作用很小。（事实上，几乎所有的语法和 API 都期待可迭代对象，而不是迭代器。）生成器对象是一个例子：

js
const aGeneratorObject = (function* () {
  yield 1;
  yield 2;
  yield 3;
})();

console.log(typeof aGeneratorObject.next);
// "function"——它有 next 方法（返回正确的值），所以它是迭代器

console.log(typeof aGeneratorObject[Symbol.iterator]);
// "function"——它有 [Symbol.iterator]() 方法（返回正确的迭代器），所以它是可迭代的

console.log(aGeneratorObject[Symbol.iterator]() === aGeneratorObject);
// true——它的 [Symbol.iterator]() 方法返回自身（一个迭代器），所以它是一个可迭代的迭代器

然而，可能的情况下，iterable[Symbol.iterator] 最好返回总是从头开始的不同的迭代器，像 Set.prototype[Symbol.iterator]() 做的那样。

异步迭代器和异步可迭代协议

还有一对用于异步迭代的协议，命名为异步迭代器和异步可迭代协议。它们与可迭代和迭代器协议有着非常类似的接口，只是从调用迭代器方法的每个返回值都包装在一个 promise 中。

当对象实现以下方法时，它会实现异步可迭代协议：

[Symbol.asyncIterator]

返回对象的无参数函数，并且符合异步迭代器协议。

当对象实现以下方法时，它会实现异步迭代器协议：

next()

无参数或者接受一个参数的函数，并返回 promise。promise 兑现为一个对象，该对象符合 IteratorResult 接口，并且这些属性与同步迭代器有着相同的语义。

return(value) 可选

无参数或者接受一个参数的函数，并返回 promise。promise 兑现为一个对象，该对象符合 IteratorResult 接口，并且这些属性与同步迭代器有着相同的语义。

throw(exception) 可选

无参数或者接受一个参数的函数，并返回 promise。promise 兑现为一个对象，该对象符合 IteratorResult 接口，并且这些属性与同步迭代器有着相同的语义。

语言和迭代协议之间的交互

JavaScript 语言指定了产生或使用可迭代对象和迭代器的 API。

内置的可迭代对象

String、Array、TypedArray、Map、Set 以及 Intl.Segments 都是内置的可迭代对象，因为它们的每个 prototype 对象都实现了 [Symbol.iterator]() 方法。此外，arguments 对象和一些 DOM 集合类型，如 NodeList 也是可迭代的。目前，没有内置的异步可迭代对象。

生成器函数返回生成器对象，它们是可迭代的迭代器。异步生成器函数返回异步生成器对象，它们是异步可迭代的迭代器。

从内置迭代返回的迭代器实际上都继承了一个公共类（目前尚未暴露），该类实现了上述 [Symbol.iterator]() { return this; } 方法，使它们都是可迭代的迭代器。将来，除了迭代器协议要求的 next() 方法外，这些内置迭代器可能还有其他辅助方法。你可以通过在图形控制台中记录迭代器的原型链来检查它。

console.log([][Symbol.iterator]()); Array Iterator {} [[Prototype]]: Array Iterator ==> This is the prototype shared by all array iterators next: ƒ next() Symbol(Symbol.toStringTag): "Array Iterator" [[Prototype]]: Object ==> This is the prototype shared by all built-in iterators Symbol(Symbol.iterator): ƒ [Symbol.iterator]() [[Prototype]]: Object ==> This is Object.prototype

接受可迭代对象的内置 API

有许多 API 接受可迭代对象。一些例子，包括：

js
const myObj = {};

new WeakSet(
  (function* () {
    yield {};
    yield myObj;
    yield {};
  })(),
).has(myObj); // true

期待迭代对象的语法

一些语句和表达式期望可迭代对象，例如 for...of 循环、数组和参数扩展、yield* 和数组解构：

js
for (const value of ["a", "b", "c"]) {
  console.log(value);
}
// "a"
// "b"
// "c"

console.log([..."abc"]); // ["a", "b", "c"]

function* gen() {
  yield* ["a", "b", "c"];
}

console.log(gen().next()); // { value: "a", done: false }

[a, b, c] = new Set(["a", "b", "c"]);
console.log(a); // "a"

当内置语法迭代迭代器，并且最后的结果中 done 为 false（即迭代器能够生成更多值）但不需要更多值时，如果存在，将调用 return 方法。例如，如果在 for...of 循环中遇到 break 或 return，或者数组解构中的标识符只是有限个的，则可能会发生这种情况。

js
const obj = {
  [Symbol.iterator]() {
    let i = 0;
    return {
      next() {
        i++;
        console.log("Returning", i);
        if (i === 3) return { done: true, value: i };
        return { done: false, value: i };
      },
      return() {
        console.log("Closing");
        return { done: true };
      },
    };
  },
};

const [b] = obj;
// Returning 1
// Closing

const [a, b, c] = obj;
// Returning 1
// Returning 2
// Returning 3
// Already reached the end (the last call returned `done: true`),
// so `return` is not called

for (const b of obj) {
  break;
}
// Returning 1
// Closing

异步生成器函数（但不是同步生成器函数）中的 for await...of 循环和 yield* 是与异步迭代交互的唯一方式。在不是同步迭代的异步迭代对象（即它有 [Symbol.asyncIterator]() 但没有 [Symbol.iterator]()）上使用 for...of、数组展开等将抛出 TypeError：x is not iterable。

不符合标准的可迭代对象

如果一个可迭代对象的 [Symbol.iterator]() 方法不能返回迭代器对象，那么可以认为它是一个不符合标准的（Non-well-formed）可迭代对象。

使用这样的可迭代对象很可能会导致如下的运行时异常，或者不可预料的表现：

js
const nonWellFormedIterable = {};
nonWellFormedIterable[Symbol.iterator] = () => 1;
[...nonWellFormedIterable]; // TypeError: [Symbol.iterator]() returned a non-object value

示例

自定义可迭代对象

你可以像这样创建自己的可迭代对象：

js
const myIterable = {
  *[Symbol.iterator]() {
    yield 1;
    yield 2;
    yield 3;
  },
};

console.log([...myIterable]); // [1, 2, 3]

简单迭代器

迭代器本质上是有状态的。如果你不将其定义为生成器函数（如上例所示），你可能需要将状态封装在闭包中。

js
function makeIterator(array) {
  let nextIndex = 0;
  return {
    next() {
      return nextIndex < array.length
        ? {
            value: array[nextIndex++],
            done: false,
          }
        : {
            done: true,
          };
    },
  };
}

const it = makeIterator(["yo", "ya"]);

console.log(it.next().value); // 'yo'
console.log(it.next().value); // 'ya'
console.log(it.next().done); // true

无穷迭代器

js
function idMaker() {
  let index = 0;
  return {
    next() {
      return {
        value: index++,
        done: false,
      };
    },
  };
}

const it = idMaker();

console.log(it.next().value); // 0
console.log(it.next().value); // 1
console.log(it.next().value); // 2
// ...

使用生成器定义一个可迭代对象

js
function* makeSimpleGenerator(array) {
  let nextIndex = 0;
  while (nextIndex < array.length) {
    yield array[nextIndex++];
  }
}

const gen = makeSimpleGenerator(["yo", "ya"]);

console.log(gen.next().value); // 'yo'
console.log(gen.next().value); // 'ya'
console.log(gen.next().done); // true

function* idMaker() {
  let index = 0;
  while (true) {
    yield index++;
  }
}

const it = idMaker();

console.log(it.next().value); // 0
console.log(it.next().value); // 1
console.log(it.next().value); // 2
// ...

使用类定义一个可迭代对象

状态封装也可以对私有字段进行。

js
class SimpleClass {
  #data;

  constructor(data) {
    this.#data = data;
  }

  [Symbol.iterator]() {
    // Use a new index for each iterator. This makes multiple
    // iterations over the iterable safe for non-trivial cases,
    // such as use of break or nested looping over the same iterable.
    let index = 0;

    return {
      // Note: using an arrow function allows `this` to point to the
      // one of `[Symbol.iterator]()` instead of `next()`
      next: () => {
        if (index < this.#data.length) {
          return { value: this.#data[index++], done: false };
        } else {
          return { done: true };
        }
      },
    };
  }
}

const simple = new SimpleClass([1, 2, 3, 4, 5]);

for (const val of simple) {
  console.log(val); // 1 2 3 4 5
}

重写内置的可迭代对象

例如，String 是一个内置的可迭代对象：

js
const someString = "hi";
console.log(typeof someString[Symbol.iterator]); // "function"

String 的默认迭代器会逐个地返回字符串的代码点：

js
const iterator = someString[Symbol.iterator]();
console.log(`${iterator}`); // "[object String Iterator]"
console.log(iterator.next()); // { value: "h", done: false }
console.log(iterator.next()); // { value: "i", done: false }
console.log(iterator.next()); // { value: undefined, done: true }

你可以提供我们自己的 [Symbol.iterator]() 重新定义迭代行为：

js
// need to construct a String object explicitly to avoid auto-boxing
const someString = new String("hi");

someString[Symbol.iterator] = function () {
  return {
    // this is the iterator object, returning a single element (the string "bye")
    next() {
      return this._first
        ? { value: "bye", done: (this._first = false) }
        : { done: true };
    },
    _first: true,
  };
};

注意，如何使用迭代协议重新定义 [Symbol.iterator]() 以影响内置结构的行为：

js
console.log([...someString]); // ["bye"]
console.log(`${someString}`); // "hi"

参见

帮助改进 MDN

此页面对您有帮助吗？

是否

了解如何参与贡献

此页面最后更新于 2025年7月16日，由 MDN 贡献者更新。

在 GitHub 上查看此页面 • 报告此内容的问题