Плагіни оболонки

Робочий стіл OmarOS працює як один довгоживучий процес Quickshell під назвою omaros-shell, і майже все, що ви бачите на екрані, — це плагін усередині нього. Панель — це плагін. Так само як і панелі, що спадають із неї, повноекранні накладення на кшталт вибірника емоджі й менеджера буфера обміну, саме меню OmarOS, екран блокування, діалог polkit і безголові служби, які стежать за вашою батареєю й теплять ваш екран уночі.

Це не просто деталь реалізації. Це означає, що ви можете вимикати частини робочого столу, вимінювати їх або писати власні, не чіпаючи жодного рядка вихідного коду OmarOS.

Плагіни від першої сторони постачаються з OmarOS і живуть у $OMAROS_PATH/shell/plugins/. Усе, що ви додаєте самі, — ваші власні експерименти або те, що ви знайшли на GitHub, — живе в ~/.config/omaros/plugins/. Обидва виявляються однаково під час запуску, але вбудовані отримують довірені інтерфейси оболонки, тоді як плагіни третіх сторін отримують обмежений інтерфейс, підпертий до їхніх власних служби й життєвого циклу. Клони вбудованих зберігають лише специфічні для джерела виклики конфігурації та UI, потрібні для оригінальної поведінки.

Побачити, що у вас є

omaros plugin list

Це друкує кожен виявлений плагін із його ідентифікатором, увімкнений він чи ні, від першої сторони він чи від третьої, його види та його відображувану назву. Додайте --json, якщо подаєте це кудись іще.

Ідентифікатори плагінів простору імен зазнають. Вбудовані всі починаються з omaros. — omaros.clock, omaros.network, omaros.notifications — і цей простір імен зарезервовано, тож плагін третьої сторони ніколи не зможе його собі привласнити.

Вмикання й вимикання

omaros plugin enable omaros.tailscale
omaros plugin disable omaros.weather

Або скористайтеся меню: Налаштування > Плагіни має Enable, Disable, Add, Clone і Remove, кожна з вибірником, який пропонує лише плагіни, доцільні для цієї дії.

Стан увімкнення зберігається в ~/.config/omaros/shell.json, і правило трохи відрізняється для двох видів плагінів. Плагін третьої сторони увімкнено рівно тоді, коли його ідентифікатор десь у цьому файлі зʼявляється — як запис розкладки панелі, як запис у plugins[], або як bar.id. Плагіни від першої сторони, що не є віджетами панелі, навпаки: вони типово увімкнені й вимикаються лише тим, що опиняються в disabledPlugins[].

Повноцінний плагін панелі взагалі не має стану «вимкнено». Завжди є рівно одна панель, тож ви замінюєте її, вмикаючи іншу. Розміщення віджетів панелі розглядається в розділі верхня панель.

Додавання плагіну з git

Плагін третьої сторони — це просто git-репозиторій із manifest.json у корені.

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

Перш ніж робити будь-що, він каже вам прямо, що плагіни працюють як довільний, непісочний код усередині вашого довгоживучого процесу оболонки, показує вам URL і просить підтвердити. Ставтеся до цього серйозно. Інтерфейс плагінів третіх сторін не виставляє служби автентифікації напряму, а панель-замінник отримує лише обмежені можливості для налаштованого неавтентифікаційного UI. Візуальні плагіни й далі ділять сцену QML оболонки й можуть ходити звичайними батьківськими обʼєктами, тоді як увесь код плагінів працює з усім, до чого може дістатися ваш обліковий запис користувача. Стан автентифікації захищено окремо тим, що ці служби тримаються поза досяжним графом обʼєктів хоста. Додавайте лише репозиторії, які ви готові запускати, і читайте їх, перш ніж вмикати.

Панель-замінник може відтворювати встановлені віджети, але віджети третіх сторін, підперті службами, можуть мати там зменшену функціональність, оскільки панелі не дозволено запитувати живий обʼєкт служби іншого плагіну. Повертайтеся до вбудованого omaros.bar, якщо такому віджетові потрібна його супровідна служба.

Потім він клонує репозиторій у каталог підготовки, перевіряє маніфест, відмовляється встановлювати, якщо інший плагін уже претендує на цей ідентифікатор, і переміщує його в ~/.config/omaros/plugins/<id>/. Без --enable він запитає, чи хочете ви його зараз увімкнути, і ви можете сказати «ні» й спершу почитати код. Він ніколи нічого не запускає з плагіну, ніколи не виконує хук встановлення і ніколи не просить sudo — він клонує файли, перевіряє маніфест і перемикає біт через IPC.

Оновлення — це fast-forward pull того самого клону:

omaros plugin update acme.weather
omaros plugin update

Без ідентифікатора він оновлює кожен керований git плагін, який у вас є. Він показує вам різницю перед застосуванням, відмовляється оновлювати, якщо у вас є локальні зміни, повз які він не може пройти fast-forward, і відкочується, якщо нова редакція провалює перевірку.

omaros plugin remove acme.weather

Видалення спочатку вимикає плагін, а потім видаляє його, якщо це git-клон (репозиторій і далі назовні), або відвʼязує його, якщо це символьне посилання. Саморобна тека плагіну без git-репозиторію замість прямого видалення переміщується до резервної копії з позначкою часу всередині каталогу плагінів.

Клонування вбудованого, щоб його змінювати

Це моя улюблена частина. Якщо ви хочете змінити, як поводиться вбудований віджет, не редагуйте файли під $OMAROS_PATH — вони належать пакункові, і наступне оновлення їх перепише. Клонуйте його натомість:

omaros plugin clone omaros.clock

Це копіює цілий плагін у ~/.config/omaros/plugins/omar.clock (ваше імʼя користувача, а не моє), перейменовує його на «My Clock», вмикає його і перемикає оболонку з вбудованого на вашу копію — зберігаючи положення й налаштування наявного віджета панелі. Додайте --edit, щоб одразу відкрити новий каталог у вашому $EDITOR, що й робить для вас Налаштування > Плагіни > Клонувати плагін у меню.

Префікс імені користувача тримає ідентифікатор вашого клону вашим, тож поширення його не конфліктує ні з чиїмсь іще. Виклики, зроблені до оригінального вбудованого ідентифікатора, маршрутизуються до вашого клону, тож нічому, що посилалося на omaros.clock, не треба оновлюватися. А якщо ви наробите безладу, omaros plugin remove omar.clock поверне вбудований назад.

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

Написання власних

Плагін — це каталог із manifest.json і якимось QML. Маніфест оголошує schemaVersion: 1, id, name, version, один або кілька kinds та обʼєкт entryPoints, що вказує на файл QML для кожного виду:

Вид	Що це
bar-widget	Компонент, який активна панель може вкидати в секцію
panel	Постійне або викликане плаваюче вікно
overlay	Повноекранне накладення
menu	Викликана поверхня меню
service	Безголовий одинак без UI
bar	Повноцінна панель, яка замінює вбудовану

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

Перш ніж будь-що публікувати, перевірте його:

omaros plugin validate ./my-plugin

Це запускає ті самі перевірки, які оболонка робить під час завантаження: версію схеми, обовʼязкові поля, ідентифікатор, який не зарезервовано, точки входу, які є безпечними відносними шляхами й насправді існують, точку входу для кожного виду, на який ви претендували, і жодних символьних посилань будь-де всередині теки.

Для розробки плагінів дивіться довідник оболонки і каталог плагінів від першої сторони.

Поділитися своїм зі світом

Щойно ви зробите те, що вам подобається, покладіть це в публічний git-репозиторій. Ось і весь механізм розповсюдження — хто завгодно зможе потім виконати omaros plugin add проти вашого URL і мати це запущеним за секунди.