Документация исходного кода; установленный выпуск может отличаться.
API пользовательских видов
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, расположение реализации — в карте архитектуры.