Dokumentation af `plugin.json`¶

Hvert Python-udvidelsesmodul erklærer sin identitet, sit indgangspunkt og sin placering på menulinjen i en plugin.json-fil ved siden af sin main.py. Det er det samme skema, C++-siden bruger; kun felterne entry og module er særlige for Python.

Eksempel¶

{
  "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 }
  ]
}

Felter¶

Påkrævede¶

Felt	Type	Bemærkninger
`id`	tekst	Entydig identifikator i omvendt DNS-form. Bruges overalt — at slå til og fra, loglinjer, indstillinger pr. udvidelsesmodul. Må ikke ændre sig fra version til version.
`apiVersion`	heltal	Skal være lig med værtens `MTE_PLUGIN_API_VERSION`. I øjeblikket `1`. En uoverensstemmelse vises på udvidelsesmodulsiden, og modulet opregnes, men indlæses ikke.
`entry`	tekst	Skal være `"python"` for at gå gennem Python-backenden. `"native"` eller ingenting går gennem Qt-indlæseren.
`module`	tekst	Navnet på det Python-modul, der indeholder `register(ctx)`. Er det `"main"`, leder arbejderen efter `main.py` inde i modulmappen. Pakkenavne med punktummer (`"src.main"`) er en fremtidig udvidelse — fase 1 understøtter kun flade navne.

Anbefalede¶

Felt	Type	Bemærkninger
`name`	tekst	Det læsbare visningsnavn, der vises på udvidelsesmodulsiden.
`version`	tekst	Semver; ellers frit formuleret.
`vendor`	tekst	Ophavsmand eller organisation. Vises på udvidelsesmodulsiden.
`description`	tekst	En eller to linjer. Vises på udvidelsesmodulsiden.

Valgfrie¶

Felt	Type	Bemærkninger
`order`	heltal	Indlæsningsrækkefølgen på tværs af udvidelsesmoduler; lavere indlæses tidligere. `1000` som standard. Uafgjorte afgøres af `id`. `requires` går forud.
`requires`	tabel af tekster	Id'erne på de udvidelsesmoduler, som dette modul ikke kan fungere uden (native og Python ens), f.eks. `["org.mte.lsp"]` — ikke pip-pakker, de hører til i `pyRequires`. De startes før dette modul, uanset hvad `order` siger; mangler et af dem, er det slået fra, spærret af licensen eller blev det ikke indlæst, startes dette modul slet ikke, og Indstillinger → Udvidelsesmoduler fortæller, hvilket det mangler og hvorfor. Samme betydning som for et native udvidelsesmodul.
`apiMinorVersion`	heltal	Den laveste minor-version af værtens API, som modulet har brug for (standard `0`). Et Python-modul har ingen kompileret `info()`, så dette er dets eneste erklæring: angiv minor-versionen for det nyeste kald, du bruger. En ældre vært viser modulet som »Kræver en nyere version af OctoEdit« og starter det ikke.
`menus`	tabel af objekter	Se nedenfor.
`pyRequires`	tabel af tekster	Pip-kravstrenge (f.eks. `["requests>=2.31"]`). Ved modulets første start sætter editoren et virtuelt miljø pr. udvidelsesmodul op, installerer disse i det med pip og kører modulets arbejder under det (se Pakning). Poster, der ikke er tekst, og tomme poster springes over.
`permissions`	tabel af tekster	Grove erklæringer om formåen (f.eks. `["network"]`), der vises skrivebeskyttet i kolonnen Tilladelser under Indstillinger → Udvidelsesmoduler, så brugerne kan se, hvad et modul siger, det gør. Kun en erklæring — håndhæves endnu ikke.
`thirdParty`	tabel af objekter	De tredjepartskomponenter, udvidelsesmodulet leverer, til kreditering i vinduet Om. Hver post: `name` (påkrævet), `license`, `url`, `file`. Lever den licenstekst, `file` navngiver, sammen med modulet under `Plugins/Licenses/<id>/`. Se nedenfor.

`menus`¶

Hver post erklærer én øverste menu, udvidelsesmodulet bidrager til, og sætter dens placering. Gentag ét objekt pr. øverste menu, du rører (Tools, Plugins, Help og så videre).

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

Felt	Type	Bemærkninger
`title`	tekst, påkrævet	Den øverste menus mærkat, punktet ligger under (`Plugins`, `Tools` …). Skal passe til det yderste venstre led i de stier, du giver til `ctx.menus.add_item()`.
`barPriority`	heltal, valgfrit	Rang fra venstre mod højre på menulinjen. Lavere = længere til venstre. Kernens menuer har faste prioriteter med 100 imellem (Filer `100`, Rediger `200` …, Vindue `600`); `570` placerer din undermenu nær `Plugins`-placeringen. Gentages på tværs af moduler, der retter sig mod den samme øverste menu; at den sidste vinder, gør ikke noget, for den kan gentages.
`itemPriority`	heltal, valgfrit	Den lodrette rang for hele dit moduls blok inde i den nederste menu. `1000` som standard. Lavere = længere oppe.

Du opregner IKKE enkelte punkter her — dem tilføjer ctx.menus.add_item() under kørslen. menus handler kun om placering på menulinjen.

`thirdParty`¶

Erklær enhver tredjepartskomponent, dit udvidelsesmodul leverer, så vinduet Om kan kreditere den. Hver post:

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

Felt	Type	Bemærkninger
`name`	tekst, påkrævet	Komponenten. Poster uden et navn, der ikke er tomt, droppes.
`license`	tekst, valgfrit	En SPDX-agtig mærkat, f.eks. `MIT` eller `LGPL-3.0`.
`url`	tekst, valgfrit	Projektets eller hjemmesidens adresse.
`file`	tekst, valgfrit	Filnavnet på den licenstekst, du leverer, som findes under `Plugins/Licenses/<your-plugin-id>/<file>`.

Du ejer licensteksterne: lever dem sammen med din udvidelsesmodulpakke under Plugins/Licenses/<id>/. Editoren opregner komponenterne og peger brugerne mod den mappe; den gemmer ikke tredjepartstekster for dit modul i sin egen Licenses/-mappe.

Den statiske efterprøvning¶

Ved opdagelsen — og igen, når en .mteplugin-pakke installeres — læser værten module, åbner <pluginDir>/<module>.py og bekræfter, at den indeholder en def register(...) på øverste niveau — der køres ingen kode. Installationsprogrammet afviser en pakke, der ikke lever op til det, med et fejlvindue; opdagelsen springer i stilhed modulet over med en fejllinje i loggen:

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

Hold register i kolonne 0 på en linje, der begynder med def register(.

Indlæsningsrækkefølge og placering på menulinjen¶

Bidrager dit udvidelsesmodul til Plugins med barPriority: 570, kommer menuen frem som nummer 570 på menulinjen. To moduler med forskellige barPriority-værdier for den samme titel kappes: det, der blev indlæst sidst, vinder, men da begge som regel erklærer den samme rang for en given menu, betyder det ikke noget. Se PLUGIN_ARCHITECTURE.md §13 for hele rækkefølgemodellen.

Hvad der IKKE hører hjemme her¶

Værten fortolker de felter, der er beskrevet ovenfor, og ser bort fra alt andet — opfind ikke felter; en ukendt nøgle er i stilhed dødvægt.

Dokumentation af plugin.json¶