O operador deencadeamento opcional?. permite a leitura do valor de uma propriedade localizada internamente em uma cadeia de objetos conectados, sem que a validação de cada referência da cadeia seja expressivamente realizada.

O operador?. funciona de maneira similar ao operador. de encadeamento, exceto que, ao invés de causar um erro se a referência énullish (null ouundefined), a expressão sofre um "curto-circuito" e retorna com um valor deundefined. Quando utilizado com uma chamada de função, retornaundefined se a função executada não existir.

Isso resulta em expressões mais curtas e simples ao acessar propriedades encadeadas quando a possibilidade de uma referência ser inexistente. Isso também pode auxiliar ao explorar o conteúdo de um objeto quando não existe garantia da existência de determinadas propriedades obrigatórias.

Experimente

const adventurer = {  name: "Alice",  cat: {    name: "Dinah",  },};const dogName = adventurer.dog?.name;console.log(dogName);// Expected output: undefinedconsole.log(adventurer.someNonExistentMethod?.());// Expected output: undefined

Sintaxe

obj.val?.propobj.val?.[expr]obj.arr?.[index]obj.func?.(args)

Descrição

O operador de encadeamento opcional provê uma forma de simplificar o acesso a valores através de objetos conectados, quando é possível que uma referência ou função possa serundefined ounull.

Por exemplo, considere um objetoobj que possui uma estrutura aninhada. Sem o encadeamento opcional, verificar proriedades profundamente aninhadas requer uma validação de referências intermediárias, algo como:

let nestedProp = obj.first && obj.first.second;

O valor deobj.first é confirmadamente não-null (e não-undefined) antes de acessar o valor deobj.first.second. Isso previne o erro que ocorreria se você simplesmente acessasseobj.first.second diretamente sem testarobj.first.

Com o operador de encadeamento opcional (?.), entretanto, você não precisa explicitamente testar e aplicar curto-circuito baseado no estado deobj.first antes de tentar acessarobj.first.second:

let nestedProp = obj.first?.second;

Ao utilizar o operador?. ao invés de apenas., o JavaScript sabe que deve implicitamente checar e ter certeza queobj.first não énull ouundefined antes de tentar acessarobj.first.second. Seobj.first énull ouundefined, a expressão automaticamente sofrerá curto-circuito, retornandoundefined.

Isso é equivalente ao seguinte, exceto que a variável temporária, de fato, não é criada:

let temp = obj.first;let nestedProp = temp === null || temp === undefined ? undefined : temp.second;

Encadeamento opcional com chamadas de funções

Você pode usar o encadeamento opcional ao tentar chamar um método que pode não existir. Isso pode auxiliar, por exemplo, ao utilizar uma API em que o método está indisponível, seja pela época da implementação ou por causa de uma funcionalidade que ainda não está disponível no dispositivo do usuário.

Usar encadeamento opcional com chamadas de função faz com que a expressão automaticamente retorneundefined ao invés de lançar uma exceção se o método não é encontrado:

let result = someInterface.customMethod?.();

Lidando com callbacks opcionais ou manipuladores de eventos

Se você usa callbacks ou consulta métodos de objetos comatribuição via desestruturação, você pode ter valores não-existentes que você não conseguirá chamar como funções, a menos que você tenha testado sua existência. Usando?., você pode evitar esse teste extra:

// Escrito como ES2019function doSomething(onContent, onError) {  try {    // ... faz algo com os dados  } catch (err) {    if (onError) {      // teste se onError realmente existe      onError(err.message);    }  }}

// Usando encadeamento opcional com chamadas de funçãofunction doSomething(onContent, onError) {  try {    // ... faz algo com os dados  } catch (err) {    onError?.(err.message); // Nenhuma exceção se onError for undefined  }}

Encadeamento opcional com expressões

Você também pode usar o operador de encadeamento opcional ao acessar propriedades com uma expressão usandoassessores de propriedade:

let nestedProp = obj?.["prop" + "Name"];

Encadeamento opcional não válido no lado esquerdo de uma atribuição

let object = {};object?.property = 1; // Uncaught SyntaxError: Invalid left-hand side in assignment

Acesso a item de Array com encadeamento opcional

let arrayItem = arr?.[42];

Exemplos

Exemplo básico

Esse exemplo busca plo valor da propriedadename para o membrobar em um map quando não existe tal membro. Portanto, o resultado éundefined.

let myMap = new Map();myMap.set("foo", { name: "baz", desc: "inga" });let nameBar = myMap.get("bar")?.name;

Avaliação com curto-circuito

Ao usar o encadeamento opcional com expressões, se o operador do lado esquerdo énull ouundefined, a expressão não será avaliada. Por exemplo:

let potentiallyNullObj = null;let x = 0;let prop = potentiallyNullObj?.[x++];console.log(x); // 0 já que x não foi incrementado

Empilhando o operator de encadeamento opcional

Com estruturadas aninhadas, é possível usar encadeamento opcional múltiplas vezes:

let customer = {  name: "Carl",  details: {    age: 82,    location: "Paradise Falls", // endereço detalhado é desconhecido  },};let customerCity = customer.details?.address?.city;// … isso também funcional com encadeamento opcional em chamada de funçãolet duration = vacations.trip?.getTime?.();

Combinando com o operador de coalescência nula (nullish coalescing)

Ooperador de coalescência nula pode ser usado após o encadeamento opcional, para construir um valor padrão quando nada é encontrado:

let customer = {  name: "Carl",  details: { age: 82 },};const customerCity = customer?.city ?? "Cidade desconhecida";console.log(customerCity); // Cidade desconhecida

Especificações

Compatibilidade com navegadores

Veja também

• ONullish Coalescing Operator
• TC39 proposals