Загрузка данных: d3.csv(), d3.tsv(), d3.json(), d3.text(), d3.xml()

D3.js предоставляет унифицированный набор функций для загрузки внешних данных поверх стандартного браузерного механизма fetch, добавляя удобные преобразования типов, обработку строковых форматов и интеграцию с потоковой обработкой данных. Основной набор функций загрузки включает d3.csv(), d3.tsv(), d3.json(), d3.text() и d3.xml(), каждая из которых оптимизирована под конкретный формат и сценарий использования.

Все функции загрузки данных в D3.js работают асинхронно и возвращают Promise. В современных версиях (v5 и выше) это основной механизм работы, заменивший колбэки.

Типовой паттерн:

d3.json("data.json").then(data => {
  console.log(data);
}).catch(error => {
  console.error("Ошибка загрузки:", error);
});

Асинхронная модель обеспечивает:

  • неблокирующую загрузку ресурсов;
  • возможность цепочек обработки данных;
  • централизованную обработку ошибок через catch.

Загрузка JSON: d3.json()

d3.json() используется для загрузки структурированных данных в формате JSON. Это наиболее универсальный формат для работы с иерархическими и сложными объектами.

d3.json("data.json").then(data => {
  console.log(data);
});

Особенности обработки:

  • автоматический парсинг строки в JavaScript-объект;
  • поддержка массивов и вложенных структур;
  • удобство интеграции с API.

Пример ответа:

[
  { "name": "A", "value": 10 },
  { "name": "B", "value": 20 }
]

После загрузки данные сразу доступны как массив объектов без дополнительного преобразования.

Загрузка CSV: d3.csv()

d3.csv() предназначена для табличных данных, где значения разделены запятыми.

d3.csv("data.csv").then(data => {
  console.log(data);
});

Пример CSV:

name,value
A,10
B,20

После загрузки каждая строка преобразуется в объект:

[
  { name: "A", value: "10" },
  { name: "B", value: "20" }
]

Преобразование типов

По умолчанию все значения приходят как строки. Для преобразования используется функция-обработчик строки:

d3.csv("data.csv", d => {
  return {
    name: d.name,
    value: +d.value
  };
}).then(data => {
  console.log(data);
});

Ключевые моменты:

  • числовые преобразования выполняются вручную;
  • оператор + часто используется для приведения к числу;
  • можно добавлять вычисляемые поля.

Загрузка TSV: d3.tsv()

d3.tsv() аналогична CSV, но использует табуляцию как разделитель.

d3.tsv("data.tsv").then(data => {
  console.log(data);
});

Пример TSV:

name    value
A   10
B   20

Преимущества TSV:

  • удобен для данных с запятыми внутри значений;
  • часто используется в научных датасетах;
  • снижает необходимость экранирования.

Обработка типов аналогична CSV:

d3.tsv("data.tsv", d => ({
  name: d.name,
  value: +d.value
})).then(data => {
  console.log(data);
});

Загрузка произвольного текста: d3.text()

d3.text() используется для получения сырого текстового содержимого без парсинга.

d3.text("file.txt").then(text => {
  console.log(text);
});

Особенности:

  • возвращает строку;
  • не выполняет структурный разбор;
  • подходит для логов, шаблонов, конфигураций.

Пример обработки многострочного текста:

d3.text("log.txt").then(text => {
  const lines = text.split("\n");
  console.log(lines);
});

Загрузка XML: d3.xml()

d3.xml() возвращает XML-документ в виде DOM-структуры.

d3.xml("data.xml").then(xml => {
  console.log(xml);
});

Пример XML:

<items>
  <item name="A" value="10"/>
  <item name="B" value="20"/>
</items>

Обработка через DOM API:

d3.xml("data.xml").then(xml => {
  const items = xml.querySelectorAll("item");

  const data = Array.from(items).map(node => ({
    name: node.getAttribute("name"),
    value: +node.getAttribute("value")
  }));

  console.log(data);
});

Ключевые особенности:

  • возвращается Document, а не строка;
  • используется стандартный DOM API (querySelector, getAttribute);
  • требует ручного извлечения значений.

Унификация работы с источниками данных

Функции загрузки в D3.js построены на едином принципе:

  • единый интерфейс Promise;
  • консистентная обработка ошибок;
  • поддержка преобразования данных на этапе загрузки;
  • совместимость с цепочками обработки.

Пример цепочки:

d3.csv("data.csv", d => ({
  name: d.name,
  value: +d.value
}))
.then(data => data.filter(d => d.value > 10))
.then(filtered => {
  console.log(filtered);
});

Преобразование данных на этапе загрузки

Во всех табличных загрузчиках (csv, tsv) поддерживается функция преобразования строки:

(row, index, columns) => transformedRow

Пример с доступом к индексам:

d3.csv("data.csv", (d, i) => ({
  id: i,
  name: d.name,
  value: +d.value
}));

Дополнительно доступен массив заголовков:

d3.csv("data.csv", (d, i, columns) => {
  return {
    index: i,
    keys: columns
  };
});

Обработка ошибок загрузки

Каждая функция возвращает Promise, что позволяет централизовать обработку ошибок:

d3.json("data.json")
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });

Типовые источники ошибок:

  • неверный путь к файлу;
  • CORS-ограничения;
  • некорректный формат данных;
  • проблемы сети.

Особенности кодировок и форматов

При работе с CSV/TSV важно учитывать:

  • UTF-8 является стандартной кодировкой;
  • наличие BOM может влиять на парсинг;
  • разделители должны быть строго согласованы;
  • пустые значения интерпретируются как пустые строки.

Пример обработки пустых значений:

d3.csv("data.csv", d => ({
  name: d.name || "unknown",
  value: d.value ? +d.value : 0
}));

Сравнение методов загрузки

  • d3.json() — структурированные данные, API, иерархии;
  • d3.csv() — табличные данные с запятыми;
  • d3.tsv() — табличные данные с табуляцией;
  • d3.text() — сырой текст без структуры;
  • d3.xml() — DOM-ориентированные данные.

Каждый метод оптимизирован под свой тип источника, но все они объединены одинаковой асинхронной моделью и единым подходом к обработке результатов.

Оглавление