JavaScript URL API

Введение в URL-объекты JavaScript

JavaScript предоставляет мощный встроенный интерфейс URL для создания, разбора и управления URL-адресами. Вместо того чтобы нарезать строки с помощью регулярных выражений или ручных вызовов split() — которые ломаются в крайних случаях с портами, закодированными символами и отсутствующими компонентами — объект URL разбирает адрес на структурированные, независимо адресуемые части.

Интерфейс URL доступен нативно в браузерах и в Node.js (это глобальный объект, require не нужен). В этом руководстве рассматривается создание и разбор URL, чтение и изменение каждого компонента, работа со строками запросов через URLSearchParams, а также решение типичных практических задач — построение API-запросов и отслеживание ссылок.

Создание и разбор URL с помощью JavaScript

Базовое создание URL

Чтобы создать URL, передайте строку адреса в конструктор URL. Если строка не является допустимым абсолютным URL, конструктор выбрасывает TypeError:

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

Разбор компонентов URL

После создания объекта URL вы можете прочитать любую его часть через соответствующее свойство:

Полный набор компонентов для URL вида https://user:[email protected]:8080/path?q=1#top:

Проверка URL перед разбором

Поскольку конструктор выбрасывает исключение при недопустимых входных данных, сначала проверяйте ненадёжные строки. Статический метод URL.canParse() возвращает boolean-значение без выбрасывания исключений:

Работа с URL-объектами

Работа со строкой запроса через URLSearchParams

Каждый URL предоставляет свойство searchParams — живой объект URLSearchParams, изменения которого сразу отражаются в URL. Это предпочтительный способ редактирования строки запроса, поскольку он берёт на себя кодирование. В примере ниже используется отдельный объект URLSearchParams, чтобы показать, как всё это работает вместе:

На практике промежуточный объект обычно не нужен — можно редактировать url.searchParams напрямую, что изменяет URL на месте:

Повторяющиеся ключи и перебор

Строки запроса могут содержать один и тот же ключ несколько раз (например, ?tag=js&tag=web). Метод get() возвращает только первое совпадение, тогда как getAll() возвращает все значения. Перебрать все пары можно с помощью for...of:

Пояснение

• Инициализация:
  • Объект URL создаётся с базовым URL, который уже содержит параметр запроса (initial=123).
• Объект URLSearchParams:
  • URLSearchParams инициализируется значением url.search, содержащим строку запроса из URL.
• Добавление параметра:
  • Метод .set() используется для добавления нового параметра (key=value) в строку запроса. Если ключ уже существует, его значение обновляется; если нет — пара ключ-значение добавляется.
• Чтение параметра:
  • Метод .get() возвращает значение параметра по указанному ключу (key), которое затем выводится в консоль.
• Удаление параметра:
  • Метод .delete() удаляет параметр по указанному ключу (initial). Это демонстрирует, как удалить параметр из строки запроса.
• Обновление строки запроса URL:
  • После изменения параметров свойство search URL обновляется строковым представлением объекта URLSearchParams.
• Вывод:
  • Наконец, изменённый URL выводится в консоль, демонстрируя результат выполненных операций.

Изменение пути и хэша

Пример JavaScript-кода, показывающего, как изменить pathname и hash URL:

Пояснение

• Инициализация объекта URL:
  • Объект URL создаётся из строки, представляющей полный URL. Этот URL включает путь, строку запроса и хэш-фрагмент.
• Изменение пути:
  • Свойству pathname объекта URL присваивается новый путь (/path/to/resource). Это свойство задаёт путь или маршрут на сервере.
• Изменение хэша:
  • Свойство hash обновляется значением "section". В URL хэш представляет закладку на странице, которая обычно используется для прокрутки к определённому разделу.
• Вывод изменений:
  • Исходный URL выводится до модификаций, чтобы показать начальное состояние.
  • После модификаций выводится новое состояние URL для демонстрации результата изменения pathname и hash.

Расширенное использование URL-объектов

Работа с относительными URL

Объект URL также может разрешать относительные URL относительно базового, что особенно полезно для веб-приложений, работающих с динамическими ссылками:

Работа с кодированием URL

При работе с URL, содержащими символы, требующие кодирования, объект URL обрабатывает их автоматически, обеспечивая допустимость URL:

Для работы с локальными файлами или blob-объектами метод URL.createObjectURL() генерирует временную строку URL, ссылающуюся на объект в памяти, что удобно для предварительного просмотра изображений или загрузки файлов непосредственно из JavaScript.

Практические примеры работы с URL

Отслеживание URL кампаний

URL-объекты можно использовать для эффективного управления URL кампаний, которые широко применяются в цифровом маркетинге для отслеживания эффективности различных маркетинговых усилий:

Интеграция с веб-API

URL-объекты отлично сочетаются с Fetch API: можно передать экземпляр URL напрямую в fetch(), а searchParams гарантирует правильное кодирование строки запроса. После получения ответа его обычно разбирают с помощью методов JSON:

Современная альтернатива (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
}

Типичные ошибки

• Конструктор выбрасывает исключение при недопустимых входных данных. new URL("example.com") завершится ошибкой, поскольку не указан протокол. Предоставьте полный абсолютный URL, передайте базовый URL вторым аргументом или используйте проверку через URL.canParse().
• Относительные строки требуют базового URL. new URL("/about") выбросит исключение самостоятельно; new URL("/about", "https://www.w3docs.com") разрешится корректно.
• origin доступен только для чтения. Нельзя присваивать значение url.origin. Вместо этого изменяйте protocol, hostname или port по отдельности.
• get() возвращает только первое значение. Для ключей, которые могут повторяться, используйте getAll().
• Нормализация выполняется автоматически. Чтение href может добавить завершающий слэш (https://w3docs.com становится https://w3docs.com/) и процентно-кодировать зарезервированные символы. При проверке равенства сравнивайте разобранные URL, а не сырые строки.
• Порядок в searchParams соответствует порядку добавления. Используйте params.sort(), если нужна каноническая, стабильная строка запроса для кэширования или подписи.

Заключение

Объект JavaScript URL — это мощный инструмент для работы со всеми аспектами управления и анализа URL-адресов. Освоив его свойства и методы, разработчики могут упростить взаимодействие своих веб-приложений с URL, улучшив как функциональность, так и пользовательский опыт. Будь то управление сложными структурами URL, интеграция с API или отслеживание маркетинговых кампаний — URL-объект предлагает надёжный и эффективный способ работы с веб-адресами в JavaScript.

Практика