`plugin.json`-dokumentaatio¶

Kukin Python-liitännäinen ilmoittaa identiteettinsä, aloituskohtansa ja valikkopalkkisijaintinsa plugin.json-tiedostossa main.py-tiedostonsa vieressä. Tämä on sama skeema, jota C++-puoli käyttää; vain kentät entry ja module ovat Python-kohtaisia.

Esimerkki¶

{
  "id":          "org.example.wordcount",
  "name":        "Word Count",
  "version":     "1.0.0",
  "vendor":      "Example, Inc.",
  "description": "Counts words and characters in the active document.",
  "apiVersion":  1,
  "entry":       "python",
  "module":      "main",
  "pyRequires":  [],
  "order":       900,
  "menus": [
    { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
  ]
}

Kentät¶

Pakolliset¶

Kenttä	Tyyppi	Huomautuksia
`id`	merkkijono	Käänteisen DNS:n muotoinen yksilöllinen tunniste. Käytetään kaikkialla — käyttöönotto ja käytöstä poisto, lokirivit, liitännäiskohtaiset asetukset. Ei saa muuttua versioiden välillä.
`apiVersion`	kokonaisluku	Täytyy olla sama kuin isännän `MTE_PLUGIN_API_VERSION`. Tällä hetkellä `1`. Ristiriita näkyy liitännäissivulla, ja liitännäinen luetellaan muttei ladata.
`entry`	merkkijono	Täytyy olla `"python"`, jotta reititetään Python-taustajärjestelmän kautta. `"native"` tai puuttuva reitittää Qt-lataajan kautta.
`module`	merkkijono	Sen Python-moduulin nimi, joka sisältää funktion `register(ctx)`. Jos arvo on `"main"`, työntekijä etsii tiedostoa `main.py` liitännäiskansion sisältä. Pistein erotetut pakettinimet (`"src.main"`) ovat tuleva laajennus — vaihe 1 tukee vain litteitä nimiä.

Suositellut¶

Kenttä	Tyyppi	Huomautuksia
`name`	merkkijono	Ihmisluettava näyttönimi, joka näkyy liitännäissivulla.
`version`	merkkijono	Semver; muutoin vapaamuotoinen.
`vendor`	merkkijono	Tekijä tai organisaatio. Näkyy liitännäissivulla.
`description`	merkkijono	Yksi tai kaksi riviä. Näkyy liitännäissivulla.

Valinnaiset¶

Kenttä	Tyyppi	Huomautuksia
`order`	kokonaisluku	Latausjärjestys liitännäisten kesken; pienempi latautuu aiemmin. Oletus `1000`. Tasapelit ratkaisee `id`. `requires` menee sen edelle.
`requires`	merkkijonotaulukko	Niiden liitännäisten tunnisteet, joita ilman tämä liitännäinen ei voi toimia (natiivit ja Python-liitännäiset samoin), esimerkiksi `["org.mte.lsp"]` — ei pip-paketteja, ne kuuluvat kenttään `pyRequires`. Ne käynnistetään ennen tätä liitännäistä riippumatta `order`-arvosta; jos jokin puuttuu, on poistettu käytöstä, lisenssin estämä tai jäi lataamatta, tätä liitännäistä ei käynnistetä lainkaan, ja Asetukset → Liitännäiset kertoo, minkä se tarvitsee ja miksi. Sama merkitys kuin natiivissa liitännäisessä.
`apiMinorVersion`	kokonaisluku	Isäntä-API:n pienin minor-versio, jota tämä liitännäinen tarvitsee (oletus `0`). Python-liitännäisellä ei ole käännettyä `info()`-funktiota, joten tämä on sen ainoa ilmoitus: ilmoita uusimman käyttämäsi kutsun minor-versio. Vanhempi isäntä näyttää liitännäisen tilana »Vaatii uudemman OctoEdit-version« eikä käynnistä sitä.
`pyRequires`	merkkijonotaulukko	Pip-vaatimusmerkkijonoja (esimerkiksi `["requests>=2.31"]`). Liitännäisen ensimmäisellä käynnistyksellä editori valmistelee liitännäiskohtaisen virtuaaliympäristön, asentaa nämä siihen pipillä ja ajaa liitännäisen työntekijän sen alla (katso Paketointi). Muut kuin merkkijonot ja tyhjät kohdat ohitetaan.
`permissions`	merkkijonotaulukko	Karkeita kykyilmoituksia (esimerkiksi `["network"]`), näytettynä vain luettavana Käyttöoikeudet-sarakkeessa kohdassa Asetukset → Liitännäiset, jotta käyttäjät näkevät, mitä liitännäinen sanoo tekevänsä. Pelkkä ilmoitus — ei vielä pakoteta.
`menus`	objektitaulukko	Katso alta.
`thirdParty`	objektitaulukko	Kolmannen osapuolen komponentit, jotka liitännäinen toimittaa, tunnustettavaksi Tietoja-ikkunassa. Kukin kohta: `name` (pakollinen), `license`, `url`, `file`. Toimita kentän `file` nimeämä lisenssiteksti liitännäisen mukana kansiossa `Plugins/Licenses/<id>/`. Katso alta.

`menus`¶

Kukin kohta ilmoittaa yhden ylimmän tason valikon, johon liitännäinen osallistuu, ja asettaa sen sijainnin. Toista yksi objekti kutakin koskettamaasi ylimmän tason valikkoa kohti (Tools, Plugins, Help ja niin edelleen).

"menus": [
  { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
]

Kenttä	Tyyppi	Huomautuksia
`title`	merkkijono, pakollinen	Ylimmän tason valikon nimiö, jonka alla kohta sijaitsee (`Plugins`, `Tools` …). Täytyy vastata niiden polkujen vasemmanpuoleisinta osaa, jotka välität funktiolle `ctx.menus.add_item()`.
`barPriority`	kokonaisluku, valinnainen	Sijainti vasemmalta oikealle valikkopalkissa. Pienempi = kauempana vasemmalla. Ytimen valikoilla on kiinteät, 100:n välein sijoitetut sijainnit (Tiedosto `100`, Muokkaa `200` …, Ikkuna `600`); `570` sijoittaa alivalikkosi lähelle `Plugins`-sijaintia. Toistetaan niiden liitännäisten kesken, jotka kohdistuvat samaan ylimmän tason valikkoon; viimeisen voittaminen on ongelmatonta, koska se on idempotenttia.
`itemPriority`	kokonaisluku, valinnainen	Liitännäisesi koko lohkon pystysuora sijainti lehtivalikon sisällä. Oletus `1000`. Pienempi = ylempänä.

Et luettele yksittäisiä kohtia täällä — ne lisää funktio ctx.menus.add_item() ajon aikana. menus koskee vain valikkopalkkisijaintia.

`thirdParty`¶

Ilmoita mikä tahansa kolmannen osapuolen komponentti, jonka liitännäisesi toimittaa, jotta Tietoja-ikkuna voi tunnustaa sen. Kukin kohta:

"thirdParty": [
  { "name": "SomeLib", "license": "MIT",
    "url": "https://example.com/", "file": "SomeLib-LICENSE.txt" }
]

Kenttä	Tyyppi	Huomautuksia
`name`	merkkijono, pakollinen	Komponentti. Kohdat, joilla ei ole ei-tyhjää nimeä, pudotetaan.
`license`	merkkijono, valinnainen	SPDX-tyylinen nimiö, esimerkiksi `MIT` tai `LGPL-3.0`.
`url`	merkkijono, valinnainen	Projektin tai kotisivun osoite.
`file`	merkkijono, valinnainen	Toimittamasi lisenssitekstin tiedostonimi, joka ratkaistaan polusta `Plugins/Licenses/<your-plugin-id>/<file>`.

Sinä omistat lisenssitekstit: toimita ne liitännäispakettisi mukana kansiossa Plugins/Licenses/<id>/. Editori luettelee komponentit ja osoittaa käyttäjät tuohon kansioon; se ei säilytä liitännäisesi kolmannen osapuolen tekstejä omassa Licenses/-kansiossaan.

Staattinen tarkistus¶

Etsintähetkellä — ja uudelleen, kun .mteplugin-paketti asennetaan — isäntä lukee kentän module, avaa tiedoston <pluginDir>/<module>.py ja vahvistaa, että siinä on ylätason def register(...) — mitään koodia ei ajeta. Asennusohjelma hylkää epäonnistuvan paketin virheikkunalla; etsintä ohittaa liitännäisen hiljaisesti ja kirjaa virherivin lokiin:

PythonPluginBackend: skipping 'org.example.wordcount': module
'.../main.py' does not declare a top-level `def register(...)`.

Pidä funktio register sarakkeessa 0 rivillä, joka alkaa merkkijonolla def register(.

Latausjärjestys ja valikkopalkkisijainti¶

Jos liitännäisesi osallistuu valikkoon Plugins arvolla barPriority: 570, valikko näkyy sijainnissa 570 valikkopalkissa. Kaksi liitännäistä, joilla on eri barPriority-arvot samalle otsikolle, kilpailevat: se, joka latautui viimeisenä, voittaa, mutta koska molemmat yleensä ilmoittavat saman sijainnin tietylle valikolle, sillä ei ole väliä. Katso koko järjestysmalli tiedostosta PLUGIN_ARCHITECTURE.md §13.

Mitä tänne EI kuulu¶

Isäntä jäsentää yllä dokumentoidut kentät ja ohittaa kaiken muun — älä keksi kenttiä; tuntematon avain on hiljaista kuollutta painoa.

plugin.json-dokumentaatio¶