Ein Plugin erstellen

Beginne mit einer nützlichen Aktion. Halte Kompatibilität, Autorität und Laufzeitverhalten sichtbar, während du Fähigkeiten hinzufügst.

Vorlage und Typen beziehen

Das öffentliche Plugin-Repository enthält eine Vorlage, Deklarationen, ein Register und Paketprüfungen. Vergleiche bei noch nicht veröffentlichten APIs den aktuellen Quellvertrag und verwende einen passenden Entwicklungs-Build. Die neueste veröffentlichte App kann älter sein als diese Dokumentation.

Verwende für die Repository-Skripte Bun. Kopiere template/ nach plugins/<your-plugin-id>/ und halte den Verzeichnisnamen identisch mit der Manifest-ID.

Ein minimales Kommando

Dieses Beispiel registriert während der Aktivierung ein Kommando und führt seine UI-Wirkung erst aus, wenn die nutzende Person es aufruft.

json

{
  "id": "hello-reader",
  "name": "Hello Reader",
  "version": "0.1.0",
  "schemaVersion": 1,
  "main": "main.js",
  "requires": {
    "contributions": { "commands": "^1.1.0" },
    "services": { "ui": "^1.17.0" }
  }
}

typescript

export default {
  activate(ctx) {
    ctx.contributions.commands.register({
      id: "hello",
      title: "Say hello",
      run: () => ctx.services.ui.showToast("Hello, reader!"),
    });
  },
};

Kompiliere das Einstiegsmodul zu einer eigenständigen main.js. Das Manifest verlangt absichtlich die aktuell dokumentierten Versionen; verwende ältere Bereiche erst, nachdem du diese Verträge geprüft und getestet hast.

Die kleinstmögliche sinnvolle Autorität hinzufügen

Nutze den Explorer, um eine Methode zu finden und ihr Start-Manifestfragment zu kopieren. Ein Fragment deklariert eine Fähigkeit; ergänze die für die konkrete Operation erforderlichen Freigaben.

Das Lesen von Bibliotheksdaten benötigt library:read; Änderungen benötigen library:write.
Einstellungen verwenden exakte settingsAccess-Pfade und Operationen.
Beliebiges HTTP benötigt service:network sowie erlaubte networkAccess.origins.
Eine lesebezogene Methode in einem berechtigungsfreien UI-Dienst kann trotzdem reading:read oder reading:write benötigen.
Buchfreigaben werden über die Zustimmung des Hosts ausgewählt und in ctx.grants.book bereitgestellt; ein Manifest kann sich keinen Zugriff auf ein anderes Buch geben.

Prüfe ctx.capabilities und behandle fehlende optionale Namespaces. Halte ReadAware-eigene Daten in ihren Domänen; Plugin-Speicher ist für eigene Datensätze, Einstellungen und Checkpoints vorgesehen.

Mit Beobachtungen und Abbruch arbeiten

Gib Handles frei, sobald du sie nicht mehr brauchst. Übergib bei unterstützten Aufrufen ein AbortSignal und warte das tatsächliche Ergebnis ab. Ein Abbruch macht einen bereits erfolgten Schreibvorgang oder eine externe Nebenwirkung nicht rückgängig.

Eine automatische Reaktion verwendet für die daraus entstehende Arbeit ctx.withEvent(delivery), auch nach einem await. Gib kausalen Abonnements, wenn vom Vertrag verlangt, eine stabile ruleId. Benutzerinitiierte Aktionen verwenden den ursprünglichen Aktivierungskontext. So kann der Host Schleifen erkennen, ohne unabhängige Aktionen zu vermischen.

Lokal bauen und installieren

Folge den Paket-Skripten des Checkouts. Im öffentlichen Plugin-Repository sind die üblichen Prüfungen:

bash

bun run build
bun run typecheck
bun test
bun run validate

Öffne ReadAware → Einstellungen → Plugins → Plugin installieren, wähle den gebauten Ordner aus und prüfe die Zustimmungsübersicht. Teste die Funktion in der Desktop-App. Baue sie erneut und installiere sie erneut, um ein Update zu prüfen.

Private Daten versionieren

schemaVersion ist unabhängig von der Paketversion. Wenn sich die Form gespeicherter KV-Daten oder Dokumente ändert, liefere die unterstützten Upgrade- und Downgrade-Übergänge über migrate(storageCtx, change).

Eine Migration erhält ausschließlich Speicherberechtigung. Teste neben dem Erfolg auch einen fehlgeschlagenen Übergang: Das vorherige Paket und die bestätigten Daten müssen nutzbar bleiben. Vermeide eine unnötige Schemaänderung bei gewöhnlichen Code-Updates.

Die Grenzen deiner Funktion testen

Prüfe tatsächliches Worker-/Tauri-Verhalten, Ablehnungen wegen Berechtigungen und Buchumfang, Abbruch, Deaktivierung und erneute Aktivierung sowie Fehlerwiederherstellung. Bei einem UI-Plugin gehören Tastaturnavigation, lange Texte und schmale Fenster dazu. Bei einem Plugin mit Datenänderungen gehören konkurrierende Bearbeitungen und Neustarts dazu, wenn Persistenz wichtig ist.

Zeitpläne laufen, solange die App geöffnet ist; dauerhafte Jobs unterstützen nur typisierte Pläne des Hosts. Keines von beiden ist ein allgemeiner Hintergrundprozess oder Job-Runner für beliebigen Code. Die API-Referenz beschreibt diese Grenzen.

Veröffentlichen

Sobald das gebaute Paket mit seinen deklarierten Mindestverträgen funktioniert, folge Veröffentlichen.