Документация исходного кода; установленный выпуск может отличаться.

API пользовательских видов

English version

Projects Plus может подключить вид, предоставленный другим включённым плагином Obsidian. API экспериментальный: совместимость нужно проверять с конкретной версией Projects Plus. Модули и хранилища состояния внутри src не являются стабильным публичным SDK.

Регистрация

При открытии панели Projects функция getProjectViews() ищет у включённых плагинов метод onRegisterProjectView. Возвращённый экземпляр регистрируется под ключом из getViewType().

Возвращайте новый экземпляр. Для ключа используйте уникальное имя с префиксом вашего плагина, например my-plugin-summary. Встроенные виды регистрируются после внешних и заменяют совпадающие ключи. После включения расширения переоткройте панель Projects, чтобы регистрация выполнилась снова.

Жизненный цикл

Метод Назначение
getViewType() Уникальный ключ вида
getDisplayName() Название в интерфейсе
getIcon() Имя значка Obsidian
onOpen(props) Создание интерфейса в props.contentEl
onData(result) Отображение текущих данных
updateProps(updates) Обновление настроек вида или проекта без пересоздания
onClose() Освобождение подписок, обработчиков и других ресурсов

Порядок вызовов определён в useView.ts. После onOpen сразу вызывается onData; завершения асинхронных методов хост не ожидает. Первичную подготовку выполняйте синхронно, а фоновую работу и её отмену организуйте внутри вида.

Полный минимальный пример находится в английском справочнике. Он показывает регистрацию и отображение количества записей. Метод updateProps в примере обязателен для текущего хоста, хотя базовый класс в пакете типов его пока не содержит.

Данные и параметры

Актуальный контракт хоста — src/customViewApi.ts, структура данных — dataframe.ts.

DataQueryResult содержит data, признаки hasSort и hasFilter, необязательный счётчик dataGeneration и список filterConditions. Хост также передаёт полный filter: с отключёнными условиями и вложенными группами. При сохранении фильтра нельзя заменять его только видимыми включёнными условиями — часть настроек потеряется.

В data находятся поля fields, записи records и необязательные ошибки разбора errors. Идентификатор записи id — путь заметки в хранилище. Значения находятся в values. Отсутствующее свойство и явное значение null имеют разный смысл. Вычисляемые поля не следует записывать в свойства заметки.

Параметр ProjectViewProps Назначение
viewId, project Текущий вид и проект
config, saveConfig Чтение и сохранение настроек вида
contentEl Контейнер интерфейса
viewApi Операции с записями и полями
readonly Признак источника только для чтения
saveViewFilter? Сохранение фильтра, если хост предоставил callback
getRecordColor Цвет записи по правилам проекта
sortRecords Сортировка списка по настройкам хоста
getRecord Поиск записи по идентификатору

Запись изменений

Используйте экземпляр viewApi, полученный от хоста. Он поддерживает создание, изменение, пакетное изменение и удаление записей, а также создание, изменение и удаление полей. deleteField принимает имя поля, а не объект поля.

Поведение записи и обработка ошибок реализованы в src/lib/viewApi.ts. Часть методов асинхронна, а пакет типов не описывает все возвращаемые значения точно. Например, хост возвращает из updateRecord значение Promise<boolean>, а пакет объявляет void. Возврат из такого вызова и изменение на экране сами по себе не подтверждают сохранение файла.

Отключайте редактирование при readonly и учитывайте признак вычисляемого поля. Не создавайте ViewApi из пакета: его методы — пустые заглушки для описания типов. Этот класс также не совпадает с конструктором реализации хоста, поэтому проверка через его instanceof ненадёжна.

Ограничения совместимости

Пакет типов имеет собственную версию 3.0.0, отдельную от версии плагина. В нём пока отсутствуют updateProps, полный filter и вариант источника native-query. Типы значений и результатов записи также отличаются от хоста.

Реализуйте updateProps, даже если обновлять ничего не требуется. Если расширение использует остальные возможности хоста, проверяйте и описывайте этот интерфейс для поддерживаемого выпуска. Компиляции с пакетом типов недостаточно: проверьте в Obsidian открытие вида, обновление данных, изменение настроек и закрытие.

Инструкции по сборке и проверке — в Contributing, расположение реализации — в карте архитектуры.

Исходник страницы ↗