Документация исходного кода; установленный выпуск может отличаться.
Устройство проекта
Эта карта описывает код в репозитории и помогает найти, где реализована та или иная возможность. Сборка и проверки — в руководстве для контрибьюторов.
Точки входа и интерфейс
| Где | За что отвечает |
|---|---|
| src/main.ts | Жизненный цикл плагина, инициализация настроек, команды и связь с Obsidian |
| src/view.ts | Рабочая область Projects и регистрация встроенных и сторонних видов |
| src/events.ts | Обработка событий хранилища |
| src/managers | Управление командами |
| src/ui/app | Навигация по проектам, общий интерфейс и жизненный цикл вида |
| src/ui/views | Интерфейсы Dashboard, доски, календаря, галереи и визуализатора |
| src/ui/tokens/tokens.css | Общие визуальные токены |
ProjectsView.getProjectViews() регистрирует доску, календарь, галерею и Dashboard. Ключ database остаётся псевдонимом Dashboard, чтобы старые сохранённые настройки находили свой вид. У панелей визуализатора своя связка с Obsidian.
Жизненный цикл стороннего вида подключён в useView.ts: он передаёт виду настройку, данные проекта и обратные вызовы записи. Прежде чем опираться на эту точку расширения, прочтите справочник API.
От заметок к представлению
- Определение проекта выбирает источник данных. Фабрика источников создаёт источник по папке, тегу, встроенному запросу или Dataview. Dataview необязателен; фабрика сообщает, когда его нет.
- Источник читает заметки через абстракцию файловой системы и отдаёт фрейм данных: описания полей, записи и, если были, ошибки разбора.
- Хранилища Svelte держат реактивные данные и согласуют их обновление при изменении записей.
- Выбранный вид отображает эти данные. Блоки Dashboard используют модули преобразований, формул, связей и агрегации для производных значений.
| Где | За что отвечает |
|---|---|
| src/lib/datasources | Выбор источника, запросы и объединение результатов |
| src/lib/metadata | Кодирование и разбор YAML-свойств заметки |
| src/lib/engine | Фильтрация, агрегация и расчёты между проектами |
| src/lib/dashboard-engine | Преобразования Dashboard, применение формул, графики и кэши |
| src/lib/formula | Разбор и вычисление формул |
| src/lib/relations | Контракты связей, обратные индексы, запись связей, объявленные типы полей и свёртки (rollupColumns.ts) |
| src/lib/visualizer | Свойства, связи и наложения визуализатора |
Кадры других проектов. Блок, график или свёртка, читающие другой проект, получают его кадр через externalFrameResolver.ts: объявленные типы связей, обратные ссылки и свёртки этого проекта применяются так же, как в его собственном виде. Кадры кэшируются в App.svelte; кэш сбрасывается при изменении файлов и при смене источника или настройки полей любого проекта. Блок с чужим источником доступен только для чтения — запись через его ViewApi попала бы не в тот проект.
Эти каталоги описывают ответственность, но зависимости не везде следуют строгой границе слоёв. Меняя путь, общий для нескольких видов, идите по импортам и вызывающим местам.
Модуль формул предоставляет единый строгий исполнитель unified-v1 для предпросмотра формул, вычисляемых столбцов преобразований и фильтров Agenda. Конвейер преобразований остаётся слоем организации операций, а не отдельным исполнителем формул. settingsMigration.ts готовит версионированные определения; жизненный цикл плагина проверяет копии настроек и отчёты миграции до их применения. Требования совместимости и отката описаны в руководстве обновления.
Запись и хранение
Правки записей и полей проходят через ViewApi и dataApi.ts: они согласуют запись в файловую систему с показанным фреймом данных. Свойства пишутся через processFrontMatter, а чтение-изменение-запись — через Vault.process по текущему содержимому файла, чтобы правка, сделанная между чтением и записью, не терялась. Часть обновлений оптимистична — видимое изменение само по себе не доказывает, что заметка записана. Путь отказа умеет вернуть прежнее значение и показать ошибку с кодом.
Схемы настроек и миграции лежат в src/settings. Записывающий модуль и согласование настроек — в src/lib/settings, связка жизненного цикла — в src/main.ts. Новые записи настроек ведите этим же путём, иначе потеряются проверка конфликтов и повторные попытки.
Содержимое заметок хранится в хранилище, настройка плагина — в его data.json. Производные значения, например результаты формул, не следует считать сохранёнными свойствами заметки.
Ошибки и диагностика
Реестр ошибок — errorCodes.ts; форматирование и журналирование лежат рядом. Двуязычный справочник кодов объясняет, что делать пользователю с каждым кодом. Меняя подачу кода, сохраняйте его смысл.
Границы расширения
Пользовательские виды — экспериментальная возможность. Модули src, хранилища и структуры настроек — внутренние интерфейсы, а не стабильный публичный SDK. Пакет типов — отдельная поверхность совместимости, и сейчас он расходится с хостом в нескольких местах, описанных в справочнике API.
Прежде чем менять общий тип, посмотрите его потребителей и относящиеся к нему тесты. Записи источника, фильтры и результаты записи проходят через несколько видов, поэтому изменение, работающее в одном блоке, может задеть другие интерфейсы.