diff --git a/docs/ru/guide/data-loading.md b/docs/ru/guide/data-loading.md new file mode 100644 index 00000000..e57d7903 --- /dev/null +++ b/docs/ru/guide/data-loading.md @@ -0,0 +1,258 @@ +# Загрузка данных в режиме реального времени {#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 + + +
{{ data }}+``` + +Результат: + +```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