Plugins erstellen - Matter.js-Dokumentation

Beispiel

Hier ist ein grundlegendes Matter.js-Plugin-Boilerplate:

var MyPlugin = {
    name: 'matter-my-plugin',

    version: '0.1.0',

    for: 'matter-js@^0.10.0',

    uses: [
        'matter-some-dependency@^0.1.0',
        'matter-another-dependency@^0.1.0'
    ],

    options: {
        something: true
    },

    install: function(matter) {
        // patch `matter` here (not the global Matter object)
    },

    // implement your plugin functions etc...
};

Matter.Plugin.register(MyPlugin);

Eine Beschreibung der erforderlichen Eigenschaften:

name String, erforderlich Der eindeutige Name des Plugins (z. B. derselbe wie package.json)
version String, erforderlich Die Version des Plugins (eine begrenzte Teilmenge von semver)
install Funktion, erforderlich Die Installationsfunktion, sie wird nur einmal aufgerufen und erhält als erstes Argument einen Verweis auf das Modul, auf dem sie installiert wird

Es gibt einige zusätzliche optionale Eigenschaften:

for String, optional Der Name und optional die Version des Moduls, auf dem dieses Plugin installiert werden soll on
uses Array, optional Die Namen und optional Versionen aller anderen Plugins, die dieses Plugin vor sich selbst installieren muss. Es ist auch möglich, hier direkt Referenzen an Plugin-Objekte zu übergeben, aber es wird nicht empfohlen.
options Objekt, optional Alle globalen Optionen für das Plugin

Obwohl der obige Boilerplate als Leitfaden dient, sollten auch alle gleichwertigen Darstellungen, die diese Eigenschaften offenlegen, funktionieren.

Boilerplate

Ein vollständiges, produktionsbereites Boilerplate-Starterprojekt ist unter „matter-plugin-boilerplate“ verfügbar, das Sie forken können, um Ihr Plugin mit allen wesentlichen Elementen (Build, Dev, Lint, Test, Doc, Release usw.) zu starten.matter-plugin-boilerplate

Versionierung

Plugins werden mit dem Semver-Ansatz versioniert, was die Angabe der Kompatibilität erleichtert. Versionen können für Plugins selbst, die Version von Matter.js, für die sie empfohlen werden, und die Versionen ihrer Abhängigkeiten angegeben werden.

Versionen haben streng das Format (wie in semver). Versionen können optional ein Prerelease-Tag im Format haben. Bereiche sind eine strikte Teilmenge von npm-Bereichen. Nur die folgenden Bereichstypen werden unterstützt: x.y.z x.y.z-alpha

Tilde-Bereiche, z. B. ~1.2.3
Caret-Bereiche, z. B. ^1.2.3
Genaue Version, z. B. 1.2.3
Jede Version *

Wenn keine Version oder kein Bereich angegeben ist, wird davon ausgegangen, dass jede Version () erfüllt.*

Registrierung

Es ist sehr wichtig, nach Ihrer Plugin-Definition aufzurufen. Dadurch kann es im Plugin-System nach Namen aufgelöst werden, was die empfohlene Methode zum Angeben von Abhängigkeiten ist.Plugin.register

Matter.Plugin.register(MyPlugin);

Patching

Die Funktion eines Plugins ist der Ort, an dem es Patches anwenden sollte, die die Funktionen des Plugins auf module.installMatter.* implementieren.

In der Bibliothek sind die Funktionen und enthalten, die Sie in den meisten Fällen zum Patchen verwenden sollten, da sie dazu beitragen, sicherzustellen, dass Sie die ursprüngliche Funktion oder andere Plugins, die sie ebenfalls patchen, nicht beschädigen.Matter.beforeMatter.after

Hier ist ein Beispiel für den empfohlenen Ansatz:

var MyPlugin = {
    // ...

    install: function(base) {
        base.before('Engine.create', function(options) {
            MyPlugin.Engine.beforeCreate(options);
        });

        base.after('Engine.create', function() {
            MyPlugin.Engine.afterCreate(this);
        });
    },

    Engine: {
        beforeCreate: function(options) {
            console.log('Creating engine for:', options);
        },
        afterCreate: function(engine) {
            console.log('Engine created:', engine);
        }
    }
};

// ...

Wenn dieses Plugin installiert ist, meldet es sich vor und nach dem Aufruf in der Konsole an.Matter.Engine.create

Unter der Haube sind und beide Helfer für .Matter.beforeMatter.afterCommon.chain

Tipps zum Patchen:

Die übergebenen Argumente sind für jede Funktion in der Kette gleich.
Der Wert von ist das letzte in der Kette zurückgegebene Objekt.
Ändern Sie nicht die ursprüngliche Funktionssignatur.
Geben Sie nicht innerhalb eines und zurück, es sei denn, Sie beabsichtigen, das Ergebnis zu ändern.
Stellen Sie bei der Rückgabe sicher, dass derselbe Typ wie bei der gepatchten Funktion vorliegt.
Speichern Sie keine Verweise auf Funktionen (da diese auf ungepatchte Versionen verweisen können). Wichtig.*

Verwenden anderer Plugins als Abhängigkeiten

Plugins können in kleinere Teile zerlegt, gemeinsam genutzt und kombiniert werden. Abhängigkeiten können innerhalb der Eigenschaft angegeben werden und werden vor dem Plugin installiert, das sie angibt. verwendet

var MyPlugin = {
    // ...

    uses: [
        'matter-some-dependency@^0.1.0',
        'matter-another-dependency@^0.1.0'
    ],

    // ...
};

// ...

Beachten Sie, dass diese Abhängigkeiten immer nur einmal installiert werden, unabhängig davon, wie viele Plugins sie verwenden. Wenn der Code eines Plugins mehrmals geladen wird, wird der mit der höchsten Version verwendet.

Richtlinien für Plugins

Einige allgemeine Richtlinien für Plugins:

Überlegen Sie, ob Sie es überhaupt als Plugin implementieren (ein Pull Request wäre möglicherweise angemessener)
Versionieren Sie alles
Dokumentieren Sie alles (Code und Readme)
Erstellen Sie Plugins unter Berücksichtigung von Freigabe und Wiederverwendung
Speichern Sie keine Verweise auf Funktionen (da diese auf ungepatchte Versionen verweisen können). Wichtig.*
Fügen Sie keine neuen Funktionen zu Modulen oder Namespaces hinzu, die Sie nicht pflegen (patchen Sie nur vorhandene Funktionen)
Fügen Sie benutzerdefinierte Eigenschaften hinzu, z. B. obj.pluginbody.plugin.newFeature.enabled
Folgen Sie derselben Namensraumstruktur wie der Kern (z. B. MyPlugin.Body.initMyPlugin.Engine.update)
Stellen Sie die Funktionen Ihres Plugins bereit und implementieren Sie sie, damit sie manuell aufgerufen werden können
Vermeiden Sie nach Möglichkeit eine bestimmte Ausführungsreihenfolge
Je kleiner, desto besser
Aber vermeiden Sie unnötige Abhängigkeiten
Ändern Sie Optionen oder Einstellungen nicht auf unerwartete oder nicht dokumentierte Weise
Verwenden Sie Bedingungen, bevor Sie möglicherweise undefinierte Eigenschaften bearbeiten
Bündeln Sie keine Abhängigkeiten (dokumentieren Sie sie)