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

CKTIS / JavaScript

HTMLImageElement.src — URL da origem da imagem

HTMLImageElement.src permite ler ou definir o URL de uma imagem. A propriedade reflete o atributo src. Ao ser lida, só devolve um URL absoluto se o valor do atributo puder ser interpretado como URL usando o URL base do documento. Não confirma que a imagem foi carregada.

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

image.src = url;
const resolvedUrl = image.src;

HTMLImageElement.src é uma propriedade de texto gravável do DOM do browser, não do próprio ECMAScript. Reflete o atributo src de um elemento img: atribuir image.src = url altera esse atributo.

Se o atributo existir, a leitura de image.src só devolve um URL absoluto se for possível interpretar o valor do atributo como URL usando o URL base do documento. Se a análise do URL falhar, image.src devolve o valor do atributo como USVString. Qualquer unidade de código substituta UTF-16 sem par, guardada no atributo, por exemplo através de setAttribute, é substituída pelo caráter de substituição U+FFFD na cadeia devolvida. Por exemplo, não é possível resolver icon.png com um URL base opaco do tipo data:. Se o atributo não existir, image.src devolve uma cadeia vazia. Em contrapartida, image.getAttribute("src") devolve o valor guardado do atributo sem resolver o URL, ou null se o atributo estiver ausente.

Alterar src inicia o processamento da origem da imagem, mas não significa que o carregamento termine imediatamente. Trata os eventos load e error, instalando os handlers antes da atribuição. Com srcset ou picture, o recurso selecionado pode ser diferente de src; utiliza currentSrc para consultar o URL do pedido atual.

O exemplo testa apenas a resolução do URL num documento separado com uma base fixa. Não testa a obtenção nem a apresentação da imagem. Executa-o num browser; a presença de Node 24 num repositório não comprova o suporte desta API.

Exemplos

const doc = document.implementation.createHTMLDocument("Demo");
const base = doc.createElement("base");
base.href = "https://example.invalid/assets/";
doc.head.append(base);

const image = doc.createElement("img");
image.src = "icon.png";

console.log(image.getAttribute("src"));
console.log(image.src);

Resultado

icon.png
https://example.invalid/assets/icon.png

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