-
Notifications
You must be signed in to change notification settings - Fork 1
RU Загрузка внешних ресурсов
Вики ▸ Справка по API ▸ Ядро ▸ Загрузка внешних ресурсов
English | Русский
Вы не можете визуализовывать данные, если вы не можете получить их! К счастью, есть множество способов доставки данных в браузер. Маленькие наборы данных вы можете «зашить» прямо в ваш скрипт, либо же внедрить их в DOM используя data-атрибуты. Большие наборы данных вы можете загрузить как внешний скрипт, определяющий ваши данные как глобальную переменную (типичный пример такого подхода — JSONP). Но самым же универсальным способом загрузки данных является использование объекта XMLHttpRequest, или, сокращённо, XHR. Этот объект позволяет загружать данные асинхронно (так что остальная часть страницы будет отображаться, пока данные загружаются), и он безопаснее, чем JSONP. Модуль xhr библиотеки D3 упрощает загрузку и разбор данных.
При асинхронной загрузке данных, код, зависящий от загружаемых данных, обычно должен находится в функции обратного вызова. Например, посмотрим на календарную визуализацию на сайте D3. Код, который не зависить от данных может запускаться сразу при загрузке страницы. Также вы можете найти удобным сохранение загруженных данных в глобальном пространстве имён, так, что бы вы могди добраться до них позднее, например в процессе перехода. Вы можете использовать для этой цели замыкания, либо просто присвоить загруженные данные в глобальную переменную:
var data; // глобальная переменная
d3.json("path/to/file.json", function(error, json) {
if (error) return console.warn(error);
data = json;
visualizeit();
});По умолчанию большинство браузеров не позволяют выполнять запросы между доменами. Для включения возможности выполнения запросов между доменами сервер должен отдавать заголовок Access-Control-Allow-Origin: *. Для получения дополнительной информации смотрите рекомендации W3C по обмену ресурсами между источниками. При работе в IE9, d3.xhr использует нестандартный объект XDomainRequest для выполнения запросов между доменами.
# d3.xhr(url[, mimeType][, callback])
Создаёт асинхронный запрос на указанный адрес url. Необязательный параметр MIME-типа mimeType может быть указан вторым параметром, например «text/plain». Если указана функция обратного вызова callback, запрос немедленно выполнится с методом GET и функция будет вызвана при загрузке ресурса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и объект XMLHttpRequest, представляющий ответ. Ответ равен undefined, если возникла ошибка. Если ответ содержит неуспешный код статуса, ошибкой будет объект XMLHttpRequest. Если функция обратного вызова не определена, возвращённый запрос может быть запущен методами xhr.get, xhr.post и подобными, а обработчик может быть зарегистрирован через метод xhr.on.
# xhr.header(name[, value])
Если указан параметр value, устанавливает заголовок запроса name в указанное значение. Если value равен null, удаляет заголовок name из запроса. Если параметр value не указан, возвращает текущее значение заголовка name запроса. Имена заголовков нечувствительны к регистру.
Заголовки запроса могут изменяться только до того, как запрос будет отправлен. Поэтому, вы не сможете передать функцию обратного вызова в конструктор d3.xhr, если вы определили заголовок. Вместо этого используете метод xhr.get и аналогичные. Пример:
d3.csv("/path/to/file.csv")
.header("header-name", "header-value")
.get(function(error, data) {
// обратный вызов
});# xhr.mimeType([type])
Если указан параметр type, устанавливает MIME-тип запроса в указанное значение. Если type равен null, сбрасывает текущий MIME-тип, если он был установлен. Если параметр type не указан, возвращает текущий MIME-тип, по умолчанию равный null. MIME-тип также используется для установки заголовка запроса «Accept» и overrideMimeType, если они поддерживаются. Заголовки запроса могут изменяться только до того, как запрос будет отправлен.
# 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. Если указана функция обратного вызова callback, она будет асинхронно вызвана по завершении запроса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и значение ответа. Значение ответа равно undefined, если возникли ошибки. Если функция обратного вызова не определена, должны быть зарегистрированы слушатели на события «load» и «error» через метод xhr.on. Метод является удобной обёрткой над xhr.send.
# xhr.post([data][, callback])
Запускает данный запрос, используя метод POST, передавая необязательные данные data в теле запроса. Если указана функция обратного вызова callback, она будет асинхронно вызвана по завершении запроса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и значение ответа. Значение ответа равно undefined, если возникли ошибки. Если функция обратного вызова не определена, должны быть зарегистрированы слушатели на события «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) {
// обратный вызов
});Пример использования декодирования JSON:
d3.csv("/path/to/file.csv")
.header("Content-Type", "application/json")
.post(JSON.stringify({a: 2, b: 3}), function(error, data) {
// обратный вызов
});# xhr.send(method[, data][, callback])
Запускает данный запрос, используя указанный метод method, передавая необязательные данные data в теле запроса. Если указана функция обратного вызова callback, она будет асинхронно вызвана по завершении запроса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и значение ответа. Значение ответа равно undefined, если возникли ошибки. Если функция обратного вызова не определена, должны быть зарегистрированы слушатели на события «load» и «error» через метод xhr.on.
# xhr.abort()
Прерывает данный запрос, если он в настоящее время выполняется. Смотрите описание метода abort объекта XMLHttpRequest.
# xhr.on(type[, listener])
Добавляет или убирает слушатель событий listener данному запросу указанного типа type. Тип слушателя может быть одним из следующих:
- beforesend — возникает перед отправкой запроса для предоставления возможности установить собственные заголовки.
- progress — для слежения за прогрессом выполнения запроса.
- load — возникает при успешном завершении запроса.
- error — возникает при неуспешном завершении запроса; это понятие включает в себя статусы 4xx и 5xx.
Если слушатель событий уже был зарегистрирован для указанного типа, существующий слушатель будет удалён перед добавлением нового слушателя. Для регистрации нескольких слушателей на однин тип события, за типом может следовать необязательное пространство имён, например, «load.foo» и «load.bar». Для удаления слушателя, передайте null в качестве параметра listener.
Если параметр listener не указан, возвращает текущий назначенный слушатель для указанного типа событий, если он существует.
Довольно часто d3.xhr не используется напрямую. Вместо него используется один из типизированных методов, вроде d3.text для обычного текста, d3.json для JSON, d3.xml для XML, d3.html для HTML, d3.csv для значений, разделённых запятой и d3.tsv для значений, разделённых символом табуляции.
# d3.text(url[, mimeType][, callback])
Создаёт асинхронный запрос для обычного текста на указанный адрес url. Необязательный параметр MIME-типа mimeType может быть указан вторым параметром, например «text/plain». Если указана функция обратного вызова callback, запрос немедленно выполнится с методом GET и функция будет асинхронно вызвана при загрузке ресурса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и текст ответа. Ответ равен undefined, если возникла ошибка. Если функция обратного вызова не определена, возвращённый запрос может быть запущен методами xhr.get и подобными, а обработчик может быть зарегистрирован через метод xhr.on.
# d3.json(url[, callback])
Создаёт асинхронный запрос для JSON-файла на указанный адрес url с MIME-типом «application/json». Если указана функция обратного вызова callback, запрос немедленно выполнится с методом GET и функция будет асинхронно вызвана при загрузке ресурса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и разобранный JSON-ответ. JSON-ответ равен undefined, если возникла ошибка. Если функция обратного вызова не определена, возвращённый запрос может быть запущен методами xhr.get и подобными, а обработчик может быть зарегистрирован через метод xhr.on.
# d3.xml(url[, mimeType][, callback])
Создаёт асинхронный запрос для XML-файла на указанный адрес url. Необязательный параметр MIME-типа mimeType может быть указан вторым параметром, например «application/xml». Если указана функция обратного вызова callback, запрос немедленно выполнится с методом GET и функция будет асинхронно вызвана при загрузке ресурса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и разобранный XML в виде документа. XML-ответ равен undefined, если возникла ошибка. Если функция обратного вызова не определена, возвращённый запрос может быть запущен методами xhr.get и подобными, а обработчик может быть зарегистрирован через метод xhr.on.
# d3.html(url[, callback])
Создаёт асинхронный запрос для HTML-файла на указанный адрес url с MIME-типом «text/html». Если указана функция обратного вызова callback, запрос немедленно выполнится с методом GET и функция будет асинхронно вызвана при загрузке ресурса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и разобранный HTML в виде фрагмента документа. HTML-ответ равен undefined, если возникла ошибка. Если функция обратного вызова не определена, возвращённый запрос может быть запущен методами xhr.get и подобными, а обработчик может быть зарегистрирован через метод xhr.on.
# d3.csv(url[, accessor][, callback])
Создаёт асинхронный запрос для CSV-файла на указанный адрес url с MIME-типом «text/csv». Если указана функция обратного вызова callback, запрос немедленно выполнится с методом GET и функция будет асинхронно вызвана при загрузке ресурса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и массив разобранных строк по RFC 4180. Массив строк равен undefined, если возникла ошибка. Если функция обратного вызова не определена, возвращённый запрос может быть запущен методами xhr.get и подобными, а обработчик может быть зарегистрирован через метод xhr.on.
# d3.tsv(url[, accessor][, callback])
Создаёт асинхронный запрос для TSV-файла на указанный адрес url с MIME-типом «text/tab-separated-values». Если указана функция обратного вызова callback, запрос немедленно выполнится с методом GET и функция будет асинхронно вызвана при загрузке ресурса или при возникновении ошибки; функция принимает два аргумента: ошибка, если есть и массив разобранных строк по RFC 4180. Массив строк равен undefined, если возникла ошибка. Если функция обратного вызова не определена, возвращённый запрос может быть запущен методами xhr.get и подобными, а обработчик может быть зарегистрирован через метод xhr.on.