CKTIS / JavaScript
Location: fragmento, origem, caminho, consulta e URL completo
Lê as cinco propriedades do URL de um documento e distingue as atribuições que podem iniciar uma navegação.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const loc = window.location;
loc.hash; // string: fragment
loc.origin; // string: URL origin (read-only)
loc.pathname; // string: path
loc.search; // string: query
loc.href; // string: complete URL
// Assignments on a live Location can initiate navigation:
loc.hash = "intro";
loc.pathname = "/guide";
loc.search = "?mode=demo";
loc.href = "/guide?mode=demo#intro";window.location devolve o objeto Location associado ao documento. É uma API Web do navegador, não uma parte do ECMAScript 2024. O objeto reflete o URL atual do documento, mas uma cadeia de caracteres lida anteriormente não é atualizada. Usa new URL(window.location.href) para examinar ou alterar um URL separado sem navegar.
href é o URL completo serializado. pathname contém apenas o caminho, sem a consulta nem o fragmento. Em HTTP(S), começa por /, mesmo na raiz. Um caminho opaco como blank em about:blank pode não ter uma barra inicial. search devolve uma consulta não vazia precedida de ?, e hash um fragmento não vazio precedido de #. Se o componente não existir ou estiver vazio, o resultado é "", mesmo que o delimitador ainda apareça em href. A leitura não descodifica as sequências codificadas com %. Usa new URLSearchParams(window.location.search) para ler os parâmetros da consulta individualmente.
origin é só de leitura e descreve a origem do URL. Em HTTP(S), inclui o esquema, o nome do anfitrião e a porta, se esta não for a predefinida. Uma origem opaca do URL é serializada como a cadeia "null", não como o valor null. Já self.origin descreve a origem do ambiente de execução: um documento about:blank pode herdá-la. Duas cadeias "null" iguais não provam que as origens sejam iguais.
Atribuir um valor a href pode iniciar uma navegação para outro URL, mesmo relativo. Se a análise do URL falhar, é lançada uma DOMException com o nome SyntaxError. Atribuir um valor a pathname ou search pode iniciar uma navegação com um caminho ou uma consulta diferentes. A atribuição a pathname não tem efeito se o caminho for opaco. Os prefixos ? e # são opcionais ao escrever em search e hash, respetivamente. search = "" remove a consulta, mas hash = "" pode deixar um # no fim. Alterar apenas o fragmento normalmente não carrega um novo documento.
A leitura de qualquer destas cinco propriedades numa janela de outra origem pode lançar uma DOMException com o nome SecurityError. A escrita em href é uma exceção: pode ser permitida sem acesso de leitura, mas as restrições de navegação do navegador continuam a aplicar-se.
Exemplos
const { hash, origin, pathname, search, href } = new URL("about:blank?mode=demo#intro");
console.log(JSON.stringify({ hash, origin, pathname, search, href }));Resultado
{"hash":"#intro","origin":"null","pathname":"blank","search":"?mode=demo","href":"about:blank?mode=demo#intro"}Executa o código em Node.js. O código lê os mesmos componentes do URL num objeto `URL`, em vez de num objeto `Location` do navegador, sem iniciar uma navegação. No resultado, `"null"` é uma cadeia de caracteres e `blank` não começa por `/`.
Lições relacionadas
- JavaScript · Lição 38 · Avançado · Versão: 4