Запросы

Справочник API ▸ Основной ▸ Запросы

Вы не сможете визуализировать данные, если не сможете к ним получить доступ! К счастью, существует множество способов получения данных в браузер. Для небольших наборов данных вы можете жестко закодировать данные в своём скрипте или встроить данные в DOM, используя атрибуты данных. Для больших наборов данных вы можете загрузить внешний скрипт, который определяет ваши данные как глобальную переменную. (JSONP — это распространённый пример.) Но наиболее универсальным способом загрузки данных в браузер является использование XMLHttpRequest или XHR. Это позволяет загружать данные асинхронно (чтобы остальная часть страницы могла отображаться во время загрузки данных) и безопаснее, чем JSONP. Модуль xhr библиотеки D3 упрощает загрузку и обработку данных.

При асинхронной загрузке данных код, зависящий от загруженных данных, обычно должен находиться внутри функции обратного вызова. Например, см. визуализацию календаря на веб-сайте D3. Код, не зависящий от данных, может выполняться сразу после загрузки страницы. Кроме того, вам может быть удобно сохранять загруженные данные в глобальном пространстве имён, чтобы вы могли получить к ним доступ после начального рендеринга, например, во время перехода. Вы можете сделать это с помощью замыканий или просто назначить загруженные данные глобальной переменной:

var data; // a global

d3.json("path/to/file.json", function(error, json) {
  if (error) return console.warn(error);
  data = json;
  visualizeit();
});

По умолчанию большинство браузеров не позволяют осуществлять запросы к другим доменам. Чтобы разрешить запросы к другим доменам, на сервере необходимо установить заголовок Access-Control-Allow-Origin. Более подробную информацию см. в рекомендациях W3C по Cross-Origin Resource Sharing. Для IE9 d3.xhr использует нестандартный XDomainRequest для междоменных запросов. Обратите внимание, что для отправки учётных данных запрос необходимо дополнить параметром .on("beforesend", function (request) {request.withCredentials = true;}), а не .headers("withCredentials", "true")

XHR

d3.xhr(url[, mimeType][, callback])

Создаёт асинхронный запрос для указанного url. В качестве второго аргумента можно указать необязательный тип MIME, например, "text/plain". Если указан обратный вызов, запрос немедленно отправляется методом GET, и обратный вызов вызывается асинхронно при загрузке ресурса или ошибке запроса; обратный вызов вызывается с двумя аргументами: ошибкой, если таковая имеется, и объектом XMLHttpRequest, представляющим ответ. Ответ не определён, если произошла ошибка. Если ответ имеет код состояния неудачи, ошибка — это объект XMLHttpRequest. Если обратный вызов не указан, возвращаемый запрос можно выполнить с помощью xhr.get, xhr.post или аналогичных методов и обработать с помощью xhr.on.

xhr.header(name[, value])

Если значение указано, устанавливает заголовок запроса с указанным именем на указанное значение. Если значение равно null, удаляет заголовок запроса с указанным именем. Если значение не указано, возвращает текущее значение заголовка запроса с указанным именем. Имена заголовков нечувствительны к регистру.

Заголовки запроса можно изменять только до отправки запроса send. Поэтому вы не можете передать обратный вызов в конструктор d3.xhr, если хотите указать заголовок. Вместо этого используйте xhr.get или аналогичные методы. Например:

d3.csv("/path/to/file.csv")
    .header("header-name", "header-value")
    .get(function(error, data) {
      // callback
    });

xhr.mimeType([type])

Если type указан, устанавливает тип MIME запроса на указанное значение. Если type равен null, очищает текущий тип MIME, если таковой имеется. Если type не указан, возвращает текущий тип MIME, который по умолчанию равен null. Тип MIME используется для установки заголовка запроса "Accept" и для "Accept" request header и для overrideMimeType, где это поддерживается. Заголовки запроса можно изменять только до отправки запроса send.

xhr.responseType(type)

Если type указан, устанавливает тип ответа, например, "", "arraybuffer", "blob", "document" или "text". Если type не указан, возвращает текущий тип ответа, который по умолчанию равен "".

xhr.response(value)

Если value указан, устанавливает функцию значения ответа на указанную функцию. Если value не указан, возвращает текущую функцию значения ответа, которая по умолчанию — функция тождественного преобразования. Функция значения ответа используется для сопоставления объекта ответа XMLHttpRequest с его связанным значением данных. Например, для текстовых запросов вы можете использовать function(request) { return request.responseText; }, а для запросов JSON — function(request) { return JSON.parse(request.responseText); }.

xhr.get([callback])

Отправляет этот запрос с помощью метода GET. Если указан обратный вызов, он вызывается асинхронно при завершении или ошибке запроса; обратный вызов вызывается с двумя аргументами: ошибкой, если таковая имеется, и значением ответа. Значение ответа не определено, если произошла ошибка. Если обратный вызов не указан, необходимо зарегистрировать слушатели "load" и "error" с помощью xhr.on. Этот метод является удобной оболочкой для xhr.send.

xhr.post([data][, callback])

Отправляет этот запрос с помощью метода POST, при необходимости отправляя указанные данные в теле запроса. Если указан обратный вызов, он вызывается асинхронно при завершении или ошибке запроса; обратный вызов вызывается с двумя аргументами: ошибкой, если таковая имеется, и значением ответа. Значение ответа не определено, если произошла ошибка. Если обратный вызов не указан, необходимо зарегистрировать слушатели "load" и "error" с помощью xhr.on. Этот метод является удобной оболочкой для xhr.send.

Пример использования кодирования URL:

d3.csv("/path/to/file.csv")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .post("a=2&b=3", function(error, data) {
      // callback
    });

Пример использования кодирования JSON:

d3.csv("/path/to/file.csv")
    .header("Content-Type", "application/json")
    .post(JSON.stringify({a: 2, b: 3}), function(error, data) {
      // callback
    });

xhr.send(method[, data][, callback])

Отправляет этот запрос с указанным методом, при необходимости отправляя указанные данные в теле запроса. Если указан обратный вызов, он вызывается асинхронно при завершении или ошибке запроса; обратный вызов вызывается с двумя аргументами: ошибкой, если таковая имеется, и значением ответа. Значение ответа не определено, если произошла ошибка. Если обратный вызов не указан, необходимо зарегистрировать слушатели "load" и "error" с помощью xhr.on.

xhr.abort()

Прерывает этот запрос, если он в данный момент выполняется. См. abort XMLHttpRequest.

xhr.on(type[, listener])

Добавляет или удаляет обработчик событий listener для этого запроса для указанного типа. Тип должен быть одним из следующих:

• beforesend - перед отправкой запроса, чтобы можно было установить пользовательские заголовки и т. п.
• progress - для мониторинга прогресса запроса.
• load - когда запрос завершается успешно.
• error - когда запрос завершается неудачно; это включает коды ответов 4xx и 5xx.

Если обработчик событий уже был зарегистрирован для того же типа, существующий обработчик удаляется перед добавлением нового. Для регистрации нескольких обработчиков событий для того же типа события тип может быть дополнен необязательным пространством имён, например "load.foo" и "load.bar". Для удаления обработчика в качестве обработчика передайте null.

Если listener не указан, возвращает текущего обработчика для указанного типа, если таковой имеется.

Удобные методы

Часто d3.xhr не используется напрямую. Вместо этого используется один из методов, специфичных для типа, например, d3.text для простого текста, d3.json для JSON, d3.xml для XML, d3.html для HTML, d3.csv для CSV и d3.tsv для TSV.

d3.text(url[, mimeType][, callback])

Создаёт запрос для текстового файла по указанному url. Необязательный тип MIME можно указать в качестве второго аргумента, например, "text/plain". Если указан обратный вызов, запрос немедленно отправляется методом GET, и обратный вызов вызывается асинхронно при загрузке файла или ошибке запроса; обратный вызов вызывается с двумя аргументами: ошибкой, если таковая имеется, и текстом ответа. Текст ответа не определён, если произошла ошибка. Если обратный вызов не указан, возвращаемый запрос можно выполнить с помощью xhr.get или аналогичных методов и обработать с помощью xhr.on.

d3.json(url[, callback])

Создаёт запрос для файла JSON по указанному url с типом MIME "application/json". Если указан обратный вызов, запрос немедленно отправляется методом GET, и обратный вызов вызывается асинхронно при загрузке файла или ошибке запроса; обратный вызов вызывается с двумя аргументами: ошибкой, если таковая имеется, и обработанным JSON. Обработанный JSON не определён, если произошла ошибка. Если обратный вызов не указан, возвращаемый запрос можно выполнить с помощью xhr.get или аналогичных методов и обработать с помощью xhr.on.

d3.xml(url[, mimeType][, callback])

Создаёт запрос для файла XML по указанному url. Необязательный тип MIME можно указать в качестве второго аргумента, например, "application/xml". Если указан обратный вызов, запрос немедленно отправляется методом GET, и обратный вызов вызывается асинхронно при загрузке файла или ошибке запроса; обратный вызов вызывается с двумя аргументами: ошибкой, если таковая имеется, и обработанным XML в виде документа. Обработанный XML не определён, если произошла ошибка. Если обратный вызов не указан, возвращаемый запрос можно выполнить с помощью xhr.get или аналогичных методов и обработать с помощью xhr.on.

d3.html(url[, callback])

Создаёт запрос для HTML-файла по указанному url с типом MIME "text/html". Если указан обратный вызов, запрос немедленно отправляется методом GET, и обратный вызов вызывается асинхронно при загрузке файла или ошибке запроса; обратный вызов вызывается с двумя аргументами: ошибкой, если таковая имеется, и обработанным HTML в виде фрагмента документа. Обработанный HTML не определён, если произошла ошибка. Если обратный вызов не указан, возвращаемый запрос можно выполнить с помощью xhr.get или аналогичных методов и обработать с помощью xhr.on.

d3.csv(url[, accessor][, callback])

Создаёт запрос на файл CSV по указанному url с типом MIME "text/csv". Если указан callback, запрос немедленно отправляется методом GET, и callback вызывается асинхронно при загрузке файла или ошибке запроса; callback вызывается с двумя аргументами: ошибкой, если таковая имеется, и массивом разпарсенных строк в соответствии с RFC 4180. Массив строк не определён, если произошла ошибка. Если callback не указан, возвращённый запрос можно отправить с помощью xhr.get или аналогичной функции и обработать с помощью xhr.on.

d3.tsv(url[, accessor][, callback])

Создаёт запрос на файл TSV по указанному url с типом MIME "text/tab-separated-values". Если указан callback, запрос немедленно отправляется методом GET, и callback вызывается асинхронно при загрузке файла или ошибке запроса; callback вызывается с двумя аргументами: ошибкой, если таковая имеется, и массивом разпарсенных строк в соответствии с RFC 4180. Массив строк не определён, если произошла ошибка. Если callback не указан, возвращённый запрос можно отправить с помощью xhr.get или аналогичной функции и обработать с помощью xhr.on.