API URL de JavaScript

Introducción a los objetos URL de JavaScript

JavaScript proporciona una poderosa interfaz URL integrada para construir, analizar y manipular URLs. En lugar de dividir cadenas con expresiones regulares o llamadas manuales a split() — que fallan en casos extremos como puertos, caracteres codificados y componentes faltantes — el objeto URL analiza una dirección en partes estructuradas e individualmente accesibles.

La interfaz URL está disponible de forma nativa en navegadores y en Node.js (es global, no se necesita require). Esta guía explica cómo crear y analizar URLs, leer y modificar cada componente, trabajar con cadenas de consulta mediante URLSearchParams, y manejar tareas comunes del mundo real como la construcción de solicitudes a API y el seguimiento de enlaces.

Creación y análisis de URLs con JavaScript

Creación básica de URL

Para crear una URL, pasa la cadena de dirección al constructor URL. Si la cadena no es una URL absoluta válida, el constructor lanza un TypeError:

const url = new URL("https://www.w3docs.com");

Análisis de componentes de URL

Una vez creado el objeto URL, puedes leer cualquier parte de él a través de una propiedad dedicada:

El conjunto completo de componentes para una URL como https://user:[email protected]:8080/path?q=1#top es:

Validar una URL antes de analizarla

Dado que el constructor lanza un error con entradas inválidas, valida primero las cadenas no confiables. El método estático URL.canParse() devuelve un boolean sin lanzar excepciones:

Manipulación de objetos URL

Trabajo con la cadena de consulta mediante URLSearchParams

Cada URL expone una propiedad searchParams — un objeto URLSearchParams en vivo cuyos cambios se escriben directamente de vuelta a la URL. Esta es la forma preferida de editar una cadena de consulta, ya que gestiona la codificación por ti. El ejemplo siguiente usa un URLSearchParams separado para mostrar cómo encajan las piezas:

En la práctica, normalmente se omite el objeto intermedio y se edita url.searchParams directamente — esto muta la URL en su lugar:

Claves repetidas e iteración

Las cadenas de consulta pueden contener la misma clave más de una vez (por ejemplo ?tag=js&tag=web). get() devuelve solo la primera coincidencia, mientras que getAll() devuelve todos los valores. También puedes recorrer todos los pares con for...of:

Explicación

• Inicialización:
  • El objeto URL se crea con una URL base que ya incluye un parámetro de consulta (initial=123).
• Objeto URLSearchParams:
  • URLSearchParams se inicializa con url.search, que contiene la cadena de consulta de la URL.
• Añadir un parámetro:
  • El método .set() se usa para añadir un nuevo parámetro (key=value) a la cadena de consulta. Si la clave ya existe, su valor se actualiza; si no, el par clave-valor se agrega.
• Leer un parámetro:
  • El método .get() recupera el valor del parámetro especificado por la clave (key), que luego se muestra en la consola.
• Eliminar un parámetro:
  • El método .delete() elimina el parámetro especificado por la clave (initial). Esto demuestra cómo eliminar un parámetro de la cadena de consulta.
• Actualizar la búsqueda de la URL:
  • Tras modificar los parámetros, la propiedad search de la URL se actualiza con la representación en string del objeto URLSearchParams.
• Salida:
  • Finalmente, la URL modificada se muestra en la consola, evidenciando el efecto de las operaciones.

Modificar la ruta y el hash

A continuación se muestra un fragmento de JavaScript que ilustra cómo modificar el pathname y el hash de una URL:

Explicación

• Inicialización del objeto URL:
  • El objeto URL se crea inicialmente a partir de una cadena que representa una URL completa. Esta URL incluye un pathname, una cadena de consulta y un fragmento hash.
• Modificar el Pathname:
  • La propiedad pathname del objeto URL se establece en una nueva ruta (/path/to/resource). Esta propiedad especifica la ruta o ruta en el servidor.
• Modificar el Hash:
  • La propiedad hash se actualiza a "section". En las URLs, el hash representa un marcador dentro de la página, frecuentemente usado para desplazarse a una sección específica.
• Registro de cambios:
  • La URL original se registra antes de las modificaciones para mostrar el estado inicial.
  • Tras las modificaciones, se registra el nuevo estado de la URL para demostrar los efectos de cambiar pathname y hash.

Uso avanzado de objetos URL

Manejo de URLs relativas

El objeto URL también puede resolver URLs relativas frente a una URL base, lo que resulta especialmente útil en aplicaciones web que trabajan con enlaces dinámicos:

Trabajo con codificación de URL

Al trabajar con URLs que incluyen caracteres que necesitan codificación, el objeto URL los gestiona automáticamente, garantizando que las URLs sean válidas:

Para manejar archivos locales o blobs, URL.createObjectURL() genera una cadena URL temporal que referencia el object en memoria, lo cual es útil para previsualizar imágenes o descargar archivos directamente desde JavaScript.

Ejemplos prácticos de manipulación de URL

Seguimiento de URLs de campaña

Puedes usar objetos URL para gestionar eficazmente las URLs de campaña, que se utilizan habitualmente en marketing digital para rastrear el rendimiento de distintos esfuerzos de marketing:

Integración con Web APIs

Los objetos URL se combinan de forma natural con la Fetch API: puedes pasar una instancia URL directamente a fetch(), y searchParams garantiza que la cadena de consulta esté correctamente codificada. Una vez resuelta la solicitud, normalmente se analiza la respuesta con los métodos JSON:

Alternativa moderna (async/await):

async function fetchPosts() {
  const apiUrl = new URL("https://jsonplaceholder.typicode.com/posts");
  apiUrl.searchParams.set("userId", "1");
  const response = await fetch(apiUrl);
  const data = await response.json();
  console.log(data[0]); // Outputs the first post by user with userId 1
}

Errores comunes

• El constructor lanza un error con entrada inválida. new URL("example.com") falla porque no tiene protocolo. Proporciona una URL absoluta completa, pasa una URL base como segundo argumento, o protégete con URL.canParse().
• Las cadenas relativas necesitan una base. new URL("/about") lanza un error por sí sola; new URL("/about", "https://www.w3docs.com") resuelve correctamente.
• origin es de solo lectura. No puedes asignar a url.origin. Cambia protocol, hostname o port individualmente.
• get() devuelve solo el primer valor. Para claves que pueden repetirse, usa getAll().
• La normalización es automática. Leer href puede añadir una barra diagonal al final (https://w3docs.com se convierte en https://w3docs.com/) y codificar en porcentaje los caracteres reservados. Compara URLs analizadas, no cadenas sin procesar, al comprobar la igualdad.
• El orden de searchParams es el orden de inserción. Usa params.sort() si necesitas una cadena de consulta canónica y estable para caché o firma.

Conclusión

El objeto URL de JavaScript es una herramienta robusta para gestionar todos los aspectos de la manipulación y el análisis de URLs. Al dominar sus propiedades y métodos, los desarrolladores pueden optimizar la interacción de su aplicación web con las URLs, mejorando tanto la funcionalidad como la experiencia del usuario. Ya sea que gestiones estructuras de URL complejas, te integres con APIs o rastrées campañas de marketing, el objeto URL ofrece una forma fiable y eficiente de trabajar con direcciones web en JavaScript.

Práctica