d3-request

Этот модуль предоставляет удобную альтернативу XMLHttpRequest. Например, для загрузки текстового файла:

d3.text("/path/to/file.txt", function(error, text) {
  if (error) throw error;
  console.log(text); // Hello, world!
});

Для загрузки и разбора файла CSV:

d3.csv("/path/to/file.csv", function(error, data) {
  if (error) throw error;
  console.log(data); // [{"Hello": "world"}, …]
});

Для отправки параметров запроса:

d3.request("/path/to/resource")
    .header("X-Requested-With", "XMLHttpRequest")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .post("a=2&b=3", callback);

Этот модуль имеет встроенную поддержку разбора JSON, CSV и TSV; в браузерах, но не в Node, также поддерживаются HTML и XML. Вы можете разпарсить дополнительные форматы, используя request или text напрямую.

Установка

Если вы используете NPM, npm install d3-request. В противном случае, скачайте последнюю версию. Вы также можете загрузить напрямую с d3js.org, как самостоятельную библиотеку standalone library или как часть D3 4.0. Поддерживаются AMD, CommonJS и обычные среды. В обычной среде экспортируется глобальная переменная d3:

<script src="https://d3js.org/d3-collection.v1.min.js"></script>
<script src="https://d3js.org/d3-dispatch.v1.min.js"></script>
<script src="https://d3js.org/d3-dsv.v1.min.js"></script>
<script src="https://d3js.org/d3-request.v1.min.js"></script>
<script>

d3.csv("/path/to/file.csv", callback);

</script>

Попробуйте d3-request в вашем браузере.

Справочник по API

d3.request(url[, callback]) Source

Возвращает новый запрос request для указанного url. Если callback не указан, возвращаемый request еще не отправлен и может быть далее настроен. Если callback указан, это эквивалентно вызову request.get сразу после создания:

d3.request(url)
    .get(callback);

Если вы хотите указать заголовок запроса или тип MIME, вы не должны указывать callback в конструктор. Используйте request.header или request.mimeType, за которым следует request.get. См. d3.json, d3.csv, d3.tsv, d3.html и d3.xml для конструкторов, удобных для определенных типов содержимого.

request.header(name[, value]) Source

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

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

d3.request(url)
    .header("Accept-Language", "en-US")
    .header("X-Requested-With", "XMLHttpRequest")
    .get(callback);

Примечание: эта библиотека не устанавливает заголовок X-Requested-With по умолчанию на XMLHttpRequest. Некоторые серверы требуют этого заголовка для снижения нежелательных запросов, но наличие заголовка вызывает проверки CORS preflight; при необходимости установите этот заголовок до отправки запроса.

request.mimeType([type]) Source

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

Тип MIME запроса может быть изменен только до того, как запрос отправлен. Поэтому вы не можете передавать callback в конструктор запроса, если хотите переопределить тип MIME; используйте request.get или аналогичное. Например:

d3.request(url)
    .mimeType("text/csv")
    .get(callback);

request.user([value]) Source

Если value указан, устанавливает имя пользователя для аутентификации на указанную строку и возвращает этот экземпляр запроса. Если value не указан, возвращает текущее имя пользователя, которое по умолчанию равно null.

request.password([value]) Source

Если value указан, устанавливает пароль для аутентификации на указанную строку и возвращает этот экземпляр запроса. Если value не указан, возвращает текущий пароль, который по умолчанию равен null.

request.timeout([timeout]) Source

Если timeout указан, устанавливает атрибут timeout запроса на указанное количество миллисекунд и возвращает этот экземпляр запроса. Если timeout не указан, возвращает текущий таймаут ответа, который по умолчанию равен 0.

request.responseType([type]) Source

Если type указан, устанавливает атрибут тип ответа запроса и возвращает этот экземпляр запроса. Типичные значения: (пустая строка), arraybuffer, blob, document, и text. Если type не указан, возвращает текущий тип ответа, который по умолчанию .

request.response(value) Source

Устанавливает функцию значения ответа на указанную функцию и возвращает этот экземпляр запроса. Функция значения ответа используется для отображения объекта XMLHttpRequest ответа на полезное значение данных. См. удобные методы json и text для примеров.

request.get([data][, callback]) Source

Эквивалентно request.send с методом GET:

request.send("GET", data, callback);

request.post([data][, callback]) Source

Эквивалентно request.send с методом POST:

request.send("POST", data, callback);

request.send(method[, data][, callback]) Source

Выполняет этот запрос с указанным method (например, GET или POST), необязательно отправляя указанные data в теле запроса, и возвращает этот экземпляр запроса. Если указан callback, callback будет вызван асинхронно, когда запрос выполнен успешно или неудачно. Callback вызывается с двумя аргументами: ошибка, если есть, и значение ответа. Значение ответа равно undefined, если произошла ошибка. Это эквивалентно:

request
    .on("error", function(error) { callback(error); })
    .on("load", function(xhr) { callback(null, xhr); })
    .send(method, data);

Если callback не указан, то слушатели «load» и «error» должны быть зарегистрированы через request.on.

request.abort() Source

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

request.on(type[, listener]) Source

Если listener указан, устанавливает обработчик событий listener для указанного type и возвращает этот экземпляр запроса. Если обработчик событий был уже зарегистрирован для того же типа, существующий обработчик удаляется перед добавлением нового обработчика. Если listener равен null, удаляет текущего обработчика событий для указанного type (если есть). Если listener не указан, возвращает текущий назначенный обработчик для указанного типа, если есть.

Тип должен быть одним из следующих:

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

Для регистрации нескольких обработчиков для того же type, тип может быть последован именем, например load.foo и load.bar. См. d3-dispatch для подробностей.

d3.csv(url[[, row], callback]) Source

Возвращает новый request для файла CSV по указанному url с типом MIME по умолчанию text/csv. Если callback не указан, это эквивалентно:

d3.request(url)
    .mimeType("text/csv")
    .response(function(xhr) { return d3.csvParse(xhr.responseText, row); });

Если callback указан, отправляется запрос GET, что делает его эквивалентным:

d3.request(url)
    .mimeType("text/csv")
    .response(function(xhr) { return d3.csvParse(xhr.responseText, row); })
    .get(callback);

Необязательная функция преобразования row может быть указана для сопоставления и фильтрации объектов строк до более специфичного представления; см. dsv.parse для подробностей. Например:

function row(d) {
  return {
    year: new Date(+d.Year, 0, 1), // convert "Year" column to Date
    make: d.Make,
    model: d.Model,
    length: +d.Length // convert "Length" column to number
  };
}

Возвращаемый request экспонирует дополнительный метод request.row как альтернативу передаче функции преобразования row в d3.csv, что позволяет настроить запрос перед отправкой. Например, это:

d3.csv(url, row, callback);

Эквивалентно этому:

d3.csv(url)
    .row(row)
    .get(callback);

d3.html(url[, callback]) Source

Возвращает новый запрос для HTML-файла по указанному url с типом MIME по умолчанию text/html. HTML-файл возвращается в виде фрагмента документа. Если обратный вызов не указан, это эквивалентно:

d3.request(url)
    .mimeType("text/html")
    .response(function(xhr) { return document.createRange().createContextualFragment(xhr.responseText); });

Если обратный вызов указан, отправляется запрос GET, что эквивалентно:

d3.request(url)
    .mimeType("text/html")
    .response(function(xhr) { return document.createRange().createContextualFragment(xhr.responseText); })
    .get(callback);

Парсинг HTML требует глобального документа и опирается на DOM Ranges, которые не поддерживаются JSDOM по состоянию на версию 8.3; таким образом, этот метод поддерживается в браузерах, но не в Node.

d3.json(url[, обратный вызов]) Исходный код

Возвращает новый запрос для получения JSON-файла по указанному url с типом MIME по умолчанию application/json. Если обратный вызов не указан, это эквивалентно:

d3.request(url)
    .mimeType("application/json")
    .response(function(xhr) { return JSON.parse(xhr.responseText); });

Если обратный вызов указан, отправляется запрос GET, что эквивалентно:

d3.request(url)
    .mimeType("application/json")
    .response(function(xhr) { return JSON.parse(xhr.responseText); })
    .get(callback);

d3.text(url[, обратный вызов]) Исходный код

Возвращает новый запрос для получения текстового файла по указанному url с типом MIME по умолчанию text/plain. Если обратный вызов не указан, это эквивалентно:

d3.request(url)
    .mimeType("text/plain")
    .response(function(xhr) { return xhr.responseText; });

Если обратный вызов указан, отправляется запрос GET, что эквивалентно:

d3.request(url)
    .mimeType("text/plain")
    .response(function(xhr) { return xhr.responseText; })
    .get(callback);

d3.tsv(url[[, функция преобразования строки], обратный вызов]) Исходный код

Возвращает новый запрос для файла TSV по указанному url с типом MIME по умолчанию text/tab-separated-values. Если обратный вызов не указан, это эквивалентно:

d3.request(url)
    .mimeType("text/tab-separated-values")
    .response(function(xhr) { return d3.tsvParse(xhr.responseText, row); });

Если обратный вызов указан, отправляется запрос GET, что эквивалентно:

d3.request(url)
    .mimeType("text/tab-separated-values")
    .response(function(xhr) { return d3.tsvParse(xhr.responseText, row); })
    .get(callback);

Можно указать необязательную функцию преобразования строки для сопоставления и фильтрации объектов строк до более специфичного представления; см. dsv.parse для получения подробностей. Например:

function row(d) {
  return {
    year: new Date(+d.Year, 0, 1), // convert "Year" column to Date
    make: d.Make,
    model: d.Model,
    length: +d.Length // convert "Length" column to number
  };
}

Возвращаемый запрос предоставляет дополнительный метод request.row как альтернативу передаче функции преобразования строки в d3.tsv, позволяя настроить запрос перед его отправкой. Например, это:

d3.tsv(url, row, callback);

Эквивалентно этому:

d3.tsv(url)
    .row(row)
    .get(callback);

d3.xml(url[, обратный вызов]) Исходный код

Возвращает новый запрос для получения XML-файла по указанному url с типом MIME по умолчанию application/xml. Если обратный вызов не указан, это эквивалентно:

d3.request(url)
    .mimeType("application/xml")
    .response(function(xhr) { return xhr.responseXML; });

Если обратный вызов указан, отправляется запрос GET, что эквивалентно:

d3.request(url)
    .mimeType("application/xml")
    .response(function(xhr) { return xhr.responseXML; })
    .get(callback);

Парсинг XML опирается на xhr.responseXML, который не поддерживается node-XMLHttpRequest по состоянию на версию 1.8; таким образом, этот метод поддерживается в браузерах, но не в Node.