Перейти к содержимому
Chapters
  1. Добро пожаловать в Omarchy!
  2. Начало работы
  3. Переход с Mac или Windows
  4. Навигация
  5. Верхняя панель
  6. Темы
  7. Горячие клавиши
  8. Единый буфер обмена и история
  9. Напоминания
  10. Извещения
  11. Извлечение текста и диктовка
  12. Скриншоты и запись
  13. Переключатели, простой и скринсейвер
  14. Omarchy CLI
  15. Терминал
  16. Neovim
  17. AI
  18. Инструменты разработки
  19. Инструменты оболочки
  20. Функции оболочки
  21. TUIs
  22. Графические приложения
  23. Браузеры
  24. Коммерческие приложения и сервисы
  25. Веб-приложения
  26. Игры
  27. Заполнение PDF
  28. Виртуальная машина Windows
  29. Другие пакеты
  30. Обновления
  31. Дотфайлы
  32. Плагины оболочки
  33. Мониторы
  34. Клавиатура, мышь, трекпад
  35. Сеть
  36. Режим сна
  37. Аппаратная аутентификация
  38. Шрифты
  39. Фоны
  40. Приглашение командной строки
  41. Брендинг
  42. Распространённые настройки
  43. Создание собственной темы
  44. Поддержка Mac
  45. Устранение неполадок
  46. Частые вопросы
  47. Снимки системы
  48. Безопасность
  49. Omarchy на...
  50. Установка с двойной загрузкой
  51. Установка без участия пользователя

Руководство

Плагины оболочки

Рабочий стол Omarchy работает как один долгоживущий процесс Quickshell под названием omarchy-shell, и почти всё, что вы видите на экране, является плагином внутри него. Панель - это плагин. Как и панели, выпадающие из неё, полноэкранные наложения вроде средства выбора эмодзи и менеджера буфера обмена, само меню Omarchy, экран блокировки, диалог polkit и безголовые службы, которые следят за вашей батареей и согревают экран ночью.

Это не просто деталь реализации. Это означает, что вы можете отключать части рабочего стола, заменять их или писать свои собственные, не трогая ни строчки исходного кода Omarchy.

Плагины первого уровня поставляются с Omarchy и живут в $OMARCHY_PATH/shell/plugins/. Всё, что вы добавляете сами, - ваши собственные эксперименты или что-то найденное на GitHub, - живёт в ~/.config/omarchy/plugins/. Оба обнаруживаются одинаковым способом при запуске, но встроенные получают доверенные интерфейсы оболочки, а сторонние плагины получают ограниченный интерфейс, ограниченный их собственной службой и жизненным циклом. Клоны встроенных сохраняют только конфигурацию, специфичную для источника, и вызовы UI, нужные для оригинального поведения.

Просмотр того, что у вас есть

omarchy plugin list

Это выводит каждый обнаруженный плагин с его id, включён ли он, является ли он плагином первого уровня или сторонним, его видами и отображаемым именем. Добавьте --json, если вы передаёте это чему-то ещё.

Id плагинов имеют пространство имён. Все встроенные начинаются с omarchy. - omarchy.clock, omarchy.network, omarchy.notifications - и это пространство имён зарезервировано, так что сторонний плагин никогда не сможет его заявить.

Включение и выключение

omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather

Или используйте меню: в Настройка > Plugins есть Enable, Disable, Add, Clone и Remove, каждый со средством выбора, предлагающим только те плагины, которые имеют смысл для этого действия.

Состояние включённости хранится в ~/.config/omarchy/shell.json, и правило слегка различается для двух видов плагинов. Сторонний плагин включён ровно тогда, когда его id появляется где-то в этом файле - как запись раскладки панели, как запись в plugins[] или как bar.id. С плагинами первого уровня, которые не являются виджетами панели, всё наоборот: они включены по умолчанию и выключаются только внесением в disabledPlugins[].

У полноценного плагина панели нет состояния «выключено» вообще. Панель всегда ровно одна, поэтому вы заменяете её, включив другую. Размещение виджетов панели описано в разделе верхняя панель.

Добавление плагина из git

Сторонний плагин - это просто репозиторий git с файлом manifest.json в корне.

omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

Прежде чем что-либо сделать, он прямо говорит вам, что плагины работают как произвольный код без песочницы внутри вашего долгоживущего процесса оболочки, показывает URL и просит подтвердить. Отнеситесь к этому серьёзно. Интерфейс сторонних плагинов напрямую не предоставляет службы аутентификации, а заменяющая панель получает только ограниченные возможности для настроенного UI без аутентификации. Визуальные плагины по-прежнему разделяют QML-сцену оболочки и могут обходить обычные родительские объекты, а весь код плагинов работает со всем, до чего может дотянуться ваша учётная запись пользователя. Состояние аутентификации защищено отдельно за счёт удержания этих служб вне достижимого графа объектов хоста. Добавляйте только репозитории, которые вы готовы запускать, и читайте их, прежде чем включать.

Заменяющая панель может отображать установленные виджеты, но сторонние виджеты со службой могут иметь там ограниченную функциональность, поскольку панели не разрешено запрашивать живой объект службы другого плагина. Вернитесь к встроенной omarchy.bar, если такому виджету нужна его сопутствующая служба.

Затем он клонирует репозиторий в промежуточный каталог, проверяет манифест, отказывает в установке, если другой плагин уже заявил этот id, и перемещает его в ~/.config/omarchy/plugins/<id>/. Без --enable он спросит, хотите ли вы включить его сейчас, и можно сказать «нет» и сначала пойти почитать код. Он никогда не запускает ничего из плагина, никогда не выполняет установочный хук и никогда не просит sudo - он клонирует файлы, проверяет манифест и переключает бит по IPC.

Обновление - это fast-forward pull того же самого клона:

omarchy plugin update acme.weather
omarchy plugin update

Без id он обновляет каждый управляемый через git плагин, который у вас есть. Он показывает вам diff перед применением, отказывается обновлять, если у вас есть локальные изменения, через которые он не может выполнить fast-forward, и откатывается, если новая ревизия не проходит проверку.

omarchy plugin remove acme.weather

Удаление сначала отключает плагин, затем удаляет его, если это клон git (репозиторий всё ещё существует в исходнике), или отсоединяет его, если это символическая ссылка. Сделанная вручную папка плагина без репозитория git вместо полного удаления перемещается в резервную копию с отметкой времени внутри каталога плагинов.

Клонирование встроенного плагина для изменения

Это моя любимая часть. Если вы хотите изменить поведение встроенного виджета, не редактируйте файлы в $OMARCHY_PATH - они принадлежат пакету, и следующее обновление их перезапишет. Вместо этого клонируйте его:

omarchy plugin clone omarchy.clock

Это копирует весь плагин в ~/.config/omarchy/plugins/dhh.clock (ваше имя пользователя, а не моё), переименовывает его в «My Clock», включает его и переключает оболочку со встроенного на вашу копию - сохраняя позицию и настройки существующего виджета панели. Добавьте --edit, чтобы сразу открыть новый каталог в вашем $EDITOR, что и делает для вас пункт меню Настройка > Plugins > Clone Plugin.

Префикс имени пользователя сохраняет id вашего клона вашим, поэтому его передача другим не столкнётся ни с чьим ещё. Вызовы, сделанные к оригинальному встроенному id, перенаправляются на ваш клон, так что ничто, что ссылалось на omarchy.clock, не нужно обновлять. А если вы там всё испортите, omarchy plugin remove dhh.clock вернёт встроенный на место.

Сохранение файла где угодно в ~/.config/omarchy/plugins/ автоматически перезагружает код плагина, так что можно оставить редактор открытым и наблюдать, как ваши изменения приземляются.

Написание собственных

Плагин - это каталог с manifest.json и некоторым QML. Манифест объявляет schemaVersion: 1, id, name, version, один или несколько kinds и объект entryPoints, указывающий на файл QML для каждого вида:

Kind What it is
bar-widget Компонент, который активная панель может поместить в секцию
panel Постоянное или вызываемое плавающее окно
overlay Полноэкранное наложение
menu Вызываемая поверхность меню
service Безголовый singleton без UI
bar Полноценная панель, заменяющая встроенную

Плагин может объявлять несколько видов сразу - плагин media является одновременно и service, и bar-widget. Виджеты панели получают дополнительный блок barWidget с отображаемым именем, категорией, необязательным defaultSection и allowMultiple, который говорит, имеет ли смысл иметь на панели больше одного. Большинство виджетов задают его как false; разделители и индикаторы задают его как true.

Прежде чем что-либо публиковать, проверьте это:

omarchy plugin validate ./my-plugin

Это запускает те же проверки, которые оболочка выполняет во время загрузки: версию схемы, обязательные поля, id, который не зарезервирован, точки входа, являющиеся безопасными относительными путями и действительно существующие, точку входа для каждого заявленного вами вида и отсутствие символических ссылок где-либо внутри папки.

О разработке плагинов см. справочник по оболочке и каталог плагинов первого уровня.

Делитесь своими со всем миром

Как только вы сделали что-то, что вам нравится, поместите это в публичный репозиторий git. Это весь механизм распространения - после этого любой может выполнить omarchy plugin add против вашего URL и получить работающий плагин за секунды.

Чтобы помочь людям действительно найти его, разместите его на plugins.omarchy.org. Это торговая площадка для плагинов оболочки Omarchy, и это первое место, куда стоит заглянуть, когда вы задаётесь вопросом, не построил ли уже кто-то виджет, который вы собираетесь писать. Просмотрите её, прежде чем начинать!