CSV

Ссылка на API ▸ CSV

Библиотека D3 предоставляет встроенную поддержку для парсинга значений, разделённых запятыми, значений, разделённых табуляцией, и значений, разделённых произвольным разделителем. Эти табличные форматы популярны в программах для работы со электронными таблицами, таких как Microsoft Excel. Табличные форматы часто более эффективны с точки зрения использования памяти, чем JSON, что может улучшить время загрузки больших наборов данных.

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

Отправляет HTTP-запрос GET для файла значений, разделённых запятыми (CSV), по указанному адресу url. Содержимое файла предполагается совместимым со спецификацией RFC4180. Тип MIME запроса будет «text/csv». Запрос обрабатывается асинхронно, так что этот метод возвращает результат сразу после открытия запроса. Когда данные CSV доступны, указанный callback вызывается со разпарсенными строками в качестве аргумента. В случае возникновения ошибки функция обратного вызова будет вызвана с значением null. Можно указать необязательную функцию accessor, которая затем передаётся в d3.csv.parse; accessor также может быть указан с помощью функции строки объекта запроса. Например:

d3.csv("path/to/file.csv")
    .row(function(d) { return {key: d.key, value: +d.value}; })
    .get(function(error, rows) { console.log(rows); });

См. пример карты с цветовой шкалой по уровню безработицы.

d3.csv.parse(string[, accessor])

Парсит указанную строку string, содержащую содержимое файла CSV, возвращая массив объектов, представляющих разпарсенные строки. Строка предполагается совместимой со спецификацией RFC4180. В отличие от метода parseRows, этот метод требует, чтобы первая строка файла CSV содержала список имен столбцов, разделённых запятыми; эти имена столбцов становятся атрибутами возвращаемых объектов. Например, рассмотрим следующий файл CSV:

Year,Make,Model,Length
1997,Ford,E350,2.34
2000,Mercury,Cougar,2.38

Результирующий JavaScript-массив:

[
  {"Year": "1997", "Make": "Ford", "Model": "E350", "Length": "2.34"},
  {"Year": "2000", "Make": "Mercury", "Model": "Cougar", "Length": "2.38"}
]

Обратите внимание, что сами значения всегда являются строками; они не будут автоматически преобразованы в числа. JavaScript может автоматически привести строки к числам (например, с помощью оператора +). Указав функцию accessor, можно преобразовать строки в числа или другие типы данных, такие как даты:

d3.csv("example.csv", function(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
  };
}, function(error, rows) {
  console.log(rows);
});

Использование + вместо parseInt или parseFloat обычно быстрее, хотя и более ограничено. Например, «30px» при приведении с помощью + возвращает NaN, в то время как parseInt и parseFloat возвращают 30.

d3.csv.parseRows(string[, accessor])

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

1997,Ford,E350,2.34
2000,Mercury,Cougar,2.38

Результирующий JavaScript-массив:

[
  ["1997", "Ford", "E350", "2.34"],
  ["2000", "Mercury", "Cougar", "2.38"]
]

Обратите внимание, что сами значения всегда являются строками; они не будут автоматически преобразованы в числа. Подробности см. в parse.

В качестве второго аргумента можно указать необязательную функцию accessor. Эта функция вызывается для каждой строки в файле CSV, принимая текущую строку и индекс в качестве двух аргументов. Возвращаемое значение функции заменяет элемент в возвращаемом массиве строк; если функция возвращает null, строка удаляется из возвращаемого массива строк. По сути, функция accessor аналогична применению операторов map и filter к возвращаемым строкам. Функция accessor используется методом parse для преобразования каждой строки в объект с именованными атрибутами.

d3.csv.format(rows)

Преобразует указанный массив rows в формат значений, разделённых запятыми, возвращая строку. Эта операция обратна parse. Каждая строка будет разделена новой строкой (\n), а каждый столбец в каждой строке будет разделен запятой (,). Значения, содержащие запятые, двойные кавычки (") или новые строки, будут экранированы с помощью двойных кавычек.

Каждая строка должна быть объектом, и все свойства объекта будут преобразованы в поля. Для большего контроля над тем, какие свойства преобразуются, преобразуйте строки в массивы, содержащие только те свойства, которые следует преобразовать, и используйте formatRows.

d3.csv.formatRows(rows)

Преобразует указанный массив rows в формат значений, разделённых запятыми, возвращая строку. Эта операция обратна parseRows. Каждая строка будет разделена новой строкой (\n), а каждый столбец в каждой строке будет разделен запятой (,). Значения, содержащие запятые, двойные кавычки (") или новые строки, будут экранированы с помощью двойных кавычек.

TSV

Значения, разделённые табуляцией, эквивалентны значениям, разделённым запятыми, за исключением того, что в качестве разделителя используется табуляция вместо запятой.

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

Эквивалентно d3.csv, но для значений, разделённых табуляцией.

d3.tsv.parse(string[, accessor])

Эквивалентно csv.parse, но для значений, разделённых табуляцией.

d3.tsv.parseRows(string[, accessor])

Эквивалентно csv.parseRows, но для значений, разделённых табуляцией.

d3.tsv.format(rows)

Эквивалентно csv.format, но для значений, разделённых табуляцией.

d3.tsv.formatRows(rows)

Эквивалентно csv.formatRows, но для значений, разделённых табуляцией.

Произвольные разделители

d3.dsv(delimiter, mimeType)

Создаёт новый парсер для заданного разделителя и типа MIME. Например, чтобы разобрать значения, разделённые символом «|», вертикальной чертой, используйте:

var dsv = d3.dsv("|", "text/plain");

dsv(url[, accessor][, callback])

Эквивалентно d3.csv, но для значений, разделённых произвольным разделителем.

dsv.parse(string[, accessor])

Эквивалентно csv.parse, но для значений, разделённых произвольным разделителем.

dsv.parseRows(string[, accessor])

Эквивалентно csv.parseRows, но для значений, разделённых произвольным разделителем.

dsv.format(rows)

Эквивалентно csv.format, но для значений, разделённых произвольным разделителем.

dsv.formatRows(rows)

Эквивалентно csv.formatRows, но для значений, разделённых произвольным разделителем.

Политика безопасности содержимого

Если введена политика безопасности содержимого CSP, обратите внимание, что csv.parse, tsv.parse и dsv.parse требуют unsafe-eval в директиве script-src, из-за (безопасного) использования динамической генерации кода для быстрого парсинга. Это также относится к конструкторам по умолчанию d3.csv, d3.tsv и dsv, которые отправляют HTTP-запрос GET для ресурса, а затем парсят ответ в объекты с помощью csv.parse, tsv.parse или dsv.parse.

Если unsafe-eval нельзя использовать, то csv.parseRows, tsv.parseRows или dsv.parseRows могут быть использованы как обходной путь, в сочетании с d3.text для получения ресурса при необходимости.