Analysieren Sie, wie Sie automatisch Vue-Komponentendokumentation generieren

1. Aktuelle Situation

Das Vue-Framework wird häufig in der Front-End-Entwicklung verwendet. Wenn ein von mehreren Personen entwickeltes Vue-Projekt über einen langen Zeitraum gewartet wird, fallen häufig viele gemeinsame Komponenten weg. Zu diesem Zeitpunkt kommt es häufig vor, dass eine Person eine Komponente entwickelt, während andere Betreuer oder Neulinge nicht wissen, was die Komponente tut oder wie sie verwendet wird. Sie müssen den Quellcode erneut durchsehen oder bemerken die Existenz der Komponente nicht einmal, was zu doppelter Entwicklung führt. Zu diesem Zeitpunkt ist es äußerst wichtig, die entsprechenden Komponentendokumente zu pflegen, um eine gute Zusammenarbeit zwischen verschiedenen Entwicklern sicherzustellen.

Die herkömmliche manuelle Pflege von Dokumenten bringt jedoch neue Probleme mit sich:

• Die Effizienz ist gering. Das Schreiben von Dokumenten ist eine zeitaufwändige und mühsame körperliche Aufgabe. Nachdem Sie endlich die Zeit gefunden haben, die Komponente zu entwickeln, müssen Sie immer noch die Dokumente schreiben. Allein der Gedanke daran überfordert mich.
• Fehleranfällig: Der Dokumentinhalt ist fehleranfällig und stimmt möglicherweise nicht mit dem tatsächlichen Komponenteninhalt überein.
• Das ist nicht klug. Beim Aktualisieren von Komponenten müssen Sie die Änderungen manuell mit dem Dokument synchronisieren, was zeitaufwändig ist und zu Auslassungen führen kann.

Die ideale Art der Dokumentenpflege ist:

• Der Arbeitsaufwand ist gering und es kann mit Vue-Komponenten kombiniert werden, um automatisch relevante Informationen abzurufen, wodurch der Arbeitsaufwand beim Schreiben von Dokumenten von Grund auf reduziert wird.
• Die Informationen sind korrekt und die Schlüsselinformationen der Komponente stimmen fehlerfrei mit dem Komponenteninhalt überein.
• Intelligente Synchronisierung: Wenn Vue-Komponenten iterativ aktualisiert werden, kann der Dokumentinhalt automatisch synchron aktualisiert werden, ohne dass manuell überprüft werden muss, ob die Informationen konsistent sind.

2. Community-Lösungen

2.1 Geschäftsbericht

Um den oben genannten idealen Effekt zu erzielen, habe ich die Lösungen in der Community gesucht und untersucht. Derzeit bietet Vue offiziell Vue-Press an, mit dem sich Vue-Projektdokumente schnell erstellen lassen. Außerdem gibt es eine Bibliothek, mit der Informationen automatisch aus Vue-Komponenten extrahiert werden können.

Die vorhandenen Bibliotheken von Drittanbietern können die Anforderungen jedoch nicht vollständig erfüllen. Es gibt hauptsächlich zwei Probleme:

• Die Informationen sind nicht umfassend und einige wichtige Inhalte können nicht abgerufen werden, z. B. die Unfähigkeit, das V-Modell zu verarbeiten, die Unfähigkeit, die Synchronisierung des Attributmodifikators zu analysieren und die Unfähigkeit, detaillierte Informationen zu den Funktionseingabeparametern in Methoden abzurufen.
• Beispielsweise können im folgenden Beispiel das Wertattribut und das Eingabeereignis kombiniert werden, um ein V-Modellattribut zu bilden. Diese Informationen werden jedoch nicht im generierten Dokument widergespiegelt und der Leser des Dokuments muss sie selbst verstehen und beurteilen. Und aus der generierten Dokumentation geht nicht hervor, ob die Synchronisierung unterstützt wird.

Es gibt viele benutzerdefinierte Logos und die Benennung der Logos ist zu persönlich, was zu großen Eingriffen in den Originalcode führt. Beispielsweise ist es im Code in der folgenden Abbildung zum Markieren von Kommentaren erforderlich, dem ursprünglichen Geschäftscode zusätzliche Bezeichner wie „@vuese“ und „@arg“ hinzuzufügen, wodurch dem Geschäftscode einige geschäftsirrelevante Inhalte hinzugefügt werden.

3. Technische Lösung

Als Reaktion auf die oben genannten Probleme und die Unzulänglichkeiten der Community-Lösungen hat unser Team ein kleines Tool speziell für die Informationserfassung von Vue-Komponenten und die Ausgabe von Komponentendokumenten entwickelt. Die allgemeine Wirkung ist wie folgt:

Im obigen Bild ist links eine allgemeine Vue-Einzeldateikomponente und rechts das generierte Dokument. Wir können sehen, dass wir die folgenden Informationen erfolgreich aus der Komponente extrahiert haben:

• Der Name der Komponente.
• Beschreibung der Komponente.
• Requisiten, Slots, Ereignisse, Methoden usw.
• Der Annotationsinhalt der Komponente.

Als nächstes erklären wir ausführlich, wie diese Informationen aus der Komponente extrahiert werden.

3.1. Vue-Dateianalyse

Da wir Informationen aus Vue-Komponenten extrahieren möchten, lautet die erste Frage, wie Vue-Komponenten analysiert werden. Vue hat die Bibliothek Vue-Template-Compiler offiziell speziell für das Vue-Parsing entwickelt, und wir können hier auch denselben Ansatz verwenden. Durch Nachschlagen in der Dokumentation können wir sehen, dass der Vue-Template-Compiler eine Methode „parseComponent“ zum Verarbeiten der ursprünglichen Vue-Datei bereitstellt.

importiere { parseComponent } von 'Vue-template-compiler'
const Ergebnis = parseComponent(VueFileContent, [Optionen])

Die verarbeiteten Ergebnisse sind wie folgt, wobei Vorlage und Skript jeweils dem Textinhalt von Vorlage und Skript in der Vue-Datei entsprechen.

Schnittstelle SFCDescriptor exportieren {
  Vorlage: SFCBlock | nicht definiert;
  Skript: SFCBlock | nicht definiert;
  Stile: SFCBlock[];
  benutzerdefinierteBlöcke: SFCBlock[];
}

Natürlich reicht es nicht aus, nur den Text zu erhalten. Um weitere Informationen zu erhalten, muss der Text weiter verarbeitet werden. Nachdem wir das Skript erhalten haben, können wir Babel verwenden, um JS in JS AST (abstrakter Syntaxbaum) zu kompilieren. Dieser AST ist ein allgemeines JS-Objekt, das durch JS durchlaufen und gelesen werden kann. Mit AST können wir die gewünschten detaillierten Komponenteninformationen erhalten.

importiere { parse } von '@babel/parser';
const jsAst = parse(Skript, [Optionen]);

Als nächstes schauen wir uns die Vorlage an. Wenn wir weiter in der Dokumentation des Vue-Template-Compilers suchen, finden wir die Kompilierungsmethode. Kompilieren wird speziell zum Kompilieren der Vorlage in AST verwendet, was genau den Anforderungen entspricht.

importiere { kompiliere } von 'Vue-template-compiler'
const templateAst = kompilieren(Vorlage, [Optionen]);

Der AST im Ergebnis ist das Kompilierungsergebnis der Vorlage.

Schnittstelle CompiledResult exportieren {
  ast: ASTElement,
  rendern: Zeichenfolge,
  staticRenderFns: Array<string>,
  Fehler: Array<string>
}

Durch den ersten Schritt der Dateianalyse haben wir erfolgreich den Vue-Vorlagen-AST und den AST von js im Skript erhalten. Im nächsten Schritt können wir daraus die gewünschten Informationen abrufen.

3.2 Informationsextraktion

Abhängig davon, ob eine Vereinbarung erforderlich ist, können Informationen in zwei Arten unterteilt werden:

• Einer besteht darin, dass es direkt von der Vue-Komponente abgerufen werden kann, z. B. Requisiten, Ereignisse usw.
• Der andere Typ erfordert zusätzliche vereinbarte Formate, wie etwa Kommentare zur Komponentenbeschreibung, Beschreibungen von Requisiteneigenschaften usw. Dieser Teil kann in die Kommentare eingefügt und durch Analysieren der Kommentare abgerufen werden.

Um bequem Informationen von ast zu lesen, finden Sie hier eine kurze Einführung in das Tool @babel/traverse, eine offizielle Bibliothek, die von Babel speziell zum Durchlaufen von js AST bereitgestellt wird. Anwendung:

Traverse aus „@babel/traverse“ importieren

traverse(jsAst, Optionen);

Indem Sie in den Optionen die Rückruffunktion des entsprechenden Inhalts konfigurieren, können Sie den gewünschten AST-Knoten erhalten. Informationen zur spezifischen Verwendung finden Sie in der offiziellen Dokumentation.

3.2.1. Direkt zugängliche Informationen

Die Informationen, die direkt aus dem Code abgerufen werden können, können das Problem der Informationssynchronisierung effektiv lösen. Unabhängig davon, wie sich der Code ändert, können die Schlüsselinformationen des Dokuments automatisch synchronisiert werden, wodurch die Mühe des manuellen Korrekturlesens entfällt.

Die Informationen, die direkt abgerufen werden können, sind:

• Komponenteneigenschaften
• Bereitstellen von Methoden für externe Aufrufe
• Veranstaltungen
• Spielautomaten

Sowohl 1 als auch 2 können Traverse verwenden, um die Objektknoten mit den Namen „Props“ und „Methoden“ im js AST direkt zu durchlaufen und sie zu erhalten.

Das Abrufen des Ereignisses ist etwas mühsamer. Sie können das Ereignis finden, indem Sie nach der Funktion $emit suchen. Die Funktion $emit kann beim Durchlaufen auf MemberExpress (Knoten mit komplexem Typ) hören und dann anhand des Attributnamens auf dem Knoten „$emit“ feststellen, ob es sich um ein Ereignis handelt. Wenn es sich um ein Ereignis handelt, lesen Sie das Argumentfeld im übergeordneten $emit-Element. Das erste Argumentelement ist der Ereignisname und die folgenden Elemente sind die Ereignisparameter.

dies.$emit('Ereignis', arg);

durchqueren(jsAst, {
 Mitgliedsausdruck(Knoten) {
  // Bestimmen Sie, ob es sich um ein Ereignis handelt
  wenn (Node.node.property.name === '$emit') {
  // Das erste Element ist der Ereignisname const eventName = Node.parent.arguments[0];
  }
 }
});

Nachdem wir erfolgreich Ereignisse erhalten und Ereignisse und Requisiten kombiniert haben, können wir die beiden speziellen Eigenschaften in Requisiten weiter bestimmen:

• Ob ein V-Modell vorhanden ist: Überprüfen Sie, ob in den Props ein Wertattribut vorhanden ist und ob in den Events ein Eingabeereignis vorhanden ist, um dies zu bestimmen.
• Ob eine Eigenschaft von Props die Synchronisierung unterstützt: Bestimmen Sie, ob im Zeitnamen von Events ein Ereignis mit „Update“ beginnt und ob der Ereignisname mit dem Eigenschaftsnamen übereinstimmt.

Die Informationen zu den Slots werden im AST der obigen Vorlage gespeichert. Durchlaufen Sie rekursiv den Vorlagen-AST, um den Knoten mit dem Namen „Slots“ zu finden, und suchen Sie dann den Namen auf dem Knoten.

3.2.2 Informationen, die einer Vereinbarung bedürfen

Warum müssen wir uns über die direkt beziehbaren Bauteilinformationen hinaus auf weitere Inhalte einigen? Erstens sind die direkt abrufbaren Informationen relativ dünn und reichen nicht aus, um ein relativ vollständiges Komponentendokument zu unterstützen. Zweitens schreiben wir bei der Entwicklung von Komponenten in unserem täglichen Leben viele Kommentare. Wenn wir einige Kommentare direkt extrahieren und in das Dokument einfügen können, kann der Arbeitsaufwand für die Dokumentenpflege erheblich reduziert werden.

Unter anderem kann Folgendes vereinbart werden:

• Der Name der Komponente.
• Eine Übersicht über die Komponente.
• Textbeschreibung von Requisiten, Ereignissen, Methoden und Slots.
• Detaillierte Beschreibung der Methoden-Tags und Eingabeparameter. Alle diese Inhalte können in Kommentaren verwaltet werden. Der Grund für die Verwaltung in Kommentaren besteht darin, dass Kommentare leicht aus dem oben erwähnten js AST und dem Template AST abgerufen werden können. Wenn wir die Vue-Komponenteninformationen analysieren, können wir diesen Teil der Zielanweisungen gemeinsam analysieren.

Als Nächstes konzentrieren wir uns darauf, wie Anmerkungen extrahiert und mit dem kommentierten Inhalt abgeglichen werden.

Kommentare in js können je nach Position in führende und nachfolgende Kommentare unterteilt werden. Kommentare an unterschiedlichen Positionen werden in entsprechenden Feldern gespeichert. Der Code wird wie folgt angezeigt:

//Header-Kommentar export default {} //Tailer-Kommentar

Ergebnisse analysieren

const exportNode = {
  Typ: "ExportDefaultDeclaration",
  führendeKommentare: [{
    Typ: 'CommentLine',
    Wert: 'Header-Kommentar'
  }],
  nachfolgende Kommentare: [{
    Typ: 'CommentLine',
    Wert: ‚Tail-Kommentar‘
  }]
}

An derselben Stelle können Kommentare entsprechend ihrem unterschiedlichen Format in einzeilige Kommentare (CommentLine) und Kommentare auf Blockebene (CommentBlock) unterteilt werden. Der Unterschied zwischen den beiden Kommentartypen spiegelt sich im Typfeld des Kommentarknotens wider:

/** * Kommentare auf Blockebene */ // Einzeiliger Kommentar export default {}

Ergebnisse analysieren

const exportNode = {
  Typ: "ExportDefaultDeclaration",
  führendeKommentare: [
    {
      Typ: 'CommentBlock',
      Wert: ‚Kommentar auf Blockebene‘
    },
    {
      Typ: 'CommentLine',
      Wert: 'Einzeiliger Kommentar'
    }
  ]
}

Darüber hinaus können wir aus den obigen Analyseergebnissen auch erkennen, dass der Kommentarknoten im kommentierten Exportknoten gemountet ist, wodurch auch ein weiteres oben erwähntes Problem gelöst wird: Wie erhält man die Zuordnung zwischen dem Kommentar und dem kommentierten Knoten? Tatsächlich hat Babel dies beim Kompilieren des Codes für uns erledigt.

Die Vorlage sucht unterschiedlich nach Kommentaren und kommentierten Inhalten. Der Kommentarknoten in der Vorlage existiert wie andere Knoten als DOM-Knoten. Beim Durchlaufen des Knotens bestimmen wir, ob es sich um einen Kommentarknoten handelt, indem wir beurteilen, ob der Wert des Felds isComment wahr ist. Der kommentierte Inhalt befindet sich nach dem Geschwisterknoten:

<!--Kommentar der Vorlage--> <slot>der kommentierte Knoten</slot>

Ergebnisse analysieren

const templateAst = [
  {
    isComment: true,
    Text: "Vorlagenkommentare",
    Typ: 3
  },
  {
    Schlagwort: "Slot",
    Typ: 1
  }
]

Da wir nun wissen, wie Kommentare verarbeitet werden, können wir mehr mit ihnen machen. Sie können beispielsweise in den Kommentaren von Methoden ein @public-Tag verwenden, um zwischen privaten und öffentlichen Methoden zu unterscheiden. Wenn Sie weitere Einzelheiten wünschen, können Sie auch das Format von js-doc zu Rate ziehen, einer anderen Bibliothek, die speziell zum Parsen von js-Kommentaren verwendet wird, um die Methodeneingabeparameter weiter zu erläutern und den Inhalt des Dokuments zu bereichern.

Wir müssen den Text nur ausschneiden und lesen, nachdem wir den Anmerkungsinhalt erhalten haben, zum Beispiel:

Standard exportieren {
  Methoden: {
    /**
     * @öffentlich
     * @param {boolean} Wertparameterbeschreibung*/
    anzeigen(Wert) {}
  }
}

Um einen zu starken Eingriff in den Code zu vermeiden, müssen wir natürlich dennoch so wenig zusätzliche Bezeichner wie möglich hinzufügen. Die Parameterbeschreibung verwendet dasselbe Format wie js-doc, hauptsächlich weil diese Lösung häufiger verwendet wird und Code-Editoren automatisch eine einfache Bearbeitung unterstützen.

IV. Fazit

Das Schreiben von Komponentendokumentationen ist eine großartige Möglichkeit, die Zusammenarbeit zwischen Front-End-Entwicklern innerhalb eines Projekts zu verbessern. Ein gut gepflegtes Dokument wird das Entwicklungserlebnis erheblich verbessern. Und wenn wir darüber hinaus Tools zur Automatisierung des Dokumentenpflegeprozesses nutzen können, lässt sich die Entwicklungszufriedenheit weiter steigern.

Nach einer Reihe von Untersuchungen und Versuchen haben wir erfolgreich eine Lösung zum automatischen Extrahieren von Vue-Komponenteninformationen gefunden, die den Arbeitsaufwand für die Pflege von Vue-Komponentendokumenten erheblich reduziert und die Genauigkeit der Dokumentinformationen verbessert hat. In Bezug auf die spezifische Implementierung verwenden wir zunächst den Vue-Template-Compiler, um die Vue-Datei zu verarbeiten und das Template-AST und das JS-AST zu erhalten. Mit diesen beiden ASTs können wir detailliertere Informationen erhalten. Lassen Sie uns den Inhalt und die Erfassungsmethoden sortieren, die in den bisher generierten Dokumenten abgerufen werden können:

Ob der Inhalt nach dem Abrufen im Markdown- oder JSON-Format ausgegeben wird, hängt von der tatsächlichen Entwicklungssituation ab.

V. Ausblick

Was wir hier diskutieren, ist das Abrufen von Informationen und die Ausgabe direkt aus einer einzelnen Vue-Datei. Wie bei vielen Komponentenbibliotheken von Drittanbietern, z. B. der Dokumentation von elementUI, gibt es jedoch nicht nur Komponenteninformationen, sondern auch Anzeigebeispiele. Wenn eine Komponentenbibliothek relativ gut gepflegt ist, sollte eine Komponente einen entsprechenden Testfall haben. Ist es also möglich, auch den Testfall der Komponente zu extrahieren und eine automatische Extraktion des Beispielteils in der Komponentendatei zu realisieren? Auch dies ist ein Thema, das einer Untersuchung bedarf.

Oben finden Sie ausführliche Informationen zur Analyse der automatischen Generierung von Vue-Komponentendokumenten. Weitere Informationen zur automatischen Generierung von Vue-Komponentendokumenten finden Sie in den anderen verwandten Artikeln auf 123WORDPRESS.COM!