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

CKTIS / JavaScript

URL.hash e URL.href: fragmento e URL completo

Usa `hash` para ler ou alterar o fragmento e `href` para ler ou substituir o URL completo. Ler apenas `hash` não permite distinguir um fragmento vazio de um fragmento ausente.

Versão: Current web platform; runtime support varies

Sintaxe

const url = new URL(input, base); // Omit base for an absolute input.
url.hash;                        // Fragment string
url.hash = fragment;
url.href;                        // Full serialized URL
url.href = absoluteUrl;

hash e href são propriedades de instância de URL, não métodos nem propriedades estáticas. url.hash devolve o fragmento não vazio com o # inicial, ou "" quando o fragmento está vazio ou não existe. url.href devolve o URL serializado completo, incluindo a cadeia de consulta, se existir. Um # final em href distingue um fragmento vazio de um fragmento ausente.

Atribui a url.hash o texto do fragmento com ou sem # inicial. Os caracteres que o exigem, como os espaços, são codificados com percentagem, mas não são descodificados automaticamente na leitura. url.hash = "" remove o fragmento; url.hash = "#" deixa um fragmento vazio. O fragmento é distinto da consulta: url.searchParams trata dos parâmetros da consulta, e o fragmento não é enviado automaticamente para o servidor num pedido HTTP.

Atribuir um valor a url.href analisa o novo valor e substitui o URL completo no mesmo objeto. Se a análise falhar, é lançada uma exceção TypeError. O setter não resolve referências relativas em relação ao URL atual; para isso, usa new URL(relative, base).href com uma base válida.

Alterar um objeto URL não desencadeia navegação, ao contrário de uma atribuição a window.location.href. Antes de navegar para um URL não fiável, verifica se o esquema e a origem são permitidos: uma análise bem-sucedida não torna o URL seguro. URL é uma API da plataforma Web, não faz parte de ECMAScript 2024; a disponibilidade depende do ambiente de execução.

Exemplos

{
  const url = new URL("https://example.com/guide?lang=en");
  const show = () => console.log(JSON.stringify([url.hash, url.href]));

  url.hash = "quick start";
  show();

  url.hash = "#";
  show();

  url.hash = "";
  show();

  url.href = "https://example.org/start#intro";
  show();
}

Resultado

["#quick%20start","https://example.com/guide?lang=en#quick%20start"]
["","https://example.com/guide?lang=en#"]
["","https://example.com/guide?lang=en"]
["#intro","https://example.org/start#intro"]

Cada linha mostra `[hash, href]`. Repara em `%20`, no `#` final apenas na segunda linha e na substituição do URL completo na última.

Lições relacionadas

  • JavaScript · Lição 30 · Avançado · Versão: 4

Fontes