Die Einstellung Ihrer Webkomponenten-APIs ist eine hervorragende Möglichkeit, Ihren Benutzern mitzuteilen, dass eine Funktion in der nächsten Hauptversion Ihres Pakets entfernt wird. Wenn Sie ein benutzerdefiniertes Elementmanifest zum Dokumentieren Ihrer Komponenten-APIs verwenden, kann dies schwieriger sein, als es scheint. Webkomponenten verfügen normalerweise über mehr öffentliche APIs als Framework-Komponenten:
- CSS-Variablen
- CSS-Teile
- Slots
- Veranstaltungen
- Methoden
- Attribute
- Eigenschaften.
In diesem Artikel werde ich zeigen, wie Sie Ihre API-Abkündigungen dokumentieren und Ersatzfunktionen hinzufügen, ohne wichtige Änderungen einzuführen.
Dokumentation
Einer der schwierigsten Teile des Einstellungsprozesses ist die Dokumentation. Für Eigenschaften, Methoden und sogar Ihre Komponente kann dies so einfach sein wie das Hinzufügen eines @deprecated-Tags zu Ihrem JSDoc-Kommentar in der Klasse der Komponente.
/** * @deprecated This component is going away. Use ... instead. */ class MyElement extends HTMLElement { /** @deprecated This property is being removed. Use ... instead. */ myProp; /** @deprecated This method is going away. Use ... instead. */ myMethod() { } }
Die CSS-Variablen, CSS-Teile, Slots, Ereignisse und Attribute werden normalerweise im JSDoc der Klasse dokumentiert.
Hier ist ein Beispiel dafür, was Sie in einem JSDoc für benutzerdefinierte Elemente dokumentieren können:
/** * @attr {boolean} disabled - disables the element * @attribute {string} foo - description for foo * * @csspart bar - Styles the bar element in the shadow DOM * * @slot - This is a default/unnamed slot * @slot container - You can put some elements here * * @cssprop --text-color - Controls the color of foo * @cssproperty [--background-color=red] - Controls the background color of bar * * @prop {boolean} prop1 - some description * @property {number} prop2 - some description * * @fires custom-event - some description for custom-event * @fires {MyType} typed-event - some description for typed-event * @event {MyType} typed-custom-event - some description for typed-custom-event * * @summary This is MyElement * * @tag my-element * @tagname my-element */ class MyElement extends HTMLElement {}
Das Problem
Die Herausforderung besteht darin, dass Sie JSDoc-Tags nicht verdoppeln und das @deprecated-Tag verwenden können, um anzugeben, dass diese Elemente veraltet sind. Andernfalls wird es so interpretiert, dass die gesamte Klasse veraltet ist.
/** * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌ */ class MyElement extends HTMLElement {}
Eine Lösung
Um dies zu umgehen, habe ich ein Tool (custom-elements-manifest-deprecator) erstellt, mit dem Sie Elemente in Ihrem JSDoc markieren können, damit sie im Custom Elements Manifest entsprechend aktualisiert werden.
Mit diesem Tool können Sie alternative Tags verwenden, um veraltete APIs zu identifizieren. Standardmäßig wird ein in Klammern eingeschlossenes @deprecated-Tag als Bezeichner verwendet (was wir heute verwenden werden), es kann jedoch nach Ihren Wünschen angepasst werden.
/** * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ? */ class MyElement extends HTMLElement {}
Aktualisieren Ihrer APIs
Eine wichtige Sache für unser Team ist, dass wir, wenn wir eine API entfernen oder ändern, versuchen, die neue Funktion vor der nächsten Hauptversion einzuführen, damit Teams frühzeitig darauf migrieren können. Wenn sie auf dem neuesten Stand bleiben, können sie auf diese Weise die Auswirkungen eines Upgrades auf eine neue Version minimieren.
In diesem nächsten Abschnitt erfahren Sie, wie Sie neue Funktionen einführen, ohne Ihre alten APIs zu beschädigen, und wie sie nebeneinander existieren können, ohne miteinander zu konkurrieren. Wir werden einige APIs für eine einfache Schaltflächenkomponente aktualisieren.
In diesem Beispiel verwende ich Lit, aber diese Funktionen und Prinzipien können auf jede Umgebung angewendet werden.
CSS-Variablen
Um eine bessere automatische Vervollständigung und Beschreibungen in unseren Editoren wie VS Code und JetBrains bereitzustellen, müssen wir komponentenspezifische CSS-Variablennamen bereitstellen.
/** * @deprecated This component is going away. Use ... instead. */ class MyElement extends HTMLElement { /** @deprecated This property is being removed. Use ... instead. */ myProp; /** @deprecated This method is going away. Use ... instead. */ myMethod() { } }
Das Schwierige daran ist, dass die Teams bereits die alten Variablen verwenden, wir brauchen also beide, um zu funktionieren. Wir können dies tun, indem wir die veralteten Variablen neuen zuordnen und unseren Schaltflächencode aktualisieren, um nur die Variablen zu verwenden. Auf diese Weise werden, wenn die Benutzer mit den veralteten Variablen formatieren, diese auf die neuen Variablen angewendet, oder Benutzer können Werte direkt auf die neuen Variablen anwenden.
/** * @attr {boolean} disabled - disables the element * @attribute {string} foo - description for foo * * @csspart bar - Styles the bar element in the shadow DOM * * @slot - This is a default/unnamed slot * @slot container - You can put some elements here * * @cssprop --text-color - Controls the color of foo * @cssproperty [--background-color=red] - Controls the background color of bar * * @prop {boolean} prop1 - some description * @property {number} prop2 - some description * * @fires custom-event - some description for custom-event * @fires {MyType} typed-event - some description for typed-event * @event {MyType} typed-custom-event - some description for typed-custom-event * * @summary This is MyElement * * @tag my-element * @tagname my-element */ class MyElement extends HTMLElement {}
Jetzt können wir unsere JSDoc-Informationen mit den neuen CSS-Variablen aktualisieren und (@deprecated) mit aktualisierten Beschreibungen zu den alten hinzufügen.
/** * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌ */ class MyElement extends HTMLElement {}
CSS-Teile
Wie unsere CSS-Variablen möchten wir für eine bessere Werkzeugunterstützung Namespace-Namen für unsere Teile bereitstellen, daher werden wir die Steuerung durch eine Schaltflächensteuerung ersetzen. CSS-Teile sind ziemlich einfach, da wir wie CSS-Klassen mehrere Teile auf ein Element anwenden können. Wenden wir also den neuen Teilnamen nebeneinander auf das Element an.
/** * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ? */ class MyElement extends HTMLElement {}
Jetzt können wir unser JSDoc mit dem neuen Teil aktualisieren, den alten Teil mit (@deprecated) als veraltet deklarieren und die Beschreibung aktualisieren.
/* old variables */ --bg-color: #ccc; --fg-color: black; /* new variables */ --button-bg-color: #ccc; --button-fg-color: black;
Spielautomaten
Mit den neuen Initiativen für unsere Komponenten zur Unterstützung der Internationalisierung (i18n) aktualisieren wir einige unserer APIs, um in RTL-Sprachen (von rechts nach links) aussagekräftiger zu sein. Eine Sache, die wir tun möchten, ist, unseren Slot zu aktualisieren, der ein Symbol vor dem Schaltflächentext von links nach rechts anzeigen soll, ohne das Erlebnis für Projekte zu beeinträchtigen, die bereits den linken Slot verwenden.
Wir können dies tun, indem wir den veralteten Slot im neuen Slot verschachteln. Wenn der neue Steckplatz nicht verwendet wird, „greift“ er auf den alten Steckplatz zurück.
--bg-color: #ccc; --fg-color: black; --button-bg-color: var(--bg-color); --button-fg-color: var(--fg-color); button { background-color: var(--button-bg-color); border: solid 1px var(--button-fg-color); color: var(--button-fg-color); }
Jetzt können wir unser JSDoc mit dem neuen Slot aktualisieren, den alten Slot mit (@deprecated) als veraltet markieren und die Beschreibung aktualisieren.
/** * An example button element. * * @tag my-button * * @cssprop [--bg-color=#ccc] - (@deprecated) (use `--button-bg-color` instead) controls the background color of the button * @cssprop [--fg-color=black] - (@deprecated) (use `--button-fg-color` instead) controls the foreground/text color of the button * @cssprop [--button-bg-color=#ccc] - controls the background color of the button * @cssprop [--button-fg-color=black] - controls the foreground/text color of the button * */
Veranstaltungen
In unserem Beispiel geben wir ein benutzerdefiniertes Fokusereignis aus, aber es wird für Teams immer verwirrender, deshalb möchten wir ein namensraumbasiertes Ereignis (my-focus) hinzufügen. Ereignisse sind ziemlich einfach, da Sie beide Ereignisse ausgeben können und Entwickler bei Gelegenheit zum neuen wechseln können.
<button part="control button-control"> <slot></slot> </button>
Jetzt können wir unser JSDoc mit dem neuen Ereignis aktualisieren, das alte Ereignis mit (@deprecated) verwerfen und die Beschreibung aktualisieren.
/** * An example button element. * * @tag my-button * * @csspart control - (@deprecated) (use `button-control` instead) provides a hook to style internal button element * @csspart button-control - provides a hook to style internal button element */
HINWEIS: Die meisten Tools akzeptieren @event und @fires zur Dokumentation von Ereignissen. Es gibt keinen wirklichen Unterschied zwischen ihnen.
Methoden
Methoden lassen sich recht einfach parallel hinzufügen und Sie können das Standard-Tag @deprecated in der Methodenbeschreibung verwenden, um mitzuteilen, dass sie veraltet sind.
/** * @deprecated This component is going away. Use ... instead. */ class MyElement extends HTMLElement { /** @deprecated This property is being removed. Use ... instead. */ myProp; /** @deprecated This method is going away. Use ... instead. */ myMethod() { } }
Eigenschaften und Attribute
Eigenschaften und Attribute können im JSDoc der Klasse mithilfe der Tags @attr/@attribute und @prop/@property dokumentiert werden. Wenn Sie sie verwenden, können Sie sie mit dem Tag (@deprecated) im Custom Elements Manifest als veraltet markieren. Allerdings ist es normalerweise besser, die Eigenschaft direkt mit einem eigenen JSDoc-Kommentar zu dokumentieren. Dadurch können Dinge wie Typen und andere Tools veraltete APIs ordnungsgemäß identifizieren.
Das Schöne ist, dass die meisten Analysatoren ziemlich gut darin sind, Attribute mit Eigenschaften zu verknüpfen, die in der Komponentenklasse mit Dekoratoren oder anderen Konfigurationen definiert werden. Wenn Sie also die Eigenschaft verwerfen, wird auch das zugehörige Attribut veraltet sein.
In unserer Demo-Komponente haben wir ein Deaktivierungsattribut, das wir auf „Deaktiviert“ aktualisieren möchten, um es besser an native HTML-Elemente anzupassen.
Das erste, was wir tun möchten, ist, die alte Eigenschaft abzuschaffen und unsere neue hinzuzufügen.
/** * @attr {boolean} disabled - disables the element * @attribute {string} foo - description for foo * * @csspart bar - Styles the bar element in the shadow DOM * * @slot - This is a default/unnamed slot * @slot container - You can put some elements here * * @cssprop --text-color - Controls the color of foo * @cssproperty [--background-color=red] - Controls the background color of bar * * @prop {boolean} prop1 - some description * @property {number} prop2 - some description * * @fires custom-event - some description for custom-event * @fires {MyType} typed-event - some description for typed-event * @event {MyType} typed-custom-event - some description for typed-custom-event * * @summary This is MyElement * * @tag my-element * @tagname my-element */ class MyElement extends HTMLElement {}
Jetzt möchten wir vermeiden, dass wir beide Eigenschaften jedes Mal überprüfen müssen, wenn wir feststellen müssen, ob die Komponente deaktiviert ist. Um dies zu vereinfachen, können wir die veraltete Eigenschaft in einen Getter/Setter umwandeln und die neue Eigenschaft als Quelle der Wahrheit verwenden.
/** * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌ */ class MyElement extends HTMLElement {}
Jetzt wird bei jeder Aktualisierung des alten Werts automatisch der neue Wert aktualisiert, sodass wir nur noch die neue Eigenschaft überprüfen müssen, um festzustellen, ob die Komponente deaktiviert ist.
/** * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ? */ class MyElement extends HTMLElement {}
Schauen Sie sich das fertige Beispiel an!
Abschluss
Das Ändern von APIs kann zu Komplikationen führen, bedeutet jedoch nicht, dass Sie die Produktion neuer Funktionen einstellen müssen, da dies möglicherweise zu bahnbrechenden Änderungen führt. Die frühzeitige Einführung neuer Funktionen und die Abschaffung alter Funktionen kann eine Möglichkeit sein, eine gute Entwicklererfahrung (DX) zu bieten. Dies bietet einen Weg zur schrittweisen Verbesserung, anstatt Teams dazu zu zwingen, zu warten und massive Änderungen auf einmal vorzunehmen, um von neuen Funktionen zu profitieren.
Das obige ist der detaillierte Inhalt vonVeralten Sie Ihre Webkomponenten-APIs. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!

Bei einem kürzlichen Konferenzgespräch (sorry, ich vergesse, welche) gab es ein kurzes Beispiel für schlechte Webleistung in Form eines Widgets von Drittanbietern. Das Beispiel

WebPagetest ist ein Online -Tool und ein Open -Source -Projekt, mit dem Entwickler die Leistung ihrer Websites prüfen können. Als Webleistung Evangelist bei

Angenommen, Sie haben eine Seite mit einer Reihe von Übergängen und Animationen zu allen möglichen Elementen. Einige von ihnen werden ausgelöst, wenn das Fenster verändert wird, weil sie

In diesem Beitrag werden wir CSS -Superkräfte verwenden, um einen visuellen Effekt zu erzielen, bei dem sich zwei Elemente überlappen und zusammenweben. Die Offenbarung für dieses Design kam

Mit CSS können Sie dynamische Layouts und Schnittstellen im Web erstellen, aber als Sprache ist es statisch: Sobald ein Wert festgelegt ist, kann er nicht geändert werden. Die Idee von

Sagen Sie, Sie möchten ein Bild (oder ein anderes Element) visuell in einen Textabsatz schweben. Aber wie ... in der Mitte des Absatzes, nicht richtig bei

Es ist heutzutage ziemlich häufig, einen Ladezustand auf Websites zu sehen, insbesondere wenn progressive Web -Apps und reaktive Websites zunehmen. Es ist ein Weg zu

Ich verfolge dieses Zeug nicht sehr gut, aber ich verstehe es. Wenn Sie eine native App für Android und iOS wünschen, wäre es sicher schön, sie nur einmal schreiben zu müssen


Heiße KI -Werkzeuge

Undresser.AI Undress
KI-gestützte App zum Erstellen realistischer Aktfotos

AI Clothes Remover
Online-KI-Tool zum Entfernen von Kleidung aus Fotos.

Undress AI Tool
Ausziehbilder kostenlos

Clothoff.io
KI-Kleiderentferner

AI Hentai Generator
Erstellen Sie kostenlos Ai Hentai.

Heißer Artikel

Heiße Werkzeuge

Dreamweaver CS6
Visuelle Webentwicklungstools

Sicherer Prüfungsbrowser
Safe Exam Browser ist eine sichere Browserumgebung für die sichere Teilnahme an Online-Prüfungen. Diese Software verwandelt jeden Computer in einen sicheren Arbeitsplatz. Es kontrolliert den Zugriff auf alle Dienstprogramme und verhindert, dass Schüler nicht autorisierte Ressourcen nutzen.

SublimeText3 Linux neue Version
SublimeText3 Linux neueste Version

MantisBT
Mantis ist ein einfach zu implementierendes webbasiertes Tool zur Fehlerverfolgung, das die Fehlerverfolgung von Produkten unterstützen soll. Es erfordert PHP, MySQL und einen Webserver. Schauen Sie sich unsere Demo- und Hosting-Services an.

WebStorm-Mac-Version
Nützliche JavaScript-Entwicklungstools