Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Symbol.iterator — o protocolo de iteração síncrona

Symbol.iterator é o símbolo conhecido que identifica um método que cria um iterador. Permite que um objeto personalizado funcione com for...of e com a sintaxe spread de arrays. Um iterável fornece um iterador, que por sua vez fornece resultados sucessivos através de next().

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

iterable[Symbol.iterator]()
({ [Symbol.iterator]() { return iterator; } })

Symbol.iterator é um símbolo conhecido, não uma função. É a chave do método [Symbol.iterator]() de um objeto iterável (iterable). Este método devolve um iterador utilizado, entre outros, por for...of e pela sintaxe spread de arrays ([...iterable]). A chave de cadeia "Symbol.iterator" não é a mesma chave.

Um iterável fornece este método, enquanto um iterador tem um método next(). Cada chamada a next() tem de devolver um objeto de resultado: done indica se a iteração terminou e value contém o elemento atual enquanto a iteração prossegue. Quando done: true, consumidores como for...of não processam value como um elemento. Ter apenas next() não torna um objeto iterável.

No exemplo, cada chamada a [Symbol.iterator]() cria um contador separado. Por isso, ambas as operações spread produzem 1,2,3. Um iterador não tem de ser, ele próprio, iterável; para o tornar iterável, pode fornecer [Symbol.iterator]() e devolver this. Devolver o mesmo iterador não garante que a iteração recomeça.

Um objeto comum não se torna iterável apenas por ter propriedades. Uma implementação inválida, como devolver um número em vez de um objeto a partir de next(), causa um TypeError quando o protocolo é utilizado. Este mecanismo é síncrono; o protocolo assíncrono utiliza o símbolo separado Symbol.asyncIterator.

Exemplos

const numbers = {
  [Symbol.iterator]() {
    let current = 1;
    return {
      next() {
        if (current <= 3) {
          return { value: current++, done: false };
        }
        return { done: true };
      }
    };
  }
};

console.log([...numbers].join(','));
console.log([...numbers].join(','));

Resultado

1,2,3
1,2,3

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes