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

CKTIS / JavaScript

String — conversão explícita em texto

String(value) converte um valor numa cadeia primitiva. Quando chamada sem argumentos, a função devolve uma cadeia vazia. Se a conversão for bem-sucedida, new String(value) cria um objeto wrapper em vez de um valor primitivo.

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

String(value)
String()
new String(value)

String é uma função incorporada do ECMAScript, não uma API do navegador. A chamada String(value) devolve uma cadeia primitiva se a conversão for bem-sucedida. O tipo String representa sequências imutáveis de unidades de código de 16 bits, normalmente interpretadas como UTF-16; uma letra visível ou outro carácter não corresponde necessariamente a uma única unidade de código.

A omissão do argumento é diferente de passar undefined: String() devolve "", mas String(undefined) devolve "undefined". Do mesmo modo, String(null) produz "null" e String(42) produz "42". Um argumento Symbol direto recebe um tratamento especial: String(Symbol("tag")) devolve "Symbol(tag)".

Este tratamento especial aplica-se apenas às chamadas sem new: new String(Symbol("tag")) lança uma exceção TypeError em vez de criar um objeto wrapper. Se a conversão for bem-sucedida, new String(value) cria um objeto wrapper. Assim, typeof String("hello") produz "string", enquanto typeof new String("hello") produz "object". A comparação estrita destes valores com === produz false. Para uma conversão normal em texto, utiliza String(value) sem new.

A conversão de um objeto pode invocar os seus próprios mecanismos de conversão, como [Symbol.toPrimitive] ou toString, e pode lançar uma exceção. String(value) não é serialização JSON nem uma forma de apresentar com segurança objetos arbitrários não fiáveis sem executar o respetivo código.

Exemplos

console.log(JSON.stringify([String(), String(undefined), String(null), String(42)]));
console.log(String(Symbol("tag")));
const text = String("hello");
const wrapped = new String("hello");
console.log(typeof text, typeof wrapped);
console.log(text === wrapped);

Resultado

["","undefined","null","42"]
Symbol(tag)
string object
false

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