suchen
HeimWeb-FrontendCSS-TutorialVeralten 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!

Deprecating Your Web Component APIs

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!

Stellungnahme
Der Inhalt dieses Artikels wird freiwillig von Internetnutzern beigesteuert und das Urheberrecht liegt beim ursprünglichen Autor. Diese Website übernimmt keine entsprechende rechtliche Verantwortung. Wenn Sie Inhalte finden, bei denen der Verdacht eines Plagiats oder einer Rechtsverletzung besteht, wenden Sie sich bitte an admin@php.cn
Zehn Tonnen WidgetsZehn Tonnen WidgetsApr 15, 2025 am 09:43 AM

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

Rezepte für Leistungstests einseitige Anwendungen in WebPagetestRezepte für Leistungstests einseitige Anwendungen in WebPagetestApr 15, 2025 am 09:42 AM

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

Stoppen Sie Animationen während der Änderung der FenstergrößenStoppen Sie Animationen während der Änderung der FenstergrößenApr 15, 2025 am 09:40 AM

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

Ein Element über und unter ein anderes Element webenEin Element über und unter ein anderes Element webenApr 15, 2025 am 09:38 AM

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

Gibt es zufällige Zahlen in CSS?Gibt es zufällige Zahlen in CSS?Apr 15, 2025 am 09:37 AM

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

Schweben Element in der Mitte eines AbsatzesSchweben Element in der Mitte eines AbsatzesApr 15, 2025 am 09:36 AM

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

Lassen Sie einen schicken, aber unkomplizierten Seitenloader machenLassen Sie einen schicken, aber unkomplizierten Seitenloader machenApr 15, 2025 am 09:33 AM

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

Die Landschaft der plattformübergreifenden App-EntwicklungDie Landschaft der plattformübergreifenden App-EntwicklungApr 15, 2025 am 09:29 AM

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

See all articles

Heiße KI -Werkzeuge

Undresser.AI Undress

Undresser.AI Undress

KI-gestützte App zum Erstellen realistischer Aktfotos

AI Clothes Remover

AI Clothes Remover

Online-KI-Tool zum Entfernen von Kleidung aus Fotos.

Undress AI Tool

Undress AI Tool

Ausziehbilder kostenlos

Clothoff.io

Clothoff.io

KI-Kleiderentferner

AI Hentai Generator

AI Hentai Generator

Erstellen Sie kostenlos Ai Hentai.

Heißer Artikel

R.E.P.O. Energiekristalle erklärten und was sie tun (gelber Kristall)
4 Wochen vorBy尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. Beste grafische Einstellungen
4 Wochen vorBy尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. So reparieren Sie Audio, wenn Sie niemanden hören können
4 Wochen vorBy尊渡假赌尊渡假赌尊渡假赌
WWE 2K25: Wie man alles in Myrise freischaltet
1 Monate vorBy尊渡假赌尊渡假赌尊渡假赌

Heiße Werkzeuge

Dreamweaver CS6

Dreamweaver CS6

Visuelle Webentwicklungstools

Sicherer Prüfungsbrowser

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 neue Version

SublimeText3 Linux neueste Version

MantisBT

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

WebStorm-Mac-Version

Nützliche JavaScript-Entwicklungstools