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

CKTIS / JavaScript

String.prototype.padStart — preencher texto à esquerda

String.prototype.padStart preenche o início de uma cadeia até um comprimento indicado, repetindo o preenchimento e, quando necessário, truncando-o. Não altera a cadeia original nem encurta uma cadeia que já tenha comprimento suficiente. O comprimento é medido em unidades de código UTF-16.

Versão: Introduced in ECMAScript 2017 (ES2017) as a standard-library method. Node.js 24 support does not establish browser support.

Sintaxe

str.padStart(maxLength[, fillString])

String.prototype.padStart devolve uma cadeia preenchida à esquerda. O argumento maxLength indica o comprimento pretendido do resultado completo, não o número de caracteres a acrescentar. A cadeia original mantém-se inalterada. O método é útil, por exemplo, para identificadores com zeros à esquerda; converta primeiro os números em cadeias.

O argumento opcional fillString é repetido até atingir o comprimento de preenchimento necessário. O excesso é removido do fim do preenchimento, não da cadeia original. Se fillString for omitido ou se for passado undefined, é utilizado um espaço U+0020. Um preenchimento vazio "" deixa a cadeia inalterada. Se maxLength não exceder o comprimento da cadeia, o método devolve-a sem preenchimento nem truncagem.

maxLength é convertido através de ToLength: as fracções positivas são truncadas para inteiros, enquanto os valores negativos e NaN passam a zero. O comprimento corresponde a unidades de código UTF-16, não a caracteres visíveis nem à largura no ecrã. A truncagem do preenchimento pode separar um par de substitutos; por isso, preenchimentos ASCII simples são adequados para estes identificadores. Chamar o método com null ou undefined como this gera um TypeError.

O método faz parte de ECMAScript 2017 (ES2017), não das Web APIs. A especificação da linguagem não define que versões dos browsers o suportam; verifique typeof String.prototype.padStart === "function" no ambiente de destino. A presença do Node 24 num repositório não comprova o suporte dos browsers.

Exemplos

const id = "42";
console.log(id.padStart(5, "0"));
console.log(id.padStart(7, "ab"));
console.log(JSON.stringify(id.padStart(4)));
console.log(id.padStart(1, "0"));
console.log(id.padStart(5, ""));
console.log(id);

Resultado

00042
ababa42
"  42"
42
42
42

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