Shell-plugins

Omarchy-skrivebordet kører som en enkelt, langlivet Quickshell-proces kaldet omarchy-shell, og næsten alt, hvad du ser på skærmen, er et plugin i den. Bjælken er et plugin. Det samme gælder panelerne, der folder sig ud fra den, fuldskærmslagene som emoji-vælgeren og udklipsholderhåndteringen, selve Omarchy-menuen, låseskærmen, polkit-dialogboksen og tjenesterne uden brugerflade, der overvåger dit batteri og gør skærmens farver varmere om natten.

Det er ikke bare en implementeringsdetalje. Det betyder, at du kan slå dele af skrivebordet fra, udskifte dem eller skrive dine egne uden at røre en eneste linje i Omarchys kildekode.

Førstepartsplugins følger med Omarchy og ligger i $OMARCHY_PATH/shell/plugins/. Alt, du selv tilføjer — dine egne eksperimenter eller noget, du har fundet på GitHub — ligger i ~/.config/omarchy/plugins/. Begge dele findes på samme måde ved opstart; den eneste forskel er, hvor de ligger på disken.

Se, hvad du har #

omarchy plugin list

Det viser alle fundne plugins med deres id, om de er aktiveret, om de er første- eller tredjepartsplugins, deres typer og deres viste navn. Tilføj --json, hvis du sender outputtet videre til noget andet.

Plugin-id'er bruger navnerum. Alle de indbyggede begynder med omarchy. — omarchy.clock, omarchy.network, omarchy.notifications — og det navnerum er reserveret, så et tredjepartsplugin aldrig kan gøre krav på det.

Slå dem til og fra #

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

Du kan også bruge menuen: Opsætning > Plugins har Aktivér, Deaktivér, Tilføj, Klon og Fjern, hver med en vælger, der kun viser de plugins, som giver mening for den pågældende handling.

Aktiveringstilstanden gemmes i ~/.config/omarchy/shell.json, og reglen er lidt forskellig for de to typer plugins. Et tredjepartsplugin er aktiveret, præcis når dets id optræder et sted i den fil — som et element i bjælkens layout, som et element i plugins[] eller som bar.id. For førstepartsplugins, der ikke er bjælke-widgets, er det omvendt: De er slået til som standard og bliver kun slået fra ved at være angivet i disabledPlugins[].

Et komplet bjælkeplugin kan slet ikke være slået fra. Der er altid præcis én bjælke, så du erstatter den ved at aktivere en anden. Placering af bjælke-widgets er beskrevet under den øverste bjælke.

Tilføj et plugin fra git #

Et tredjepartsplugin er blot et git-repository med en manifest.json i roden.

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

Før kommandoen gør noget, fortæller den dig tydeligt, at plugins kører som vilkårlig kode uden sandboxing i din langlivede shell-proces, viser dig URL'en og beder dig bekræfte. Tag det alvorligt. Et plugin er ikke en konfigurationsfil — det er kode, der kører, så længe din session gør, med adgang til alt, din brugerkonto kan nå. Tilføj kun repositories, du er villig til at køre, og læs koden, før du aktiverer dem.

Derefter kloner kommandoen repositoriet til en midlertidig mappe, validerer manifestet, afviser installationen, hvis et andet plugin allerede gør krav på det pågældende id, og flytter det til ~/.config/omarchy/plugins/<id>/. Uden --enable spørger den, om du vil slå det til nu, og du kan sige nej og læse koden først. Den kører aldrig noget fra pluginet, udfører aldrig en installations-hook og beder aldrig om sudo — den kloner filer, kontrollerer manifestet og ændrer en tilstand via IPC.

En opdatering er et fast-forward-pull af den samme checkout:

omarchy plugin update acme.weather
omarchy plugin update

Uden et id opdaterer kommandoen alle dine git-administrerede plugins. Den viser dig forskellen, før den anvender den, nægter at opdatere, hvis du har lokale ændringer, den ikke kan komme forbi med fast-forward, og ruller tilbage, hvis den nye revision ikke består valideringen.

omarchy plugin remove acme.weather

Ved fjernelse deaktiveres pluginet først, hvorefter det slettes, hvis det er en git-checkout (repositoriet findes stadig upstream), eller linket fjernes, hvis det er et symbolsk link. En håndlavet pluginmappe uden et git-repository flyttes i stedet til en tidsstemplet sikkerhedskopi i pluginmappen frem for at blive slettet permanent.

Klon et indbygget plugin for at ændre det #

Dette er min yndlingsdel. Hvis du vil ændre, hvordan en indbygget widget opfører sig, skal du ikke redigere filerne under $OMARCHY_PATH — de tilhører pakken, og den næste opdatering overskriver dem. Klon den i stedet:

omarchy plugin clone omarchy.clock

Det kopierer hele pluginet til ~/.config/omarchy/plugins/dhh.clock (dit brugernavn, ikke mit), omdøber det til “Mit ur”, aktiverer det og får shellen til at skifte fra det indbyggede plugin til din kopi — samtidig med at en eksisterende bjælke-widgets placering og indstillinger bevares. Tilføj --edit for straks at åbne den nye mappe i din $EDITOR, hvilket er det, menuvalget Opsætning > Plugins > Klon plugin gør for dig.

Brugernavnspræfikset sikrer, at din klons id tilhører dig, så den ikke kolliderer med andres, hvis du deler den. Kald til det oprindelige indbyggede id omdirigeres til din klon, så intet, der henviste til omarchy.clock, behøver at blive opdateret. Og hvis du roder det hele til, gendanner omarchy plugin remove dhh.clock det indbyggede plugin.

Når du gemmer en fil hvor som helst under ~/.config/omarchy/plugins/, genindlæses plugin-koden automatisk, så du kan lade editoren stå åben og se dine ændringer træde i kraft.

Skriv dit eget #

Et plugin er en mappe med en manifest.json og noget QML. Manifestet erklærer schemaVersion: 1, et id, et name, en version, en eller flere kinds samt et entryPoints-objekt, der peger på QML-filen for hver type:

Type	Hvad det er
bar-widget	En komponent, som den aktive bjælke kan placere i et afsnit
panel	Et permanent eller fremkaldt flydende vindue
overlay	Et fuldskærmslag
menu	En menuflade, der kan fremkaldes
service	En singleton uden brugerflade
bar	En komplet bjælke, der erstatter den indbyggede

Et plugin kan erklære flere typer på én gang — mediepluginet er både en service og en bar-widget. Bjælke-widgets får en ekstra barWidget-blok med et vist navn, en kategori, en valgfri defaultSection og allowMultiple, som angiver, om det giver mening at have mere end én på bjælken. De fleste widgets sætter den til false; afstandselementer og indikatorer sætter den til true.

Kontrollér dit plugin, før du udgiver noget:

omarchy plugin validate ./my-plugin

Det udfører de samme kontroller, som shellen gør ved indlæsning: skemaversionen, de obligatoriske felter, et id, der ikke er reserveret, indgangspunkter, der er sikre relative stier og faktisk findes, et indgangspunkt for hver type, du har angivet, samt at der ikke findes symbolske links noget sted i mappen.

Hvis du vil have det fulde overblik, er kildekoden dokumentationen: shell/README.md i Omarchy-repositoriet beskriver manifestets skema, shellens IPC-kontrakt og den præcise struktur af shell.json, mens shell/plugins/README.md oplister alle førstepartsplugins med deres id, typer og indgangspunkter.

Del dit plugin med verden #

Når du har lavet noget, du kan lide, skal du lægge det i et offentligt git-repository. Det er hele distributionsmekanismen — derefter kan alle køre omarchy plugin add med din URL og have det kørende på få sekunder.

For at hjælpe folk med rent faktisk at finde det kan du registrere det på omarchyplugins.com. Det er fællesskabets katalog over Omarchy-shell-plugins, og det er det første sted, du bør lede, når du overvejer, om nogen allerede har bygget den widget, du er ved at skrive. Gå på opdagelse der, før du går i gang!