Veralten Sie Ihre Webkomponenten-APIs

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!