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

CKTIS / JavaScript

Uint8ClampedArray — bytes com valores limitados

Uint8ClampedArray é um array tipado que armazena números inteiros de 0 a 255. Ao escrever, limita os valores a esse intervalo e arredonda as fracções, em vez de os fazer voltar ao início como acontece com Uint8Array.

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

new Uint8ClampedArray(length)
new Uint8ClampedArray(values)
new Uint8ClampedArray(buffer)
new Uint8ClampedArray(buffer, byteOffset)
new Uint8ClampedArray(buffer, byteOffset, length)

Uint8ClampedArray é um tipo padrão de ECMAScript: uma vista sobre um buffer cujos elementos ocupam um byte cada e representam números inteiros sem sinal de 0 a 255. Os valores lidos são do tipo Number; não é um Array normal.

As escritas aplicam ToUint8Clamp: os valores abaixo de 0 passam a 0, e os acima de 255 passam a 255. As fracções são arredondadas para o número inteiro mais próximo; em caso de empate exacto, arredonda-se para o número inteiro par. Assim, 2.5 passa a 2 e 3.5 a 4. Esta regra é diferente de Math.round. NaN passa a 0, Infinity a 255 e -Infinity a 0. Uint8Array, por sua vez, trunca as fracções e faz os números inteiros voltar ao início módulo 256.

new Uint8ClampedArray(length) cria elementos preenchidos com zeros, enquanto new Uint8ClampedArray(values) copia e converte os valores. A forma com buffer cria uma vista sobre a memória existente, sem copiar; só criar a vista não converte os bytes armazenados. O construtor requer new.

O exemplo mostra a limitação e o arredondamento durante a construção e uma atribuição posterior. A limitação aplica-se às escritas nos elementos, não aos cálculos efectuados sobre números lidos do array. É uma funcionalidade da linguagem, não uma API do browser; a especificação não é uma tabela de compatibilidade dos browsers.

Exemplos

const values = new Uint8ClampedArray([-20, 2.5, 3.5, 300, NaN]);
values[0] = 260;
console.log(JSON.stringify(Array.from(values)));

Resultado

[255,2,4,255,0]

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