String.prototype.charCodeAt()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

O método charCodeAt() retorna um número inteiro entre 0 e 65535 que representa a unidade de código UTF-16 no índice fornecido. A unidade de código UTF-16 corresponde ao ponto de código Unicode para pontos de códigos representáveis em uma única unidade de código UTF-16, mas também pode ser a primeira unidade de código de um par substituto não representável em uma única unidade de código UTF-16. Po exemplo: pontos de código Unicode > (0x10000). Se você quer o valor do ponto de código inteiro, use codePointAt().

Sintaxe

str.charCodeAt(index)

Parâmetros

index

Um inteiro maior ou igual a 0 e menor que o comprimento da string. Se não for um número, o padrão será 0.

Valor retornado

Um número representando o valor de unidade de código UTF-16 do caractere no índice fornecido. O valor NaN é retornado se o índice estiver fora do intervalo aceitável.

Descrição

Os pontos de código Unicode variam de 0 a 1114111 (0x10FFFF). Os primeiros 128 pontos de código Unicode são uma correspondência direta da codificação de caracteres ASCII. (Para informações sobre Unicode, veja o JavaScript Guide.)

Nota: O charCodeAt() sempre retornará um valor menor do que 65536. Isso ocorre pois os pontos de código mais altos são representados por um par de pseudo-caracteres "substitutos" (de menor valor) que são usados para compreender o caracter real.

Por isso, para examinar (ou reproduzir) o caractere completo para valores de caracteres individuais de valor 65536 e acima, é necessário recuperar não apenas o charCodeAt(i), mas também o charCodeAt(i+1) (como se examinando/reproduzindo a string com duas letras), ou usar o codePointAt(i). Veja o exemplo 2 e 3 (abaixo).

Compatibilidade com versões anteriores: Em versões históricas (como JavaScript 1.2) o método charCodeAt() retorna um número indicando o valor de conjunto de códigos ISO-Latin-1 do caractere no dado índice. O conjunto de códigos ISO-Latin-1 varia de 0 a 255. Os primeiros 128 (do 0 ao 127) são uma correspondência direta ao conjunto de caracteres ASCII.

Exemplos

Usando charCodeAt()

O exemplo a seguir retorna 65, o valor Unicode para A.

js
"ABC".charCodeAt(0); // retorna 65

Corrigindo o charCodeAt() para manipular caracteres de Plano Multilingual não Básico se sua presença na string é desconhecida

Essa versão pode ser usada em loops for e afins quando não sabemos se caracteres de Plano Multilingual não Básico existem antes da posição do índice especificado.

js
function fixedCharCodeAt(str, idx) {
  // ex. fixedCharCodeAt('\uD800\uDC00', 0); // 65536
  // ex. fixedCharCodeAt('\uD800\uDC00', 1); // false
  idx = idx || 0;
  var code = str.charCodeAt(idx);
  var hi, low;

  // Substituto elevado (poderia mudar o último hex para 0xDB7F para tratar
  // substitutos privados elevados como caracteres únicos)
  if (0xd800 <= code && code <= 0xdbff) {
    hi = code;
    low = str.charCodeAt(idx + 1);
    if (isNaN(low)) {
      throw "High surrogate not followed by low surrogate in fixedCharCodeAt()";
    }
    return (hi - 0xd800) * 0x400 + (low - 0xdc00) + 0x10000;
  }
  if (0xdc00 <= code && code <= 0xdfff) {
    // Low surrogate
    // Retornamos false para permitir os loops pularem essa iteração já que já deveria
    //ter tratado os substitutos elevados acima, na iteração anterior
    return false;
    /*hi = str.charCodeAt(idx - 1);
    low = code;
    return ((hi - 0xD800) * 0x400) + (low - 0xDC00) + 0x10000;*/
  }
  return code;
}

Especificações

Specification
ECMAScript® 2025 Language Specification
# sec-string.prototype.charcodeat
Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
charCodeAt

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Veja também