# Загрузка данных в режиме реального времени {#build-time-data-loading}

VitePress предоставляет функцию **загрузчиков данных**, которая позволяет загружать произвольные данные и импортировать их со страниц или компонентов. Загрузка данных выполняется **только во время сборки**: Полученные данные будут сериализованы в виде JSON в финальной сборке JavaScript.

Загрузчики данных могут использоваться для получения удалённых данных или генерирования метаданных на основе локальных файлов. Например, вы можете использовать загрузчики данных для анализа всех локальных страниц API и автоматического создания индекса всех записей API.

## Пример использования {#basic-usage}

Файл загрузчика данных должен заканчиваться либо `.data.js`, либо `.data.ts`. Файл должен предоставлять экспорт объекта по умолчанию с помощью метода `load()`:

```js
// example.data.js
export default {
  load() {
    return {
      hello: 'мир'
    }
  }
}
```

Модуль загрузчика выполняется только в Node.js, поэтому вы можете импортировать любые API Node и зависимости npm по мере необходимости.

Затем вы можете импортировать данные из этого файла в страницы `.md` и компоненты `.vue` с помощью экспорта с именем `data`:

```vue
<script setup>
import { data } from './example.data.js'
</script>

<pre>{{ data }}</pre>
```

Результат:

```json
{
  "hello": "мир"
}
```

Вы заметите, что сам загрузчик данных не экспортирует `data`. Это VitePress вызывает метод `load()` за кулисами и неявно раскрывает результат через именованный экспорт `data`.

Это работает, даже если загрузчик асинхронный:

```js
export default {
  async load() {
    // получение удалённых данных
    return (await fetch('...')).json()
  }
}
```

## Данные из локальных файлов {#data-from-local-files}

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

Опция `watch` удобна ещё и тем, что вы можете использовать [шаблоны glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) для соответствия нескольким файлам. Шаблоны могут быть относительными к самому файлу загрузчика, а функция `load()` будет получать совпадающие файлы в виде абсолютных путей.

В следующем примере показана загрузка CSV-файлов и их преобразование в JSON с помощью [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/). Поскольку этот файл выполняется только во время сборки, вы не будете передавать CSV-парсер клиенту!

```js
import fs from 'node:fs'
import { parse } from 'csv-parse/sync'

export default {
  watch: ['./data/*.csv'],
  load(watchedFiles) {
    // watchedFiles будет представлять собой массив абсолютных путей к найденным файлам.
    // Формируем массив метаданных записи блога, которые можно использовать для визуализации списка в макете темы
    return watchedFiles.map((file) => {
      return parse(fs.readFileSync(file, 'utf-8'), {
        columns: true,
        skip_empty_lines: true
      })
    })
  }
}
```

## `createContentLoader` {#createcontentloader}

При создании сайта, ориентированного на контент, нам часто приходится создавать страницы типа «архив», или «индекс», на которых мы перечисляем все доступные записи в нашей коллекции контента. Например, записи в блоге или страницы API. Мы **можем** реализовать это напрямую с помощью API загрузчика данных, но поскольку это очень распространённый случай использования, VitePress также предоставляет функцию `createContentLoader`, чтобы упростить эту задачу:

```js
// posts.data.js
import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md' /* параметры */)
```

Эта функция принимает шаблон glob относительно [исходного каталога](./routing#source-directory) и возвращает объект `{ watch, load }` загрузчика данных, который может быть использован в качестве экспорта по умолчанию в файле загрузчика данных. В нем также реализовано кэширование на основе временных меток изменения файлов для повышения производительности dev.

Обратите внимание, что загрузчик работает только с файлами Markdown — совпадающие файлы, не относящиеся к Markdown, будут пропущены.

Загруженные данные будут представлять собой массив с типом `ContentData[]`:

```ts
interface ContentData {
  // отображаемый URL-адрес страницы, например: /posts/hello.html (не включает `base`)
  // выполните итерацию вручную или используйте пользовательскую `трансформацию` для нормализации путей
  url: string
  // метаданные страницы
  frontmatter: Record<string, any>

  // следующие параметры присутствуют только в том случае, если соответствующие опции включены
  // мы рассмотрим их ниже
  src: string | undefined
  html: string | undefined
  excerpt: string | undefined
}
```

По умолчанию указываются только `url` и `frontmatter`. Это связано с тем, что загруженные данные будут вложены в клиентский пакет в виде JSON, поэтому нам нужно быть осторожными с их размером. Вот пример использования этих данных для создания минимальной индексной страницы блога:

```vue
<script setup>
import { data as posts } from './posts.data.js'
</script>

<template>
  <h1>Все записи блога</h1>
  <ul>
    <li v-for="post of posts">
      <a :href="post.url">{{ post.frontmatter.title }}</a>
      <span>by {{ post.frontmatter.author }}</span>
    </li>
  </ul>
</template>
```

### Параметры {#options}

Данные по умолчанию могут не соответствовать всем требованиям — вы можете изменить данные с помощью параметров:

```js
// posts.data.js
import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md', {
  includeSrc: true, // включить исходный текст в формате Markdown?
  render: true, // включать в себя полный HTML страницы?
  excerpt: true, // включить отрывок?
  transform(rawData) {
    // составляйте карты, сортируйте или фильтруйте исходные данные по своему усмотрению.
    // конечный результат — это то, что будет отправлено клиенту.
    return rawData
      .sort((a, b) => {
        return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
      })
      .map((page) => {
        page.src // исходный текст в формате Markdown
        page.html // отображение полной страницы HTML
        page.excerpt // отображаемый отрывок HTML (содержимое выше первого `---`)
        return {
          /* ... */
        }
      })
  }
})
```

Посмотрите, как он используется в [блоге Vue.js](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts).

API `createContentLoader` также можно использовать внутри [хуков сборки](../reference/site-config#build-hooks):

```js
// .vitepress/config.js
export default {
  async buildEnd() {
    const posts = await createContentLoader('posts/*.md').load()
    // генерируем файлы на основе метаданных сообщений, например, RSS-канал
  }
}
```

**Типы**

```ts
interface ContentOptions<T = ContentData[]> {
  /**
   * Включаем src?
   * @default false
   */
  includeSrc?: boolean

  /**
   * Преобразовываем src в HTML и включаем в данные?
   * @default false
   */
  render?: boolean

  /**
   * Если `boolean`, то следует ли разбирать и включать отрывок? (отображается как HTML)
   *
   * Если `function`, то управляйте тем, как отрывок извлекается из содержимого.
   *
   * Если `string`, определите пользовательский разделитель, который будет использоваться для извлечения
   * отрывка. Разделителем по умолчанию является `---`, если `excerpt` имеет значение `true`.
   *
   * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt
   * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt_separator
   *
   * @default false
   */
  excerpt?:
    | boolean
    | ((
        file: {
          data: { [key: string]: any }
          content: string
          excerpt?: string
        },
        options?: any
      ) => void)
    | string

  /**
   * Преобразуйте данные. Обратите внимание, что при импорте из компонентов или файлов
   * с разметкой данные будут вложены в клиентский пакет в виде JSON.
   */
  transform?: (data: ContentData[]) => T | Promise<T>
}
```

## Загрузчики типизированных данных {#typed-data-loaders}

При использовании TypeScript можно ввести свой загрузчик и экспортировать `data` следующим образом:

```ts
import { defineLoader } from 'vitepress'

export interface Data {
  // тип данных
}

declare const data: Data
export { data }

export default defineLoader({
  // тип проверенных опций загрузчика
  watch: ['...'],
  async load(): Promise<Data> {
    // ...
  }
})
```

## Конфигурация {#configuration}

Чтобы получить информацию о конфигурации внутри загрузчика, вы можете использовать код, подобный этому:

```ts
import type { SiteConfig } from 'vitepress'

const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG
```